diff --git a/twander.1 b/twander.1 index 1730ce8..5c084d7 100644 --- a/twander.1 +++ b/twander.1 @@ -1,8 +1,6 @@ .TH twander 1 "TundraWare Inc." -.ds CF Configuration File .ds CP 2002-2005 -.ds W3 \'win32all\' .SH NAME twander \- File Browser @@ -15,7 +13,7 @@ filesystem, but .B you define the commands you want available via "Command Definitions" -in the \*(CF. +in the Configuration File. If you're new to \'twander\' and want to know why this program is better and different than whatever you're @@ -63,15 +61,15 @@ will display an error message and abort. .TP -.B -c path/name of \*(CF +.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 \*(CF without exiting the program (which you would -presumably do after fixing the \*(CF problem). +the Configuration File without exiting the program (which you would +presumably do after fixing the Configuration File problem). .TP .B -d debuglevel @@ -171,7 +169,7 @@ 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 \*(CF. This +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 @@ -181,7 +179,7 @@ Internally set default value of options .IP \(bu 4 -Options set in the \*(CF +Options set in the Configuration File .IP \(bu 4 Options set in the TWANDER environment variable @@ -192,23 +190,23 @@ .P This means, for example, that the environment variable overrides a -corresponding setting in the \*(CF, but the command line +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 \*(CF and are not available in +be set/changed the Configuration File and are not available in either the environment variable or on the command line. This also means that options set on the command line are not read -until after the \*(CF has been processed. So, the -q +until after the Configuration File has been processed. So, the -q argument on the command line will not inhibit warnings generated -during the reading of the \*(CF. This is best done by +during the reading of the Configuration File. This is best done by adding the statement, WARN=False, at the top of the Configuration File. -If the \*(CF is reloaded while the program is running +If the Configuration File is reloaded while the program is running (see the READCONF key below), any options set in the file will have -the last word. This allows you to edit the \*(CF and +the last word. This allows you to edit the Configuration File and have your changes reflected in a running instance of \'twander\', but it also means that the environment variable/command line arguments are ignored after initial program startup. @@ -266,7 +264,7 @@ 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 \*(CF, also described below. +in the Configuration File, also described below. .SH NOTES ON KEYBOARD ARROW/KEYPAD BEHAVIOR AND TEXT DIALOG EDITS @@ -331,7 +329,7 @@ button assignments are documented below for the sake of completeness. However, .B mouse button assignments cannot be changed by the user, -even in the \*(CF. +even in the Configuration File. .SS General Program Commands @@ -394,9 +392,9 @@ available in all sizes/weights like they are on Win32 TrueType) as you change the font size with FONTDECR/FONTINCR. -Reloading the \*(CF (READCONF) will reset the fonts +Reloading the Configuration File (READCONF) will reset the fonts to either their default values or any font sizes specified in the -\*(CF. +Configuration File. .TP .B Display Command Menu (MOUSECTX) @@ -405,7 +403,7 @@ 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 \*(CF, via selection in 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 Command Menu. @@ -444,20 +442,20 @@ Exit the program. .TP -.B Re-Read \*(CF (READCONF) +.B Re-Read Configuration File (READCONF) Control-r -Re-read the \*(CF. This allows you to edit the -\*(CF 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. Program Options are set back to their default each time a -\*(CF is about to be read (initially or on reload) just -before the \*(CF is parsed. This means commenting out or +Configuration File is about to be read (initially or on reload) just +before the Configuration File is parsed. This means commenting out or removing a Program Option Statement (see relevant section below) in -the \*(CF and then pressing READCONF causes that option to +the Configuration File and then pressing READCONF causes that option to be reset to its default value. STARTDIR defaults to either its internal default ($HOME or ./) or to the value given in the Environment Variable/Command line. @@ -493,14 +491,14 @@ Toggle between detailed and filename-only views of the directory. .TP -.B Toggle \*(W3 Features (TOGWIN32ALL) +.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 \*(W3 +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. This is useful if you happen to -be examining a very large directory. The \*(W3 features, +be examining a very large directory. The \'win32all\' features, while handy, can be computationally expensive and make updates of a directory with many entries somewhat slow. This toggle is provided as a means to temporarily disable the advanced features when viewing @@ -581,7 +579,7 @@ This is a Win32-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 \*(W3 package installed, AND the +running on Win32 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 @@ -777,7 +775,7 @@ the Wildcard Menu (see below). There is also provision for pre-defining frequently used -selection wildcards in your \*(CF (see below) so +selection wildcards in your Configuration File (see below) so you don't have to type them in manually each time you start the program - you can just select them from the Wildcard Menu. @@ -835,7 +833,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 \*(CF. +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. @@ -975,7 +973,7 @@ .B Run User-Defined Command User-Defined (Single Letter) Key -Each command defined in the \*(CF 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. @@ -984,7 +982,7 @@ \'twander\' provides a way to directly navigate into a frequently-used directory using a single keystroke. You can define up to 12 such -"Directory Shortcuts" in the \*(CF. Each of the +"Directory Shortcuts" in the Configuration File. Each of the definitions is associated with one of the following 12 keys: .TP @@ -992,8 +990,8 @@ F1 ... F12 Pressing one of these keys changes to the directory associated with it -in the \*(CF. For more information on this topic, see -the discussion of the \*(CF below entitled, +in the Configuration File. For more information on this topic, see +the discussion of the Configuration File below entitled, .B Directory Shortcut Statements. .SS Program Memories @@ -1146,7 +1144,7 @@ truncated to fit the screen on Unix-like systems. There are two User-Settable Options options available to help you manage -the maximum size of dynamic menus (see the section below on the \*(CF +the maximum size of dynamic menus (see the section below on the Configuration File which explains how such options are actually set. The MAXMENU option specifies the maximum number entries .B that will be displayed @@ -1172,18 +1170,18 @@ .SS Commands Menu (Alt-c) [Right-Mouse-Button] -Every command defined in the \*(CF 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 \*(CF. 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 \*(CF. If no -commands are defined, either because the \*(CF contains -no Command Definitions or because the \*(CF 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). @@ -1216,7 +1214,7 @@ \'twander\' keeps track of every command you attempt to execute, whether it is an invocation of a Command Definition found in the -\*(CF or a manually entered command via the RUNCMD key. +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. @@ -1226,14 +1224,14 @@ the command before running it again. One important point of clarification is in order here. If you run -one of the commands defined in your \*(CF, it is +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 \*(CF are written +(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 @@ -1271,7 +1269,7 @@ This menu provides a list of all previously used selection "wildcard" regular expressions. Any regular expressions defined in the -\*(CF (see below) using the "WILDCARD = " statement will +Configuration File (see below) using the "WILDCARD = " statement will also appear in this menu. This saves you the tedium of constantly having to enter complex regular expression syntax every time you wish to do wildcard-based selections. @@ -1280,14 +1278,14 @@ allows you to edit the selected wildcard before using it. Bear in mind that the size of the displayed menu is governed by the -MAXMENU and MAXMENUBUF \*(CF options (see below). i.e., +MAXMENU and MAXMENUBUF Configuration File options (see below). i.e., Only the last MAXMENU number of wildcards are actually displayed on the menu. The Wildcard Menu is emptied and grayed out when you press the CLRHIST key. (default: Control-y) This history is .B not -cleared if the \*(CF is reloaded. +cleared if the Configuration File is reloaded. .SS Help Menu (Alt-l) [No Mouse Shortcut] @@ -1314,9 +1312,9 @@ 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 -"\*(CF". 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 \*(CF present, it will warn you that it is +without a Configuration File present, it will warn you that it is doing so with no commands defined. @@ -1331,16 +1329,16 @@ ) Actually, \'twander\' can look in a number -of places to find its \*(CF. 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 \*(CF. +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 \*(CF 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 @@ -1352,7 +1350,7 @@ .SH CONFIGURATION FILE FORMAT -\'twander\' \*(CFs 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. @@ -1378,13 +1376,13 @@ Everything else is considered invalid. \'twander\' will respond with errors or warnings as is appropriate anytime it encounters a problem -in a \*(CF. An error will cause the program to +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 true both when the program initially loads as well as during any subsequent -\*(CF reloads initiated from the keyboard while running +Configuration File reloads initiated from the keyboard while running \'twander\'. The following sections describe each of the valid Configuration @@ -1393,7 +1391,7 @@ .SS Comments A comment is begun with the "#" character which may be placed anywhere -on a line. Comments may appear freely within a \*(CF. +on a 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 @@ -1412,7 +1410,7 @@ .SS Program Option Statements Many of \'twander\'s internal program defaults can be overriden in the -\*(CF using Program Option statements. These statements +Configuration File using Program Option statements. These statements look just like the User-Defined variables described later in this document except \'twander\' recognizes the variable name as a Program Option rather than an arbitrary variable. Program Option Statements @@ -1453,10 +1451,10 @@ treats this character as the beginning of a comment no matter where it appears. -For consistency with other \*(CF entries, Program Option Statements +For consistency with other Configuration File entries, Program Option Statements may have a blank Right Hand Side. Such statements are simply ignored. This is convenient when you want to leave -a placeholder in your \*(CF but don't actually want to +a placeholder in your Configuration File but don't actually want to activate it at the moment. However, be careful - depending on what precedes the statement, you'll get different settings for the option in question. For example: @@ -1464,7 +1462,7 @@ .ft C \" courier .nf # This effectively sets BCOLOR to its default value when - # the \*(CF is reloaded + # the Configuration File is reloaded BCOLOR = # But this means the value of BCOLOR is set to red @@ -1548,7 +1546,7 @@ In fact, on Unix, the need for this idiom is so common, it's best to define some variables for this. If you look in the example \'.twander\' -\*(CF provided in the program distribution, you'll see +Configuration File provided in the program distribution, you'll see something like (comments removed): .ft C \" courier @@ -1578,7 +1576,7 @@ to any literal text. That text will be .B automatically prepended to any command you enter manually. In this case you could do either of the following in the -\*(CF: +Configuration File: .ft C \" courier .nf @@ -1595,7 +1593,7 @@ To disable CMDSHELL operation .B permanently, -just remove the statement above from your \*(CF. If you +just remove the statement above from your Configuration File. If you want to leave it in as a placeholder, but deactivate CMDSHELL, use the following statement: @@ -1607,7 +1605,7 @@ You also may want to occasionally use RUNCMD to do something without CMDSHELL processing, even though that feature has been defined in the -\*(CF. You can disable CMDSHELL operation on a +Configuration File. You can disable CMDSHELL operation on a per-RUNCMD basis. Just begin your entering your command with the double-quote (") character. \'twander\' understands this to "escape" CMDSHELL processing. @@ -1629,7 +1627,7 @@ way being the -d command line argument). For example, say you want to always dump the current Command Definitions to stdout when the program starts - perhaps you want to redirect this output to a file or -printer. Just add this line to your \*(CF: +printer. Just add this line to your Configuration File: .ft C \" courier .nf @@ -1820,7 +1818,7 @@ The NODETAILS and NONAVIGATE commands are .B not security features. They can easily be defeated by editing the -\*(CF. They exist to make it easy for you to create +Configuration File. They exist to make it easy for you to create \'twander' configurations for technically unsophisticated users. Say you want to define a few simple commands for your boss to use @@ -1974,17 +1972,17 @@ .TP .B USEWIN32ALL [Boolean] (True) -Win32 only. If \*(W3 is installed, determines whether its +Win32 only. If \'win32all\' is installed, determines whether its features should be used (see section below entitled, .B ADVANCED WIN32 FEATURES for details). Normally, this option should be left alone. However, if you have -\*(W3 installed on your system for some other reason, but don't +\'win32all\' installed on your system for some other reason, but don't want it used by \'twander\', set this option to False. The main reason to do this would be on a slow machine with very large -directories. The advanced features of \*(W3 come at a +directories. The advanced features of \'win32all\' come at a computational price. This is especially noticeable when it is computing the attributes, ownership, and size in a directory with hundreds (or more) of entries. Typically, you would just use the @@ -2002,12 +2000,12 @@ Setting this option to False is the same thing as using the -q command line option with one important difference: The -\*(CF is parsed before the command line is +Configuration File is parsed before the command line is parsed. Even if you have -q on the command line (or in the TWANDER environment variable), if there is an error in -your \*(CF, you will see warning messages +your Configuration File, you will see warning messages at program startup time. Putting WARN=False at the -top of your \*(CF will suppress this. +top of your Configuration File will suppress this. It is not recommended that you operate normally with the -q flag or with WARN=False. \'twander\' is pretty @@ -2025,7 +2023,7 @@ .IP \(bu 4 You can set the same option multiple times in a single -\*(CF - \'twander\' pays no attention. +Configuration File - \'twander\' pays no attention. However, only the .B last (the one nearest the end of the file) instance of that Program Option @@ -2051,7 +2049,7 @@ usually ugly, so try to specify font information for things that actually exist on your system. -If your setting in the \*(CF seems not to work, take a +If your setting in the Configuration File seems not to work, take a look at the command window in which you started \'twander\' (or start it from one manually, if you're using a GUI shortcut to start it). Attempts to use unavailable colors and weights will cause @@ -2081,7 +2079,7 @@ Say MAXMENU is set to 4, but you've actually visited 20 different directories and issued 30 commands. You'll only see 4 of each on the associated menus. But, if you edit MAXMENU to now be 32 and reload -the \*(CF, you will see all 20 directories and 30 commands on their +the Configuration File, you will see all 20 directories and 30 commands on their respective menus. .IP \(bu 4 @@ -2123,16 +2121,16 @@ 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 \*(CF. +via entries in the Configuration File. 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 \*(CF 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 \*(CF. 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: @@ -2150,7 +2148,7 @@ both in print and on the Internet.) Keyboard binding assignments look just like variable definitions -in the \*(CF. (The \'twander\' \*(CF parser +in the Configuration File. (The \'twander\' Configuration File parser automatically distinguishes between Key Binding Statements and Variable Definitions or other legitimate statements. This means you can never use one of the program function names as one of your own @@ -2168,7 +2166,7 @@ to the desired keystroke. Examples of all the default key bindings are shown as comments in the -".twander" example \*(CF supplied in the program +".twander" example Configuration File supplied in the program distribution. The easiest way to rebind a particular function is to copy the relevant line, uncomment the copy, and change the right side of the assignment to the new key you'd like to use. @@ -2199,7 +2197,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 \*(CF. 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: .ft C \" courier @@ -2217,8 +2215,8 @@ User-Defined variable of that name in its symbol table. .IP \(bu 4 -When you're done making changes to the \*(CF, be sure to -either restart the program or reload the \*(CF 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 @@ -2233,7 +2231,7 @@ \'twander\' provides a mechanism for directly navigating into one of 12 frequently used directories. 12 keys, KDIRSC1 ... KDIRSC12 (default: F1 ... F12) have been set aside for this purpose. Directory -Shortcut Statements are entries in the \*(CF which +Shortcut Statements are entries in the Configuration File which associate one of these keys with a particular directory path. These statements are in the form: @@ -2277,7 +2275,7 @@ .IP \(bu 4 All defined Directory Shortcut paths are also automatically inserted into the Directory Menu at program startup (or -\*(CF reload) whether or not you've actually +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 @@ -2323,7 +2321,7 @@ This regular expression will then be pre-loaded into the Wildcard Menu (making it easy to invoke by just clicking on it) when \'twander\' starts. -You may place as many of these as you like in your \*(CF. +You may place as many of these as you like in your Configuration File. (Though the menu will be limited to displaying MAXMENU number of items - see the section above on Program Option Statements.) @@ -2397,8 +2395,8 @@ .ft \" revert Why bother with this? Because it makes maintaining complex -\*(CFs easier. If you look in the example ".twander" -\*(CF 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. @@ -2459,7 +2457,7 @@ .ft \" revert This recursive definition is a no-no and will be cause \'twander\' -to generate an error while parsing the \*(CF and then +to generate an error while parsing the Configuration File and then terminate. Your variable definitions can also nest other kinds of variables @@ -2545,7 +2543,7 @@ .IP \(bu 4 Unlike previous versions of \'twander\', Variable Names may be redefined. This makes it more convenient to exploit the ability for \'twander\' -to process the contents of a \*(CF conditionally (see the +to process the contents of a Configuration File conditionally (see the .B Conditional Processing Statements section below). @@ -2586,7 +2584,7 @@ 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 \*(CF. If \'twander\' finds multiple Command +given Configuration File. If \'twander\' finds multiple Command Definitions assigned to the same Command Key, it will associate the .B last definition it finds with that Command Key. A Command Key can @@ -2599,7 +2597,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 \*(CF. 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. @@ -2681,7 +2679,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 \*(CF? Now, our command looks +throughout the whole Configuration File? Now, our command looks like this: .ft C \" courier @@ -2888,7 +2886,7 @@ Earlier releases of \'twander\' .B did include the trailing path separator and you may have to edit -older \*(CFs 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.) @@ -2935,7 +2933,7 @@ .IP \(bu 4 User-Defined and Environment Variables are processed -at the time the \*(CF 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. @@ -2972,10 +2970,10 @@ .SS Conditional Processing Statements Most of \'twander\'s power lies in its ability to be customized to each -different user and operating system via its \*(CF. To make this a bit +different user and operating system via its Configuration File. To make this a bit easier to manage, the \'twander\' configuration language recognizes so-called "Conditional Processing Statements". These statements give -you the ability to write a single \*(CF which automatically tailors +you the ability to write a single Configuration File which automatically tailors itself to run \'twander\' properly wherever you are running. The general idea is to define a "Condition Block" which begins by @@ -2987,7 +2985,7 @@ A Conditional Block always begins with a "Condition Test Statement" and ends with the ".endif" statement. Conditional Processing Statements may be nested without limit. \'twander\' keeps track of which -\&'.endif' matches which Condition Test Statement. Like all \*(CF +\&'.endif' matches which Condition Test Statement. Like all Configuration File entries, whitespace is ignored when processing Conditional Statements and you are free to indent (or not) as you see fit. @@ -3097,7 +3095,7 @@ .SS The Include Directive -You may include other files in your \*(CF with the following +You may include other files in your Configuration File with the following directive: .ft C \" courier @@ -3106,7 +3104,7 @@ .fi .ft \" revert -You may place as many of these statements in your \*(CF as you wish. +You may place as many of these statements in your Configuration File as you wish. The only syntactic requirement is that there must be whitespace between the directive and the file path. \'twander\' makes no attempt to validate that path, and you will see an warning message if the @@ -3139,7 +3137,7 @@ .ft \" revert -Now, you can create your own personal \*(CF which takes advantage +Now, you can create your own personal Configuration File which takes advantage of this standard file, but augments it with additional configuration information of your choosing: @@ -3156,7 +3154,7 @@ .ft \" revert -Keep in mind that \'twander\' reads the contents of its \*(CF +Keep in mind that \'twander\' reads the contents of its Configuration File .B in order. In this case, it means that all of "/usr/local/etc/.twander.global" is read and @@ -3165,7 +3163,7 @@ than once, the .B last definition is what is used. In this case, DIRSC2 is overriden in the local -\*(CF and is ultimately assigned to "/etc". Similarly, you +Configuration File and is ultimately assigned to "/etc". Similarly, you can override previous definitions for User-Defined Variables and even Command Definitions. @@ -3174,40 +3172,40 @@ 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 \*(W3 Python extensions if +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 \*(W3 for \'twander\' to operate properly +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 \*(W3, you can toggle these features +If you've installed \'win32all\', you can toggle these features on- and off with the TOGWIN32ALL key described above. -.SS Getting \*(W3 +.SS Getting \'win32all\' -You can get the \*(W3 extensions one of two ways. If you've +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/) \*(W3 is +(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 -\*(W3 to your installation. You'll find the extensions and +\'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 \*(W3 +.SS New Features Supported With \'win32all\' One important note is in order here: The features enabled by -\*(W3 are only available on "true" Win32 systems like Windows +\'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, 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 \*(W3 installed on +without blowing-up so you can safely have \'win32all\' installed on one of these older systems to take advantage of the features that do work. @@ -3223,7 +3221,7 @@ .IP \(bu 4 Instead of showing Unix-style file permissions (which don't mean much -under Win32), systems with \*(W3 installed will show the +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: @@ -3241,7 +3239,7 @@ .ft \" revert .IP \(bu 4 -A top-level "Drive List View" is enabled if \*(W3 is installed. This +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 @@ -3258,7 +3256,7 @@ 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 - \*(CF STARTDIR option. + Configuration File STARTDIR option. .fi The "Drive List View" is available on all Win32 variants, however the @@ -3304,7 +3302,7 @@ .IP \(bu 4 The TOGWIN32ALL key (default: Control-w) is disabled in Drive List -View. Drive List View is only available in \*(W3 mode and +View. Drive List View is only available in \'win32all\' mode and toggling that mode off makes no sense here. .IP \(bu 4 @@ -3320,11 +3318,11 @@ .B do select it as is appropriate. -.SS Disabling \*(W3 Features +.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 \*(CF. -This allows you to leave \*(W3 installed on your system +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\' @@ -3430,7 +3428,7 @@ .SS Getting Command Results Displayed In A New Window When you invoke a command via \'twander\' (whether via a command -definition in the \*(CF or the keyboard shortcut), you +definition in the Configuration File or the keyboard shortcut), you generally want it to run in a new window. This turns out to be tricky on Unix-like systems. If the program you are running is GUI-aware, this should not be a problem. However, if you are using \'twander\' @@ -3661,7 +3659,7 @@ takes so long that as soon as one refresh finishes, the next starts right away. The program will appear to hang. There are two possibilities here. Either disable autorefreshing (via the -r command -line option or the AUTOREFRESH \*(CF option), or set the +line option or the AUTOREFRESH Configuration File option), or set the REFRESHINT value to some high number so that \'twander\' has plenty of time to process a directory before the next refresh occurs. @@ -3674,20 +3672,20 @@ .IP \(bu 4 By far the worst culprit here, though, is when running Win32 -with \*(W3 options enabled. It takes a lot more work +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 -off \*(W3 features alone can speed up directory processing +off \'win32all\' features alone can speed up directory processing by a factor as high as 4X. .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. -With \*(W3 processing enabled this took over a minute. +With \'win32all\' processing enabled this took over a minute. By disabling these features, the time came down to under 30 seconds. -.SS Your \*(CF Does Not Produce The Desired Results +.SS Your Configuration File Does Not Produce The Desired Results It's easy to fall into the trap of treating the \'twander\' configuration capabilities as a real "programming language". @@ -3739,7 +3737,7 @@ You have to be careful when overriding variable or command definitions. User-Defined Variables referenced in a Command Definition are de-referenced -.B at the time the Command Definition is encountered in the \*(CF. +.B at the time the Command Definition is encountered in the Configuration File. This means that if you change a User-Defined Variable after it has already been used in a Command Definition, only future references to that variable will reflect the change: @@ -3843,7 +3841,7 @@ appropriate release of Tkinter. This is the case, for example, with FreeBSD. -You must install the \*(W3 extensions if you want to use +You must install the \'win32all\' extensions if you want to use the advanced Win32 features. You'll find the latest version, and occasionally, Release Candidates @@ -3865,7 +3863,7 @@ use have been noted: .IP \(bu 4 -The \*(CF parser does no validation to check the sanity +The Configuration File parser does no validation to check the sanity 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 @@ -3878,7 +3876,7 @@ Tkinter/Tk/X-Windows. .IP \(bu 4 -Some \*(W3 features do not work correctly or at all on +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 @@ -3920,7 +3918,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 \*(CF, ".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. (You'll also find documentation for \'twander\' in various formats in this directory as well.) @@ -3987,19 +3985,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 \*(CF 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 \*(CF. +line option to point to this Configuration File. -On Win32, where to put the \*(CF 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 \*(CF. +where it can find its Configuration File. You can run the program several ways on Win32 systems: @@ -4113,7 +4111,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 \*(CF +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.