diff --git a/twander.1 b/twander.1 index 5d616af..218be31 100644 --- a/twander.1 +++ b/twander.1 @@ -26,7 +26,8 @@ .SH OPTIONS .TP .B startdir -Directory in which to begin. (default: ./) +Directory in which to begin. (default: directory in which program was +started) If this directory does not exist or cannot be opened, \'twander\' will display an error message and abort. @@ -128,7 +129,7 @@ on Unix: .nf -.B export TWANDER=-qt +export TWANDER=-qt .fi From then on, every time you run the program, the -q and -t options @@ -303,6 +304,18 @@ (12+1+1) which does not exist, and the menu and help text to 12 point (10+1+1) which does exist, so that change is visible. +The "User-Settable Options" Help Menu displays the font metrics (name, +size, weight) you've currently specified. Pressing FONTDECR/FONTINCR +changes the size specification and this will be reflected in that +menu. However, most system do some form of "best match" font +substitution - if you ask for a font that does not exist, the system +will use the "closest matching" font as a substitute. This means the +font you see specified in the Help Menu is not necessarily the font +you're actually using. You're more likely to run into this when +running on a Unix/X-Windows system (where not all the fonts are +available in all sizes/weights like they are on Win32 TrueType) as you +change the font size with FONTDECR/FONTINCR. + Reloading the Configuration File (READCONF) will reset the fonts to either their default values or any font sizes specified in the Configuration File. @@ -549,7 +562,7 @@ single-click of the left mouse button selects a particular item. Clicking and dragging selects an adjacent group of items. Clicking an item and then clicking a second item while holding down the "Shift" -key also selects an adjacent group of items. Finally, a group +key also selects an adjacent group of items. Finally, a group of non-adjacent items can also be selected. The first item is selected with a single left mouse button click as usual. Each subsequent (non-adjacent) item is then selected by holding down the "Control" @@ -608,7 +621,7 @@ selected files to a new directory, press RUNCMD and enter (on Unix): .nf -.B cp [SELECTIONS] newdir +cp [SELECTIONS] newdir .fi \'twander\' understands the variable reference syntax here just as it @@ -619,7 +632,7 @@ systems: .nf -.B [$EDITOR] [SELECTIONS] +[$EDITOR] [SELECTIONS] .fi Unless you have set the MAXHIST option to 0, RUNCMD keeps track of @@ -1008,7 +1021,7 @@ thus take the form: .nf -.B Option Name = Option Value +Option Name = Option Value .fi The Option Name is case-sensitive and must be entered exactly as @@ -1033,8 +1046,8 @@ is not allowed: .nf -.B # Bad String Option Assignment - Causes Warning -.B BCOLOR = +# Bad String Option Assignment - Causes Warning +BCOLOR = .fi Furthermore, as described above, you cannot use the \'#\' symbol @@ -1050,15 +1063,15 @@ to a spectacular program failure and Python traceback on stdout: .nf -.B # A Nice Way To Clobber \'twander\' -.B BCOLOR = goo +# A Nice Way To Clobber \'twander\' +BCOLOR = goo .fi The following sections document each available Program Option using this general format: .nf -.B Option-Name [Type] (Default Value) +Option-Name [Type] (Default Value) .fi .TP @@ -1090,7 +1103,7 @@ well. So, it's common to see Command Definitions like: .nf -.B x MyCommand xterm -l -e bash -c stuff-for-my-command +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 @@ -1099,15 +1112,15 @@ something like (comments removed): .nf -.B SHELL = bash -c -.B VSHELL = [XTERM] [SHELL] -.B XTERM = xterm -fn 9x15 -l -e +SHELL = bash -c +VSHELL = [XTERM] [SHELL] +XTERM = xterm -fn 9x15 -l -e .fi Now the Command Definition above becomes: .nf -.B x MyCommand [VSHELL] stuff-for-my-command +x MyCommand [VSHELL] stuff-for-my-command .fi That's all well and good for Command Definitions, but what happens @@ -1124,11 +1137,11 @@ Configuration File: .nf -.B CMDSHELL = xterm -l -e bash -c +CMDSHELL = xterm -l -e bash -c - or - -.B CMDSHELL = [VSHELL] # Assuming VSHELL is defined previously +CMDSHELL = [VSHELL] # Assuming VSHELL is defined previously .fi Now every time you enter a command, this will be placed in @@ -1142,7 +1155,7 @@ blank): .nf -.B CMDSHELL = "" +CMDSHELL = "" .fi You also may want to occasionally use RUNCMD to do something without @@ -1266,19 +1279,19 @@ all variables. For example, suppose you have this: .nf -.B FOO = bax -.B BAM = x[FOO] +FOO = bax +BAM = x[FOO] -.B x mycmd [BAM] [SELECTION] +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 -.B [BAM] [SELECTION] -> x[FOO] [SELECTION] -.B x[FOO] [SELECTION] -> xbax [SELECTION] -.B xbax [SELECTION] -> xbax selected-item +[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 @@ -1286,7 +1299,7 @@ We have to do this to stop runaway definitions like this: .nf -.B FOO = x[FOO] +FOO = x[FOO] .fi This kind of construct will cause \'twander\' to iterate @@ -1577,7 +1590,7 @@ Definition like this: .nf -.B x mycmd MyPythonScript [DSELECTIONS] other stuff +x mycmd MyPythonScript [DSELECTIONS] other stuff .fi When MyPythonScript runs, it can immediately tell which arguments @@ -1634,7 +1647,7 @@ variable names.) Key Binding Statements thus take the form: .nf -.B Program Function Name = Tkinter Keystroke Name +Program Function Name = Tkinter Keystroke Name .fi Changing the default bindings is therefore nothing more than a matter @@ -1662,11 +1675,11 @@ .B without any quotation marks. .nf -.B # Incorrect -.B QUITPROG = '' +# Incorrect +QUITPROG = '' -.B # Correct -.B QUITPROG = +# Correct +QUITPROG = .fi .IP \(bu 4 @@ -1676,7 +1689,7 @@ recognize such an attempt. For example, suppose you try to do this: .nf -.B QUITPROG = something-or-other +QUITPROG = something-or-other .fi Because you want to be able to reference [QUITPROG] in a subsequent @@ -1709,7 +1722,7 @@ These statements are in the form: .nf -.B DIRSCxx = path +DIRSCxx = path where, xx is a number from 1-12 .fi @@ -1719,7 +1732,7 @@ File: .nf -.B DIRSC5 = c:\\Documents And Settings +DIRSC5 = c:\\Documents And Settings .fi There are several subtleties to Directory Shortcuts you should @@ -1736,7 +1749,7 @@ .nf # This "undefines" shortcut #5 -.B DIRSC5 = +DIRSC5 = .fi .IP \(bu 4 @@ -1806,19 +1819,19 @@ User-Defined Variables are defined using the syntax: .nf -.B Variable Name = Replacement String +Variable Name = Replacement String .fi Environment Variables are referenced using the syntax: .nf -.B [$VARIABLE] +[$VARIABLE] .fi Say we have a configuration line like this, .nf -.B EDITOR = emacs blah blah blah blah +EDITOR = emacs blah blah blah blah .fi Later on, when defining a command, instead of typing in "emacs blah @@ -1832,7 +1845,7 @@ could thus become: .nf -.B EDITOR = [$EDITOR] blah blah blah blah +EDITOR = [$EDITOR] blah blah blah blah .fi Why bother with this? Because it makes maintaining complex @@ -1849,7 +1862,7 @@ definition that refers to another variable: .nf -.B NewVar = somestring [OldVar] +NewVar = somestring [OldVar] .fi It is important to realize that this only means: "If you encounter @@ -1876,9 +1889,9 @@ MAXNESTING Program Option). You can have constructs like: .nf -.B Var1 = Foo -.B Var2 = Bar -.B FB = [Var1][Var2] +Var1 = Foo +Var2 = Bar +FB = [Var1][Var2] .fi Later on (when defining some command) when \'twander\' runs into the @@ -1888,7 +1901,7 @@ This limit has to be imposed to catch silly things like this: .nf -.B Var = a[Var] +Var = a[Var] .fi This recursive definition is a no-no and will be cause \'twander\' @@ -1900,9 +1913,9 @@ OK: .nf -.B Var1 = [$PAGER] -.B Var2 = command-arguments -.B V = [Var1] [Var2] [DSELECTION] +Var1 = [$PAGER] +Var2 = command-arguments +V = [Var1] [Var2] [DSELECTION] .fi .IP \(bu 4 @@ -1922,16 +1935,16 @@ are actually needed: .nf -.B Var1 = foo -.B Var2 = [Var3] # This is just a string substitution, not a reference -.B Var3 = bar -.B MyVar = [Var1][Var2] +Var1 = foo +Var2 = [Var3] # This is just a string substitution, not a reference +Var3 = bar +MyVar = [Var1][Var2] -.B # Now comes the Command Definition -.B # If we put this before the Variable Definitions above, -.B # it would be an error. +# Now comes the Command Definition +# If we put this before the Variable Definitions above, +# it would be an error. -.B x mycommand [MyVar] +x mycommand [MyVar] .fi .IP \(bu 4 @@ -1960,7 +1973,7 @@ named "something". If you do this: .nf -.B $MYVAR = some-string +$MYVAR = some-string .fi You will never be able to subsequently reference it because, @@ -1987,7 +2000,7 @@ fields separated by whitespace: .nf -.B Command-Key Command-Name Command-String +Command-Key Command-Name Command-String .fi The @@ -2022,8 +2035,8 @@ In its simplest form, a Command Definition looks like this: .nf -.B # A simple Command Definition -.B m MyMore more somefile +# A simple Command Definition +m MyMore more somefile .fi This command can be invoked pressing the "m" key on the keyboard or @@ -2041,8 +2054,8 @@ this: .nf -.B # Our command setup to run as a GUI window -.B m MyMore xterm -l -e more somefile +# Our command setup to run as a GUI window +m MyMore xterm -l -e more somefile .fi .SS User-Defined Variables In A Command String @@ -2055,12 +2068,12 @@ like this: .nf -.B # Our command enhanced with a User-Defined Variable. -.B # Remember that the variable has to be defined *before* -.B # it is referenced. +# Our command enhanced with a User-Defined Variable. +# Remember that the variable has to be defined *before* +# it is referenced. -.B XTERM = xterm -l -e # This defines the variable -.B m MyMore [XTERM] more somefile # And the command then uses it +XTERM = xterm -l -e # This defines the variable +m MyMore [XTERM] more somefile # And the command then uses it .fi .SS Environment Variables In A Command String @@ -2074,11 +2087,11 @@ looks like this: .nf -.B # Our command using both a User-Defined Variable and -.B # an Environment Variable to make it more general +# Our command using both a User-Defined Variable and +# an Environment Variable to make it more general -.B XTERM = xterm -l -e -.B m MyMore [XTERM] [$PAGER] somefile +XTERM = xterm -l -e +m MyMore [XTERM] [$PAGER] somefile .fi .SS Built-In Variables In A Command String @@ -2099,11 +2112,11 @@ .nf -.B # Our command in its most generic form using -.B # User-Defined, Environment, and Built-In Variables +# Our command in its most generic form using +# User-Defined, Environment, and Built-In Variables -.B XTERM = xterm -l -e -.B m MyMore [XTERM] [$PAGER] [DSELECTION] +XTERM = xterm -l -e +m MyMore [XTERM] [$PAGER] [DSELECTION] .fi The "DSELECTION" built-in is what communicates the currently @@ -2187,16 +2200,16 @@ command: .nf -.B # Copy a group of items to a location set by -.B # the user at runtime -.B UnixCopy = cp -R -.B Win32Copy = copy +# Copy a group of items to a location set by +# the user at runtime +UnixCopy = cp -R +Win32Copy = copy -.B # Unix Version -.B c UnixCP [UnixCopy] [DSELECTIONS] [PROMPT:Enter Destination] +# Unix Version +c UnixCP [UnixCopy] [DSELECTIONS] [PROMPT:Enter Destination] -.B # Win32 Version -.B C Win32CP [Win32Copy] [DSELECTIONS] [PROMPT:Enter Destination] +# Win32 Version +C Win32CP [Win32Copy] [DSELECTIONS] [PROMPT:Enter Destination] .fi .IP \(bu 4 @@ -2212,7 +2225,7 @@ their intentions: .nf -.B D BigDelete [YESNO:Are You Absolutely Sure About This?] rm -rf [SELECTIONS] +D BigDelete [YESNO:Are You Absolutely Sure About This?] rm -rf [SELECTIONS] .fi .SS Program Memory Built-Ins @@ -2231,7 +2244,7 @@ a move command like this: .nf -.B m move mv [MEM1] ./ +m move mv [MEM1] ./ .fi .SS Notes On Built-In Variable Use @@ -2254,24 +2267,24 @@ selected item is: .nf -.B # Unix Path Separator -.B UPSEP = / +# Unix Path Separator +UPSEP = / -.B #Win32 Path Separator -.B WPSEP = \\ +#Win32 Path Separator +WPSEP = \\ -.B [DIR][UPSEP][SELECTION] +[DIR][UPSEP][SELECTION] - or - -.B [DIR][WPSEP][SELECTION] +[DIR][WPSEP][SELECTION] .fi Be aware that, because of \'twander\' quoting rules, such constructs will result in strings like: .nf -.B "/mydir"/"myfile" +"/mydir"/"myfile" - or - @@ -2313,7 +2326,7 @@ define a generic Unix copy command: .nf -.B g gencopy cp -R [PROMPT:Enter Source] [PROMPT:Enter Destination] +g gencopy cp -R [PROMPT:Enter Source] [PROMPT:Enter Destination] .fi When the user presses "g" (or clicks on "gencopy" on the Command @@ -2498,7 +2511,7 @@ taking place. A simple way to do this with \'ksh\' or \'bash\' is: .nf -.B export HOSTNAME=`hostname` +export HOSTNAME=`hostname` .fi (Note the backticks used to execute the \'hostname\' program @@ -2533,15 +2546,15 @@ text: .nf -.B encoding = "ascii" # Default value set by _PyUnicode_Init() +encoding = "ascii" # Default value set by _PyUnicode_Init() -.B if 0: -.B # Enable to support locale aware default string encodings. -.B import locale +if 0: + # Enable to support locale aware default string encodings. + import locale .fi Change the -.B if 0: +.B if 0: statement to .B if 1: and the problem will disappear. @@ -2549,18 +2562,19 @@ .SS Getting Command Results Displayed In A New Window -When you invoke a command via \'twander\', whether via a command -definition in the Configuration File or the keyboard shortcut, you -generally want it to run in a new window. If the program you are -running is GUI-aware, this should not be a problem. However, if you -are using \'twander\' to run a command line program or script, you -have to take extra care in the formulation of the Command String. -In the case of Unix-like systems you have to invoke the command -so that it runs in some GUI context. Say you want to use a pager like -\'less\' to view files. You would expect that this entry might do it: +When you invoke a command via \'twander\' (whether via a command +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\' +to run a command line program or script, you have to take extra care +in the formulation of the Command String. In the case of Unix-like +systems you have to invoke the command so that it runs in some GUI +context. Say you want to use a pager like \'less\' to view files. +You would expect that this entry might do it: .nf -.B V view less [DSELECTIONS] +V view less [DSELECTIONS] .fi Sadly, this will not work, at least not the way you expect. @@ -2573,19 +2587,130 @@ a \'nohup\' ... & invocation, you will get .B no output. This is not a \'twander\' problem, it is innate to how -command line programs run under Unix shell control. To achieve the -desired results, you'll need something like this in your Configuration -File: +command line programs run under Unix shell control. + +To achieve the desired results, you have to create a new GUI window in +which your command can run and display results. The easiest way to do +this is to run your command in a new \'xterm\' window like this: .nf -.B V view xterm -l -e less [DSELECTIONS] +V view xterm -l -e less [DSELECTIONS] .fi -This causes your command line program to execute in an \'xterm\' -context. +Some program further require you to provide a shell so they +can execute correctly. For instance, running \'ls\' in a +command definition requires something like this: -This is not so much of an issue on Win32 systems where the first -form of the command above works fine. +.nf +L lshome xterm -l -e bash -c 'ls / | [$PAGER]' +.fi + +In fact, this idiom is so common, you will see variables +defined in the example \'.twander\' file to simplify +such definitions (comments removed): + +.nf +SHELL = bash -c +VSHELL = [XTERM] [SHELL] +XTERM = xterm -fn 9x15 -l -e +.fi + +Now you can write the command above like this: + +.nf +L lshome [VSHELL] 'ls / | [$PAGER]' +.fi + + +This causes your command line program to execute in an \'xterm\' +context +.B and +under a shell interpreter. + +This is not much of an issue on Win32 systems where the first +form of the command above works fine. Win32 appears to have +no problem invoking a new window whether the command is GUI-aware +or not. + +.SS Using Wildcards In Command Definitions + +The [PROMPT:...] Built-In Variable is provided to make +it possible to write general-purpose commands which +interact with the user. For example, you might want to +define a directory listing command for Win32 like this: + +.nf +L DirList dir [PROMPT:Directory Of What?] | more +.fi + +When the user presses the "L", they are presented with a +dialog box into which they enter their directory name +or wildcard pattern such as "\\*.bat" and everything +works as expected. + +On Unix-like systems, however, this does not work as expected. +Suppose we define the command for these systems to be: + +.nf +L DirList [VSHELL] 'ls -l [PROMPT:Directory Of What?] | [$PAGER]' +.fi + +This works fine +.B so long as the user does not enter a wildcard pattern +in response to the prompt. Why? Recall that \'twander\' +quotes all Built-In Variable substitutions by default. +If the user enters this at the prompt: + +.nf +/kern* +.fi + +The command \'twander\' tries to execute is: + +.nf +VSHELL Stuff ... 'ls -l "/kern*" | ... pager stuff +.fi + +The argument to \'ls\' is double-quoted. The Unix shells +understands this kind of quoting to mean +.B no expansion of wildcard characters is to be done, +which is the exact opposite of what we want. + +You might think that the easy way to solve this problem is to turn off +argument quoting with the -t command line flag. However, this is not +really practical. Quoting is on or off globally in the program. +Turning it off means no Built-In Variable substitutions will be +quoted. That's fine so long as no directory/file you select via the +user interface has a space in the name. However, you are almost +certain to run into such files sooner or later. (Recall that the only +way to deal a directory/file name with spaces in it as a single +argument is to quote that name.) + +So, we need a way to leave quoting on but also properly deal with +wildcard string entries from the user. Fortunately, because of +the richness of Unix shells, there is a simple way to do this: +we'll use a "shell variable" to hold the user's response and the +shell's ability to handle multiple commands on one line separated +by semi-colons: + +.nf +L DirList [VSHELL] 'UsrResp=[PROMPT:Directory Of What?] ; ls -l $UsrResp | [$PAGER]' +.fi + +Why does this work? Because the shell interprets (and drops) the double-quotes, +when the results of the [PROMPT:...] are +.B assigned to "UsrResp". +The later reference to "$UsrResp" return just the string the user +entered without the quotes and the command works as expected. + +Interestingly, this problem does not occur when entering text +via the RUNCMD dialog. (default: Control-z) Here the text +you enter is +.B not +part of a Built-In Variable substitution, so it is not quoted. (The +exception, of course, would be if you entered a [PROMPT:...] reference +in the RUNCMD dialog. In this case, the same problem we've just +described could occur.) .SS Modal Operation Of New Windows @@ -2736,8 +2861,8 @@ \'twander\' with the correct version of Python: .nf -.B #!/bin/sh -.B python2 twander.py $* +#!/bin/sh +python2 twander.py $* .fi .IP \(bu 4