diff --git a/twander.1 b/twander.1 index 120b938..2357670 100644 --- a/twander.1 +++ b/twander.1 @@ -1019,6 +1019,9 @@ A Boolean Option must be assigned a value of True or False. These logical values can be in any case, so TRUE, TRue, and tRue all work. +Note that if you view these variables in the Help menu entitled, +.B User-Settable Options, +they are displayed as 0 (False) and 1 (True). A Numeric Option must be a number 0 or greater. Numbers can also be entered in hexadecimal format: 0x#, where # is the @@ -1063,13 +1066,13 @@ refresh the display with any changes. If you are running on a very slow machine or slow connection between the X-Windows server and client, set this option to False. You can manually force an update at -any time using the REFRESH key. (default: Control-l) +any time using the REFRESH key (default: Control-l). .TP .B BCOLOR [String] (Black) -This selects the main display Background Color. +Selects the main display Background Color. .TP .B CMDSHELL [String] ("") @@ -1108,7 +1111,7 @@ That's all well and good for Command Definitions, but what happens when you want to .B manually enter a command -via the RUNCMD key? (default: Control-z) You have to manually +via the RUNCMD key (default: Control-z)? You have to manually enter the gobbledy-gook above, or at least start your command with [VSHELL] (since RUNCMD understands variable references). @@ -1149,7 +1152,11 @@ .B anything you like before a manually entered command - literal text, references to variables, or even the name of a script the system will use to execute -your command. +your command. Whatever value you use for CMDSHELL will appear in the +Command Menu history for each manually initiated command which +used this feature - i.e., All the manual commands that +.B did not +escape the feature. .TP .B DEBUGLEVEL [Numeric] (0) @@ -1165,9 +1172,9 @@ .fi .TP -.B FCOLOR [String] (Green) +.B FCOLOR [String] (green) -This selects the main display Foreground (Text) Color. +Selects the main display Foreground (Text) Color. .TP .B FNAME [String] (Courier) @@ -1189,22 +1196,22 @@ .TP .B HBCOLOR [String] (lightgreen) -This selects the help menu Background Color. +Selects the help menu Background Color. .TP .B HEIGHT [Numeric] (600) -This selects the initial height of the \'twander\' window (in pixels). +Initial vertical offset of the \'twander\' window in pixels. .TP .B HFCOLOR [String] (black) -This selects the help menu Foreground (Text) Color. +Selects the help menu Foreground (Text) Color. .TP .B HFNAME [String] (Courier) -This selects the help menu Font Name. +Selects the help menu Font Name. .TP .B HFSZ [Numeric] (10) @@ -1216,10 +1223,287 @@ This selects the help menu Font Weight. +.TP +.B MAXDIR [Numeric] (32) +Maximum number of entries to +.B display +in the Directory Menu. This keeps the menu size reasonable. +Internally, \'twander\' keeps track of way more than this +number of directories (see the MAXDIRBUF option below). + +.TP +.B MAXDIRBUF [Numeric] (250) +Maximum number of visited directories \'twander\' +.B tracks internally. +This value need normally not be changed. It is present only +to bound how much memory \'twander\' consumes for this task. + +.TP +.B MAXHIST [Numeric] (32) + +Maximum number of entries to +.B display +in the History Menu. This keeps the menu size reasonable. +Internally, \'twander\' keeps track of way more than this +number of commands (see the MAXHISTBUF option below). + +.TP +.B MAXHISTBUF [Numeric] (250) +Maximum number of commands executed \'twander\' +.B tracks internally. +This value need normally not be changed. It is present only +to bound how much memory \'twander\' consumes for this task. + +.TP +.B MAXNESTING [Numeric] (32) + +Number of time a Command Definition is processed to dereference +all variables. For example, suppose you have this: + +.nf +FOO = bax +BAM = x[FOO] + +x mycmd [BAM] [SELECTION] +.fi + +When you press the x key, the \'twander\' command interpreter has to +process the line repeatedly until all variables are resolved: + +.nf +[BAM] [SELECTION] -> x[FOO] [SELECTION] +x[FOO] [SELECTION] -> xbax [SELECTION] +xbax [SELECTION] -> xbax selected-item +.fi + +So, in this case, it took 3 iterations to do this. MAXNESTING +merely sets the maximum number of times this is permitted. +We have to do this to stop runaway definitions like this: + +.nf +FOO = x[FOO] +.fi + +This kind of construct will cause \'twander\' to iterate +MAXNESTING number of times and then give up with +a warning about exeeding this limit. + +A 32 iteration limit should be plenty for any reasonable +Command Definitions. If you set MAXNESTING to 0, \'twander\' +will not allow *any* variable dereferencing, +.B including the Built-In Variables. +This is probably not what you want. + +.TP +.B MBARCOL [String] (beige) + +Selects the Menu Bar color. + +.TP +.B MBCOLOR [String] (beige) + +Selects the menu Background Color. + +.TP +.B MFCOLOR [String] (black) + +Selects the menu Foreground (text) Color. + +.TP +.B MFNAME [String] (Courier) + +Selects the menu Font Name. + +.TP +.B MFSZ [Numeric] (12) + +Selects the menu Font Size. + +.TP +.B MFWT [String] (bold) + +Selects the menu Font Weight. + +.TP +.B NODETAILS [Boolean] (False) + +Prevents details from ever being displayed. + +.TP +.B NONAVIGATE [Boolean] (False) + +Prevents the user from navigating out of the starting directory. +Command Definitions and commands initiated manually via RUNCMD +(default: Control-z) can still "see" other directories, the user +just cannot move elsewhere with any of the \'twander\' navigation +commands. + +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 +\'twander' configurations for technically unsophisticated users. + +Say you want to define a few simple commands for your boss to use +which won't challenge his or her feeble managerial mind ;) By +defining these commands and setting both NODETAILS and NONAVIGATE +to TRUE, you really limit what can be done with \'twander\'. +They can't wander off into other directories and get lost, or +worse yet, clobber files they don't understand. There are no +details to confuse them. Your instructions for using the program +thus become, "Select the files you're interested in and press +P to print them, M to mail them to Headquarters.." and so on. + +Again, +.B these are NOT security features. +Anyone with even very modest technical skills can thwart these +limitations. But, it is suprising just how effective these can be in +simplifying life for technically challenged users. + +.TP +.B QUOTECHAR [String] (") + +As described below, \'twander\' ordinarily quotes most Built-In +Variables as it replaces them during command processing. This +is useful because modern operating systems allow file and +directory names to have spaces in them. Such names must be +quoted for most programs to understand them as a single entity +on a command line. + +By default, the double-quote char is used for this purpose. +You can suppress quote processing by using the -t command +line argument. This does nothing more than set QUOTECHAR +to an empty string. Unfortunately, since the RHS of a +Program Option Statement cannot be blank, you cannot +disable quoting with this option. However, you +.B can +set the quotation character to be anything else you like, such as +a single-quote. In fact, you can set QUOTECHAR to any +.B string of characters +you like and they will faithfully be used on either side of +a Built-In Variable replacement. + +.TP +.B REFRESHINT [Numeric] (3000) + +Nominal time in milliseconds between automatic directory +refreshes (if AUTOREFRESH is True). This time is +.B really +nominal and should not be used with any accurate timing +in mind. REFRESHINT=5000 says that the refresh +interval will be nominally 5 seconds (and certainly more +than the default of 3 seconds), but it can be off this +nominal value by quite a bit. + +If you run \'twander\' on a slow system (or have a slow +link between X-Client and X-Server) you might want to +increase this value substantially. You can get into +the situtation where, just as one refresh completes, +its time to do the next one, and the \'twander\' +will seem really sluggish and unresponsive. + +.TP +.B STARTDIR [String] (Directory In Which Program Started) + +This allows you to force a starting directory of your choice no matter +where the program actually is launched. This is useful both for +day-to-day operation - perhaps you always want to start in you home +directory - and in tandem with the NODETAILS and NONAVIGATE options to +force a user to the only directory which they should be using. + +.TP +.B STARTX [Numeric] (0) + +Initial horizontal offset of the \'twander\' window in pixels. + +.TP +.B STARTY [Numeric] (0) + +Initial vertical offset of the \'twander\' window in pixels. + +.TP +.B USETHREADS [Boolean] (True) + +Normally, \'twander\' uses threads to run the commands you've +defined/entered and requested. As noted later in the +.B GOTCHAS +section, there are circumstances under which this does not +work properly. In this case setting USETHREADS=False, +will cause \'twander\' to use more traditional process +mechanics to run a command. + +This option applies only to Unix-like operating systems. +Win32 commands are +.B always +run as a thread - this is the only process model Win32 +supports.. + +.TP +.B USEWIN32ALL [Boolean] (True) + +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 +\'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 \'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 +TOGWIN32ALL key (default: Control-w) to temporarily disable these +features before entering such a directory. However, if your starting +directory is in this category, setting USEWIN32ALL=False might not +be a bad idea. + +.TP +.B WARN [Boolean] (True) + +Determines whether interactive warnings should be displayed +as \'twander\' encounters them (while parsing a Configuration +File or just in normal execution). + +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 +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 +at program startup time. Putting WARN=False at the +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 +forgiving in most cases and when it does warn you about +something, there is a good reason for it - you probably +want to know what the problem is. + +.TP +.B WIDTH [Numeric] (800) + +Initial width of the \'twander\' window in pixels. + +.P A few general notes about Program Options are worth mentioning here: .IP \(bu 4 +You can set the same option multiple times in a single +Configuration File - \'twander\' pays no attention. +However, only the +.B last +(the one nearest the end of the file) instance of that Program Option +Statement actually takes effect. This is handy if you want to +temporarily change something without modifying your existing +configuration. Just add your temporary change at the end of the file. +When you're done with it, just remove it. No need to edit and re-edit +your preferred configuration... + +.IP \(bu 4 The colors, weights, and sizes available for your use will vary somewhat by system. For instance, Win32 TrueType fonts are effectively available in every size and weight. On the other hand, @@ -1231,7 +1515,6 @@ will cause Python/Tkinter to dump traceback information on stdout. .IP \(bu 4 - Most systems attempt some kind of "best fit" font matching. If you specify a font size/weight/name that does not exist, the system will try to find what it thinks is the closest match. This is @@ -1239,12 +1522,43 @@ actually exist on your system. .IP \(bu 4 - Although you can use proportionally spaced fonts with \'twander\', the result is pretty ugly. \'twander\' assumes a fixed width font when it calculates display formatting. Variable-width fonts will cause your display to be ragged and hard to read. +.IP \(bu 4 +If you set MAXDIR or MAXDIRBUF to 0, it disables both the tracking of +visited directories and the retention of last manually entered +directory with CHANGEDIR (default: Control-x). + +.IP \(bu 4 +Similarly if you set MAXHIST or MAXHISTBUF to 0, you disable both +command history and the retention of the last manually entered command +via RUNCMD (default: Control-z). + +.IP \(bu 4 +At first glance, the ability to set QUOTECHAR to any arbitary string +may seem silly, but it actually has a purpose. As good as the +\'twander\' macro capability is, it is still a fairly simple language. +Really complex tasks will need to be handed off to some other +scripting language (like Python!). It may be useful to delimit +Built-In Variables (which indicate your selections via the \'twander\' +interface) in such a way that your script knows where they came +from. So, say you set QUOTECHAR=+++ and you have a Command +Definition like this: + +.nf +x mycmd MyPythonScript [DSELECTIONS] other stuff +.fi + +When MyPythonScript runs, it can immediately tell which arguments +came from \'twander\' (the ones that are in the form +++dir+++ +or +++file+++) and which arguments are just other stuff. + +You probably won't need this often, but its nice to have. + + .SS Key Binding Statements No program that runs in many operating environments can satisfy @@ -1532,7 +1846,8 @@ Later on (when defining some command) when \'twander\' runs into the variable reference [FB], it will keep substituting variables until all -[...] references have been resolved or it hits the nesting limit (32). +[...] references have been resolved or it hits the nesting limit (The +default is 32, but you can change it with the MAXNESTING option). This limit has to be imposed to catch silly things like this: .nf @@ -1955,9 +2270,7 @@ default is recommended so that any built-in substitutions of, say, file names with spaces in them, will be properly recognized by your commands. You can suppress the addition of double-quotes by using the --t command line option when starting \'twander\'. You can also -suppress quoting by redefining the QUOTECHAR Program Option described -previously. +-t command line option when starting \'twander\'. .IP \(bu 4 Any of the variable types may appear multiple times in the