diff --git a/twander.1 b/twander.1 index 0be181a..7714945 100644 --- a/twander.1 +++ b/twander.1 @@ -19,7 +19,7 @@ various startup options. This document also describes the format and content of a \fCtwander\fP -Configuration File. You will find an example configuration file +Configuration File. You will find an example Configuration File called \fC.twander\fP in the distribution tarball. All the entries in that file are commented out, so you'll need to uncomment and edit the ones you want to work with. @@ -106,7 +106,7 @@ 6 0x040 Dump Command History Stack After Command Executes 7 0x080 Dump Contents Of Program Memories As They Change 8 0x100 Dump Contents Of Filter/Selection Wildcard Lists As They Change (0x100) - 9 0x200 Reserved/Unused + 9 0x200 Dump Associations Table 10 0x400 Reserved/Unused 11 0x800 Dump Requested Debug Information And Exit Immediately .fi @@ -818,9 +818,9 @@ Of course, the full form is also fine as well. .B This "shortcut" feature is only supported in RUNCMD!!! -Configuration file entries must use the full form of all built-in +Configuration File entries must use the full form of all built-in variables. This is a conscious design decision to help enforce -some consistency and clarity in the configuration files. +some consistency and clarity in the Configuration Files. Unless you have set the MAXMENU option to 0, RUNCMD keeps track of @@ -839,7 +839,7 @@ their output can been seen in a GUI window. This is particularly handy on Unix. -As with command definitions in a configuration file, you can +As with command definitions in a Configuration File, you can tell \fCtwander\fP to force a display refresh after the command has been initiated. You do this by beginning the command with the \'+\' symbol. So, for example, if you enter, @@ -924,12 +924,12 @@ .B Directory Shortcut Statements , the directory shortcut keys are associated with particular directories in the -\fCtwander\fP configuration file. However, it is possible to +\fCtwander\fP Configuration File. However, it is possible to temporarily assign them to something else while the program is running. This is handy if you need to temporarily "remember" one or more directories so you can jump back to them with a single keystroke. Think of it as a way to "override" the directory shortcut assignments -defined in the configuration file. +defined in the Configuration File. There are twelve "override" keys associated with each of the directory shortcuts. They default to the top row of letter keys on a standard @@ -945,8 +945,8 @@ Any such reassociation of a directory shortcut is temporary. Directory shortcuts are set back to the values specified in the -configuration file if you restart the program or reload the -configuration file (Default: \fCControl-r\fP). +Configuration File if you restart the program or reload the +Configuration File (Default: \fCControl-r\fP). .SS Program Memories @@ -1487,7 +1487,7 @@ .SS Shortcut Menu (Alt-u) [Control-Right-Mouse-Button] This menu provides a way to access any of the Directory Shortcuts -defined in the configuration file. It also provides a number of +defined in the Configuration File. It also provides a number of "canned" navigation shortcuts to go up a directory, back a directory, to the home directory, to the starting directory, and to the root directory. On Windows systems using the Win32All extensions, there is @@ -1574,18 +1574,17 @@ .SS Help Menu (Alt-l) [No Mouse Shortcut] This menu provides information about various internal settings of -\fCtwander\fP including User-Defined Variables, Command Definitions, -Internal Program Variables, User-Settable Options, Keyboard and -Assignments. It also has an About feature which provides version and -copyright information about the program. +\fCtwander\fP including Internal Program Variables, User-Settable +Options, Keyboard Assignments, User-Defined Variables, Command +Definitions, and Associations. It also has an About feature which +provides version and copyright information about the program. For the most part, this help information should fit on screen easily. -However, very long Command Definitions will probably not fit on-screen -once User-Defined and Environment Variables have been substituted. In -this case, if you are curious about just how \fCtwander\fP is -interpreting your Command Definitions, invoke the program with the -relevant debug bit turned on and watch the output on stdout as -\fCtwander\fP runs. +However, very long Command Definitions will probably not fit +on-screen. In this case, if you are curious about just how +\fCtwander\fP is interpreting your Command Definitions, invoke the +program with the relevant debug bit turned on and watch the output on +stdout as \fCtwander\fP runs. .SH THE \fCtwander\fP CONFIGURATION FILE @@ -1650,6 +1649,7 @@ Directory Shortcut Statements Wildcard Statements Variables And Command Definitions + Associations Conditional Processing Statements The Include Directive .fi @@ -1788,7 +1788,7 @@ the display from getting cluttered with the longer strings required to display the actual lengths in bytes. If you want the program to display the actual lengths for these items by default, set -ACTUALLENGTH=True in your configuration file. You can also "toggle" +ACTUALLENGTH=True in your Configuration File. You can also "toggle" between normalized and actual size display with the TOGLENGTH key (default: Control-0). @@ -1811,7 +1811,7 @@ of REFRESHINT is .B not shown in the program options help menu. The value there is the one -set by default or set in the configuration file. Think of this as the +set by default or set in the Configuration File. Think of this as the "base" value for REFRESHINT. If ADAPTREFRESH is set to False, then adaptive refresh timing is @@ -1866,7 +1866,7 @@ By default, \fCtwander\fP populates the command menu on the menu bar (and the popup command menu) with commands in the order in which they -are defined in the configuration file. This was done so that you +are defined in the Configuration File. This was done so that you could define the most important or most frequently used commands first and they would thus conveniently appear at the top of the menu list. However, if you prefer your command list to be sorted, set the @@ -1994,7 +1994,7 @@ response in \fC{PROMPT: ...}\fP and \fC{YESNO: ...}\fP Built-In Variables. You may change this to any string you like, though doing so is not recommended. Changing DEFAULTSEP will require you to edit -any configuration files that use these Built-Ins with default +any Configuration Files that use these Built-Ins with default responses. In no case should the delimiter string include any of the characters, \fC[ ]{ }\fP since these are used as delimiters in the \fCtwander\fP configuration language. @@ -3061,7 +3061,7 @@ Definition, it will be replaced with any text that "program" produces as it runs. That text will have any trailing newline stripped. Notice that this is different that most \fCtwander\fP variables that -are evaluated once when the configuration file is first read in. +are evaluated once when the Configuration File is first read in. This is true wherever the execution variable appears - either as the right-hand-side of a variable statement or explicitly inline within a @@ -3083,7 +3083,7 @@ .ft C \" courier .nf a mycommand echo "[\`-ls\`]" # We need the double-quotes - # to make echo work right + # to make echo work right .fi .ft \" revert @@ -3601,14 +3601,233 @@ and then the command will run. +.SS Associations + +Most X-Windows window managers and Microsoft Windows support the idea +of "associations". That is, based on the name of a file, they +"associate" an application that can handle it. So, for example, a +filename ending in ".txt" is handled by a text editor, a filename +ending in ".ps" is handled by a PostScript processing program, and so +on. This is handy inside of visual interfaces because you can +double-click on a file and the interface can infer which program to +load to process that file. + +The problem is that the various window manager and Microsoft Windows don't +all handle associations the same way. Some lighter X-Windows window +managers may not even have associations at all. In order for to remain +portable across operating systems, and work more-or-less the same way +everywhere, association support has been implemented directly within +\fCtwander\fP itself. + +All you have to do is tell \fCtwander\fP which program to use for a +given file "type". A "type" is defined as a group of files whose +names end with the same string of characters. You do this +by adding association statement to the Configuration File: + +.ft C \" courier +.nf + + # Associations are in the form: + # ASSOC file-type-string command-to-handle-this-type-of-file + + ASSOC .txt emacs [SELECTION] +.fi +.ft \" revert + +Thereafter, when \fCtwander\fP runs, the "emacs" command will +be loaded to process any file whose name ends in ".txt" when the +user selects that file and either double-clicks on it or presses +"Enter". + +Notice that the "handler command" can consist of pretty much anything +that you can use in a command definition (as described in the previous +sections). For instance, you can do things like: + +.ft C \" courier +.nf + + EDITOR = emacs -fn 10x20 + + ASSOC .txt {YESNO:Are You Sure You Want To Edit This File?} [EDITOR] [SELECTION] +.fi +.ft \" revert + +You can also insert special association command that will be used if no other +explicit association matches. Think of this as a "default" association: + +.ft C \" courier +.nf + ASSOC .pdf mypdfreader [SELECTION] + ASSOC .ps mypostscriptprogram [SELECTION] + ASSOC * myfineeditor [SELECTION] +.fi +.ft \" revert + +In this situation, if you double-click or press "Enter" on any file +not ending in either ".pdf" or ".ps", the default association action +will be taken: The file will be opened with \fCmyfineeditor\fP. + + +.SS A Few Association Subtleties + +.IP \(bu 4 +The \fCASSOC\fP keyword is case-sensitive. You must enter it entirely +in upper-case. However, the order of \fCASSOC\fP statements is unimportant. +\fCtwander\fP distinguishes \fCASSOC\fP statements by their unique +file "type" strings. Well ... this is true so long as you make sure +the type strings +.B are +unique! Suppose you put this in your Configuration File: + +.ft C \" courier +.nf + + ASSOC .text emacs [SELECTION] + ASSOC xt ci [SELECTION] +.fi +.ft \" revert + +A file whose name ends in ".text" will match +.B both +of these associations. So which one does \fCtwander\fP use? There is +no way to tell - it's a nonsense condition when a given file type +matches more than one association. The moral of the story here is to +make sure each of your \fCASSOC\fP statements associates a completely +unique file type. + +.IP \(bu 4 +The "default" association - if defined - will only be applied +if no explicit association for a given selection is found. +However, there is one exception. If a selection has no matching +association but is known to the underlying operating system to be +.B executable, +the default association will not be applied. That way, you can +still double-click (or press "Enter") on executable files to run +them without the default association getting in the way. Of course, +if you've explicitly defined an association for the type of executable +file selected, then that +.B will +be applied to the selected file. This can be handy if, say, you +don't want to actually run the executable, but just edit it when +you double-click on it. + +.IP \(bu 4 +Note that there is no wildcarding in the type definition. This +will not do what you might think: + +.ft C \" courier +.nf + ASSOC t*xt emacs [SELECTION] +.fi +.ft \" revert + +This will cause \fCtwander\fP to match only on filenames that literally +end with "t*xt", whereas you probably meant "match any filename starting with +t and ending with xt". In short, you cannot use regular expressions +in association type fields. The one exception is the default association, +where * is understood to mean "match any file whose type is not otherwise +handled by another association statement". + +.IP \(bu 4 +Be careful which Built In Variables you use in an association handler +definition. Suppose you do this: + +.ft C \" courier +.nf + ASSOC .txt emacs [SELECTIONS] +.fi +.ft \" revert + +Note the use of the multiple selection Built In Variable, +\fC[SELECTIONS]\fP (as opposed to the single selection +\fC[SELECTION]\fP used in the previous examples). What happens +when you double-click or press "Enter" when multiple files +have been selected in the \fCtwander\fP interface? Well, +it depends. The program decides which association to use +based on the +.B last +filename you have selected. Suppose, in order, you select +"foo.c", "bar.py", and "baz.txt". Since the last file selected +ends with ".txt", the handler defined above will match and +.B all +the files will be processed using this association. This +may not be what you want. + +Even stranger things can happen if the last filename selected +is an executable and you've defined an association for it: + +.ft C \" courier +.nf + ASSOC .py python [SELECTIONS] +.fi +.ft \" revert + +Say you select "foo.c" and "bar.py". Since "bar.py" is +the last file in the multiple selection, it will match the +association above. This will effectively produce a command +that like this: + +.ft C \" courier +.nf + python foo.c bar.py +.fi +.ft \" revert + +Which is, um ... bogus. + +As a general matter, multiple selection Built Ins are fine +if you are specifying an association handler that does things +like editing, viewing, printing, and so on. But be wary of +them if the handler runs some language processor or other program +that expects the content of its arguments to be in a particular +format. + + +.SS Associations On Microsoft Windows + +On Unix-like operating systems \fCtwander\fP ignores the underlying +associations (if any) of the system and/or window manager. It only +observes its own associations. That's because there is no consistent +association mechanism across the many OS and window manager variants +in use on those platforms. + +But Microsoft Windows is a different matter. All modern variants +of these systems have consistent built-in support for association. +\fCtwander\fP was designed to "play nice" with the underlying +associations defined in the Windows registry. It works very +simply. \fCtwander\fP associations take precedence. If you +define this: + +.ft C \" courier +.nf + ASSOC .txt myowneditor [SELECTION} +.fi +.ft \" revert + +Then double-clicking "foo.txt" will cause "myowneditor" +to be invoked, even though Windows, by default, associates +"notepad" with text files. + +If no matching \fCtwander\fP association is found for a particular +selection, then the execution request is handed to Windows, and it's +association for that file type (if any) will be applied. + +This is a very handy feature. You may wish to temporarily or +permanently change which Windows program is associated with +a given file type. Instead of having to fiddle around with +reassociating things in Windows, you can just edit the \fCtwander\fP +Configuration File. + + .SS Conditional Processing Statements -Most of \fCtwander\fPs power lies in its ability to be customized to each -different user and operating system via its Configuration File. To make this a bit -easier to manage, the \fCtwander\fP configuration language recognizes -so-called "Conditional Processing Statements". These statements give -you the ability to write a single Configuration File which automatically tailors -itself to run \fCtwander\fP properly wherever you are running. +Most of \fCtwander\fPs power lies in its ability to be customized to +each different user and operating system via its Configuration File. +To make this a bit easier to manage, the \fCtwander\fP configuration +language recognizes so-called "Conditional Processing Statements". +These statements give you the ability to write a single Configuration +File which automatically tailors itself to run \fCtwander\fP properly +wherever you are running. The general idea is to define a "Condition Block" which begins by doing a logical test. If that test evaluates to True, all statements @@ -3752,7 +3971,7 @@ free to use (but not modify) that standard configuration. You are then free to add to, or even override the standard configuration content with statements of your own following the ".include". Suppose -you have the following "standard" configuration file available on your +you have the following "standard" Configuration File available on your system: .ft C \" courier @@ -4232,7 +4451,7 @@ .ft C \" courier .nf # Note that the line below is split for printing purposes - # In an actual configuration file, this needs to all be on one line + # In an actual Configuration File, this needs to all be on one line L DirList [VSHELL] 'UsrResp={PROMPT:Directory Of What?} ; ls -l $UsrResp | [$PAGER]' @@ -4351,7 +4570,7 @@ of REFRESHINT is .B not shown in the program options help menu. The value there is the one -set by default or set in the configuration file. Think of this as the +set by default or set in the Configuration File. Think of this as the "base" value for REFRESHINT. .P @@ -4829,4 +5048,4 @@ .ft \" revert .SH DOCUMENT REVISION INFORMATION -$Id: twander.1,v 1.132 2006/12/14 08:47:30 tundra Exp $ \ No newline at end of file +$Id: twander.1,v 1.133 2006/12/15 07:33:37 tundra Exp $ \ No newline at end of file