diff --git a/twander.1 b/twander.1 index ebea098..d1fb809 100644 --- a/twander.1 +++ b/twander.1 @@ -410,6 +410,13 @@ This is a shortcut that allows you to directly move to a new directory/path - i.e., Without having to navigate to it. +Unless you have set the MAXDIR option to 0, CHANGEDIR keeps track of +your last manually entered directory and presents it as a default when +you press CHANGEDIR again. You can then move to that directory, edit +the string to specify another directory, or delete it and enter an +entirely new directory. Directories can be edited with either the +arrow and keypad keys defined on your system or by emacs editing +commands like Control-a, Control-k, Control-e, and so forth. .TP .B Go To Home Directory (DIRHOME) @@ -572,6 +579,46 @@ It is more-or-less like having a miniature command line environment at your disposal. +You may enter a number of different things in the RUNCMD dialog. You +may type literal text or refer to any of the variable types +(User-Define, Environment, or Built-In) supported by \'twander\' just +as you do in writing Command Definitions (see below). This makes +it easy to enter complex commands without having to type everything +literally. For example, if you would like to copy all the currently +selected files to a new directory, press RUNCMD and enter (on Unix): + +.nf +cp [SELECTIONS] newdir +.fi + +\'twander\' understands the variable reference syntax here just as it +does in a Command Definition. This is also real handy so you don't +have to remember the exact syntax for environment variables (and how +it differs) across Unix and Win32. Assuming the EDITOR environment +variable is set, for example, this command works the same on both +systems: + +.nf +[$EDITOR] [SELECTIONS] +.fi + +Unless you have set the MAXHIST option to 0, RUNCMD keeps track of +your last manually entered command and presents it as a default when +you press RUNCMD again. You can then run the command again exactly +as you last entered it, you can modify it before running the command +again, or you can delete it and enter an entirely new command. Commands +can be edited with either the arrow and keypad keys defined on your +system or by emacs editing commands like Control-a, Control-k, +Control-e, and so forth. + +Also see the section below entitled, +.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 +handy on Unix. + + .TP .B Run Selected File / Move To Selected Directory (SELKEY and MOUSESEL) .PD 000 @@ -615,9 +662,16 @@ .SH MENU OPTIONS Although \'twander\' is primarily keyboard-oriented, several -menu-based features are also implemented to make the program -more convenient to use. These menus appear at the top of the -\'twander\' display window, above the directory listing. +menu-based features are also implemented to make the program more +convenient to use. These menus appear at the top of the \'twander\' +display window, above the directory listing. + +A menu can be invoked in one of several ways. You can click on it, +you can press its associated "Accelerator Key" combination, or you can +use the "Mouse Shortcut" to cause a copy of the menu to pop-up near +the mouse pointer. The Accelerator Keys are shown in +parenthesis next to the menu names below and the Mouse Shortcuts are +similarly shown below in square brackets. The first item in each menu is a dashed line ("----") which indicates that it is a "tearoff" menu. Clicking on the dashed line will detach @@ -627,7 +681,16 @@ instances of these menus if you'd like copies of them at several locations on the screen simultaneously. -.SS Commands Menu +On Win32 systems, if a menu gets too long to physically fit on screen, +up- and down- scrolling arrows automatically appear at the top- +and bottom of the menu respectively. This is not a feature of the +Unix Tk implementation, so menus which grow too large are simply +truncated to fit the screen on Unix-like systems. As described in +the following paragraphs, \'twander\' provides some options to +limit the size of the Directory and History menus especially, for this +reason. + +.SS Commands Menu (Alt-c) [Right-Mouse-Button] Every command defined in the Configuration File is listed in this menu by its Command Name. The association Command Key is also shown in @@ -644,7 +707,7 @@ be opened for some reason, the Commands Menu will be disabled (grayed out). -.SS Directories Menu +.SS Directories Menu (Alt-d) [Shift-Right-Mouse-Button] \'twander\' keeps track of every directory visited. The previously described command to move "Back" one directory allows directory navigation @@ -659,16 +722,110 @@ navigate to it again, back up to it, or name it explictly using the Change Directory command. +There are two user-settable options associated with the Directory +Menu. MAXDIR specifies the maximum number of visited directories +to +.B display in the menu. +This defaults to 32 as is intended as a way to keep the menu +size reasonable. If you set MAXDIR=0, it means you are +disabling this menu feature altogether as well as disabling +the tracking of the last manually entered directory via +the CHANGEDIR key (default: Control-x). + +MAXDIRBUF specifies how many directories \'twander\' keeps track +of internally, no matter how many are actually displayed. It defaults +to 250. + +In summary, the Directory Menu shows the last MAXDIR directories +visited in alphabetically sorted order (unless you change MAXDIRBUF to +be smaller than MAXDIR). "Visited", in this case, is stretching things +a bit. All Directory Shortcut (see below) locations are preloaded into +the Directory Menu when the program starts even though they have not +yet actually been visited. + +The Directory Menu is emptied and grayed out when you press the +CLRHIST key (default: Control-y). + +.SS History Menu (Alt-h) [Shift-Control-Right-Mouse-Button] + +\'twander\' keeps track of every command you attempt to execute, +whether it is an invocation of a Command Definition found in the +Configuration File or a manually entered command via the RUNCMD key +(default: Control-z). This is done whether or not the command is +successfully executed. + +This feature provides a quick way to re-execute a command you've +previously run. When you select a command to run this way, +a dialog box is opened, giving you an opportunity to edit +the command before running it again. + +There are two user-settable options associated with the History +Menu. MAXHIST specifies the maximum number of previously run commands +to +.B display in the menu. +This defaults to 32 as is intended as a way to keep the menu +size reasonable. If you set MAXHIST=0, it means you are +disabling this menu feature altogether as well as disabling +the tracking of the last manually entered command via +the RUNCMD key. + +MAXHISTBUF specifies how many previously-run commands \'twander\' +keeps track of internally, no matter how many are actually displayed. +It defaults to 250. + +One other point of clarification is in order here. If you run +one of the commands defined in your Configuration File, it is +stored in the History +.B after all variable substitutions have been made. +But, manually entered commands are stored in the History +.B literally as typed - +i.e., Without variable substitution. This allows you easily reuse a +manually entered command in another directory or context. +(Presumably, Command Definitions in the Configuration File are written +in such a way so as to be useful across many different directories and +contexts. Running such a command again is simply a matter of pressing +its associated letter key once more. By storing the resolved version +of the command in the History, you can see what such a command +actually did.) + + +The History Menu is emptied and grayed out when you press the +CLRHIST key (default: Control-y). + +.SS Help Menu (Alt-l) [No Mouse Shortcut] + +This menu provides information about various internal settings of +\'twander\' including User-Defined Variables, Command Definitions, +Internal Program Variables, User-Settable Options, Keyboard +Assignments, and Directory Shortcuts. It also has an About feature +which provides version and copyright information about the program. + +For the most part, this help information should fit on screen easily. +However, very long Command Definitions will probably not fit on-screen +once User-Defined and Environment Variables have been substituted. In +this case, if you are curious about just how \'twander\' is +interpreting your Command Definitions, invoke the program with the +relevant debug bit turned on and watch the output on stdout as +\'twander\' runs. + + +.SH THE \'twander\' CONFIGURATION FILE + +Much of \'twander\'s flexibility comes from the fact that it is +a +.B macro-programmable user interface. +The program itself does little more than provide a way to navigate +around a filesystem. It must be configured (programmed) to actually +do something with the files you specify. This is done via a +"Configuration File". This file is also used to set program options +and change keyboard assignments. Although the program will run +without a Configuration File present, it will warn you that it is +doing so with no commands defined. + + .SH LOCATION OF CONFIGURATION FILE -\'twander\' needs a Configuration File in order to define commands -available to the user. Although the program will run without a -Configuration File present, it will warn you that it is doing so with -no commands defined. Not only are commands defined in this -Configuration File, but keyboard bindings can optionally be assigned -(changed from their defaults) in this file. - By default, the program expects to find configuration information in .B $HOME/.twander but you can override this with the -c command line option. (Recommended @@ -704,13 +861,16 @@ cross into the next line. Whitespace is ignored within a line as are blank lines. -There are only four possible legal lines in a \'twander\' -Configuration File: Comments, User-Defined Variables, Key Binding -Statements 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. +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. This is both true when the program initially loads as well as during any subsequent Configuration File reloads initiated from the keyboard @@ -737,15 +897,48 @@ See the section on Built-In Variables below for a more complete description. -.SS User-Defined Variables +.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. + +.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. + + +.SH \'twander\' VARIABLES AND COMMAND DEFINITIONS + +\'twander\' provides a fairly simple but powerful +macro language. This language is how you "program" +the interface and equip it with commands of your +own choosing. Command Definitions are built +out of literal text and may also have any combination +of three variable types: User-Defined Variables, +Environment Variables, and Built-In Variables. + +.SS User-Defined Variables And Environment Variables User-Defined Variables are defined using the syntax: .nf Variable-Name = Replacement-String +.fi -For example, +Environment Variables are referenced using the syntax: +.nf +[$VARIABLE] +.fi + +Say we have a configuration line like this, + +.nf EDITOR = emacs blah blah blah blah .fi @@ -755,6 +948,14 @@ .B referring to a previously defined variable. +Similarly, suppose you have an environment variable called "EDITOR" +which indicates your preferred editing program. Our definition +could thus become: + +.nf +EDITOR = [$EDITOR] blah blah blah blah +.fi + Why bother with this? Because it makes maintaining complex Configuration Files easier. If you look in the example ".twander" Configuration File provided in the program distribution, you will see @@ -895,14 +1096,6 @@ Definitions) or one of the Program Function Names (used for Key Bindings). -.P -.SS Key Binding Statements - -Key Binding Statements look just like User-Defined Variables. The -\'twander\' parser automatically figures out which is which. For a -detailed explanation of key binding, see the section below entitled, -.B CHANGING KEYBOARD BINDINGS. - .SS Command Definitions The heart of the \'twander\' configuration process is creating @@ -1208,6 +1401,19 @@ 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 @@ -1240,10 +1446,10 @@ 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 -variable definitions. 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: +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