diff --git a/twander.1 b/twander.1 index c3d821f..9ee8225 100644 --- a/twander.1 +++ b/twander.1 @@ -5,8 +5,9 @@ Wander around a filesystem executing commands of your choice on selected files and directories. If you're new to \'twander\' and want to know why this program is better and different than whatever you're -using at the moment, take a moment to read the section called "DESIGN -PHILOSOPHY" toward the end of this document first. +using at the moment, take a moment to read the section called +.B "DESIGN PHILOSOPHY" +toward the end of this document first. .SH SYNOPSIS twander [-bcdfhnqrstvwxy] [startdir] @@ -45,7 +46,7 @@ .TP .B -h -Print this help information. +Print help information on stdout. .TP .B -n fontname @@ -62,11 +63,11 @@ Normally, \'twander\' re-reads and displays the current directory every few seconds to reflect any changes that might have occured to -that directory's contents. This is useful on slow machines (or slow X -connections) and/or when working with very large directories. In this -situtation, the frequent updating of the \'twander\' display can make -the program unacceptably slow and unresponsive. In this case you can -still force an update manually with the \'Control-l\' key. +that directory's contents. This option is useful on slow machines (or +slow X connections) and/or when working with very large directories. +In this situtation, the frequent updating of the \'twander\' display +can make the program unacceptably slow and unresponsive. In this case +you can still force an update manually with the Control-l key. .TP .B -s fontsize @@ -76,9 +77,9 @@ .B -t Turn off quoting when substituting built-in variables. (default: quoting on) -Anytime \'twander\' encounters a reference to one of the built-in variables -(DIR, DSELECTION, DSELECTIONS, PROMPT:, SELECTION, SELECTIONS), it will -replace them with +Anytime \'twander\' encounters a reference to one of the built-in +variables (DIR, DSELECTION, DSELECTIONS, PROMPT:, SELECTION, +SELECTIONS) in a command, it will replace them with .B double quoted strings. This is necessary because any of these can return values which have embedded spaces in them. By quoting them, they can be passed to a @@ -115,7 +116,7 @@ key bindings. However, it is not difficult to change the defaults. They are listed near the top of the program file (twander.py) to allow people to tailor them as they -wish. The only thing you need to know is the \'Tkinter\' +wish. The only thing you need to know is the Tkinter nomenclature for keystroke names. You can get a pretty good idea of this from reading the first part of the program, and failing that, there is abundant documentation @@ -124,7 +125,7 @@ The only convention that ought to be observed here (to keep the program sane - it assumes this convention throughout), is that -.B navigation commands are Control keys. +.B keyboard navigation and selection commands are Control keys. The obvious question here is, "Why isn't this a configuration option maintained in the configuration file?" The answer is that it would @@ -236,6 +237,8 @@ .B PGUP Control-c +.SH MENU OPTIONS + .SH LOCATION OF CONFIGURATION FILE \'twander\' @@ -255,7 +258,7 @@ \'twander\' configuration files consist of freeform lines of -text. Each line is considered separately - no legal configuration +text. Each line is considered separately - no configuration line may cross into the next line. Whitespace is ignored within a line as are blank lines. @@ -266,7 +269,7 @@ appropriate anytime it encounters a problem in a configuration file. This is both true when the program initially loads as well as during any subsequent configuration file reloads -initiated from the keyboard while running \'twander\. +initiated from the keyboard while running \'twander\'. .SH GOTCHAS @@ -276,17 +279,19 @@ .B 1) Getting Command Results Displayed In A New Window -When you invoke a command via \'twander\', 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 configuration -file entry. 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. 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: -&View less [FILE] & +.nf +V view less [DSELECTIONS] +.fi Sadly, this will not work, at least not the way you expect. If you started \'twander\' from a terminal session and use @@ -298,52 +303,41 @@ 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 shell control. To achieve +how command line programs run under Unix shell control. To achieve the desired results, you'll need something like this in your configuration file: .nf -&View xterm -fn 9x15 -e $PAGER [FILE] & +V view xterm -l -e less [DSELECTIONS] .fi This causes your command line program to execute in an \'xterm\' context. -Note also that the command ends with \'&\'. If you do not have -this, \'twander\' will execute the command of interest and -hang waiting until the command completes. This so-called -"modal" operation may be useful sometimes, but usually it is -not what you want. +This is not so much of an issue on Win32 systems where the first +form of the command above works fine. -For Win32, the issue is a bit simpler. Just make sure that you -run \'twander\' with the \'pythonw\' version of the python -binary. This version is specifically intended for running -Python programs with no controlling command line window open. -In this case, our example looks like: +.B 2) Non-Modal Operation Of New Windows -.nf -&view cmd /c " less [FILE] " -.fi +Notice our example commands above do not end with "&". +These should not be needed on either Unix-like or Win32 +operating systems. When a command is executed, \'twander\' +starts a new thread of execution which runs concurrently +with \'twander\' itself. This means you should be able to +continue using \'twander\' while the new command executes. +If not (\'twander\' is locked out while the new command runs - +so-called "modal" operation), it means your system does not +completely or correctly implement threading. In that case, +if you want non-modal command operation, try adding a "&" at +the end of your command definition. -.B 2) File- Or Directory Names Which Contain Whitespace - -[FILE] and [DIRECTORY] faithfully return the name of the item you -select, whitespace and all. The shells of some operating systems, -notably the Unix-like systems (FreeBSD, Linux...), require -special handling for this sort of thing. Here is our example -again, with this taken into account: - - -.nf -&View xterm -e bash -c ' cat "[FILE]" | less ' & -.fi .SH OTHER -You must have \'python\' 2.2 or later installed as well as \'Tkinter\' -support installed for that release. In the case of Win32, \'Tkinter\' -is bundled with the standard Windows \'python\' distribution. In -the case of Unix, you may have to first install \'python\' and -then the appropriate release of \'Tkinter\'. This is the case, +You must have Python 2.2 or later installed as well as Tkinter +support installed for that release. In the case of Win32, Tkinter +is bundled with the standard Windows Python distribution. In +the case of Unix, you may have to first install Python and +then the appropriate release of Tkinter. This is the case, for example, with FreeBSD. .SH BUGS AND MISFEATURES @@ -408,7 +402,7 @@ to the previous directory, moving up one directory level, moving to any previously visited directory, (de)selecting any or all files/directories in the current view, and escaping to the operating -system to run a command. Many (but not all) of these features are +system to run a command. Some (but not all) of these features are also doubled via GUI/mouse operations. .TP