| |
---|
| | describes how to install and start \fCtwander\fP as well as it's |
---|
| | 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. |
---|
| | |
---|
| |
---|
| | 5 0x020 Dump Directory Stack As It Changes |
---|
| | 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 |
---|
| | .ft \" revert |
---|
| |
---|
| | |
---|
| | 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 |
---|
| | your last manually entered command and presents it as a default when |
---|
| |
---|
| | greatly simplifies running command-line programs from RUNCMD so |
---|
| | 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, |
---|
| | |
---|
| |
---|
| | As discussed in |
---|
| | .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 |
---|
| | keyboard and are invoked with the \'Alt\' key. When you select a particular |
---|
| |
---|
| | shortcut #12 (Default: \fCF12\fP). |
---|
| | |
---|
| | 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 |
---|
| | |
---|
| |
---|
| | |
---|
| | .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 |
---|
| | also a shortcut to the Drive List View. |
---|
| |
---|
| | |
---|
| | .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 |
---|
| | |
---|
| |
---|
| | Key Binding Statements |
---|
| | Directory Shortcut Statements |
---|
| | Wildcard Statements |
---|
| | Variables And Command Definitions |
---|
| | Associations |
---|
| | Conditional Processing Statements |
---|
| | The Include Directive |
---|
| | .fi |
---|
| | .ft \" revert |
---|
| |
---|
| | expressed in bytes, Kilobytes, Megabytes, or Gigabytes. This keeps |
---|
| | 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). |
---|
| | |
---|
| | .TP |
---|
| |
---|
| | REFRESHINT will be reset to its default value. The changing value |
---|
| | 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 |
---|
| | disabled and a directory refresh will be attempted every REFRESHINT |
---|
| |
---|
| | .B CMDMENUSORT [Boolean] (False) |
---|
| | |
---|
| | 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 |
---|
| | \fCCMDMENUSORT\fP option to \fCTrue\fP. |
---|
| |
---|
| | This is the string that separates the prompting text and the default |
---|
| | 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. |
---|
| | |
---|
| |
---|
| | If you have something like \fC[\`program\`]\fP in a Command |
---|
| | 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 |
---|
| | command definition. You can confirm this by looking at the |
---|
| |
---|
| | |
---|
| | .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 |
---|
| | |
---|
| | |
---|
| |
---|
| | Menu), they will be presented with two prompts, one after the other, |
---|
| | 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 |
---|
| | in the block are included in the current configuration. If the test |
---|
| |
---|
| | the standard configuration in a place anyone can read it. Everyone is |
---|
| | 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 |
---|
| | .nf |
---|
| |
---|
| | |
---|
| | .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]' |
---|
| | |
---|
| |
---|
| | REFRESHINT will be reset to its default value. The changing value |
---|
| | 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 |
---|
| | If you don't like this adaptive refresh interval business, set |
---|
| |
---|
| | .fi |
---|
| | .ft \" revert |
---|
| | |
---|
| | .SH DOCUMENT REVISION INFORMATION |
---|
| | $Id: twander.1,v 1.132 2006/12/14 08:47:30 tundra Exp $ |
---|
| | $Id: twander.1,v 1.133 2006/12/15 07:33:37 tundra Exp $ |
---|
| | |