diff --git a/twander.1 b/twander.1 index 3241ed6..120b938 100644 --- a/twander.1 +++ b/twander.1 @@ -1014,6 +1014,237 @@ "AUTOREFRESH" as a Program Option, but will treat "AutoRefresh" as a User-Defined Variable. +The Option Value is checked to make sure it conforms to the proper +type for this variable. The Type can be Boolean, Numeric, or String. + +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. + +A Numeric Option must be a number 0 or greater. Numbers can +also be entered in hexadecimal format: 0x#, where # is the +numeric expression in hex. + +A String Option can be any string of characters but the empty string +is not allowed: + +.nf +# Bad String Option Assignment - Causes Warning +BCOLOR = +.fi + +Furthermore, as described above, you cannot use the \'#\' symbol +as part of the string assignment because \'twander\' always +treats this character as the beginning of a comment no matter +where it appears. + +Other than this basic type-checking, \'twander\' does no further +validation of the Right Hand Side of a Program Option Statement. +It is perfectly possible to provide a RHS which passes \'twander\'s +type validation but which makes no sense whatsoever to the program. +Entries like this cause everything from a mild \'twander\' warning +to a spectacular program failure and Python traceback on stdout: + +.nf +# A Nice Way To Clobber \'twander\' +BCOLOR = goo +.fi + +The following sections document each available Program Option +using this general format: + +.nf +Option-Name [Type] (Default Value) +.fi + +.TP +.B AUTOREFRESH [Boolean] (True) + +By default, \'twander\' regularly re-reads the current directory to +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) + + +.TP +.B BCOLOR [String] (Black) + +This selects the main display Background Color. + +.TP +.B CMDSHELL [String] ("") + +This option is primarily intended for people running \'twander\' on +Unix-like operating systems like FreeBSD and Linux. As described in +the +.B GOTCHAS +section below, running a command line program or script requires some +extra effort if you want to see the results presented in a GUI window. +Typically, you need to run these commands in some kind of \'xterm\' +context so that the results will be visible, possibly using a shell as +well. So, it's common to see Command Definitions like: + +.nf +x MyCommand xterm -l -e bash -c stuff-for-my-command +.fi + +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 +something like (comments removed): + +.nf +SHELL = bash -c +VSHELL = [XTERM] [SHELL] +XTERM = xterm -fn 9x15 -l -e +.fi + +Now the Command Definition above becomes: + +.nf +x MyCommand [VSHELL] stuff-for-my-command +.fi + +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 +enter the gobbledy-gook above, or at least start your command +with [VSHELL] (since RUNCMD understands variable references). + +The CMDSHELL option is a way to automate this. You can assign it +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: + +.nf +CMDSHELL = xterm -l -e bash -c + + - or - + +CMDSHELL = [VSHELL] # Assuming VSHELL is defined previously +.fi + +Now every time you enter a command, this will be placed in +front of your text before command execution commences. + +To disable CMDSHELL operation +.B permanently, +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 (since the RHS of a string variable cannot be +blank): + +.nf +CMDSHELL = "" +.fi + +If you want to disable CMDSHELL operation +.B for just a single manually entered command, +begin your command with the backslash (\\) character. \'twander\' +understands this to "escape" CMDSHELL processing. + +As a general matter, CMDSHELL allows you to prepend +.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. + +.TP +.B DEBUGLEVEL [Numeric] (0) + +This is another way to set the debugging level you desire (the other +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: + +.nf +DEBUGLEVEL = 0x004 +.fi + +.TP +.B FCOLOR [String] (Green) + +This selects the main display Foreground (Text) Color. + +.TP +.B FNAME [String] (Courier) + +This selects the Font Name for the main display. + +.TP +.B FSZ [Numeric] (12) + +This selects the main display Font Size. + +.TP +.B FWT [String] (bold) + +This selects the main display Font Weight. This can be assigned +to: normal, bold, italic, or underlined. Depending on your +system, other values may also be possible. + +.TP +.B HBCOLOR [String] (lightgreen) + +This selects the help menu Background Color. + +.TP +.B HEIGHT [Numeric] (600) + +This selects the initial height of the \'twander\' window (in pixels). + +.TP +.B HFCOLOR [String] (black) + +This selects the help menu Foreground (Text) Color. + +.TP +.B HFNAME [String] (Courier) + +This selects the help menu Font Name. + +.TP +.B HFSZ [Numeric] (10) + +This selects the help menu Font Size. + +.TP +.B HFWT [String] (italic) + +This selects the help menu Font Weight. + + +A few general notes about Program Options are worth mentioning here: + +.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, +most Unix-like systems have a more limited palette of fonts and colors +with which to work. If your setting in the Configuration File seems +not to work, take a look at the command windows in which you started +\'twander\' (or start it from one manually, if you're using a GUI +shortcut directly). Attempts to use unavailable colors and weights +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 +usually ugly, so try to specify font information for things that +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. + .SS Key Binding Statements No program that runs in many operating environments can satisfy