Added sections on Association options and processing.
Updated help menu section to reflect recent changes.
1 parent d43a853 commit 8f477ecc8911221b0ddfe2f4eeb75917a769f243
@tundra tundra authored on 15 Dec 2006
Showing 1 changed file
View
293
twander.1
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 $