diff --git a/twander.1 b/twander.1 index d1fb809..66538d6 100644 --- a/twander.1 +++ b/twander.1 @@ -231,7 +231,7 @@ or mouse action. You can ignore it unless you intend to override the default assignments. This use is described below in the section entitled, -.B CHANGING KEYBOARD BINDINGS. +.B Key Binding Statements. It is important to realize that \'twander\' key-bindings are .B case-sensitive. @@ -612,7 +612,7 @@ Control-e, and so forth. Also see the section below entitled, -.B PROGRAM OPTION STATEMENTS +.B Program Option Statements, to understand the CMDSHELL option. This option greatly simplifies running command-line programs from RUNCMD so their output can been seen in a GUI window. This is particularly @@ -658,6 +658,37 @@ command to be run. If no command is associated with a given keystroke, nothing will happen when it is pressed. +.SS PROGRAM MEMORIES + +If you've used GUIs before, you're probably familiar with the idea +of a program "Clipboard" - a temporary holding area which is used when +cutting, copying, and pasting files. This is a good idea, but has +several limitations. First, most systems only have a +.B single clipboard. +It would be mighty handy to have muliple Clipboard-like storage +areas for keeping track of several different operations at once. +Secondly, when you copy or paste something to a conventional Clipboard, +.B its old contents get overwritten. +There is no way to keep appending items to the Clipboard. +Finally, items usually can only be cut or copied to the Clipboard +.B from the current directory. +It would be nice if we could not only keep adding things to the +Clipboard, but be able to do so as we navigate around the filesystem. + +\'twander\' addresses these concerns by means of 12 separate +"Program Memories". At any point while using the program, you +can +.B append +the fully qualified path names of your currently selected items +to any one of these 12 Program Memories. This is done using the +MEMSET1-MEMSET12 keys (default: Alt-F1 through Alt-F12). You +can also selectively +.B clear +any of these memories with the CLRMEM1-CLRMEM12 keys (default: +Control-F1 through Control-F12) or you can clear them +.B all +with the MEMCLRALL key (default: Control-m). + .SH MENU OPTIONS @@ -855,29 +886,39 @@ .SH CONFIGURATION FILE FORMAT - \'twander\' Configuration Files consist of freeform lines of text. Each line is considered independently - no configuration line may cross into the next line. Whitespace is ignored within a line as are blank lines. There are several possible legal lines in a \'twander\' Configuration -File: Comments, Program Option Statements, Key Binding Statements, -User-Defined Variables, 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. An error will cause the program to terminate, but the program -continues to run after a warning. For the most part, \'twander\' -tries to be forgiving and merely ignores invalid configuration statements -(after an appropriate warning). It only declares an error when it -cannot continue. +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\'. +.nf +Comments +Program Option Statements +Key Binding Statements +Directory Shortcut Statements +Variables And Command Definitions +.fi -See the ".twander" file provided with the program distribution -for examples of valid configuration statements. +(See the ".twander" file provided with the program distribution +for examples of valid configuration statements.) + +Everything else is considered invalid. \'twander\' will respond with +errors or warnings as is appropriate anytime it encounters a problem +in a Configuration File. An error will cause the program to +terminate, but the program continues to run after a warning. For the +most part, \'twander\' tries to be forgiving and merely ignores +invalid configuration statements (after an appropriate warning). It +only declares an error when it cannot continue. 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 following sections describe each of the valid Configuration +File entires in more detail. + .SS Comments @@ -894,25 +935,138 @@ It is conceivable that the "#" character might be needed in the Command String portion of a Command Definition. \'twander\' provides a Built-In Variable, [HASH], for exactly this purpose. -See the section on Built-In Variables below for a more complete -description. +See the section below entitled, +.B Variables And Command Definitions, +for a more complete description. + .SS Program Option Statements -\'twander\'s internal program defaults are highly configurable. For a -detailed explanation on how this is done, see the section below -entitled, -.B SETTING PROGRAM OPTIONS. +Many of \'twander\'s internal program defaults can be overriden in the +Configuration File using Program Option statements. These statements +look just like User-Defined variables except \'twander\' recognizes +the variable name as a program option rather than an arbitrary +variable. Program Option Statements thus take the form: + +.nf +Option Name = Option Value +.fi + +The Option Name is case-sensitive and must be entered exactly as +described below. For instance, \'twander\' understands +"AUTOREFRESH" as a program option, but will treat "AutoRefresh" +as a User-Defined Variable. + .SS Key Binding Statements -Key Binding Statements allow you to override the default keyboard -assignments. For a detailed explanation of key binding, see the -section below entitled, -.B CHANGING KEYBOARD BINDINGS. +No program that runs in many operating environments 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. + +This feature is available only for +.B Keyboard Assignments. +Mouse Button Assignments may not be changed by the user. An attempt +to do so in the Configuration File will cause \'twander\' to display a +warning and ignore the offending line. + +It is not difficult to override the default keyboard bindings by +adding entries in the Configuration File. Doing so requires some +familiarity with how Tkinter names keystrokes. Good resources for +learning this exist abundantly on the Internet, among them: + +.nf +http://www.pythonware.com/library/tkinter/introduction/index.htm +http://www.nmt.edu/tcc/help/pubs/lang.html +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-Defined +Variables. This means you can never use one of the program +function names as one of your own variable names.) Key Binding +Statements thus take the form: + +.nf +Program-Function-Name = Tkinter-Keystroke-Name +.fi + +Changing the default bindings is therefore nothing more than a matter +of assigning the appropriate Program Function Name (found in +parenthesis next to the description in the default descriptions above) +to the desired keystroke. + +Examples of all the default key bindings are shown as comments in the +".twander" example Configuration File supplied in the program +distribution. The easiest way to rebind a particular function is to +uncomment the relevant line and change the right side of the +assignment to the new key you'd like to use. More detailed +instructions on what to do are found in the example ".twander" file +itself. + +It is important to observe several rules when rebinding keys: + +.IP \(bu 4 +It is best if keyboard navigation commands are all Control or Function +keys. If you assign a navigation or selection function to a single +keystroke, it may conflict with a user-defined command. If you assign +it to a keypad/special key it may conflict with that key's normal GUI +behavior. + +.IP \(bu 4 +The Tkinter keynames should placed on the right side of the "=" symbol +.B without any quotation marks. + +.nf +So, this is correct: QUITPROG = + +But, this is not: QUITPROG = '' +.fi + +.IP \(bu 4 +The Program Function Name variables (the left side of the assignment) +may not be used as names for your own user-defined variables elsewhere +in the Configuration File. In fact, \'twander\' will never even +recognize such an attempt. For example, suppose you try to do this: + +.nf +QUITPROG = something-or-other +.fi + +Because you want to be able to reference [QUITPROG] in a subsequent +Command Definition. \'twander\' will actually interpret this as just +another key binding command, in this case binding the program function +QUITPROG to "something-or-other" - probably not what you intended. +Moreover, if you have a Command String somewhere with [QUITPROG] in it, +\'twander\' will declare and error and abort because it has no +User-Defined variable of that name in its symbol table. + +.IP \(bu 4 +When you're done making changes to the Configuration File, be sure to +either restart the program or reload the Configuration File to assign +the new bindings. + +.IP \(bu 4 +Be aware that \'twander\' does no sanity testing on the assignments +you change. If you assign a particular \'twander\' function to +an illegal or silly key string, the program will probably blow-up +spectacularly. At the very least, that program feature will probably +be unusable, even if \'twander\' manages to run. -.SH \'twander\' VARIABLES AND COMMAND DEFINITIONS +.SS Directory Shortcut Statements + + + +.SS Variables And Command Definitions \'twander\' provides a fairly simple but powerful macro language. This language is how you "program" @@ -1231,8 +1385,13 @@ selected item from the GUI to your command when the command actually gets run. -\'twander\' has a small, but rich set of Built-In Variables -for use in your Command Definitions: +.SS Selection-Related Built-Ins + +\'twander\' has a rich set of Built-In Variables for use in your +Command Definitions. The first group of these is used to convey your +current directory and items which you've selected to a Command +Definition: + .IP \(bu 4 .B [DIR] @@ -1258,19 +1417,6 @@ items currently selected in the GUI. .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] 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] [SELECTION] is replaced with the name of the currently @@ -1288,6 +1434,24 @@ items currently selected in the GUI. The path to those names is not included. +.SS Prompting And Special-Purpose Built-Ins + +There are also several special-purpose Built-In Variables which are used +for creating more powerful Command Definitions: + +.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] 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 [PROMPT:Prompt-String] @@ -1312,9 +1476,42 @@ C Win32CP [Win32Copy] [DSELECTIONS] [PROMPT:Enter Destination] .fi +.IP \(bu 4 +.B [YESNO:Question-String] -.P -A few other points about Built-In Variables are worth noting: +[YESNO:...] allows you to prompt the user with a dialog containing a +Yes/No question and buttons for their response. If the user presses +"Yes", command interpretation/execution continues. If the user +presses "No", the command is aborted. This is handy when you want to +make sure the user really wants to run the command before continuing. +For instance, suppose you define a recursive file/directory deletion +command. Before running it, it's good to prompt the user to confirm +their intentions: + +.nf +D BigDelete [YESNO:Are You Absolutely Sure About This?] rm -rf [SELECTIONS] +.fi + +.SS Program Memory Built-Ins + +As described previously, \'twander\' implements an advanced notion of +a Clipboard called "Program Memories". There is a corresponding group +of Built-In Variables which allows the contents of these memories to +be used in a Command Definition: + +.IP \(bu 4 +.B [MEM1] - [MEM12] + +Return the file/directory names currently stored in the indicated memory. +For example, to move all the files/directories currently named in +the first Program Memory to the current directory we could define +a move command like this: + +.nf +m move mv [MEM1] ./ +.fi + +.SS Notes On Built-In Variable Use .IP \(bu 4 Built-In Variables which return a directory name do @@ -1401,123 +1598,6 @@ and then the command will run. -.SH SETTING PROGRAM OPTIONS - -Many of \'twander\'s internal program defaults can be overriden in the -Configuration File using Program Option statements. These statements -look just like User-Defined variables except \'twander\' recognizes -the variable name as a program option rather than an arbitrary -variable. Program Option Statements thus take the form: - -.nf -Option-Name = Option-Value -.fi - - -.SH CHANGING KEYBOARD BINDINGS - -No program that runs in many operating environments 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. - -This feature is available only for -.B Keyboard Assignments. -Mouse Button Assignments may not be changed by the user. An attempt -to do so in the Configuration File will cause \'twander\' to display a -warning and ignore the offending line. - -It is not difficult to override the default keyboard bindings by -adding entries in the Configuration File. Doing so requires some -familiarity with how Tkinter names keystrokes. Good resources for -learning this exist abundantly on the Internet, among them: - -.nf -http://www.pythonware.com/library/tkinter/introduction/index.htm -http://www.nmt.edu/tcc/help/pubs/lang.html -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-Defined -Variables. This means you can never use one of the program -function names as one of your own variable names.) Key Binding -Statements thus take the form: - -.nf -Program-Function-Name = Tkinter-Keystroke-Name -.fi - -Changing the default bindings is therefore nothing more than a matter -of assigning the appropriate Program Function Name (found in -parenthesis next to the description in the default descriptions above) -to the desired keystroke. - -Examples of all the default key bindings are shown as comments in the -".twander" example Configuration File supplied in the program -distribution. The easiest way to rebind a particular function is to -uncomment the relevant line and change the right side of the -assignment to the new key you'd like to use. More detailed -instructions on what to do are found in the example ".twander" file -itself. - -It is important to observe several rules when rebinding keys: - -.IP \(bu 4 -It is best if keyboard navigation commands are all Control or Function -keys. If you assign a navigation or selection function to a single -keystroke, it may conflict with a user-defined command. If you assign -it to a keypad/special key it may conflict with that key's normal GUI -behavior. - -.IP \(bu 4 -The Tkinter keynames should placed on the right side of the "=" symbol -.B without any quotation marks. - -.nf -So, this is correct: QUITPROG = - -But, this is not: QUITPROG = '' -.fi - -.IP \(bu 4 -The Program Function Name variables (the left side of the assignment) -may not be used as names for your own user-defined variables elsewhere -in the Configuration File. In fact, \'twander\' will never even -recognize such an attempt. For example, suppose you try to do this: - -.nf -QUITPROG = something-or-other -.fi - -Because you want to be able to reference [QUITPROG] in a subsequent -Command Definition. \'twander\' will actually interpret this as just -another key binding command, in this case binding the program function -QUITPROG to "something-or-other" - probably not what you intended. -Moreover, if you have a Command String somewhere with [QUITPROG] in it, -\'twander\' will declare and error and abort because it has no -User-Defined variable of that name in its symbol table. - -.IP \(bu 4 -When you're done making changes to the Configuration File, be sure to -either restart the program or reload the Configuration File to assign -the new bindings. - -.IP \(bu 4 -Be aware that \'twander\' does no sanity testing on the assignments -you change. If you assign a particular \'twander\' function to -an illegal or silly key string, the program will probably blow-up -spectacularly. At the very least, that program feature will probably -be unusable, even if \'twander\' manages to run. - - .SH ADVANCED WIN32 FEATURES As shipped from the factory, \'twander\' runs pretty much identically