.TH twander 1 "TundraWare Inc."
.SH twander
Wander around a filesystem executing commands of your choice on selected
files.
.SH SYNOPSIS
twander [-bcdfhnqrstwvxy] [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. (default is ~/.twander)

.TP
.B -d
Start in debug mode.  The program runs, but does not actually execute
any commands.  Instead, the contents of various internal tables such
as the Symbol Table and Command Table are listed on standard output.
If the user presses a defined command key, the command that would have
been executed is printed to standard output, but no command is
actually performed.  This option is mildly useful in debugging
configuration files insfar as it will display the command string after
all substitutions of variables (both builtins and user-defined) has
been done.  (default: debug off)

.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 -r
Turn off automatic refreshing of directory display. (default: refresh on)
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.

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

.TP
.B -t
Turn off quoting when substituting builtin variables. (default: quoting on)

.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 Arrow Keys and Spacebar
The Left- and Right-Arrow keys are used for horizontal scrolling,
if needed. The Up- and Down-Arrow keys move up and down through
the currently displayed directory listing.  Pressing the Spacebar
will cause the currently underlined item to be selected just as
if you had clicked on it.

.TP
.B Backspace
Move
.B up 
one directory ("..") in the filesystem hierarchy.

.TP
.B Esc
Exit \'twander\'

.TP
.B Home
Return to the original starting directory

.TP
.B Ctrl-L
Redraw/update the directory listing.

.TP
.B Ctrl-Left Arrow
Move 
.B back
to previously visited directory.  This can be done repeatedly until
you end up in 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).


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 GOTCHAS

There are several tricky corners of \'twander\' which need
further explanation:

.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:

&View    less [FILE] &

Sadly, this will not work, at least not the way you expect.
If you started \'twander\' from a terminal session and use
the command above, it will work, but the results will appear
in the invoking terminal window,
.B not
in a new window as you might expect. If you started \'twander\'
from a GUI or disconnected it from the initating terminal with
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
the desired results, you'll need something like this in your
configuration file:

.nf
&View    xterm -fn 9x15 -e $PAGER [FILE] &
.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.

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:

.nf
&view    cmd /c " less [FILE] "
.fi

.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,
for example, with FreeBSD.

.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.

This program has not been tested on MacOS.  Please let me know how/if
it works there and any issues you discover.

.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
twander@tundraware.com