diff --git a/twander.1 b/twander.1 index 5c084d7..6ab03a2 100644 --- a/twander.1 +++ b/twander.1 @@ -270,7 +270,7 @@ .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 +on the system in question. On Windows systems, particularly, there ought to be no odd arrow/keypad behavior. X-Windows is somewhat more problematic in this area. Just what an @@ -363,9 +363,9 @@ 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 +systems like Windows 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, +However, in systems like X-Windows or Windows using fixed-size fonts, you may have to press these keys repeatedly until \'twander\' finds a font matching the requested size. @@ -389,7 +389,7 @@ font you see specified in the Help Menu is not necessarily the font you're actually using. You're more likely to run into this when running on a Unix/X-Windows system (where not all the fonts are -available in all sizes/weights like they are on Win32 TrueType) as you +available in all sizes/weights like they are on Windows TrueType) as you change the font size with FONTDECR/FONTINCR. Reloading the Configuration File (READCONF) will reset the fonts @@ -407,7 +407,7 @@ 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\' +Windows users should note that, unlike Windows Explorer, the \'twander\' 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 Command Menu to operate on a previously @@ -424,7 +424,7 @@ this pop-up menu. .TP -.B Display History Menu (None - Derived internally) +.B Display History Menu (MOUSEHIST) Control-Shift-Right-Mouse-Button Displays a list of all commands executed so far (including those @@ -436,6 +436,35 @@ command you entered by hand.) .TP +.B Display Shortcut Menu (MOUSESC) +Control-Right-Mouse-Button + +Displays a list of all user-defined directory shortcuts in a pop-up +menu near the mouse. The menu also has "canned" navigation shortcuts +to go up a directory, back a directory, to the home directory, to the +starting directory, and to the root directory. On Windows systems +with the Win32All extensions, there is also a shortcut to the Drive +List View. + +.TP +.B Display Wildcard Menu (MOUSEWILD) +Alt-Control-Right-Mouse-Button + +(Note that on Windows you must press Alt +.B then +Control +.B then +Right-Mouse-Button for this to work. Windows appears to care deeply +about keystroke order.) + +Displays a list (if any) of any previously used selection wildcards in +a pop-up menu near the mouse. Selecting one of the entries therein +pops-up a dialog that allows you to edit the wildcard before actually +doing another selection. This allows use to modify previous wildcards +for new use. + + +.TP .B Quit Program (QUITPROG) Control-q @@ -495,8 +524,8 @@ 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 +features for Windows users who also install Mark Hammond's \'win32all\' +extensions for Python on Windows. This key binding will toggle those advanced features on- and off. This is useful if you happen to be examining a very large directory. The \'win32all\' features, while handy, can be computationally expensive and make updates of @@ -576,10 +605,10 @@ .B Display Drive List View (DRIVELIST) Control-k -This is a Win32-only feature which displays a list of all available +This is a Windows-only feature which displays a list of all available 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 +running on Windows AND have the \'win32all\' package installed, AND the 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 @@ -718,7 +747,7 @@ Notice that these regular expressions are .B not the same thing as the filename "globbing" wildcards commonly -used with Unix and Win32 shells. If you enter constructs like +used with Unix and Windows shells. If you enter constructs like "*.txt" or "*.tar.gz", you will not get the results you expect. In fact, these specific examples will cause \'twander\' to grumble and present a warning message. @@ -855,7 +884,7 @@ does in a Command Definition. This also gives you a single way of referring to environment variables, regardless of OS platform. Recall that in Unix-like shells, an environment variable is in the form -"$NAME", but on Win32 it is in the form "%NAME%". Instead if having +"$NAME", but on Windows it is in the form "%NAME%". Instead if having to keep track of this difference, you can just use a \'twander\' Environment Variable reference. For instance, assuming the EDITOR environment variable is set, this command works the same @@ -957,7 +986,7 @@ must be set for the user running \'twander\' (or their group) for the file to be executed. -On Win32, the file will be executed if the user has permission to do +On Windows, the file will be executed if the user has permission to do so .B and that file is either executable or there is a Windows association @@ -967,7 +996,7 @@ been changed). If \'twander\' determines that it is running on neither a Unix-like -or Win32 system, double-clicking on a file does nothing. +or Windows system, double-clicking on a file does nothing. .TP .B Run User-Defined Command @@ -1137,7 +1166,7 @@ Wildcard menus all keep some sort of "history" of what the program has done. Their content thus grows longer as the program is used. -On Win32 systems, if such menus grow too long to physically fit on +On Windows systems, if such menus grow 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 @@ -1203,9 +1232,7 @@ Unless MAXMENU is set to 0, the Directory Menu shows the last MAXMENU directories visited in alphabetically sorted order (unless you change MAXMENUBUF to be smaller than MAXMENU). "Visited", in this case, is -stretching things 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. +stretching things a bit. The Directory Menu is emptied and grayed out when you press the CLRHIST key. (default: Control-y) @@ -1243,6 +1270,15 @@ CLRHIST key. (default: Control-y) +.SS Shortcut Menu (Alt-u) [Control-Right-Mouse-Button] + +This menu provides a way to access any of the Directory Shortcuts +defined in the configuration file. It also provides a number of +"canned" navigation shortcuts to go up a directory, back a directory, +to the home directory, to the starting directory, and to the root +directory. On Windows systems using the Win32All extensions, there is +also a shortcut to the Drive List View. + .SS Sorting Menu (Alt-s) [No Mouse Shortcut] This menu provides a way to select any of the available sorting @@ -1258,13 +1294,11 @@ .SS Wildcard Menu (Alt-w) [Alt-Control-Right-Mouse-Button] -\ - -(Note that on Win32 you must press Alt +(Note that on Windows you must press Alt .B then Control .B then -Right-Mouse-Button for this to work. Win32 appears to care deeply +Right-Mouse-Button for this to work. Windows appears to care deeply about keystroke order.) This menu provides a list of all previously used selection "wildcard" @@ -1321,9 +1355,9 @@ .SH LOCATION OF CONFIGURATION FILE By default, the program expects to find configuration information in -.B $HOME/.twander (%HOME%\\\\.twander on Win32) +.B $HOME/.twander (%HOME%\\\\.twander on Windows) but you can override this with the -c command line -option. (Recommended for Win32 systems - see the section below +option. (Recommended for Windows systems - see the section below entitled, .B INSTALLING \'twander\' ) @@ -1499,6 +1533,48 @@ .ft \" revert .TP +.B ADAPTREFRESH [Boolean] (True) + +Whenever a directory is read, the time to do so is tracked. If that +time is less than the current value of REFRESHINT - i.e., The +directory read took less than REFRESHINT milliseconds to complete - +nothing special happens. But, if the actual directory read time takes +.B longer +than REFRESHINT milliseconds, \'twander\' adjusts the value of +REFRESHINT upwards. That way, you're guaranteed to have time +after the read completes to actually do something. + +This dynamic adjustment takes place on every directory read. If you +go to a slow directory and REFRESHINT gets dynamically adjusted to, +say, 25 seconds, when you go back to a faster/smaller directory, +REFRESHINT will be reset to its default value. The changing value +of REFRESHINT is +.B not +shown in the program options help menu. The value there is the one +set by default or set in the configuration file. Think of this as the +"base" value for REFRESHINT. + +If ADAPTREFRESH is set to False, then adaptive refresh timing is +disabled and a directory refresh will be attempted every REFRESHINT +milliseconds. + + +.TP +.B AFTERCLEAR [Boolean] (True) + +Tells \'twander\' to clear any selections in the GUI if a command +forces a display refresh after it completes. (See the AFTERWAIT and +.B Forcing Display Updates In Command Definitions +sections below). This is done because a command that forces a display +update is probably changing the content of the current directory +(otherwise, why bother with the update?), and the current selections +may no longer be relevant. + +Setting AFTERCLEAR to False, will leave the current selections alone +after doing a command with a forced update. + + +.TP .B AFTERWAIT [Numeric] (1) It is possible to define commands so that a display refresh is forced @@ -1664,17 +1740,19 @@ command definition are replaced with strings that list one or more files and/or directories. When this substitution is made at runtime, these strings contain the path separator character appropriate for the -underlying operating system ("/" for Unix and "\\\\" for Windows). +underlying operating system ("/" for Unix and "\\" for Windows). If you set FORCEUNIXPATH to True, \'twander\' will .B always -use the Unix path separator character("/") in these substitutions, -regardless of the OS in in use. +use the Unix path separator character("/") in these substitutions. This option is primarily useful when writing command definitions with Unix tools under Windows (such as cygwin) that are fussy about path separator conventions. +This option is only relevant on Windows systems. It is ignored on +other operating systems. + .TP .B HBCOLOR [String] (lightgreen) @@ -1951,6 +2029,17 @@ Initial vertical offset of the \'twander\' window in pixels. .TP +.B SYMDIR [Boolean] (True) + +This option causes symbolic links that point to directories to be +treated as directories for purposes of sorting. This is relevant when +"separated" sorting is selected - i.e., When the directories are +sorted separately from files. If SYMDIR is set to False, then +symbolic links will be sorted as files, regardless of what the link +points to. + + +.TP .B USETHREADS [Boolean] (False) \'twander\' defaults to using normal "heavy weight" processes @@ -1964,15 +2053,15 @@ section below. This option applies only to Unix-like operating systems. -Win32 commands are +Windows commands are .B always -run as a thread - this is the only process model Win32 +run as a thread - this is the only process model Windows supports.. .TP .B USEWIN32ALL [Boolean] (True) -Win32 only. If \'win32all\' is installed, determines whether its +Windows only. If \'win32all\' is installed, determines whether its features should be used (see section below entitled, .B ADVANCED WIN32 FEATURES for details). @@ -2035,7 +2124,7 @@ .IP \(bu 4 The font colors, weights, and sizes available for your use will vary -somewhat by system. For instance, Win32 TrueType fonts are +somewhat by system. For instance, Windows TrueType fonts are effectively available in every size and weight. On the other hand, most Unix-like systems have a more limited palette of fonts and colors with which to work. Most systems should support obvious color names @@ -2273,16 +2362,6 @@ .ft \" revert .IP \(bu 4 -All defined Directory Shortcut paths are also automatically -inserted into the Directory Menu at program startup (or -Configuration File reload) whether or not you've actually -visited those directories. The assumption is that you -will be visiting these directories a lot (which is why -you've defined shortcuts to them), so \'twander\' also -makes them available in the directory "history" for easy -access. - -.IP \(bu 4 \'twander\' does absolutely no checking of what you enter to the right of the equals sign. If you enter something silly for the shortcut path, you will probably get a warning @@ -2556,7 +2635,7 @@ MyEditor = [$EDITOR] - # Override this if we're on Win32 + # Override this if we're on Windows \&.if [.OS] == nt MyEditor = write @@ -2623,7 +2702,7 @@ 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 +the result you'd like (...well, on X-Windows - is does work on Windows as written). (For more details on why, see the .B GOTCHAS section below.) It turns out that starting a non-GUI program like @@ -2649,7 +2728,7 @@ cycle - automatic if AUTORFRESH is enabled, manual otherwise. Placing \'+\' symbol to the beginning of the Command String tells -\'twander\' that, when the command is run, a display refresh should be +\'twander\' that, when the command is run, a display refresh should be forced afterwards. Not immediately afterwards, but AFTERWAIT seconds (default: 1) later. Why? To give the command in question a chance to complete before updating the display. For instance, @@ -2672,6 +2751,14 @@ The idea here is to use this feature for "quicky" updates between more conventional display refreshes, whether via AUTOREFRESH or manually. +By default, anytime you run a command that uses this feature, any +selections in the GUI are cleared and the cursor is positioned under +the first item on the display. This is because a forced update +presumably is required because the command changes something in the +current directory. In that case, the current selections may no longer +be relevant. If you wish to disable this behavior, set the AFTERCLEAR +program option to False. + .SS User-Defined Variables In A Command String @@ -2923,8 +3010,8 @@ .ft \" revert This should not generally be a problem with the various Unix -shells, and may work for some Win32 commands. However, some -Win32 programs (noted in \'notepad\') reject this kind of +shells, and may work for some Windows commands. However, some +Windows programs (noted in \'notepad\') reject this kind of file name when passed on the command line. The workaround (and a generally easier way to do this sort of thing), is to use the [DSELECTION] built-in which returns the full path name of @@ -3171,7 +3258,7 @@ .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 +various Unix variants (FreeBSD, Linux) and Windows. 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 @@ -3179,18 +3266,18 @@ 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. +on your Windows system. Installing this package just means you'll +get even more \'twander\' features on Windows 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, +installed the Active State version of Python for Windows, (http://www.activestate.com/Products/ActivePython/) \'win32all\' is already installed on your system. If you installed the standard -Python release for Win32 +Python release for Windows (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: @@ -3199,7 +3286,7 @@ .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 +\'win32all\' are only available on "true" Windows 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 @@ -3221,7 +3308,7 @@ .IP \(bu 4 Instead of showing Unix-style file permissions (which don't mean much -under Win32), systems with \'win32all\' installed will show the +under Windows), 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: @@ -3259,7 +3346,7 @@ Configuration File STARTDIR option. .fi -The "Drive List View" is available on all Win32 variants, however the +The "Drive List View" is available on all Windows variants, however the free/total space values will be incorrect on older systems like Win98. .SS Notes On Drive List View @@ -3360,7 +3447,7 @@ 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 +On Windows, environment variables are set via the System Properties menu. .SS \'twander\' Loads Slowly @@ -3377,18 +3464,18 @@ 3) Once Python is loaded type: import twander 4) Exit \'twander\'. 5) Exit Python by pressing Control-d on Unix or - Control-z on Win32. + Control-z on Windows. 6) You will now see a new file in this directory: twander.pyo This file should be significantly smaller than twander.py. 7) Now you can run the program by entering: python twander.pyo - on Unix/Win32 or pythonw twander.pyo on Win32. + on Unix/Windows or pythonw twander.pyo on Windows. 8) You have to repeat this procedure each time you install a new version of twander.py .fi -.SS Cannot Enter Certain Directories On Win32 +.SS Cannot Enter Certain Directories On Windows -Win32 allows file/directory names to contain non-ASCII +Windows allows file/directory names to contain non-ASCII characters. Python, as shipped, defaults to ASCII only and grumbles mightily when it is asked to deal with a string containing characters with ordinal values greater than @@ -3502,8 +3589,8 @@ .B and under a shell interpreter. -This is not as much an issue on Win32 systems where the first -form of the command above works fine. Win32 appears to have +This is not as much an issue on Windows systems where the first +form of the command above works fine. Windows appears to have no problem invoking a new window whether the command is GUI-aware or not. @@ -3513,10 +3600,10 @@ start \'twander\' from a terminal session, all terminal output will be sent to .B the terminal session you used to invoke the program. -The way to work around this is to start \'twander\' from a Win32 +The way to work around this is to start \'twander\' from a Windows shortcut, using \'pythonw.exe\' rather than \'python.exe\'. Now each time you run a command that needs a terminal session for -output, Win32 will automatically create that session for you. +output, Windows will automatically create that session for you. .SS Using Shell Wildcards In Command Definitions @@ -3524,7 +3611,7 @@ The [PROMPT:...] Built-In Variable is provided to make it possible to write general-purpose commands which interact with the user. For example, you might want to -define a directory listing command for Win32 like this: +define a directory listing command for Windows like this: .ft C \" courier .nf @@ -3612,7 +3699,7 @@ .SS Modal Operation Of New Windows Notice our example commands above do not end with "&". These should -not be needed on either Unix-like or Win32 operating systems. When a +not be needed on either Unix-like or Windows operating systems. When a command is executed, \'twander\' starts a process which runs concurrently with \'twander\' itself. This means you should be able to continue using \'twander\' while the new command executes. @@ -3671,7 +3758,7 @@ refresh interval as described in the previous bullet. .IP \(bu 4 -By far the worst culprit here, though, is when running Win32 +By far the worst culprit here, though, is when running Windows with \'win32all\' options enabled. It takes a lot more work to get win32all-style information about each directory entry, than the default Unix-style information. Simply turning @@ -3681,10 +3768,39 @@ .P When you combine these factors, it is possible to get really long processing times. One test situation we observed was -reading a directory with over 4000 entries on a Win32 CDROM. +reading a directory with over 4000 entries on a Windows CDROM. With \'win32all\' processing enabled this took over a minute. By disabling these features, the time came down to under 30 seconds. +.IP \(bu 4 +For all these reasons, \'twander\' implements an "adaptive refresh" +scheme by default. Whenever a directory is read, the time to do +so is tracked. If that time is less than the current value of +REFRESHINT - i.e., The directory read took less than REFRESHINT +milliseconds to complete - nothing special happens. But, if the +actual directory read time takes +.B longer +than REFRESHINT milliseconds, \'twander\' adjusts the value of +REFRESHINT upwards. That way, you're guaranteed to have time +after the read completes to actually do something. + +.P +This dynamic adjustment takes place on every directory read. If you +go to a slow directory and REFRESHINT gets dynamically adjusted to, +say, 25 seconds, when you go back to a faster/smaller directory, +REFRESHINT will be reset to its default value. The changing value +of REFRESHINT is +.B not +shown in the program options help menu. The value there is the one +set by default or set in the configuration file. Think of this as the +"base" value for REFRESHINT. + +.P +If you don't like this adaptive refresh interval business, set +the ADAPTREFRESH program option to False. In that case, +REFRESHINT will be strictly observed. + + .SS Your Configuration File Does Not Produce The Desired Results It's easy to fall into the trap of treating the \'twander\' @@ -3826,23 +3942,23 @@ .SH OTHER File/Directory name sorting is done without-case sensitivity on -Win32 systems because the underlying operating system does not +Windows systems because the underlying operating system does not observe case. Because this program has not been tested on anything other than -Unix-like and Win32 systems, command execution by double-click +Unix-like and Windows systems, command execution by double-click or pressing Enter is inhibited on all other operating systems by default. 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 +installed for that release. In the case of Windows, Tkinter is bundled with the standard Windows Python distribution. In the case of Unix-like systems, you may have to first install Python and then the 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. +the advanced Windows features. You'll find the latest version, and occasionally, Release Candidates of the next version of \'twander\' at: @@ -3889,7 +4005,7 @@ appears to not be exported consistently on all systems. .IP \(bu 4 -If you are running Win32 and have file or directory names with +If you are running Windows 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, @@ -3913,7 +4029,7 @@ easiest to get started by editing the example ".twander" file to taste. Be aware that this file is shipped with everything commented out. You have to uncomment/edit the section relevant to your -operating system: Unix-like or Win32. +operating system: Unix-like or Windows. .SS Installing Using The FreeBSD Port @@ -3971,7 +4087,7 @@ 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 +.SS Installing Manually On A Windows System Copy the "twander.py" file to a directory somewhere on your path, or create a new directory to hold this file and add that directory path @@ -3980,17 +4096,17 @@ .B IMPORTANT NOTE TO WIN32 USERS: Windows has the old MS-DOS legacy of assuming that a "." begins a file "extension". Although you can create and read files in the form -".something", it is not recommended because many Win32 programs get +".something", it is not recommended because many Windows programs get confused when they see this. It is also difficult to remove files named this way with the standard Windows programs and utilities. This -is especially the case for older Win32 operating systems like Win98. +is especially the case for older Windows operating systems like Win98. For this reason, it is recommended that you rename the ".twander" 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. -On Win32, where to put the Configuration File raises an interesting +On Windows, 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". @@ -3999,10 +4115,10 @@ you can invoke \'twander\' with the -c argument to explictly declare where it can find its Configuration File. -You can run the program several ways on Win32 systems: +You can run the program several ways on Windows systems: .IP \(bu 4 -Create a Win32 shortcut which points to the "twander.py" file using +Create a Windows shortcut which points to the "twander.py" file using the "pythonw" command to invoke it. Normally, starting a Python program from the Windows GUI creates a parent window which persists as long as the program runs. Using "pythonw" instead of "python" to run @@ -4123,7 +4239,7 @@ .TP 4) Because \'twander\' is written in Python using Tkinter, the same -program runs essentially identically on many Unix-like and Win32 +program runs essentially identically on many Unix-like and Windows systems. The only thing that may need to be changed across these various platforms are the Command Definitions in the configuration file. You only need to learn one interface (and the commands you've