diff --git a/twander.1 b/twander.1 index e48387e..e57dfd3 100644 --- a/twander.1 +++ b/twander.1 @@ -1,8 +1,10 @@ .TH twander 1 "TundraWare Inc." + .SH NAME twander \- File Browser + .SH OVERVIEW Wander around a filesystem executing commands of your choice on selected files and directories. If you're new to \'twander\' and want @@ -16,8 +18,9 @@ .B INSTALLING \'twander\' which describes how the program should be installed. + .SH SYNOPSIS -twander [-bcdfhnqrstvwxy] [startdir] +twander [-cdhqrstv] [startdir] .SH OPTIONS .TP @@ -28,47 +31,56 @@ will display an error message and abort. .TP -.B -b backcolor -Desired background color. (default: black) - -.TP -.B -c path/name of configuration file +.B -c path/name of Configuration File Specify the location and name of the configuration file. (default is ~/.twander) If this file does not exist or cannot be opened, \'twander\' will display a warning to that effect but continue to run. This is reasonable behavior because \'twander\' provides a command to reload -the configuration file without exiting the program (which you would -presumably do after fixing the configuration file problem). +the Configuration File without exiting the program (which you would +presumably do after fixing the Configuration File problem). .TP -.B -d -Start in debug mode. (default: debug off) +.B -d debuglevel +Start in debug mode dumping the items specified in the debuglevel. +(default: debuglevel=0/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. The 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 variable substitution (User-Defined, -Environment, and Built-Ins) has been done. +\'twander\' is able to selectively dump debugging information to +stdout. \'debuglevel\' is understood to be a bitfield in which +each bit specifies some kind of debugging information or +behavior. \'debuglevel\' can be specified in either decimal +or hex (using the form 0x#) formats. The bits in the bitfield +are defined as follows: -.TP -.B -f forecolor -Desired foreground color. (default: green) +.nf +Bit Hex Value Meaning +--- --------- ------- + +0 0x001 Dump Internal Options & User-Settable Options +1 0x002 Dump User-Defined Variables +2 0x004 Dump Command Definitions +3 0x008 Dump Key Bindings +4 0x010 Display, Do Not Execute, Commands When Invoked +5 0x020 Dump Directory Stack As It Changes +6 0x040 Dump Command History Stack After Command Executes +7 0x080 Dump Contents Of Program Memories As They Change +8 0x100 Reserved/Unused +9 0x200 Reserved/Unused +10 0x400 Reserved/Unused +11 0x800 Dump Requested Debug Information And Exit Immediately +.fi + +These bits can be combined to provided very specific debugging +information. For example, \'-d 0x80f\' will dump (to stdout) all the +Internal Options, User-Settable Options, User-Defined Options, Command +Definitions, and Key Bindings and then terminate the program. .TP .B -h Print help information on stdout. .TP -.B -n fontname -Name of desired font family. (e.g., courier, times, helvetica) (default: courier) - -.TP .B -q Quiet mode - suppresses warnings. (default: warnings on) @@ -87,16 +99,13 @@ assignment is to the Control-l key). .TP -.B -s fontsize -Font size in points. (default: 12) - -.TP .B -t 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) in a command, it will replace them with +variables which do string replacement (DIR, DSELECTION, DSELECTIONS, +MEM1-12, PROMPT:, SELECTION, SELECTIONS) in a command, 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 @@ -107,17 +116,56 @@ .B -v Print detailed version information. -.TP -.B -w fontweight -One of: bold, italic, underline, overstrike. (default: bold) -.TP -.B -x width -Set window width. (default: 90) +.SH OTHER WAYS TO SET \'twander\' OPTIONS -.TP -.B -y width -Set window width. (default: 25) +In addition to these command line options, there are two other ways +you can set \'twander\' program features. If you prefer, you +can set the command line options via the environment variable, +TWANDER. That way you don't have to type them in each time you +start the program. Say you set the environment variable this way +on Unix: + +.nf +export TWANDER=-qt +.fi + +From then on, every time you run the program, the -q and -t options +would be invoked (No Quoting, No Warnings) just as if you had typed +them in on the command line. + +The second way to set these (and MANY more) program options is +by setting the appropriate entries in the Configuration File. This +is covered later in this document. + +\'twander\' evaluates options in the following order (from first +to last: + +.IP \(bu 4 +Internally set default value of options + +.IP \(bu 4 +Options set in the Configuration File + +.IP \(bu 4 +Options set in the TWANDER environment variable + +.IP \(bu 4 +Options set on the command line + + +This means, for example, that the environment variable overrides a +corresponding setting in the Configuration File, but the command line +overrides the environment variable. Furthermore, there are many +program options which can +.B only +be set/changed the Configuration File and are not available in +either the environment variable or on the command line. + +Reloading the Configuration File (see READCONF below) causes this +4-step assessment to take place again, thereby allowing \'twander\' to +reflect any changes made in the configuration. + .SH KEYBOARD USE @@ -125,9 +173,9 @@ using only the keyboard. Various \'twander\' features are thus associated with particular keystrokes which are described below. It is also very simple to change the default key assignments with entries -in the configuration file, also described below. +in the Configuration File, also described below. -.SH A NOTE ON KEYBOARD ARROW AND KEYPAD BEHAVIOR +.SH NOTES ON KEYBOARD ARROW/KEYPAD BEHAVIOR AND TEXT DIALOG EDITS Generally, the arrow and keypad keys should do what you would expect on the system in question. On Win32 systems, particularly, there ought @@ -141,6 +189,18 @@ do nothing, or do strange things, look into your key maps, don't blame \'twander\'. +There are several features of \'twander\' than will present the user a +text entry dialog. These include the CHANGEDIR and RUNCMD features as +well as the [PROMPT:...] Built-In Variable (all described below). + +Any time you are entering text in such a dialog, be aware that the +text can be edited several ways - You can edit it using the +arrow/keypad editing assignments which are enabled/normal for your +operating system, OR you can use emacs- style commands to edit the +text. For instance, Control-a, Control-k will erase the text +currently entered in the dialog. + + .SH DEFAULT KEYBOARD AND MOUSE BINDINGS Here, ordered by category, are the default keyboard and mouse @@ -162,12 +222,24 @@ section entitled, .B CHANGING KEYBOARD BINDINGS. +It is important to realize that \'twander\' key-bindings are +.B case-sensitive. +This means that \'Control-b\' and \'Control-B\' are different. +This was a conscious design decision because it effectively +doubles the number of Control/Alt key combinations available +for the addition of future features. + +The default bindings chosen for \'twander\' features are all currently +.B lower-case. +If your program suddenly stops responding to keyboard commands, +check to make sure you don't have CapsLock turned on. + .B NOTE: Some \'twander\' features are doubled on the mouse. These mouse button assignments are documented below for the sake of completeness. However, .B mouse button assignments cannot be changed by the user, -even in the configuration file. +even in the Configuration File. .SS GENERAL PROGRAM COMMANDS @@ -175,20 +247,68 @@ This family of commands controls the operation of \'twander\' itself. .TP -.B Display Context Menu (MOUSECTX) +.B Clear History (CLRHIST) +Control-y + +Clears out various program histories including the All Directory list, +the Directory Stack, the Command History, and the last +manually-entered values for CHANGEDIR and RUNCMD. The 12 Program +Memories are not cleared - they have specially dedicated key bindings +for this purpose. + +.TP +.B Decrement Font Size (FONTDECR) +Control-[ + +Decrease font size. + +.TP +.B Increment Font Size (FONTINCR) +Control-] + +Increase font size. + +These two features allow you to change the display font sizes while +\'twander\' is running. But, you may not immediately get the results +you expect. \'twander\' internally keeps track of separate font +sizes for the main display, the main menu text, and the help menu +text. When you use the two font sizing commands above, \'twander\' +subtracts or adds 1 to each of these three values respectively. On +systems like Win32 using TrueType fonts, this works as you would +expect, because every font is effectively available in every size. +However, in systems like X-Windows or Win32 using fixed-size fonts, +you may have to press these keys repeatedly until \'twander\' finds +a font matching the requested size. + +This can also cause some parts of the display to change but not +others. Suppose you are running on X-Windows and have specified that +the main display is use a 12 point font, and that menus and help +should use 10 point font. Let's also suppose that the next font +available larger than 12 point is 16 point. If you press FONTINCR +twice, both the menu text and help text will jump to 12 point, but the +main display text will remain unchanged. Why? Because pressing +FONTINCR twice tells \'twander\' to set the main display to 14 point +(12+1+1) which does not exist, and the menu and help text to 12 point +(10+1+1) which does exist, so the change is visible. + +Reloading the Configuration File (READCONF) will reset the fonts +to either their default values or any font sizes specified in the +Configuration File. + +.B Display Command Menu (MOUSECTX) Right-Mouse-Button Displays a list of all available commands in a pop-up menu near the mouse pointer. If no commands are defined, this feature does nothing at all. This means commands can be invoked one of three ways: Directly via the -Command Key defined in the configuration file, via selection in the -Command Menu at the top of the GUI, or via selection from the Context +Command Key defined in the Configuration File, via selection in the +Command Menu at the top of the GUI, or via selection from the Command Menu. Win32 users should note that, unlike Windows Explorer, the \'twander\' -Context Menu does not change the set of currently selected items. It +Command Menu does not change the set of currently selected items. It merely provides a list of available commands. This allows the -command chosen via the Context Menu to operate on a previously +command chosen via the Command Menu to operate on a previously selected set of items. .TP @@ -202,6 +322,18 @@ this pop-up menu. .TP +.B Display History Menu (None - Derived internally) +Control-Shift-Right-Mouse-Button + +Displays a list of all commands executed so far, including those +entered manually. If the Command History is empty, this command does +nothing. This means you can repeat a previously entered command via +the History Menu or this mouse command. (You can also repeat +the last manually entered command by pressing RUNCMD - it will +preload its text entry area with the last command you entered by +hand.) + +.TP .B Quit Program (QUITPROG) Control-q @@ -211,13 +343,13 @@ .B Re-Read Configuration File (READCONF) Control-r -Re-read the configuration file. This allows you to edit the -configuration file while \'twander\' is running and then read your +Re-read the Configuration File. This allows you to edit the +Configuration File while \'twander\' is running and then read your changes in without having to exit the program. This is handy when editing or changing command definitions. However, if you edit the -configuration file and introduce an error, \'twander\' will terminate +Configuration File and introduce an error, \'twander\' will terminate when you try to re-read it (just as it will if you try to start the -program with a bad configuration file). +program with a bad Configuration File). .TP .B Refresh Display (REFRESH) @@ -410,7 +542,7 @@ Control-z This is a shortcut that allows you to run any command you'd like -without having to define it ahead of time in the configuration file. +without having to define it ahead of time in the Configuration File. It is more-or-less like having a miniature command line environment at your disposal. @@ -448,11 +580,12 @@ .B Run User-Defined Command User-Defined (Single Letter) Key -Each command defined in the configuration file has a Command Key +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 Although \'twander\' is primarily keyboard-oriented, several @@ -470,18 +603,18 @@ .SS Commands Menu -Every command defined in the configuration file is listed in this 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 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 forgotten. It is also handy to confirm which commands are defined -after you've edited and reloaded the configuration file. The commands +after you've edited and reloaded the Configuration File. The commands are listed in the order in which they are defined in the configuration file. This allows most frequently used commands to appear at the top -of the menu by defining them first in the configuration file. If no -commands are defined, either because the configuration file contains -no Command Definitions or because the configuration file cannot +of the menu by defining them first in the Configuration File. If no +commands are defined, either because the Configuration File contains +no Command Definitions or because the Configuration File cannot be opened for some reason, the Commands Menu will be disabled (grayed out). @@ -500,13 +633,14 @@ navigate to it again, back up to it, or name it explictly using the Change Directory command. + .SH LOCATION OF CONFIGURATION FILE -\'twander\' needs a configuration file in order to define commands +\'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 +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 +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 @@ -517,16 +651,16 @@ ) Actually, \'twander\' can look in a number -of places to find its configuration file. It does this using +of places to find its Configuration File. It does this using the following scheme (in priority order): .IP \(bu 4 If the -c argument was given on the command line, use this argument -for a configuration file. +for a Configuration File. .IP \(bu 4 If -c was not given on the command line, but the HOME environment -variable is set, look for the a configuration file as $HOME/.twander. +variable is set, look for the a Configuration File as $HOME/.twander. .IP \(bu 4 If the HOME environment variable is not set @@ -535,24 +669,25 @@ for a file called ".twander" in the directory from which \'twander\' was invoked. + .SH CONFIGURATION FILE FORMAT -\'twander\' configuration files consist of freeform lines of text. +\'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 only four possible legal lines in a \'twander\' -configuration file: Comments, User-Defined Variables, Key Binding +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. +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. This is both true when the program initially loads as well as during -any subsequent configuration file reloads initiated from the keyboard +any subsequent Configuration File reloads initiated from the keyboard while running \'twander\'. See the ".twander" file provided with the program distribution @@ -561,7 +696,7 @@ .SS Comments A comment is begun with the "#" string which may be placed anywhere on a -line. Comments may appear freely within a configuration file. +line. Comments may appear freely within a Configuration File. \'twander\' strictly ignores everything from the "#" to the end of the line on which it appears without exception. This means that "#" cannot occur anywhere within a User-Defined Variable Definition, Key @@ -595,8 +730,8 @@ to a previously defined variable. 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 +Configuration Files easier. If you look in the example ".twander" +Configuration File provided in the program distribution, you will see this is mighty handy when setting up complex "xterm" sessions, for example. @@ -649,7 +784,7 @@ .fi This recursive definition is a no-no and will be cause \'twander\' -to generate an error while parsing the configuration file and then +to generate an error while parsing the Configuration File and then terminate. Your variable definitions can also nest other kinds of variables @@ -728,7 +863,7 @@ .IP \(bu 4 Variable Names may not be redefined. This means you can only define a -given Variable Name once per configuration file. It is also +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 Built-In Variables (used in Command Definitions) or one of the Program Function Names (used for Key @@ -761,9 +896,9 @@ 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 +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 "#" +Key in a given Configuration File. A Command Key can never be "#" which is always understood to be the beginning of a comment. The @@ -772,7 +907,7 @@ 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 +given Configuration File. That is, two different Command Definitions may have identical Command Names associated with them, though this is not ordinarily recommended. @@ -817,7 +952,7 @@ using the string "xterm -l -e" over and over again for any shell commands we'd like to see run in a new window. Why not create a User-Defined Variable for this string so we can simplify its use -throughout the whole configuration file? Now, our command looks +throughout the whole Configuration File? Now, our command looks like this: .nf @@ -972,7 +1107,7 @@ Earlier releases of \'twander\' .B did include the trailing path separator and you may have to edit -older configuration files accordingly. This change was necessary +older Configuration Files accordingly. This change was necessary because certain commands like Unix \'cp\' will not work if given a source directory with the path separator included.) @@ -1015,7 +1150,7 @@ .IP \(bu 4 User-Defined and Environment Variables are processed -at the time the configuration file is read by \'twander\'. That +at the time the Configuration File is read by \'twander\'. That is, they are handled .B once at load time. @@ -1046,6 +1181,7 @@ 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 @@ -1057,11 +1193,11 @@ 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 +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 +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: @@ -1077,7 +1213,7 @@ 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 +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 @@ -1093,7 +1229,7 @@ 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 +".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 @@ -1122,7 +1258,7 @@ .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 +in the Configuration File. In fact, \'twander\' will never even recognize such an attempt. For example, suppose you try to do this: .nf @@ -1138,8 +1274,8 @@ 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 +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 @@ -1149,6 +1285,7 @@ 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 @@ -1157,7 +1294,7 @@ .B 1) Getting Command Results Displayed In A New Window When you invoke a command via \'twander\', whether via a command -definition in the configuration file or the keyboard shortcut, you +definition in the Configuration File or the keyboard shortcut, you 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 @@ -1182,7 +1319,7 @@ output. This is not a \'twander\' problem, it is innate to how command line programs run under Unix-like shell control. To achieve the desired results, you'll need something like this in your -configuration file: +Configuration File: .nf V view xterm -l -e less [DSELECTIONS] @@ -1216,6 +1353,7 @@ workaround is to manually kill the window or press enter once when the command is complete and the window has input focus. + .SH OTHER You must have Python 2.2 or later installed as well as Tkinter support installed for that release. In the case of Win32, Tkinter is bundled @@ -1224,6 +1362,7 @@ appropriate release of Tkinter. This is the case, for example, with FreeBSD. + .SH BUGS AND MISFEATURES The color options (-b, -f), font options (-n, -s, -w), and size option (-x, -y) are @@ -1235,7 +1374,7 @@ interesting and entertaining error messages. The program could be more gracious about this. -The configuration file parser does no validation of key binding +The Configuration File parser does no validation of key binding override values. It is entirely possible to bind a \'twander\' feature to a bogus key definition. This will cause either a spectacular program failure or, at the very least, that feature will @@ -1246,6 +1385,7 @@ This program has not been tested on MacOS. Please let me know how/if it works there and any issues you discover. + .SH INSTALLING \'twander\' Installation of \'twander\' is fairly simple and takes only a few @@ -1262,7 +1402,7 @@ .SS Installing Using The FreeBSD Port If you've installed \'twander\' using the FreeBSD port, all you have -to do is copy the example configuration file, ".twander" found in +to do is copy the example Configuration File, ".twander" found in /usr/local/share/doc/twander to your home directory and edit it to taste. @@ -1293,19 +1433,19 @@ named this way with the standard Windows programs and utilities. This is especially the case for older Win32 operating systems like Win98. For this reason, it is recommended that you rename the ".twander" -default configuration file provided in the program distribution to +default Configuration File provided in the program distribution to something else like "twander.conf" and use the \'twander\' -c command -line option to point to this configuration file. +line option to point to this Configuration File. -On Win32, where to put the configuration file raises an interesting +On Win32, where to put the Configuration File raises an interesting question. Microsoft operating systems normally do not set the "HOME" environment variable, because they have no notion of a "home" directory - Well, they do, but it is called "USERPROFILE" not "HOME". So, you can either create a new user-specific environment variable called HOME yourself (which points to your desired home directory) or you can invoke \'twander\' with the -c argument to explictly declare -where it can find its configuration file. +where it can find its Configuration File. You can run the program several ways on Win32 systems: @@ -1336,6 +1476,7 @@ 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 @@ -1393,7 +1534,7 @@ .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 +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. @@ -1418,12 +1559,14 @@ (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 install \'twander\' on a FreeBSD system using the 'ports' mechanism, you will also find this file in /usr/local/share/doc/twander. + .SH AUTHOR .nf Tim Daneliuk