diff --git a/twander.1 b/twander.1 index 1338563..64d84fa 100644 --- a/twander.1 +++ b/twander.1 @@ -1,3 +1,4 @@ +.ds CF Configuration File .ds CP 2002-2003 .ds TW \'twander\' .ds W3 \'win32all\' @@ -16,7 +17,7 @@ filesystem, but .B you define the commands you want available via "Command Definitions" -in the Configuration File. +in the \*(CF. If you're new to \*(TW and want to know why this program is better and different than whatever you're @@ -44,15 +45,15 @@ will display an error message and abort. .TP -.B -c path/name of Configuration File +.B -c path/name of \*(CF Specify the location and name of the configuration file. (default is ~/.twander) If this file does not exist or cannot be opened, \*(TW will display a warning to that effect but continue to run. This is reasonable behavior because \*(TW provides a command to reload -the Configuration File without exiting the program (which you would -presumably do after fixing the Configuration File problem). +the \*(CF without exiting the program (which you would +presumably do after fixing the \*(CF problem). .TP .B -d debuglevel @@ -78,7 +79,7 @@ 5 0x020 Dump Directory Stack As It Changes 6 0x040 Dump Command History Stack After Command Executes 7 0x080 Dump Contents Of Program Memories As They Change -8 0x100 Reserved/Unused +8 0x100 Dump Contents Of Wildcard Stack As It Changes 9 0x200 Reserved/Unused 10 0x400 Reserved/Unused 11 0x800 Dump Requested Debug Information And Exit Immediately @@ -148,7 +149,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 Configuration File. This +by setting the appropriate entries in the \*(CF. This is covered later in this document. \*(TW evaluates options in the following order (from first @@ -158,7 +159,7 @@ Internally set default value of options .IP \(bu 4 -Options set in the Configuration File +Options set in the \*(CF .IP \(bu 4 Options set in the TWANDER environment variable @@ -169,23 +170,23 @@ .P This means, for example, that the environment variable overrides a -corresponding setting in the Configuration File, but the command line +corresponding setting in the \*(CF, but the command line overrides the environment variable. Furthermore, there are many Program Options which can .B only -be set/changed the Configuration File and are not available in +be set/changed the \*(CF 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 Configuration File has been processed. So, the -q +until after the \*(CF has been processed. So, the -q argument on the command line will not inhibit warnings generated -during the reading of the Configuration File. This is best done by +during the reading of the \*(CF. This is best done by adding the statement, WARN=False, at the top of the Configuration File. -If the Configuration File is reloaded while the program is running +If the \*(CF 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 Configuration File and +the last word. This allows you to edit the \*(CF and have your changes reflected in a running instance of \*(TW, but it also means that the environment variable/command line arguments are ignored after initial program startup. @@ -197,7 +198,7 @@ using only the keyboard. Various \*(TW features are thus associated with particular keystrokes which are described below. It is also very simple to change the default key assignments with entries -in the Configuration File, also described below. +in the \*(CF, also described below. .SH NOTES ON KEYBOARD ARROW/KEYPAD BEHAVIOR AND TEXT DIALOG EDITS @@ -264,7 +265,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 Configuration File. +even in the \*(CF. .SS General Program Commands @@ -327,9 +328,9 @@ available in all sizes/weights like they are on Win32 TrueType) as you change the font size with FONTDECR/FONTINCR. -Reloading the Configuration File (READCONF) will reset the fonts +Reloading the \*(CF (READCONF) will reset the fonts to either their default values or any font sizes specified in the -Configuration File. +\*(CF. .TP .B Display Command Menu (MOUSECTX) @@ -338,7 +339,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 Configuration File, via selection in the +Command Key defined in the \*(CF, via selection in the Command Menu at the top of the GUI, or via selection from the Command Menu. @@ -377,20 +378,20 @@ Exit the program. .TP -.B Re-Read Configuration File (READCONF) +.B Re-Read \*(CF (READCONF) Control-r -Re-read the Configuration File. This allows you to edit the -Configuration File while \*(TW is running and then read your +Re-read the \*(CF. This allows you to edit the +\*(CF while \*(TW 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 -Configuration File is about to be read (initially or on reload) just -before the Configuration File is parsed. This means commenting out or +\*(CF is about to be read (initially or on reload) just +before the \*(CF is parsed. This means commenting out or removing a Program Option Statement (see relevant section below) in -the Configuration File and then pressing READCONF causes that option to +the \*(CF 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. @@ -567,7 +568,135 @@ Select first item in the directory. This will always be the ".." entry, but it is a quick way to get to the first part of a very long directory listing which does not all fit on-screen. -.PP + +.TP +.B Select Using Regular-Expression \'Wildcards\' (SELWILD) +Control-\\ + +Although \*(TW provides a very rich set of keyboard and mouse +selection commands, selecting a group of files out of list +of hundreds or thousands in a large directory can be tedious. +If the files/directories you want to select have some lexical commonality +.B in their names OR details +you can have \*(TW select them for you using so-called "Regular +Expressions". The idea here is that you press SELWILD +and enter a "matching" string or regular expression, and \*(TW will +select all entries which match this criteria for you. For example, if +you just enter the text, + +.nf +tar +.fi + +\*(TW would select every file or directory in the current display +where the string "tar" +.B appeared anywhere on the line for that file/directory. +This is very important: Wildcard matching takes place anywhere on the +visible line. So, if you have details turned on, the match can occur +anywhere on the permissions, links, group, owner, and so on. +Obviously, if you have details turned off, the match can only occur on +the name of the file or directory since that's all that is visible. + +This is a purposeful design decision because it allows you to +make selections on more than just the name. Say you enter the +following in the SELWILD dialog: + +.nf +drwx------ +.fi + +\*(TW will select all directories with no permissions enabled for +group or world users. + + +The matching string above could also select other entries (not having +the permissions just described), if say, this string +appeared in their name ... a rather unlikely scenario, but not +impossible. If we want to get +.B real +specific about which entries we want selected, we need to +enter a "regular expression" in the SELWILD dialog. +Regular expressions are a far more powerful pattern-matching +tool than simple text strings and will allow you to do some +fairly amazing selections. For example, this regular expression +selects all entries which contain a string beginning with "Ju" +followed by any other character, a single space, and ending +in "0": + +.nf +Ju. 0 +.fi + +So, for instance, this would select files with date details (or names, +or anything else on the line...) like "Jun 01", "Jul 03", and "Jul +09". + +No matter what you specify, a literal matching string or a +regular expression, the ".." entry of the currently viewed +directory is never selected by SELWILD. + +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 +"*.txt" or "*.tar.gz", you will not get the results you expect. +In fact, these specific examples will cause \*(TW to grumble +and present a warning message. + +For an excellent tutorial on Python-compliant regular +expressions, see: + +.nf + http://www.amk.ca/python/howto/regex/ +.fi + +By default, SELWILD will select an entry when your regular expression +matches anything on the displayed line. This allows you to make +selections based on any visible column of information. This "match +anywhere on the line" semantic is possible because SELWILD +automatically massages the regular expression you provide to make "any +match on the line" true. There may be times when you want to provide +very specific regular expression definitions which seek a match at +specific locations. In that case, you can prevent SELWILD from +fiddling with your regular expression, by beginning it with the +double-quote (") character. SELWILD understands this to mean that +your regular expression is to be treated literally without +modification. (It only throws away this leading escape character.) + +Suppose we changed our example above slightly and used this +regular expression: + +.nf +"^drwx------ +.fi + +Now \*(TW would select +.B only +the directories without any group and world access because: + +.IP \ 10 +The leading double-quote (") forces literal interpretation of the +regular expression - i.e. It turns off "match anywhere" semantics +as just described. + +The carat (^) at the beginning of the actual regular expression +"anchors" the match to the start of the line. For a match +to be declared (and for \*(TW to select an item) the regular +expression must be satisfied at the beginning-of-line. + +.P +.IP +Because regular expressions can get complicated and tedious to type +in, any such expression you use is saved in a history available via +the Wildcard Menu (see below). + +There is also provision for pre-defining frequently used +selection wildcards in your \*(CF (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. + +.TP +.B Mouse-Based Selections The mouse can also be used to select one or more items. A single-click of the left mouse button selects a particular item. @@ -579,6 +708,7 @@ (non-adjacent) item is then selected by holding down the "Control" key when clicking on the item. + .SS Scrolling Commands If a given directory's contents cannot be displayed on a single @@ -619,7 +749,7 @@ Control-z This is a shortcut that allows you to run any command you'd like -without having to define it ahead of time in the Configuration File. +without having to define it ahead of time in the \*(CF. It is more-or-less like having a miniature command line environment at your disposal. @@ -700,7 +830,7 @@ .B Run User-Defined Command User-Defined (Single Letter) Key -Each command defined in the Configuration File has a Command Key +Each command defined in the \*(CF 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. @@ -709,7 +839,7 @@ \*(TW 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 Configuration File. Each of the +"Directory Shortcuts" in the \*(CF. Each of the definitions is associated with one of the following 12 keys: .TP @@ -719,8 +849,8 @@ .PD Pressing one of these keys changes to the directory associated with it -in the Configuration File. For more information on this topic, see -the discussion of the Configuration File below entitled, +in the \*(CF. For more information on this topic, see +the discussion of the \*(CF below entitled, .B Directory Shortcut Statements. .SS Program Memories @@ -809,18 +939,18 @@ .SS Commands Menu (Alt-c) [Right-Mouse-Button] -Every command defined in the Configuration File is listed in this menu +Every command defined in the \*(CF is listed in this menu by its Command Name. The association Command Key is also shown in parenthesis. Clicking on an item in this menu is the same as invoking it from the keyboard by its Command Key. This is a convenient way to invoke an infrequently used command whose Command Key you've forgotten. It is also handy to confirm which commands are defined -after you've edited and reloaded the Configuration File. The commands +after you've edited and reloaded the \*(CF. The commands are listed in the order in which they are defined in the configuration file. This allows most frequently used commands to appear at the top -of the menu by defining them first in the Configuration File. If no -commands are defined, either because the Configuration File contains -no Command Definitions or because the Configuration File cannot +of the menu by defining them first in the \*(CF. If no +commands are defined, either because the \*(CF contains +no Command Definitions or because the \*(CF cannot be opened for some reason, the Commands Menu will be disabled (grayed out). @@ -867,7 +997,7 @@ \*(TW keeps track of every command you attempt to execute, whether it is an invocation of a Command Definition found in the -Configuration File or a manually entered command via the RUNCMD key. +\*(CF or a manually entered command via the RUNCMD key. (default: Control-z) This is done whether or not the command is successfully executed. @@ -891,14 +1021,14 @@ It defaults to 250. One other point of clarification is in order here. If you run -one of the commands defined in your Configuration File, it is +one of the commands defined in your \*(CF, 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 Configuration File are written +(Presumably, Command Definitions in the \*(CF 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 @@ -909,6 +1039,38 @@ The History Menu is emptied and grayed out when you press the CLRHIST key. (default: Control-y) + +.SS Wildcard Menu (Alt-w) [Alt-Control-Right-Mouse-Button] + +\ + +(Note that on Win32 you must press Alt +.B then +Control +.B then +Right-Mouse-Button for this to work. Win32 appears to care deeply +about keystroke order.) + +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 +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. + +Selecting something from this menu brings up a dialog box which +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., +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. + .SS Help Menu (Alt-l) [No Mouse Shortcut] This menu provides information about various internal settings of @@ -934,9 +1096,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 -"Configuration File". This file is also used to set Program Options +"\*(CF". 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 +without a \*(CF present, it will warn you that it is doing so with no commands defined. @@ -951,16 +1113,16 @@ ) Actually, \*(TW can look in a number -of places to find its Configuration File. It does this using +of places to find its \*(CF. It does this using the following scheme (in priority order): .IP \(bu 4 If the -c argument was given on the command line, use this argument -for a Configuration File. +for a \*(CF. .IP \(bu 4 If -c was not given on the command line, but the HOME environment -variable is set, look for the a Configuration File as $HOME/.twander. +variable is set, look for the a \*(CF as $HOME/.twander. .IP \(bu 4 If the HOME environment variable is not set @@ -972,7 +1134,7 @@ .SH CONFIGURATION FILE FORMAT -\*(TW Configuration Files consist of freeform lines of text. +\*(TW \*(CFs 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. @@ -985,6 +1147,7 @@ Program Option Statements Key Binding Statements Directory Shortcut Statements +Wildcard Statements Variables And Command Definitions .fi @@ -993,13 +1156,13 @@ Everything else is considered invalid. \*(TW will respond with errors or warnings as is appropriate anytime it encounters a problem -in a Configuration File. An error will cause the program to +in a \*(CF. An error will cause the program to terminate, but the program continues to run after a warning. For the most part, \*(TW 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 -Configuration File reloads initiated from the keyboard while running +\*(CF reloads initiated from the keyboard while running \*(TW. The following sections describe each of the valid Configuration @@ -1008,7 +1171,7 @@ .SS Comments A comment is begun with the "#" character which may be placed anywhere -on a line. Comments may appear freely within a Configuration File. +on a line. Comments may appear freely within a \*(CF. \*(TW 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 @@ -1027,7 +1190,7 @@ .SS Program Option Statements Many of \*(TWs internal program defaults can be overriden in the -Configuration File using Program Option statements. These statements +\*(CF using Program Option statements. These statements look just like the User-Defined variables described later in this document except \*(TW recognizes the variable name as a Program Option rather than an arbitrary variable. Program Option Statements @@ -1121,7 +1284,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\' -Configuration File provided in the program distribution, you'll see +\*(CF provided in the program distribution, you'll see something like (comments removed): .nf @@ -1147,7 +1310,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 -Configuration File: +\*(CF: .nf CMDSHELL = xterm -l -e bash -c @@ -1162,7 +1325,7 @@ To disable CMDSHELL operation .B permanently, -just remove the statement above from your Configuration File. If you +just remove the statement above from your \*(CF. If you want to leave it in as a placeholder, but deactivate CMDSHELL, use the following statement (since the RHS of a string variable cannot be blank): @@ -1173,7 +1336,7 @@ You also may want to occasionally use RUNCMD to do something without CMDSHELL processing, even though that feature has been defined in the -Configuration File. You can disable CMDSHELL operation on a +\*(CF. You can disable CMDSHELL operation on a per-RUNCMD basis. Just begin your entering your command with the backslash (\\) character. \*(TW understands this to "escape" CMDSHELL processing. @@ -1195,7 +1358,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 Configuration File: +printer. Just add this line to your \*(CF: .nf DEBUGLEVEL = 0x004 @@ -1374,7 +1537,7 @@ The NODETAILS and NONAVIGATE commands are .B not security features. They can easily be defeated by editing the -Configuration File. They exist to make it easy for you to create +\*(CF. 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 @@ -1506,12 +1669,12 @@ Setting this option to False is the same thing as using the -q command line option with one important difference: The -Configuration File is parsed before the command line is +\*(CF 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 Configuration File, you will see warning messages +your \*(CF, you will see warning messages at program startup time. Putting WARN=False at the -top of your Configuration File will suppress this. +top of your \*(CF will suppress this. It is not recommended that you operate normally with the -q flag or with WARN=False. \*(TW is pretty @@ -1529,7 +1692,7 @@ .IP \(bu 4 You can set the same option multiple times in a single -Configuration File - \*(TW pays no attention. +\*(CF - \*(TW pays no attention. However, only the .B last (the one nearest the end of the file) instance of that Program Option @@ -1555,7 +1718,7 @@ usually ugly, so try to specify font information for things that actually exist on your system. -If your setting in the Configuration File seems not to work, take a +If your setting in the \*(CF seems not to work, take a look at the command window in which you started \*(TW (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 @@ -1587,7 +1750,7 @@ Say MAXDIR and MAXHIST are set to 4, but you've actually visited 20 different directories and issued 30 commands. You'll only see 4 of each. But, if you edit MAXDIR and MAXHIST to now be 32 and reload the -Configuration File, you will see all 20 directories and 30 commands on +\*(CF, you will see all 20 directories and 30 commands on their respective menus. .IP \(bu 4 @@ -1627,16 +1790,16 @@ differ considerably on what keys should be bound to what feature. \*(TW 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. +via entries in the \*(CF. This feature is available only for .B Keyboard Assignments. Mouse Button Assignments may not be changed by the user. An attempt -to do so in the Configuration File will cause \*(TW to display a +to do so in the \*(CF will cause \*(TW to display a warning and ignore the offending line. It is not difficult to override the default keyboard bindings by -adding entries in the Configuration File. Doing so requires some +adding entries in the \*(CF. Doing so requires some familiarity with how Tkinter names keystrokes. Good resources for learning this exist abundantly on the Internet, among them: @@ -1652,7 +1815,7 @@ both in print and on the Internet.) Keyboard binding assignments look just like variable definitions -in the Configuration File. (The \*(TW Configuration File parser +in the \*(CF. (The \*(TW \*(CF 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 @@ -1668,7 +1831,7 @@ to the desired keystroke. Examples of all the default key bindings are shown as comments in the -".twander" example Configuration File supplied in the program +".twander" example \*(CF 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. @@ -1697,7 +1860,7 @@ .IP \(bu 4 The Program Function Name variables (the left side of the assignment) may not be used as names for your own user-defined variables elsewhere -in the Configuration File. In fact, \*(TW will never even +in the \*(CF. In fact, \*(TW will never even recognize such an attempt. For example, suppose you try to do this: .nf @@ -1713,8 +1876,8 @@ User-Defined variable of that name in its symbol table. .IP \(bu 4 -When you're done making changes to the Configuration File, be sure to -either restart the program or reload the Configuration File to assign +When you're done making changes to the \*(CF, be sure to +either restart the program or reload the \*(CF to assign the new bindings. .IP \(bu 4 @@ -1729,7 +1892,7 @@ \*(TW 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 Configuration File which +Shortcut Statements are entries in the \*(CF which associate one of these keys with a particular directory path. These statements are in the form: @@ -1772,7 +1935,7 @@ .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 +\*(CF 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 \*(TW also @@ -1826,6 +1989,27 @@ any combination of three variable types: User-Defined Variables, Environment Variables, and Built-In Variables. +.SS Wildcard Statements + +As discussed above, \*(TW provides powerful regular +expression-based "wildcard" selection capabilities +via the SELWILD command. (default: Control-\\) These +regular expressions can be complex and tedious to enter +by hand each time you need them. You can pre-defined +frequently needed wildcard strings in your Configuration +File using the following statement: + +.nf +WILDCARD = regular-expression-string +.fi + +This regular expression will then be pre-loaded into the Wildcard Menu +(making it easy to invoke by just clicking on it) when \*(TW starts. +You may place as many of these as you like in your \*(CF. +(Though the menu will be limited to displaying MAXMENU number of items - +see the section above on Program Option Statements.) + + .SS User-Defined Variables And Environment Variables User-Defined Variables are defined using the syntax: @@ -1861,8 +2045,8 @@ .fi Why bother with this? Because it makes maintaining complex -Configuration Files easier. If you look in the example ".twander" -Configuration File provided in the program distribution, you will see +\*(CFs easier. If you look in the example ".twander" +\*(CF provided in the program distribution, you will see this is mighty handy when setting up complex "xterm" sessions, for example. @@ -1917,7 +2101,7 @@ .fi This recursive definition is a no-no and will be cause \*(TW -to generate an error while parsing the Configuration File and then +to generate an error while parsing the \*(CF and then terminate. Your variable definitions can also nest other kinds of variables @@ -1996,7 +2180,7 @@ .IP \(bu 4 Variable Names may not be redefined. This means you can only define a -given Variable Name once per Configuration File. It is also +given Variable Name once per \*(CF. It is also considered a variable redefinition if you try to use a variable name which matches either one of the Built-In Variables (used in Command Definitions) or one of the Program Function Names (used for Key @@ -2021,7 +2205,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 Configuration File. If \*(TW finds multiple Command +given \*(CF. If \*(TW 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 @@ -2033,7 +2217,7 @@ of the command which is used to invoke the command from the Command Menu. Command Names are case-sensitive ("command" and "Command" are different names), but they are not required to be unique within a -given Configuration File. That is, two different Command Definitions +given \*(CF. That is, two different Command Definitions may have identical Command Names associated with them, though this is not ordinarily recommended. @@ -2076,7 +2260,7 @@ using the string "xterm -l -e" over and over again for any shell commands we'd like to see run in a new window. Why not create a User-Defined Variable for this string so we can simplify its use -throughout the whole Configuration File? Now, our command looks +throughout the whole \*(CF? Now, our command looks like this: .nf @@ -2271,7 +2455,7 @@ Earlier releases of \*(TW .B did include the trailing path separator and you may have to edit -older Configuration Files accordingly. This change was necessary +older \*(CFs accordingly. This change was necessary because certain commands like Unix \'cp\' will not work if given a source directory with the path separator included.) @@ -2314,7 +2498,7 @@ .IP \(bu 4 User-Defined and Environment Variables are processed -at the time the Configuration File is read by \*(TW. That +at the time the \*(CF is read by \*(TW. That is, they are handled .B once at load time. @@ -2432,7 +2616,7 @@ 3) Press the DRIVELIST key. (default: Control-k) 4) Start \*(TW using "\\\\" as the starting directory argument, either on the command line or using the - Configuration File STARTDIR option. + \*(CF STARTDIR option. .fi The "Drive List View" is available on all Win32 variants, however the @@ -2497,7 +2681,7 @@ .SS Disabling \*(W3 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. +setting the USEWIN32ALL option to False in the \*(CF. This allows you to leave \*(W3 installed on your system if you need it for other reasons but don't want these features enabled in \*(TW @@ -2575,7 +2759,7 @@ .SS Getting Command Results Displayed In A New Window When you invoke a command via \*(TW (whether via a command -definition in the Configuration File or the keyboard shortcut), you +definition in the \*(CF 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 \*(TW @@ -2747,7 +2931,7 @@ If not (\*(TW is locked out while the new command runs - so-called "modal" operation), it means your system does not completely or correctly implement threading. In this case, -try adding this statement to your Configuration File: +try adding this statement to your \*(CF: "USETHREADS=False" which will force \*(TW to invoke new commands using conventional (heavyweight) process spawning. @@ -2769,7 +2953,7 @@ seems to not be properly informed that the window size has changed. This seems to be an interaction caused by running such programs as threads rather than processes. Once again, the workaround here is -to set "USETHREADS=False" in the Configuration File. +to set "USETHREADS=False" in the \*(CF. .SS Really Slow Response Times When Changing To A New Directory @@ -2788,7 +2972,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 Configuration File option), or set the +line option or the AUTOREFRESH \*(CF option), or set the REFRESHINT value to some high number so that \*(TW has plenty of time to process a directory before the next refresh occurs. @@ -2814,7 +2998,7 @@ With \*(W3 processing enabled this took over a minute. By disabling these features, the time came down to under 30 seconds. -.SS Your Configuration File Does Not Produce The Desired Results +.SS Your \*(CF Does Not Produce The Desired Results It's easy to fall into the trap of treating the \*(TW configuration capabilities as a real "programming language". @@ -2959,7 +3143,7 @@ use have been noted: .IP \(bu 4 -The Configuration File parser does no validation to check the sanity +The \*(CF 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 @@ -3012,7 +3196,7 @@ .SS Installing Using The FreeBSD Port If you've installed \*(TW using the FreeBSD port, all you have -to do is copy the example Configuration File, ".twander" found in +to do is copy the example \*(CF, ".twander" found in /usr/local/share/doc/twander to your home directory and edit it to taste. @@ -3076,19 +3260,19 @@ named this way with the standard Windows programs and utilities. This is especially the case for older Win32 operating systems like Win98. For this reason, it is recommended that you rename the ".twander" -default Configuration File provided in the program distribution to +default \*(CF provided in the program distribution to something else like "twander.conf" and use the \*(TW -c command -line option to point to this Configuration File. +line option to point to this \*(CF. -On Win32, where to put the Configuration File raises an interesting +On Win32, where to put the \*(CF 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 \*(TW with the -c argument to explictly declare -where it can find its Configuration File. +where it can find its \*(CF. You can run the program several ways on Win32 systems: @@ -3196,7 +3380,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 \*(CF 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 \*(TW every time.