.TH twander 1 "TundraWare Inc."

.SH twander

Wander around a filesystem executing commands of your choice on
selected files and directories. If you're new to \'twander\' and want
to know why this program is better and different than whatever you're
using at the moment, take a moment to read the section called "DESIGN
PHILOSOPHY" toward the end of this document first.

.SH SYNOPSIS
twander [-bcdfhnqrstvwxy] [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.  (default: debug off)

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 built-ins and user-defined) has been
done.

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

Normally, \'twander\' re-reads and displays the current directory
every few seconds to reflect any changes that might have occured to
that directory's contents.  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 built-in variables. (default: quoting on)

Anytime \'twander\' encounters a reference to one of the built-in variables
(DIR, DSELECTION, DSELECTIONS, PROMPT:, SELECTION, SELECTIONS), it will
replace them with
.B double quoted
strings.  This is necessary because any of these can return values which
have embedded spaces in them.  By quoting them, they can be passed to a
command or script as a single item.  The -t option disables this behavior
and replaces the built-in variable with unquoted literals.

.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 KEYBOARD BINDINGS AND HOW TO CHANGE THEM

No program that runs on many operating systems can satisfy 
everyone's (anyone's!) idea of what the "correct" key bindings
should be.  An emacs user, vi user, BSD user, and Windows user
are going to differ considerably on what keys should be bound
to what feature.

So, what follows is documentation on
the
.B default
key bindings.  However, it is not difficult to change the
defaults.  They are listed near the top of the program
file (twander.py) to allow people to tailor them as they
wish.  The only thing you need to know is the \'Tkinter\'
nomenclature for keystroke names.  You can get a pretty
good idea of this from reading the first part of the
program, and failing that, there is abundant documentation
of this topic on The Net.

The only convention that ought to be observed here (to keep
the program sane - it assumes this convention throughout), is
that
.B navigation commands are Control keys.

The obvious question here is, "Why isn't this a configuration option
maintained in the configuration file?"  The answer is that it would
make the configuration file parser overly complex to handle something
which should be changed very rarely, if at all.  The downside to this
approach is that per-user customization requires each user to keep a
copy of \'twander.py\' in their own directory space.


.SH ARROW AND KEYPAD BEHAVIOR

Generally, the arrow and keypad keys should do what you would expect
on the system in question. On Win32 systems, particularly, there ought
to be no odd arrow/keypad behavior.  

X-Windows is somewhat more problematic in this area.  Just what an
arrow key is "supposed" to do depends on how its been mapped in your X
server software.  Testing \'twander\' on various X servers showed
quite a bit of variability on how they handled the arrows and keypad.
So ... if you're running in an X Windows universe and arrows or keypad
do nothing, or do strange things, look into your key maps, don't blame
\'twander\'.

.SH DEFAULT KEYBOARD AND MOUSE BINDINGS


Here, ordered by category, are the default keyboard and mouse
bindings for \'twander\':

.SS General Program Commands

.PP

.TP
.B KEYPRESS KeyPress

.TP
.B QUITPROG Control-q

.TP
.B READCONF Control-r

.TP
.B REFRESH  Control-l

.TP
.B RUNCMD   Control-z

.TP
.B TOGDETAILControl-t


.SS Directory Navigation

.TP
.B CHANGEDIR Control-x

.TP
.B DIRHOME  Control-h

.TP
.B DIRBACK  Control-b

.TP
.B DIRSTART Control-s

.TP
.B DIRUP    Control-u

.TP
.B MSEBACK  Control-Double-ButtonRelease-1

.TP
.B MSEUP    Control-Double-ButtonRelease-3

.SS Selection Keys

.TP
.B SELALL   Control-comma

.TP
.B SELNEXT  Control-n

.TP
.B SELNONE  Control-period

.TP
.B SELPREV  Control-p

.TP
.B SELEND   Control-e

.TP
.B SELTOP   Control-a

.TP
.B SELKEY   Control-space

.TP
.B SELMOUSE Double-ButtonRelease-1


.SS Intra-Display Movement

.TP
.B PGDN     Control-v

.TP
.B PGUP     Control-c


.SH LOCATION OF CONFIGURATION FILE

\'twander\'
.B requires
a startup configuration file in order to run.  It is in this file that
the user defines the commands which can be applied to the files and
directories selected in the program GUI.

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


.SH CONFIGURATION FILE FORMAT


\'twander\' configuration files consist of freeform lines of
text.  Each line is considered separately - no legal configuration
line may cross into the next line.  Whitespace is ignored within
a line as are blank lines.

There are only three possible legal lines in a \'twander\'
configuration file: Comments, Variable Definitions, and 
Command Definitions.  Everything else is considered invalid.
\'twander\' will respond with errors or warnings as is 
appropriate anytime it encounters a problem in a configuration
file.  This is both true when the program initially loads as
well as during any subsequent configuration file reloads
initiated from the keyboard while running \'twander\.


.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 DESIGN PHILOSOPHY
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 consequence 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 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