diff --git a/twander.1 b/twander.1 index 29d0d18..45fd487 100644 --- a/twander.1 +++ b/twander.1 @@ -47,12 +47,12 @@ 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. The Key -Bindings are also listed. If the user presses a defined command key, +Bindings are also listed. 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. +Command String after all variable substitution (User-Defined, +Environment, and Built-Ins) has been done. .TP .B -f forecolor @@ -139,7 +139,6 @@ 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 @@ -393,11 +392,10 @@ .B Run User-Defined Command User-Defined (Single Letter) Key -Each command defined in the configuration file has both a "Command -Key" and a "Command Name" associated with it. Pressing that key -will cause the command associated with it to be run. If no command -is associated with a given keystroke, nothing will happen. - +Each command defined in the configuration file has a Command Key +associated with it. Pressing that key will cause the associated +command to be run. If no command is associated with a given +keystroke, nothing will happen when it is pressed. .SH MENU OPTIONS @@ -417,10 +415,10 @@ .SS Commands Menu Every command defined in the configuration file is listed in this menu -by its "Command Name". The association "Command Key" is also shown in +by its Command Name. The association Command Key is also shown in parenthesis. Clicking on an item in this menu is the same as invoking -it from the keyboard by its "Command Key". This is a convenient way -to invoke an infrequently used command whose command key you've +it from the keyboard by its Command Key. This is a convenient way +to invoke an infrequently used command whose Command Key you've forgotten. It is also handy to confirm which commands are defined after you've edited and reloaded the configuration file. The commands are listed in the order in which they are defined in the configuration @@ -444,8 +442,7 @@ displays that list in sorted order. This provides another way to move directly to a previously visited directory without having to manually navigate to it again, back up to it, or name it explictly using the -"Change Directory" command. - +Change Directory command. .SH LOCATION OF CONFIGURATION FILE @@ -479,7 +476,6 @@ for a file called ".twander" in the directory from which \'twander\' was invoked. - .SH CONFIGURATION FILE FORMAT @@ -517,13 +513,13 @@ It is conceivable that the "#" character might be needed in the Command String portion of a Command Definition. \'twander\' -provides a builtin variable, [HASH], for exactly this purpose. -See the section on Builtin Variables below for a more complete +provides a Built-In Variable, [HASH], for exactly this purpose. +See the section on Built-In Variables below for a more complete description. .SS User-Defined Variables -Variables are defined using the syntax: +User-Defined Variables are defined using the syntax: .nf Variable-Name = Replacement-String @@ -598,21 +594,21 @@ terminate. Your variable definitions can also nest other kinds of variables -(Environment and Builtins). So, constructs like this are perfectly +(Environment and Built-Ins). So, constructs like this are perfectly OK: .nf Var1 = [$PAGER] Var2 = command-arguments -V = [Var1] [Var2] [DSELECTIONS] +V = [Var1] [Var2] [DSELECTION] .fi -Notice that since the right-hand side of User-Defined Variables -is literally replaced, we have to make sure there is -space between the various variable references. If we -used "[Var1][Var2][DSELECTIONS]" we would get one long string -back instead of a command with arguments and a list of selected -items. +.IP \(bu 4 +In the example above, notice that since the right-hand side of +User-Defined Variables is literally replaced, we have to make sure +there is space between the various variable references. If we used +[Var1][Var2][DSELECTION] we would get one long string back instead +of a command with arguments and a list of selected items. .IP \(bu 4 Variables must be @@ -621,7 +617,7 @@ variable name in another User-Variable Definition so long as all these variable are defined by the time they appear in a Command String. The following is OK because all variables are defined by the time they -actually get used in the Command Definition: +actually needed: .nf Var1 = foo @@ -646,12 +642,11 @@ .IP \(bu 4 The "=" is what separates the Variable Name from the replacement -string. Therefore, the "=" cannot ever be part of a Variable -Name. A Variable Name cannot begin with "$" (see next bullet). - -Other than these minor restrictions, both Variable Names and -Replacement Characters can be any string of characters of any length. -Good judgment would suggest that Variable Names should be somewhat +string. Therefore, the "=" cannot ever be part of a Variable Name. A +Variable Name cannot begin with "$" (see next bullet). Other than +these minor restrictions, both Variable Names and Replacement +Characters can be any string of characters of any length. Good +judgment would suggest that Variable Names should be somewhat self-descriptive and of reasonable length - i.e., Much shorter than the replacement string! @@ -660,7 +655,7 @@ Definition containing a string in the form [$something] is understood by \'twander\' to be a reference to an .B Environment Variable, -named "something". If you this: +named "something". If you do this: .nf $MYVAR = some-string @@ -676,10 +671,9 @@ Variable Names may not be redefined. This means you can only define a given Variable Name once per configuration file. It is also considered a variable redefinition if you try to use a variable name -which matches either one of the Builtin Variables (used in Command -Definitions) or one of the Program Function Names (used for key -bindings). - +which matches either one of the Built-In Variables (used in Command +Definitions) or one of the Program Function Names (used for Key +Bindings). .P .SS Key Binding Statements @@ -692,36 +686,41 @@ .SS Command Definitions The heart of the \'twander\' configuration process is creating -of one or more "Command Definitions". These definitions are the -way user-defined commands are added to a given instance of \'twander\'. -A Command Definition consists of three fields separated by -whitespace: +of one or more +.B Command Definitions. +These definitions are the way user-defined commands are added to a +given instance of \'twander\'. A Command Definition consists of three +fields separated by whitespace: .nf Command-Key Command-Name Command-String .fi -The "Command Key" -.B is any single character -which can be typed on the keyboard. This is the key that will be used -to invoke the command from the keyboard. Command Keys are -case-sensitive. If "m" is used as a Command Key, "M" will not invoke -that command. Command Keys must be unique within a given -configuration file. \'twander\' will declare an error and refuse to -run if it sees two Command Definitions with the same Command Key in a -given configuration file. A Command Key can never be "#" which is -always understood to be the beginning of a comment. +The +.B Command Key +is any single character which can be typed on the keyboard. This is +the key that will be used to invoke the command from the keyboard. +Command Keys are case-sensitive. If "m" is used as a Command Key, "M" +will not invoke that command. Command Keys must be unique within a +given configuration file. \'twander\' will declare an error and +refuse to run if it sees two Command Definitions with the same Command +Key in a given configuration file. A Command Key can never be "#" +which is always understood to be the beginning of a comment. -The "Command Name" is a string of any length containing any -characters. This is the name of the command which is used to invoke -the command from the Command Menu. Command Names are case-sensitive -("command" and "Command" are different names), but they are not -required to be unique within a given configuration file. That is, two -different Command Definitions may have identical Command Names -associated with them, though this is not ordinarily recommended. +The +.B Command Name +is a string of any length containing any characters. This is the name +of the command which is used to invoke the command from the Command +Menu. Command Names are case-sensitive ("command" and "Command" are +different names), but they are not required to be unique within a +given configuration file. That is, two different Command Definitions +may have identical Command Names associated with them, though this is +not ordinarily recommended. -The "Command String" is any arbitrary string which is what \'twander\' -actually tries to execute when the command is invoked. +The +.B Command String +is any arbitrary string which is what \'twander\' actually tries to +execute when the command is invoked. .SS A Simple Command Definition @@ -738,7 +737,8 @@ \'twander\' will then execute the command, "more somefile". The problem is that this command as written actually will not give you -the result you'd like. (For more details on why, see the +the result you'd like (...well, on X-Windows - is does work on Win32 +as written). (For more details on why, see the .B GOTCHAS section below.) It turns out that starting a non-GUI program like \'more\' in a new window needs some extra work. What we want to do @@ -789,16 +789,16 @@ m MyMore [XTERM] [$PAGER] somefile .fi -.SS Builtin Variables In A Command String +.SS Built-In Variables In A Command String It would also be really nice if the command applied to more than just a single file called "somefile". The whole point of \'twander\' is to allow you to use the GUI to select one or more directories and/or files and have your Command Definitions make use of those selections. \'twander\' uses a set of -.B Builtin Variables +.B Built-In Variables to communicate the current directory and user selections to the -any commands you've defined. Builtin Variables are referenced +any commands you've defined. Built-In Variables are referenced just like User-Defined Variables and Environment Variables and may be inserted any appropriate place in the Command String. In our example, we probably want the command to pickup whatever @@ -808,17 +808,17 @@ .nf # Our command in its most generic form using -# User-Defined, Environment, and Builtin Variables +# User-Defined, Environment, and Built-In Variables XTERM = xterm -l -e m MyMore [XTERM] [$PAGER] [DSELECTION] .fi -The "DSELECTION" builtin is what communicates the currently +The "DSELECTION" built-in is what communicates the currently selected item from the GUI to your command when the command actually gets run. -\'twander\' has a small, but rich set of Builtin Variables +\'twander\' has a small, but rich set of Built-In Variables for use in your command definitions: .IP \(bu 4 @@ -833,7 +833,7 @@ [DSELECTION] is replaced with the fully-qualified path name of the item currently selected in the GUI. If more than one item is selected, [DSELECTION] refers to the last item -in the group. +in the group. .IP \(bu 4 .B [DSELECTIONS] @@ -846,15 +846,15 @@ .IP \(bu 4 .B [HASH] -Because \'twander\' always recognizes the "#" as the beginning -of a comment, there is no direct way to include this character -in a Command String. It is conceivable that some commands (such -as \'sed\') need to make use of this character. The [HASH] -builtin is provided for this purpose. Anywhere it appears in -the Command String, it will be replaced with the "#" at command -execution time. Unlike the Builtin Variables, [HASH] is never -quoted when it is replaced in a Command String, regardless of -whether the -t command argument is used or not. +Because \'twander\' always recognizes the "#" as the beginning of a +comment, there is no direct way to include this character in a Command +String. It is conceivable that some commands (such as \'sed\') need +to make use of this character. The [HASH] built-in is provided for +this purpose. Anywhere it appears in the Command String, it will be +replaced with the "#" at command execution time. Unlike all the other +Built-In Variables, [HASH] is never quoted when it is replaced in a +Command String, regardless of whether the -t command argument is used +or not. .IP \(bu 4 .B [SELECTION] @@ -895,17 +895,18 @@ c UnixCP [UnixCopy] [DSELECTIONS] [PROMPT:Enter Destination] # Win32 Version -C Win32CP [UnixCopy] [DSELECTIONS] [PROMPT:Enter Destination] +C Win32CP [Win32Copy] [DSELECTIONS] [PROMPT:Enter Destination] .fi .P -A few other points about Builtin Variables are worth noting: +A few other points about Built-In Variables are worth noting: .IP \(bu 4 -Any of the builtins that return selections from the GUI will -always end a directory name with a path separator character -("/" or "\\"). +Any of the built-ins that return selections from the GUI will always +end a directory name with a path separator character ("/" or "\\") +appended at the end. This allows you to safely concatenate this +string with something else in your Command String. .IP \(bu 4 User-Defined and Environment Variables are processed @@ -915,17 +916,17 @@ at load time. .IP \(bu 4 -By contrast, Builtin Variables are resolved +By contrast, Built-In Variables are resolved .B on each command invocation, -i.e - at runtime. +i.e - at command runtime. .IP \(bu 4 -The results of all builtins are put inside double-quotes when they -are replaced in the command string. This default is recommended -so that any builtin substitutions of, say, file names with spaces -in them, will be properly recognized by your commands. You can -suppress the addition of double-quotes by using the -t command line -option when starting \'twander\'. +The results of all built-ins (except HASH) are put inside +double-quotes when they are replaced in the Command String. This +default is recommended so that any built-in substitutions of, say, +file names with spaces in them, will be properly recognized by your +commands. You can suppress the addition of double-quotes by using the +-t command line option when starting \'twander\'. .IP \(bu 4 Any of the variable types may appear multiple times in the @@ -940,8 +941,6 @@ Menu), they will be presented with two prompts, one after the other, and then the command will run. - - .SH CHANGING KEYBOARD BINDINGS No program that runs in many operating environments can satisfy @@ -961,6 +960,11 @@ http://www.cs.mcgill.ca/~hv/classes/MS/TkinterPres/ .fi +(As an aside - Tkinter is nothing more than a Python interface to +the Tcl/Tk windowing system. The "real" naming conventions for +keystokes can be found in the many sources of Tk documentation, +both in print and on the Internet.) + Keyboard binding assignments look just like local variable definitions in the configuration file. (The \'twander\' configuration file parser automatically distinguishes between key binding statements and user @@ -1034,7 +1038,6 @@ spectacularly. At the very least, that program feature will probably be unusable, even if \'twander\' manages to run. - .SH GOTCHAS There are several tricky corners of \'twander\' which need @@ -1047,7 +1050,7 @@ generally want it to run in a new window. If the program you are running is GUI-aware, this should not be a problem. However, if you are using \'twander\' to run a command line program or script, you -have to take extra care in the formulation of the command string. +have to take extra care in the formulation of the Command String. In the case of Unix-like systems you have to invoke the command so that it runs in some GUI context. Say you want to use a pager like \'less\' to view files. You would expect that this entry might do it: @@ -1209,7 +1212,6 @@ installed, there should be an association for ".py" file types and \'twander\' should start automatically. - .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 @@ -1234,11 +1236,11 @@ 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: +\'twander\' is another 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