diff --git a/twander.1 b/twander.1 index e57dfd3..6415046 100644 --- a/twander.1 +++ b/twander.1 @@ -196,7 +196,7 @@ 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 +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. @@ -295,6 +295,7 @@ to either their default values or any font sizes specified in the Configuration File. +.TP .B Display Command Menu (MOUSECTX) Right-Mouse-Button @@ -325,13 +326,13 @@ .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.) +Displays a list of all commands executed so far (including those +entered manually) in a pop-up menu near the mouse pointer. 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) @@ -346,7 +347,7 @@ 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 +editing or changing Command Definitions. However, if you edit the 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). @@ -365,6 +366,15 @@ Toggle between detailed and filename-only views of the directory. +.TP +.B Toggle \'win32all\' Features (TOGWIN32ALL) +Control-w + +As described later in this document, \'twander\' provides enhanced +features for Win32 users who also install Mark Hammond's \'win32all\' +extensions for Python on Win32. This key binding will toggle those +advanced features on- and off. + .SS DIRECTORY NAVIGATION @@ -819,7 +829,7 @@ Var3 = bar MyVar = [Var1][Var2] -# Now comes the command definition +# Now comes the Command Definition # If we put this before the Variable Definitions above, # it would be an error. @@ -1013,7 +1023,7 @@ actually gets run. \'twander\' has a small, but rich set of Built-In Variables -for use in your command definitions: +for use in your Command Definitions: .IP \(bu 4 .B [DIR] @@ -1266,7 +1276,7 @@ .fi Because you want to be able to reference [QUITPROG] in a subsequent -command definition. \'twander\' will actually interpret this as just +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, @@ -1286,6 +1296,163 @@ be unusable, even if \'twander\' manages to run. +.SH ADVANCED WIN32 FEATURES + +As shipped from the factory, \'twander\' runs pretty much identically +on various Unix variants (FreeBSD, Linux) and Win32. However, +\'twander\' is written to take advantage of Mark Hammond's +\'win32all\' Python extensions if they are present on the system. +These extensions add many Windows-specific features to Python +and allow \'twander\' to provide quite a bit more Windows-centric +information about files, directories, and drives. You do +.B not +have to install \'win32all\' for \'twander\' to operate properly +on your Win32 system. Installing this package just means you'll +get even more \'twander\' features on Win32 than you would otherwise. +If you've installed \'win32all\', you can toggle these features +on- and off with the TOGWIN32ALL key described above. + +.SS Getting \'win32all\' + +You can get the \'win32all\' extensions one of two ways. If you've +installed the Active State version of Python for Win32, +(http://www.activestate.com/Products/ActivePython/) \'win32all\' is +already installed on your system. If you installed the standard +Python release for Win32 +(http://www.python.org/download/download_windows.html), you must add +\'win32all\' to your installation. You'll find the extensions and +painless installation instructions at: +http://starship.python.net/crew/mhammond/ + +.SS New Features Supported With \'win32all\' + +One important note is in order here: The features enabled by +\'win32all\' are only available on "true" Win32 systems like Windows +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 +Windows operating systems. \'twander\' handles this gracefully +without blowing-up so you can safely have \'win32all\' installed on +one of these older systems. + +Once you have these extensions installed, \'twander\' will +automatically enable three new features otherwise unavailable. + +.IP \(bu 4 +When viewing file/directory detail information, the owner and group +names will be the actual names reported by the operating system rather +than the filler values normally seen in those fields (\'win32owner\' +and \'win32group\'). (Does not work on older Windows systems like +Win98.) + +.IP \(bu 4 +Instead of showing Unix-style file permissions (which don't mean much +under Win32), systems with \'win32all\' installed will show the +so-called "file attributes" maintained by the operating system. Each +detailed entry in the display will have one or more of the following +attributes displayed in what is normally the Unix permissions field: + +.nf +d - Directory +A - Archive +C - Compressed +H - Hidden +N - Normal +R - Read-Only +S - System +.fi + +.IP \(bu 4 +A top-level "Drive List View" is enabled if \'win32all\' is installed. +This shows you a list of all currently available drives reachable by +the system, and information about those drives. For locally attached +drives, the drive label is shown. For network-attached drives, the +share string is shown. The drive type (CD/DVD, Fixed, Ramdisk, +Remote, Removable) is shown as are the free/total space statistics. +As is the case with other \'twander\' displays, these details can be +toggled on- and off via the TOGDETAIL key. + +You can enter the Drive List View in a number of ways: + +.nf +1) Select the ".." from the root directory of any drive. +2) Enter the string "\\\\" from the CHANGDIR dialog. +3) Press the DRIVELIST key (default: Control-k). +4) Start \'twander\' using "\\\\" as the starting directory + argument, either on the command line or using the + Configuration File STARTDIR option. +.fi + +The "Drive List View" is available on all Win32 variants, however the +free/total space values will be incorrect on older systems like Win98. + +.SS Notes On Drive List View + +The Drive List View is a little different than the usual +file/directory view. Program behavior (semantics) is thus also slightly +different than usual in several ways: + +.IP \(bu 4 +While in Drive List View, the various Built-In Variables which return +the current selections will return +.B the name or names of the selected drive(s) +(without a trailing slash) just as you would expect them to +in a normal file/directory view. This allows you to write +commands which take drive names (letters) as an argument. +The [DIR] Built-In returns an empty string in this view. + +.IP \(bu 4 +Normally, as you navigate around a file system, \'twander\' sets its +own program context to the current directory. This is why you can +write Command Definitions using only the file/directory name currently +selected - \'twander\' knows the current directory. When you are in +Drive List View, the notion of "current directory" has no real +meaning. So, \'twander\' treats the directory from which you entered +Drive List View as the "current directory" while in that view. + +.IP \(bu 4 +By default, \'twander\' automatically rereads the current view +about every 3 seconds. This is fine for a file/directory view +but would be annoyingly slow in the Drive List View since +it takes a moment or two to get the status of any floppy disk +drives attached to the system. Instead of forcing the user to +listen to (and wait for) the floppy drive status to be determined +every 3 seconds, \'twander\' +.B only reads the drive information once when it enters Drive List View. +This means if a drive is connected or a floppy is inserted into the +system while in Drive List View, this fact will not be automatically +noted. You can force a manual update of the Drive List View by +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. + +.IP \(bu 4 +The SELALL (default: Control-comma) and SELINV (default: Control-i) +features work slightly differently in Drive List View than they +do otherwise. Ordinarily, these features never select the first +item of a file/directory display because it is always the ".." +entry pointing to the directory parent. In Drive List View, +the first entry +.B is +an entry of interest - usually, but not always, Drive A: - so +these two keys +.B do +select it as is appropriate. + +.SS Disabling \'win32all\' Features +You can toggle these features on-and off using the TOGWIN32ALL key +(default: Control-w). You can also permanently disable them by +setting the USEWIN32ALL option to False in the Configuration File. +This allows you to leave \'win32all\' installed on your system +if you need it for other reasons but don't want these features +enabled in \'twander\' + + + .SH GOTCHAS There are several tricky corners of \'twander\' which need @@ -1343,7 +1510,7 @@ so-called "modal" operation), it means your system does not completely or correctly implement threading. In that case, if you want non-modal command operation, try adding a "&" at -the end of your command definition. +the end of your Command Definition. .B 3) Windows That Don't Disappear On Command Completion @@ -1362,25 +1529,22 @@ appropriate release of Tkinter. This is the case, for example, with FreeBSD. +You must install the \'win32all\' extensions if you want to use +the advanced Win32 features. + .SH BUGS AND MISFEATURES -The color options (-b, -f), font options (-n, -s, -w), and size option -(-x, -y) are -.B not -checked for validity when the command line is initially read. -If you enter something unreasonable for -these options, \'twander\' will refuse to run with some -.B really -interesting and entertaining error messages. The program could be -more gracious about this. -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 -not work correctly or at all. The assumption here is that if you are -smart enough to want to change key bindings, you're smart enough to -learn how Tkinter names keys. You have been warned. +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. + +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. This program has not been tested on MacOS. Please let me know how/if it works there and any issues you discover. @@ -1463,7 +1627,7 @@ .fi This runs the program starting at the root directory of -the current drive (assuming "twander.py" is located in C:\\". +the current drive (assuming "twander.py" is located in C:\\. .IP \(bu 4 Start a command line window and issue a command like the one @@ -1477,6 +1641,25 @@ and \'twander\' should start automatically. +.SH GETTING HELP: THE \'twander\' MAILING LIST + +TundraWare Inc. maintains an email list for \'twander\' +users to get help and exchange ideas. To subscribe, +send mail to: + +.nf +majordomo@tundraware.com +.fi + +In the body (not the subject line) of the email, enter +the following text, substituting your own email address +as indicated: + +.nf +subscribe twander-users your-email-address +.fi + + .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 @@ -1534,7 +1717,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. @@ -1548,7 +1731,7 @@ Because \'twander\' is written in Python using Tkinter, the same program runs essentially identically on many Unix-like and Win32 systems. The only thing that may need to be changed across these -various platforms are the command definitions in the configuration +various platforms are the Command Definitions in the configuration file. You only need to learn one interface (and the commands you've defined) across all the different systems you use.