.TH twander 1 "TundraWare Inc."
.SH twander
Wander around a filesystem executing commands of your choice on selected
files.
.SH SYNOPSIS
twander [-bcfhnqswvxy] [startdir]
.SH DESCRIPTION
\'twander\' is a GUI-based file tree navigation tool.  It lets you "wander"
through your file system at will.  Unlike other similar programs,
.B YOU
define what features or commands are available to manipulate selected
files.  You do this via a configuration file.  This gives you the
convenience of a GUI-driven file navigator with the flexibility of
defining almost any kind of command you'd like at your disposal.

.SH OPTIONS
.TP
.B startdir
directory in which to begin (default: ./)

.TP
.B -b backcolor
desired background color (default: black)

.TP
.B -c path/name of configuration file
specify the location and name of the configuration
file you wish to use. (default is ~/.twander)

.TP
.B -f forecolor
desired foreground color (default: green)

.TP
.B -h
print this help information

.TP
.B -n fontname
name of desired font family (e.g., courier, times, helvetica) (default: courier)

.TP
.B -q
quiet mode - suppresses warnings (default: warnings on)

.TP
.B -s fontsize
font size in points (default: 12)

.TP
.B -v
print detailed version information.

.TP
.B -w fontweight
one of:  bold, italic, underline, overstrike (default: bold)

.TP
.B -x width
set window width (default: 60)

.TP
.B -y width
set window width (default: 25)

.SH PREASSIGNED KEYS

A few of the keys on the keyboard are preassigned to special
functions:

.TP
.B Esc
Exit \'twander\'

.TP
.B Home
Return to the original starting directory

.SH CONFIGURATION FILE FORMAT

\'twander\'
.B requires
a startup configuration file in order to run.  It
is the only way the program knows what features you wish to enable
and what commands are required to implement each feature.

By default, the program expects to find configuration information in
.B ~/.twander
but you can override this with the
.B -c 
command line option.

\'twander\' configuration files consist of freeform lines of
text.  Whitespace is ignored, and a comment may be inserted
anywhere.  Comments must  begin with the
.B #
character.

Each line of configuration information consists of two parts,
the
.B Command Name
and the
.B Command String.

The Command Name is nothing more than your name for a given
command.  The Command String tells \'twander\' what to do
when you issue the command in question.

Within the Command Name you can specify a single letter
to be the
.B Command Key
by placing the 
.B &
character before letter you wish to use.  This letter will
be a keyboard shortcut to the command.  If you select a file
via the \`twander\` interface and then press this key, the
command associated with that key will be executed.  The case
of the Command Key is ignored, so \'X\' and \'x\' will
both invoke the same command, if any.

Within the Command String you can specify several different
kinds of information: literal text which \'twander\'
will not touch, words beginning with the
.B $
symbol, which are interpreted as environment variables,
the special symbol
.B [FILE],
and the special symbol
.B [DIRECTORY].
When you decide to run a command, \'twander\' will replace
[FILE] with the currently selected file name.  This will be the
.B fully qualified name of the file
- i.e., it will include the full path name.  Similarly,
[DIRECTORY] is replaced with the current directory
name (ending with a path separator character).

If one of these special symbols is used at the end of a line which is
quoted, be sure to leave a space between the symbol and the
terminating quote or \'twander\' will not recognize the special
symbol:

.nf

# This is OK
some-command "arg1 arg2 [FILE] "

# This is NOT OK
some-command "arg1 arg2 [FILE]"

.fi

This is required because \'twander\' expects whitespace separators
between the various kinds of configuration file entries (literals,
environment variables, [FILE], and [DIRECTORY].  It thus parses
[FILE]" in our example as
.B literal text
since the closing double-quote appears to be part of the string.


Here is an example .twander file:
.nf

# 'twander' configuration file example

&edit $EDITOR [FILE]
vie&w $PAGER  [FILE]
ls    /bin/ls -al [FILE] | $PAGER

.fi

The first line is a comment and is completely ignored.  The
second line is blank (all whitespace) and is also ignored.

Line 3 means this: Invoke the \'edit\' command using \'e\' as the
command key.  Use the $EDITOR environment variable to determine which
program to use for editing and place the current directory/file name
immediately after the program name to invoke the editing session.

Similarly, Line 4 means: Use the program defined in he $PAGER
environment variable when invoking the \'view\' command via
the \'w\' key.  Pass the currently selected directory or
file name to that program as its only argument.

Line 5 is similar except for one thing: There is no Command Key
shortcut defined for that command.  \'twander\' will permit this, but
it will warn you about it when the program starts.

If you specify an environment variable in the configuration
file which is not actually defined, \'twander\' will print
an error to that effect and refuse to run.  In other words,
every environment variable referenced in your configuration
file must be defined in order for the program to run at all.
This is an intentional design choice to force the creation
of sane and meaningful configuration files.


.SH OTHER
You must have \'python\' 2.2 or later installed as well as Tkinter 
support installed for that release.

.SH BUGS AND MISFEATURES
The color options (-b, -f), font options (-n, -s, -w), and size option
(-x, -y) are
.B not
checked for validity when the command line is initially read.
If you enter something unreasonable for
these options, \'twander\' will refuse to run with some
.B really
interesting and entertaining error messages.

The program could be more gracious about this.

.SH COPYRIGHT AND LICENSING
\'twander\' is Copyright(c) 2002 TundraWare Inc.  For terms of use, see
the twander-license.txt file in the program distribution.  If you
install \'twander\' on a FreeBSD system using the 'ports' mechanism, you
will also find this file in /usr/local/share/doc/twander.

.SH AUTHOR
.nf
Tim Daneliuk
tundra@tundraware.com