.TH twander 1 "TundraWare Inc."

.SH twander
Wander around a filesystem executing commands of your choice on selected
files and directories.

.SH THE BIG PICTURE
Graphical User Interfaces (GUIs) are a blessing and a curse. On the
one hand, they make it easy to learn and use a computer system.  On
the other, they are a real inconvenience to experienced users who are 
touch typists.  Taking hands off the keyboard to use the mouse
can really slow down a good typist.

Nowhere is this more apparent than in filesystem browsers.  In one
corner we have the GUI variants like \'Konqueror\' and \'Microsoft
Windows Explorer\'.  These are very easy to use but you pretty much
need the mouse in your hand to do anything useful.  In the other
corner are the text-based file browsers like \'List\', \'Norton
Commander\', and \'Midnight Commander\'.  These are really efficient
to use, but have limited functionality and generally do not operate
very well on
.B groups
of things.

Both of these approaches also suffer from the well-known
interface problem of "What You See Is
.B All
You Get" - Each program has a predefined set of commands and the user
cannot easily extend these with their own, new commands.

\'twander\' is a new approach to the filesystem navigation problem which
embraces the best of both the GUI-based approach and the text-based
approach.  It also provides a rich mechanism whereby each user can
easily define their own command set and thereby customize the program
as they see fit.  This is done with a number of key features:


.TP
1)
The
.B Navigation
of the filesystem is graphical - you can use the mouse to select files,
directories, or to change directories.  However, each major filesystem
navigational feature is also doubled on the keyboard (using Control keys)
so you can move around and select things without ever touching the mouse.

.TP
2)
\'twander\' also supports a number of
.B navigation shortcuts.
It provides single control-key access to changing directories, moving
to the previous directory, moving up one directory level, moving to
any previously visited directory, (de)selecting any or all
files/directories in the current view, and escaping to the operating
system to run a command.  Many (but not all) of these features are
also doubled via GUI/mouse operations.

.TP
3)
There are
.B no
built-in file or directory commands.  All commands which manipulate
the files or directories selected during navigation are user-defined.
This command definition is done in an external configuration file
using a simple but powerful command macro language.  This means that
that the command set of the program can easily be changed or expanded
without having to release a new version of \'twander\' every time.
Better still, every different user can have their own command set
defined in a way that suits their style of working.  Best of all,
commands can be invoked either graphically (with a mouse click) or via
a single keypress to minimize moving your hands off the keyboard.

.TP
4)
Because \'twander\' is written in Python using Tkinter, the same
program runs essentially identically on many Unix-style and Win32
systems.  The only thing that may need to be changed across these
various platforms are the command definitions in the configuration
file.  You only need to learn one interface (and the commands you've
defined) across all the different systems you use.

.P
The consquence of all this is that \'twander\' is an extremely
powerful and highly customizable filesystem navigator.  Once
learned, both navigation and command execution are lightning-fast
(or at least, as fast as your machine can go ;) while minimizing
dependency on the mouse.

.SH SYNOPSIS
twander [-bcdfhnqrstwvxy] [startdir]

.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