diff --git a/twander.1 b/twander.1 index 35e1f4c..c3d821f 100644 --- a/twander.1 +++ b/twander.1 @@ -1,93 +1,15 @@ .TH twander 1 "TundraWare Inc." .SH twander -Wander around a filesystem executing commands of your choice on selected -files and directories. -.SH THE BIG PICTURE -Graphical User Interfaces (GUIs) are a blessing and a curse. On the -one hand, they make it easy to learn and use a computer system. On -the other, they are a real inconvenience to experienced users who are -touch typists. Taking hands off the keyboard to use the mouse -can really slow down a good typist. - -Nowhere is this more apparent than in filesystem browsers. In one -corner we have the GUI variants like \'Konqueror\' and \'Microsoft -Windows Explorer\'. These are very easy to use but you pretty much -need the mouse in your hand to do anything useful. In the other -corner are the text-based file browsers like \'List\', \'Norton -Commander\', and \'Midnight Commander\'. These are really efficient -to use, but have limited functionality and generally do not operate -very well on -.B groups -of things. - -Both of these approaches also suffer from the well-known -interface problem of "What You See Is -.B All -You Get" - Each program has a predefined set of commands and the user -cannot easily extend these with their own, new commands. - -\'twander\' is a new approach to the filesystem navigation problem which -embraces the best of both the GUI-based approach and the text-based -approach. It also provides a rich mechanism whereby each user can -easily define their own command set and thereby customize the program -as they see fit. This is done with a number of key features: - - -.TP -1) -The -.B Navigation -of the filesystem is graphical - you can use the mouse to select files, -directories, or to change directories. However, each major filesystem -navigational feature is also doubled on the keyboard (using Control keys) -so you can move around and select things without ever touching the mouse. - -.TP -2) -\'twander\' also supports a number of -.B navigation shortcuts. -It provides single control-key access to changing directories, moving -to the previous directory, moving up one directory level, moving to -any previously visited directory, (de)selecting any or all -files/directories in the current view, and escaping to the operating -system to run a command. Many (but not all) of these features are -also doubled via GUI/mouse operations. - -.TP -3) -There are -.B no -built-in file or directory commands. All commands which manipulate -the files or directories selected during navigation are user-defined. -This command definition is done in an external configuration file -using a simple but powerful command macro language. This means that -that the command set of the program can easily be changed or expanded -without having to release a new version of \'twander\' every time. -Better still, every different user can have their own command set -defined in a way that suits their style of working. Best of all, -commands can be invoked either graphically (with a mouse click) or via -a single keypress to minimize moving your hands off the keyboard. - -.TP -4) -Because \'twander\' is written in Python using Tkinter, the same -program runs essentially identically on many Unix-style and Win32 -systems. The only thing that may need to be changed across these -various platforms are the command definitions in the configuration -file. You only need to learn one interface (and the commands you've -defined) across all the different systems you use. - -.P -The consquence of all this is that \'twander\' is an extremely -powerful and highly customizable filesystem navigator. Once -learned, both navigation and command execution are lightning-fast -(or at least, as fast as your machine can go ;) while minimizing -dependency on the mouse. +Wander around a filesystem executing commands of your choice on +selected files and directories. If you're new to \'twander\' and want +to know why this program is better and different than whatever you're +using at the moment, take a moment to read the section called "DESIGN +PHILOSOPHY" toward the end of this document first. .SH SYNOPSIS -twander [-bcdfhnqrstwvxy] [startdir] +twander [-bcdfhnqrstvwxy] [startdir] .SH OPTIONS .TP @@ -105,15 +27,17 @@ .TP .B -d -Start in debug mode. The program runs, but does not actually execute -any commands. Instead, the contents of various internal tables such -as the Symbol Table and Command Table are listed on standard output. -If the user presses a defined command key, the command that would have -been executed is printed to standard output, but no command is -actually performed. This option is mildly useful in debugging -configuration files insfar as it will display the command string after -all substitutions of variables (both builtins and user-defined) has -been done. (default: debug off) +Start in debug mode. (default: debug off) + +The program runs, but does not actually execute any commands. +Instead, the contents of various internal tables such as the Symbol +Table and Command Table are listed on standard output. If the user +presses a defined command key, the command that would have been +executed is printed to standard output, but no command is actually +performed. This option is mildly useful in debugging configuration +files insfar as it will display the command string after all +substitutions of variables (both built-ins and user-defined) has been +done. .TP .B -f forecolor @@ -132,13 +56,17 @@ Quiet mode - suppresses warnings. (default: warnings on) .TP -.B -r -Turn off automatic refreshing of directory display. (default: refresh on) -This is useful on slow machines (or slow X connections) and/or -when working with very large directories. In this situtation, the -frequent updating of the \'twander\' display can make the program -unacceptably slow and unresponsive. In this case you can still -force an update manually with the \'Control-l\' key. +.B -r +Turn off automatic refreshing of directory display. (default: refresh +on) + +Normally, \'twander\' re-reads and displays the current directory +every few seconds to reflect any changes that might have occured to +that directory's contents. This is useful on slow machines (or slow X +connections) and/or when working with very large directories. In this +situtation, the frequent updating of the \'twander\' display can make +the program unacceptably slow and unresponsive. In this case you can +still force an update manually with the \'Control-l\' key. .TP .B -s fontsize @@ -146,7 +74,16 @@ .TP .B -t -Turn off quoting when substituting builtin variables. (default: quoting on) +Turn off quoting when substituting built-in variables. (default: quoting on) + +Anytime \'twander\' encounters a reference to one of the built-in variables +(DIR, DSELECTION, DSELECTIONS, PROMPT:, SELECTION, SELECTIONS), it will +replace them with +.B double quoted +strings. This is necessary because any of these can return values which +have embedded spaces in them. By quoting them, they can be passed to a +command or script as a single item. The -t option disables this behavior +and replaces the built-in variable with unquoted literals. .TP .B -v @@ -164,51 +101,148 @@ .B -y width Set window width. (default: 25) -.SH PREASSIGNED KEYS +.SH KEYBOARD BINDINGS AND HOW TO CHANGE THEM -A few of the keys on the keyboard are preassigned to special -functions: +No program that runs on many operating systems can satisfy +everyone's (anyone's!) idea of what the "correct" key bindings +should be. An emacs user, vi user, BSD user, and Windows user +are going to differ considerably on what keys should be bound +to what feature. + +So, what follows is documentation on +the +.B default +key bindings. However, it is not difficult to change the +defaults. They are listed near the top of the program +file (twander.py) to allow people to tailor them as they +wish. The only thing you need to know is the \'Tkinter\' +nomenclature for keystroke names. You can get a pretty +good idea of this from reading the first part of the +program, and failing that, there is abundant documentation +of this topic on The Net. + +The only convention that ought to be observed here (to keep +the program sane - it assumes this convention throughout), is +that +.B navigation commands are Control keys. + +The obvious question here is, "Why isn't this a configuration option +maintained in the configuration file?" The answer is that it would +make the configuration file parser overly complex to handle something +which should be changed very rarely, if at all. The downside to this +approach is that per-user customization requires each user to keep a +copy of \'twander.py\' in their own directory space. + + +.SH ARROW AND KEYPAD BEHAVIOR + +Generally, the arrow and keypad keys should do what you would expect +on the system in question. On Win32 systems, particularly, there ought +to be no odd arrow/keypad behavior. + +X-Windows is somewhat more problematic in this area. Just what an +arrow key is "supposed" to do depends on how its been mapped in your X +server software. Testing \'twander\' on various X servers showed +quite a bit of variability on how they handled the arrows and keypad. +So ... if you're running in an X Windows universe and arrows or keypad +do nothing, or do strange things, look into your key maps, don't blame +\'twander\'. + +.SH DEFAULT KEYBOARD AND MOUSE BINDINGS + + +Here, ordered by category, are the default keyboard and mouse +bindings for \'twander\': + +.SS General Program Commands + +.PP .TP -.B Arrow Keys and Spacebar -The Left- and Right-Arrow keys are used for horizontal scrolling, -if needed. The Up- and Down-Arrow keys move up and down through -the currently displayed directory listing. Pressing the Spacebar -will cause the currently underlined item to be selected just as -if you had clicked on it. +.B KEYPRESS KeyPress .TP -.B Backspace -Move -.B up -one directory ("..") in the filesystem hierarchy. +.B QUITPROG Control-q .TP -.B Esc -Exit \'twander\' +.B READCONF Control-r .TP -.B Home -Return to the original starting directory +.B REFRESH Control-l .TP -.B Ctrl-L -Redraw/update the directory listing. +.B RUNCMD Control-z .TP -.B Ctrl-Left Arrow -Move -.B back -to previously visited directory. This can be done repeatedly until -you end up in the original starting directory. +.B TOGDETAILControl-t -.SH CONFIGURATION FILE FORMAT + +.SS Directory Navigation + +.TP +.B CHANGEDIR Control-x + +.TP +.B DIRHOME Control-h + +.TP +.B DIRBACK Control-b + +.TP +.B DIRSTART Control-s + +.TP +.B DIRUP Control-u + +.TP +.B MSEBACK Control-Double-ButtonRelease-1 + +.TP +.B MSEUP Control-Double-ButtonRelease-3 + +.SS Selection Keys + +.TP +.B SELALL Control-comma + +.TP +.B SELNEXT Control-n + +.TP +.B SELNONE Control-period + +.TP +.B SELPREV Control-p + +.TP +.B SELEND Control-e + +.TP +.B SELTOP Control-a + +.TP +.B SELKEY Control-space + +.TP +.B SELMOUSE Double-ButtonRelease-1 + + +.SS Intra-Display Movement + +.TP +.B PGDN Control-v + +.TP +.B PGUP Control-c + + +.SH LOCATION OF CONFIGURATION FILE \'twander\' .B requires -a startup configuration file in order to run. It -is the only way the program knows what features you wish to enable -and what commands are required to implement each feature. +a startup configuration file in order to run. It is in this file that +the user defines the commands which can be applied to the files and +directories selected in the program GUI. By default, the program expects to find configuration information in .B ~/.twander @@ -216,86 +250,24 @@ .B -c command line option. + +.SH CONFIGURATION FILE FORMAT + + \'twander\' configuration files consist of freeform lines of -text. Whitespace is ignored, and a comment may be inserted -anywhere. Comments must begin with the -.B # -character. +text. Each line is considered separately - no legal configuration +line may cross into the next line. Whitespace is ignored within +a line as are blank lines. -Each line of configuration information consists of two parts, -the -.B Command Name -and the -.B Command String. +There are only three possible legal lines in a \'twander\' +configuration file: Comments, Variable Definitions, and +Command Definitions. Everything else is considered invalid. +\'twander\' will respond with errors or warnings as is +appropriate anytime it encounters a problem in a configuration +file. This is both true when the program initially loads as +well as during any subsequent configuration file reloads +initiated from the keyboard while running \'twander\. -The Command Name is nothing more than your name for a given -command. The Command String tells \'twander\' what to do -when you issue the command in question. - -Within the Command Name you can specify a single letter -to be the -.B Command Key -by placing the -.B & -character before letter you wish to use. This letter will -be a keyboard shortcut to the command. If you select a file -via the \`twander\` interface and then press this key, the -command associated with that key will be executed. The case -of the Command Key is ignored, so \'X\' and \'x\' will -both invoke the same command, if any. - -Within the Command String you can specify several different -kinds of information: literal text which \'twander\' -will not touch, words beginning with the -.B $ -symbol, which are interpreted as environment variables, -the special symbol -.B [FILE], -and the special symbol -.B [DIRECTORY]. -When you decide to run a command, \'twander\' will replace -[FILE] with the currently selected file name. This will be the -.B fully qualified name of the file -- i.e., it will include the full path name. Similarly, -[DIRECTORY] is replaced with the current directory -name (ending with a path separator character). - - -Here is an example .twander file: -.nf - -# 'twander' configuration file example - -&edit $EDITOR [FILE] -vie&w $PAGER [FILE] -ls /bin/ls -al [FILE] | $PAGER - -.fi - -The first line is a comment and is completely ignored. The -second line is blank (all whitespace) and is also ignored. - -Line 3 means this: Invoke the \'edit\' command using \'e\' as the -command key. Use the $EDITOR environment variable to determine which -program to use for editing and place the current directory/file name -immediately after the program name to invoke the editing session. - -Similarly, Line 4 means: Use the program defined in he $PAGER -environment variable when invoking the \'view\' command via -the \'w\' key. Pass the currently selected directory or -file name to that program as its only argument. - -Line 5 is similar except for one thing: There is no Command Key -shortcut defined for that command. \'twander\' will permit this, but -it will warn you about it when the program starts. - -If you specify an environment variable in the configuration -file which is not actually defined, \'twander\' will print -an error to that effect and refuse to run. In other words, -every environment variable referenced in your configuration -file must be defined in order for the program to run at all. -This is an intentional design choice to force the creation -of sane and meaningful configuration files. .SH GOTCHAS @@ -388,6 +360,88 @@ This program has not been tested on MacOS. Please let me know how/if it works there and any issues you discover. +.SH DESIGN PHILOSOPHY +Graphical User Interfaces (GUIs) are a blessing and a curse. On the +one hand, they make it easy to learn and use a computer system. On +the other, they are a real inconvenience to experienced users who are +touch typists. Taking hands off the keyboard to use the mouse +can really slow down a good typist. + +Nowhere is this more apparent than in filesystem browsers. In one +corner we have the GUI variants like \'Konqueror\' and \'Microsoft +Windows Explorer\'. These are very easy to use but you pretty much +need the mouse in your hand to do anything useful. In the other +corner are the text-based file browsers like \'List\', \'Norton +Commander\', and \'Midnight Commander\'. These are really efficient +to use, but have limited functionality and generally do not operate +very well on +.B groups +of things. + +Both of these approaches also suffer from the well-known +interface problem of "What You See Is +.B All +You Get" - Each program has a predefined set of commands and the user +cannot easily extend these with their own, new commands. + +\'twander\' is a new approach to the filesystem navigation problem which +embraces the best of both the GUI-based approach and the text-based +approach. It also provides a rich mechanism whereby each user can +easily define their own command set and thereby customize the program +as they see fit. This is done with a number of key features: + + +.TP +1) +The +.B Navigation +of the filesystem is graphical - you can use the mouse to select files, +directories, or to change directories. However, each major filesystem +navigational feature is also doubled on the keyboard (using Control keys) +so you can move around and select things without ever touching the mouse. + +.TP +2) +\'twander\' also supports a number of +.B navigation shortcuts. +It provides single control-key access to changing directories, moving +to the previous directory, moving up one directory level, moving to +any previously visited directory, (de)selecting any or all +files/directories in the current view, and escaping to the operating +system to run a command. Many (but not all) of these features are +also doubled via GUI/mouse operations. + +.TP +3) +There are +.B no +built-in file or directory commands. All commands which manipulate +the files or directories selected during navigation are user-defined. +This command definition is done in an external configuration file +using a simple but powerful command macro language. This means that +that the command set of the program can easily be changed or expanded +without having to release a new version of \'twander\' every time. +Better still, every different user can have their own command set +defined in a way that suits their style of working. Best of all, +commands can be invoked either graphically (with a mouse click) or via +a single keypress to minimize moving your hands off the keyboard. + +.TP +4) +Because \'twander\' is written in Python using Tkinter, the same +program runs essentially identically on many Unix-style and Win32 +systems. The only thing that may need to be changed across these +various platforms are the command definitions in the configuration +file. You only need to learn one interface (and the commands you've +defined) across all the different systems you use. + +.P +The consequence of all this is that \'twander\' is an extremely +powerful and highly customizable filesystem navigator. Once +learned, both navigation and command execution are lightning-fast +(or at least, as fast as your machine can go ;) while minimizing +dependency on the mouse. + .SH COPYRIGHT AND LICENSING \'twander\' is Copyright(c) 2002 TundraWare Inc. For terms of use, see the twander-license.txt file in the program distribution. If you