diff --git a/twander.1 b/twander.1 index dafc14d..3241ed6 100644 --- a/twander.1 +++ b/twander.1 @@ -14,13 +14,13 @@ toward the end of this document first. Similarly, if this is the first time you've worked with \'twander\', -there is a section towards the end of this document entitled +there is a section near the end of this document entitled .B INSTALLING \'twander\' which describes how the program should be installed. .SH SYNOPSIS -twander [-cdhqrstv] [startdir] +twander [-cdhqrtv] [startdir] .SH OPTIONS @@ -135,7 +135,7 @@ 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 +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. @@ -159,7 +159,7 @@ 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 +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. @@ -231,7 +231,7 @@ The "Program Function Name" is the internal variable \'twander\' uses to associate a particular feature with a particular keystroke or mouse action. You can ignore it unless you intend to override -the default assignments. This use is described below in the +the default key assignments. This use is described below in the section entitled, .B Key Binding Statements. @@ -301,7 +301,7 @@ 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. +(10+1+1) which does exist, so that change is visible. Reloading the Configuration File (READCONF) will reset the fonts to either their default values or any font sizes specified in the @@ -376,8 +376,8 @@ Control-l Re-read the current directory's contents and display it. This is most useful -if you have turned off automatic directory refreshing with the -r command -line flag. +if you have turned off automatic directory refreshing with either the -r command +line flag or setting the AUTOREFRESH Program Option to False. .TP .B Toggle Details (TOGDETAIL) @@ -401,11 +401,10 @@ .SS Directory Navigation -This family of commands controls movement between directories. If at any point, -you attempt to navigate into a directory that does not exist or which -does not have appropriate permissions, \'twander\' will issue an appropriate -message, and remain in the original directory where the request was issued. -This is +This family of commands controls movement between directories. If you +attempt to navigate into a directory that does not exist or which does +not have appropriate permissions, \'twander\' will display a warning +message and remain in the current directory. This is .B unlike the case of a non-existent or unreadable directory specified when the program is first started. In that case, \'twander\' reports the error and aborts. @@ -448,7 +447,7 @@ the directory name from the visited list. The "Directory" menu (see .B MENU OPTIONS below) implements a similar feature in a different way and keeps track of -all directories visited regardless of order, never discarding any entry. +all directories visited regardless of order. .TP .B Go To Root Directory (DIRROOT) @@ -482,7 +481,7 @@ disk drives. Details about each drive are also displayed if you have details enabled. In order for this feature to work, you must be running on Win32 AND have the \'win32all\' package installed, AND the -USEWIN32ALL program option must be True (default condition,) AND you +USEWIN32ALL Program Option must be True (default condition,) AND you must not have toggled these features off with the TOGWIN32ALL key described above. For more details about Drive List View, see the section below entitled, @@ -602,9 +601,9 @@ 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 +(User-Defined, 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): @@ -744,10 +743,10 @@ .B Set Selected Program Memory (MEMSET1 - MEMSET12) Alt-F1 ... Alt-F12 -Append the names of the currently selected files and directories to -the Program Memory desired. More specifically, append -.B the full pathname -of each selected directory or path to that Program Memory. +Append the +.B the full path names +of the currently selected files and directories to the Program Memory +desired. .SH MENU OPTIONS @@ -830,9 +829,9 @@ 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. +a bit. All Directory Shortcut locations are also 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). @@ -908,7 +907,7 @@ 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 +"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. @@ -917,9 +916,10 @@ .SH LOCATION OF CONFIGURATION 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 -for Win32 systems - see the section below entitled, +.B $HOME/.twander +(%HOME%/.twander on Win32) but you can override this with the -c +command line option. (Recommended for Win32 systems - see the section +below entitled, .B INSTALLING \'twander\' ) @@ -1002,7 +1002,7 @@ 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 +the variable name as a Program Option rather than an arbitrary variable. Program Option Statements thus take the form: .nf @@ -1011,16 +1011,18 @@ 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" +"AUTOREFRESH" as a Program Option, but will treat "AutoRefresh" as a User-Defined Variable. .SS Key Binding Statements -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. +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. \'twander\' ships from the factory with a set of default key +bindings, but it also provides a mechanism for changing these bindings +via entries in the Configuration File. This feature is available only for .B Keyboard Assignments. @@ -1288,7 +1290,8 @@ .IP \(bu 4 User-Defined Variables may be .B nested -up to 32 levels deep. You can have constructs like: +up to 32 levels deep (this default can be changed via the +MAXNESTING Program Option). You can have constructs like: .nf Var1 = Foo @@ -1410,10 +1413,11 @@ 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. +given Configuration File. If \'twander\' finds multiple Command +Definitions assigned to the same Command Key, it will warn you and +ignore everything except the first definition. A Command Key can +never be "#" which is always understood to be the beginning of a +comment. The .B Command Name @@ -1441,8 +1445,9 @@ .fi This command can be invoked pressing the "m" key on the keyboard or -selecting the "MyMore" entry from the Command Menu. Either way, -\'twander\' will then execute the command, "more somefile". +selecting the "MyMore" entry from the Command Menu - either directly +from the menu or from the Command Menu Pop-Up. No matter how it is +invoked, \'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 (...well, on X-Windows - is does work on Win32 @@ -1535,23 +1540,21 @@ .IP \(bu 4 .B [DIR] -[DIR] is replaced with the current directory which \'twander\' +[DIR] is replaced with the current directory \'twander\' is viewing. .IP \(bu 4 .B [DSELECTION] -[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 (the bottom-most, not the most recent item -you selected). +[DSELECTION] is replaced with the full 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 (the bottom-most, not the most +recent item you selected). .IP \(bu 4 .B [DSELECTIONS] -[DSELECTIONS] is replaced with the fully-qualified path -name of +[DSELECTIONS] is replaced with the full path name of .B all items currently selected in the GUI. @@ -1588,8 +1591,8 @@ 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. +Command String (regardless of whether the -t command argument is used +or how the QUOTECHAR Program Option is defined). .IP \(bu 4 .B [PROMPT:Prompt-String] @@ -1721,7 +1724,9 @@ 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\'. +-t command line option when starting \'twander\'. You can also +suppress quoting by redefining the QUOTECHAR Program Option described +previously. .IP \(bu 4 Any of the variable types may appear multiple times in the @@ -1772,10 +1777,11 @@ 2000 and Windows XP. Earlier versions of Windows like Win98 and WinME emulate portions of the Win32 API and do not implement the advanced security features found in the NTFS file system. Therefore, as noted -below, most of these features will not work on any of the older 16-bit +below, some of these features will not work on any of the older 16-bit Windows operating systems. \'twander\' handles this gracefully without blowing-up so you can safely have \'win32all\' installed on -one of these older systems. +one of these older systems to take advantage of the features that +do work. Once you have these extensions installed, \'twander\' will automatically enable three new features otherwise unavailable. @@ -1867,9 +1873,9 @@ pressing the REFRESH key (default: Control-l). .IP \(bu 4 -The TOGWIN32ALL key (default: Control-w) is disabled in -Drive List View. This view is only available in \'win32all\' -mode and toggling it off makes no sense here. +The TOGWIN32ALL key (default: Control-w) is disabled in Drive List +View. Drive List View is only available in \'win32all\' mode and +toggling that mode off makes no sense here. .IP \(bu 4 The SELALL (default: Control-comma) and SELINV (default: Control-i) @@ -1919,10 +1925,10 @@ (Note the backticks used to execute the \'hostname\' program and assign its results to HOSTNAME.) -Be aware that \'bash\' claims to set this variable when it -starts, but it does not appear to export it properly. Programs -started from \'bash\' do not see HOSTNAME set, so you have -to do this manually as just described even when using \'bash\' +Be aware that \'bash\' claims to automatically set this variable when +it starts. However, it does not appear to export it properly on some +systems (noted on FreeBSD 4.7 with \'bash\' 2.05b). In this case, you +have to do this manually as just described even when using \'bash\' On Win32, environment variables are set via the System Properties menu. @@ -1984,10 +1990,10 @@ from a GUI or disconnected it from the initiating terminal with a \'nohup\' ... & invocation, you will get .B no -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: +output. This is not a \'twander\' problem, it is innate to how +command line programs run under Unix shell control. To achieve the +desired results, you'll need something like this in your Configuration +File: .nf V view xterm -l -e less [DSELECTIONS] @@ -2057,19 +2063,44 @@ .SH BUGS AND MISFEATURES +As of this release, a number of problems relating to \'twander\' +use have been noted: +.IP \(bu 4 The Configuration File parser does no validation to check the sanity -of its various entries for Command Definitions, Key Bindings, Options, -and Directory Shortcuts. It is entirely possible to edit something -into this file that makes no sense at all and causes \'twander\' -to misbehave. +of its various entries for Program Options, Key Bindings, Directory +Shortcuts, Variable Definitions, and Command Definitions. It is +entirely possible to edit something into this file that makes no sense +at all and causes \'twander\' to misbehave. +.IP \(bu 4 There appears to be a Tkinter/Tk bug on Unix which sometimes inhibits the correct title display when you tear-off a menu. This is a -cosmetic defect and may disappear as future releases of -Tkinter/Tk/X-Windows appear. +cosmetic defect and may disappear in future releases of +Tkinter/Tk/X-Windows. -This program has not been tested on MacOS. Please let me know how/if +.IP \(bu 4 +Some \'win32all\' features do not work correctly or at all on +older Windows OSs. For example, the free/total space available in the +Drive List View has been noted to display incorrect values on Win98. +Similarly, the owner and group names are displayed as "Unavailable" on +pre-NTFS file systems. These are OS limitations which \'twander\' +handles gracefully. + +.IP \(bu 4 +If you are using \'bash\' as your Unix shell, be aware that, +although it sets HOSTNAME automatically, this environment variable +appears to not be exported consistently on all systems. + +.IP \(bu 4 +If you are running Win32 and have file or directory names with +non-ASCII characters in them, you must configure Python to +properly deal with such characters. This is described above in +the section entitled, +.B GOTCHAS. + +.IP \(bu 4 +This program has not been tested on MacOS. Please let us know how/if it works there and any issues you discover. @@ -2107,7 +2138,7 @@ To run the program, just type "twander.py" from a shell prompt. .B Red Hat Linux Users Please Note: -RH Linux (and possibly other Linux systems) install two versions of +RH Linux (and possibly other Linux systems) installs two versions of Python. Version 1.52 is called \'python\', and Version 2.2 is called \'python2\'. \'twander\' requires the latter and will not run on the former. As shipped, \'twander\' invokes Python with the Unix shell @@ -2132,12 +2163,12 @@ to \'python2\' instead of \'python\'. .P -Red Hat users who have upgraded from earlier versions should +Red Hat users who have upgraded from earlier Linux versions should also note that you may have files in your home directories owned by -owners and groups which are not defined in the system! \'twander\' -shows the owner and group fields for such files as numbers rather than -names. As best as we can determine, this is caused when an RH -installation is updated from an older version. +owners and groups which are no longer defined in the system! +\'twander\' shows the owner and group fields for such files as numbers +rather than names. As best as we can determine, this is caused when +an RH installation is updated from an older version. .SS Installing Manually On A Win32 System @@ -2300,10 +2331,11 @@ .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. +\'twander\' is Copyright(c) 2002-2003 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