.TH twander 1 "TundraWare Inc."
.ds CP 2002-2005
.SH NAME
twander \- File Browser
.SH OVERVIEW
Wander around a filesystem executing commands of your choice on
selected files and directories. The general idea here is
that \fCtwander\fP provides GUI facilities for navigating around your
filesystem, but
.B you
define the commands you want available via "Command Definitions"
(in the Configuration File). In other words, \fCtwander\fP can't
do anything useful until you've defined some commands. This document
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
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.
If you're new to \fCtwander\fP 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
.B DESIGN PHILOSOPHY
toward the end of this document first.
Similarly, if this is the first time you've worked with \fCtwander\fP,
there is a section near the end of this document entitled
.B INSTALLING \fCtwander\fP
which describes how the program should be installed.
You can get the latest version of the program and documentation
from the \fCtwander\fP homepage:
.ft C \" courier
.nf
http://www.tundraware.com/Software/twander/
.fi
.ft \" revert
You should check this site periodically for program updates,
bug fixes, and enhancements.
Also, you are strongly encouraged to join the \fCtwander\fP mailing
list where you'll find help and answers to questions you
have about this program. Details of how to do this can
be found toward the end of this document in the section
entitled,
.B GETTING HELP: THE \fCtwander\fP MAILING LIST.
.SH SYNOPSIS
twander [-cdhqrtv] [startdir]
.SH OPTIONS
.TP
.B startdir
Directory in which to begin. (default: directory in which program was
started)
If this directory does not exist or cannot be opened, \fCtwander\fP
will display an error message and abort.
.TP
.B -c path/name of Configuration File
Specify the location and name of the configuration
file. (default is ~/.twander)
If this file does not exist or cannot be opened, \fCtwander\fP will
display a warning to that effect but continue to run. This is
reasonable behavior because \fCtwander\fP provides a command to reload
the Configuration File without exiting the program (which you would
presumably do after fixing the Configuration File problem).
.TP
.B -d debuglevel
Start in debug mode dumping the items specified in the debuglevel.
(default: debuglevel=0/debug off)
\fCtwander\fP is able to selectively dump debugging information to
stdout. \'debuglevel\' is understood to be a bitfield in which
each bit specifies some kind of debugging information or
behavior. \'debuglevel\' can be specified in either decimal
or hex (using the form 0x#) formats. The bits in the bitfield
are defined as follows:
.ft C \" courier
.nf
Bit Hex Value Meaning
--- --------- -------
0 0x001 Dump Internal Options & User-Settable Options
1 0x002 Dump User-Defined Variables
2 0x004 Dump Command Definitions
3 0x008 Dump Key Bindings
4 0x010 Display, Do Not Execute, Commands When Invoked
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
10 0x400 Reserved/Unused
11 0x800 Dump Requested Debug Information And Exit Immediately
.fi
.ft \" revert
These bits can be combined to provided very specific debugging
information. For example, \'-d 0x80f\' will dump (to stdout) all the
Internal Options, User-Settable Options, User-Defined Options, Command
Definitions, and Key Bindings and then terminate the program.
.TP
.B -h
Print help information on stdout.
.TP
.B -q
Quiet mode - suppresses warnings. (default: warnings on)
.TP
.B -r
Turn off automatic refreshing of directory display. (default: refresh
on)
Normally \fCtwander\fP re-reads and displays the current directory
every few seconds to reflect any changes that might have occurred to
that directory's contents. This option is useful on slow machines (or
slow X connections) and/or when working with very large directories.
In this situation, the frequent updating of the \fCtwander\fP display
can make the program unacceptably slow and unresponsive. In this case
you can still force an update manually with the REFRESH function (default
assignment is to the Control-l key).
.TP
.B -t
Turn off quoting when substituting built-in variables. (default: quoting on)
Anytime \fCtwander\fP encounters a reference to one of the built-in
variables which do string replacement (DIR, DSELECTION, DSELECTIONS,
MEM1-12, PROMPT:, SELECTION, SELECTIONS) in a command, 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.
.SH OTHER WAYS TO SET \fCtwander\fP OPTIONS
In addition to these command line options, there are two other ways
you can set \fCtwander\fP program features. If you prefer, you
can set the command line options via the environment variable,
TWANDER. That way you don't have to type them in each time you
start the program. Say you set the environment variable this way
on Unix:
.ft C \" courier
.nf
export TWANDER=-qt
.fi
.ft \" revert
From then on, every time you run the program, the -q and -t options
would be invoked (No Quoting, No Warnings) just as if you had typed
them in on the command line.
The second way to set these (and MANY more) Program Options is
by setting the appropriate entries in the Configuration File. This
is covered later in this document.
\fCtwander\fP evaluates options in the following order (from first
to last):
.IP \(bu 4
Internally set default value of options
.IP \(bu 4
Options set in the Configuration File
.IP \(bu 4
Options set in the TWANDER environment variable
.IP \(bu 4
Options set on the command line
.P
This means, for example, that the environment variable overrides a
corresponding setting in the Configuration File, but the command line
overrides the environment variable. Furthermore, there are many
Program Options which can
.B only
be set/changed the Configuration File and are not available in
either the environment variable or on the command line.
This also means that options set on the command line are not read
until after the Configuration File has been processed. So, the -q
argument on the command line will not inhibit warnings generated
during the reading of the Configuration File. This is best done by
adding the statement, WARN=False, at the top of the Configuration
File.
If the Configuration File is reloaded while the program is running
(see the READCONF key below), any options set in the file will have
the last word. This allows you to edit the Configuration File and
have your changes reflected in a running instance of \fCtwander\fP, but
it also means that the environment variable/command line arguments are
ignored after initial program startup.
.SH THE TITLE BAR
\fCtwander\fP displays a lot of information about the state of the running
program in the main window title bar. From left to right you will see:
.IP \(bu 4
Program name and version number.
.IP \(bu 4
Login name and machine/domain of current user.
.IP \(bu 4
The path of the directory you are currently viewing. If
this path length is greater than 60 characters, \fCtwander\fP will
show the last 60 characters of the path length, prepended with
"..." to show that it is truncated.
.IP \(bu 4
Any "filter" that is limiting which files you see. If you've toggled
the filter, you will see the word "NOT" before the filter string.
.IP \(bu 4
An indication of whether or not "dotfiles" are currently hidden.
.IP \(bu 4
The total number of files in this directory. The ".." entry is
not included in this count.
.IP \(bu 4
The total size of all the files in this directory. The size of the ".."
directory is not included in this total.
.IP \(bu 4
They key used to sort the display. If a reverse sort is
selected, you will see "-" appended to the end of the
key to indicated this. "Sort By: NAME-" means you are
doing a reverse sort by name.
.IP \(bu 4
An indication of whether or not directories and ordinary files
are being separated in the display.
.IP \(bu 4
An indication of whether or not automatic refreshing is enabled.
Anytime refreshing is actually underway, whether automatic,
manual, because you are executing a command that forces a
refresh, or just because you changed directories, you will see
the '*' character appended to this field. Ordinarily, this
happens so quickly you will not see it. However, on really
large directories and/or very slow disks like CDROMs, you'll
see the asterisk stay on for some time. During refresh, the program
is locked from user input. On very long refreshes, it can appear
to be "hung". This indicator is there just to let you know the
program is busy refreshing and all is well.
.SH KEYBOARD USE
By design, \fCtwander\fP allows you to do almost everything of interest
using only the keyboard. Various \fCtwander\fP features are thus
associated with particular keystrokes which are described below. It
is also very simple to change the default key assignments with entries
in the Configuration File, also described below.
.SH NOTES ON KEYBOARD ARROW/KEYPAD BEHAVIOR AND TEXT DIALOG EDITS
Generally, the arrow and keypad keys should do what you would expect
on the system in question. On Windows 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 it's been mapped in your X
server software. Testing \fCtwander\fP on various X servers showed
quite a bit of variability in 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
\fCtwander\fP.
There are several features of \fCtwander\fP that will present the user a
text entry dialog. These include the CHANGEDIR and RUNCMD features as
well as the {PROMPT:...} Built-In Variable (all described below).
Any time you are entering text in such a dialog, be aware that the
text can be edited several ways - You can edit it using the
arrow/keypad editing assignments which are enabled/normal for your
operating system, OR you can use emacs-style commands to edit the
text. For instance, Control-a, Control-k will erase the text
currently entered in the dialog.
.SH DEFAULT KEYBOARD AND MOUSE BINDINGS
Here, ordered by category, are the default keyboard and mouse
bindings for \fCtwander\fP. The general format is:
.TP
.B Description (Program Function Name)
Default Key Assignment
.IP
Default Mouse Assignment (if any)
.P
The "Program Function Name" is the internal variable \fCtwander\fP
uses to associate a particular feature with a particular keystroke
or mouse action. You can ignore it unless you intend to override
the default key assignments. This use is described below in the
section entitled,
.B Key Binding Statements.
It is important to realize that \fCtwander\fP key-bindings are
.B case-sensitive.
This means that \'Control-b\' and \'Control-B\' are different.
This was a conscious design decision because it effectively
doubles the number of Control/Alt key combinations available
for the addition of future features.
The default bindings chosen for \fCtwander\fP features are all currently
.B lower-case.
If your program suddenly stops responding to keyboard commands,
check to make sure you don't have CapsLock turned on.
.B NOTE:
Some \fCtwander\fP features are doubled on the mouse. These mouse
button assignments are documented below for the sake of completeness.
However,
.B mouse button assignments cannot be changed by the user,
even in the Configuration File.
.SS General Program Commands
This family of commands controls the operation of \fCtwander\fP itself.
.TP
.B Clear History (CLRHIST)
Control-y
Clears out various program histories including the All Visited Directories list,
the Directory Stack, the Command History, and the last
manually-entered values for CHANGEDIR and RUNCMD. The 12 Program
Memories are not cleared - they have specially dedicated key bindings
for this purpose.
.TP
.B Decrement Font Size (FONTDECR)
Control-[
Decrease font size.
.TP
.B Increment Font Size (FONTINCR)
Control-]
Increase font size.
These two features allow you to change the display font sizes while
\fCtwander\fP is running. But, you may not immediately get the results
you expect. \fCtwander\fP internally keeps track of separate font
sizes for the main display, the main menu text, and the help menu
text. When you use the two font sizing commands above, \fCtwander\fP
subtracts or adds 1 to each of these three values respectively. On
systems like Windows using TrueType fonts, this works as you would
expect, because every font is effectively available in every size.
However, in systems like X-Windows or Windows using fixed-size fonts,
you may have to press these keys repeatedly until \fCtwander\fP finds
a font matching the requested size.
This can also cause some parts of the display to change but not
others. Suppose you are running on X-Windows and have specified that
the main display is to use a 12 point font, and that menus and help
should use 10 point font. Let's also suppose that the next font
available larger than 12 point is 16 point. If you press FONTINCR
twice, both the menu text and help text will jump to 12 point, but the
main display text will remain unchanged. Why? Because pressing
FONTINCR twice tells \fCtwander\fP to set the main display to 14 point
(12+1+1) which does not exist, and the menu and help text to 12 point
(10+1+1) which does exist, so that change is visible.
The "User-Settable Options" Help Menu displays the font metrics (name,
size, weight) you've currently specified. Pressing FONTDECR/FONTINCR
changes the size specification and this will be reflected in that
menu. However, most systems do some form of "best match" font
substitution - if you ask for a font that does not exist, the system
will use the "closest matching" font as a substitute. This means the
font you see specified in the Help Menu is not necessarily the font
you're actually using. You're more likely to run into this when
running on a Unix/X-Windows system (where not all the fonts are
available in all sizes/weights like they are on Windows TrueType) as you
change the font size with FONTDECR/FONTINCR.
Reloading the Configuration File (READCONF) will reset the fonts
to either their default values or any font sizes specified in the
Configuration File.
.TP
.B Display Command Menu (MOUSECTX)
Right-Mouse-Button
Displays a list of all available commands in a pop-up menu near the mouse
pointer. If no commands are defined, this feature does nothing at all.
This means commands can be invoked one of three ways: Directly via the
Command Key defined in the Configuration File, via selection in the
Command Menu at the top of the GUI, or via selection from the Command
Menu.
Windows users should note that, unlike Windows Explorer, the \fCtwander\fP
Command Menu does not change the set of currently selected items. It
merely provides a list of available commands. This allows the
command chosen via the Command Menu to operate on a previously
selected set of items.
.TP
.B Display Directory Menu (MOUSEDIR)
Shift-Right-Mouse-Button
Displays a list of all the directories visited so far in a pop-up menu
near the mouse. This means that you can navigate to a previously
visited directory in one of two ways: Via a selection in the
Directory Menu at the top of the GUI or via a selection from
this pop-up menu.
.TP
.B Display History Menu (MOUSEHIST)
Control-Shift-Right-Mouse-Button
Displays a list of all commands executed so far (including those
entered manually) in a pop-up menu near the mouse pointer. If the
Command History is empty, this command does nothing. This means you
can repeat a previously entered command via the History Menu or this
mouse command. (You can also repeat the last manually entered command
by pressing RUNCMD - it will preload its text entry area with the last
command you entered by hand.)
.TP
.B Display Shortcut Menu (MOUSESC)
Control-Right-Mouse-Button
Displays a list of all user-defined directory shortcuts in a pop-up
menu near the mouse. The menu also has "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
with the Win32All extensions, there is also a shortcut to the Drive
List View.
.TP
.B Display Sorting Menu (MOUSESORT)
Alt-Shift-Right-Mouse-Button
(Note that on Windows you must press Alt
.B then
Shift
.B then
the Right-Mouse-Button for this to work. Windows appears to care deeply
about keystroke order.)
Displays a list of all the sorting options in a pop-up menu near the
mouse.
.TP
.B Quit Program (QUITPROG)
Control-q
Exit the program.
.TP
.B Re-Read Configuration File (READCONF)
Control-r
Re-read the Configuration File. This allows you to edit the
Configuration File while \fCtwander\fP is running and then read your
changes in without having to exit the program. This is handy when
editing or changing Command Definitions.
Program Options are set back to their default each time a
Configuration File is about to be read (initially or on reload) just
before the Configuration File is parsed. This means commenting out or
removing a Program Option Statement (see relevant section below) in
the Configuration File and then pressing READCONF causes that option to
be reset to its default value. STARTDIR defaults to either its
internal default ($HOME or ./) or to the value given in the
Environment Variable/Command line.
.TP
.B Refresh Display (REFRESH)
Control-l
Re-read the current directory's contents and display it. This is most useful
if you have turned off automatic directory refreshing with either the -r command
line flag or setting the AUTOREFRESH Program Option to False.
.TP
.B Toggle Autorefreshing (TOGAUTO)
Control-o
Toggle Autorefreshing on- and off. This is handy if you are about to
enter a very large directory and/or a very slow disk (like a CDROM).
With very large or slow directory reads, \fCtwander\fP can end up spending all
its time doing re-reads of the directory and never give you time to do
anything there. If you find this is consistently the case, then you
need to increase REFRESHINT. But for the occasional adventure into
very large/slow directories, just toggling Autorefresh off is
more convenient.
The state of the Autorefresh feature is displayed on the main
window title bar.
.TP
.B Toggle Details (TOGDETAIL)
Control-t
Toggle between detailed and filename-only views of the directory.
.TP
.B Toggle Between Normalized And Actual File Length Display (TOGLENGTH)
Control-0
By default, the program "normalizes" file sizes and expresses them in
bytes, Kilobytes, Megabytes, or Gigabytes rather than showing their
actual size. This is done everywhere a file size is displayed: on
individual files, the total files size displayed on the title bar, and
the drive sizes in Win32 Drive List View. This key binding invokes a
feature that toggles these size displays between normalized and
actual. See the ACTUALLENGTH configuration option below to set the
default as you prefer it.
.TP
.B Toggle \'win32all\' Features (TOGWIN32ALL)
Control-w
As described later in this document, \fCtwander\fP provides enhanced
features for Windows users who also install Mark Hammond's \'win32all\'
extensions for Python on Windows. This key binding will toggle those
advanced features on- and off. This is useful if you happen to
be examining a very large directory. The \'win32all\' features,
while handy, can be computationally expensive and make updates of
a directory with many entries somewhat slow. This toggle is provided
as a means to temporarily disable the advanced features when viewing
such a directory.
.SS Directory Navigation
This family of commands controls movement between directories. If you
attempt to navigate into a directory that does not exist or which does
not have appropriate permissions, \fCtwander\fP will display a warning
message and remain in the current directory. This is
.B unlike
the case of a non-existent or unreadable directory specified when the program
is first started. In that case, \fCtwander\fP reports the error and aborts.
.TP
.B Change Directory (CHANGEDIR)
Control-x
This is a shortcut that allows you to directly move to a new directory/path -
i.e., Without having to navigate to it.
Unless you have set the MAXMENU option to 0, CHANGEDIR keeps track of
your last manually entered directory and presents it as a default when
you press CHANGEDIR again. You can then move to that directory, edit
the string to specify another directory, or delete it and enter an
entirely new directory. Directories can be edited with either the
arrow and keypad keys defined on your system or by emacs editing
commands like Control-a, Control-k, Control-e, and so forth.
.TP
.B Go To Home Directory (DIRHOME)
Control-h
If the "HOME" environment variable is defined on your system, this will move
you to that directory. If the "HOME" environment variable is not defined,
this command will move to the original starting directory.
.TP
.B Go Back One Directory (DIRBACK and MOUSEBACK)
Control-b
.IP
Control-DoubleClick-Left-Mouse-Button
\fCtwander\fP keeps track of every directory visited and the order in
which they are visited. This command allows you to move back
successively until you get to the directory in which you started.
This feature is implemented as a stack - each "backing up" removes
the directory name from the visited list. The "Directory" menu (see
.B MENU OPTIONS
below) implements a similar feature in a different way and keeps track of
all directories visited regardless of order.
.TP
.B Go To Root Directory (DIRROOT)
Control-j
Go to the root directory.
.TP
.B Go To Starting Directory (DIRSTART)
Control-s
Go back to the original directory in which \fCtwander\fP was started.
.TP
.B Go Up To Parent Directory (DIRUP and MOUSEUP)
Control-u
.IP
Control-DoubleClick-Right-Mouse-Button
Move to the parent of the current directory ("..").
.TP
.B Display Drive List View (DRIVELIST)
Control-k
This is a Windows-only feature which displays a list of all available
disk drives. Details about each drive are also displayed if you have
details enabled. In order for this feature to work, you must be
running on Windows AND have the \'win32all\' package installed, AND the
USEWIN32ALL Program Option must be True (default condition,) AND you
must not have toggled these features off with the TOGWIN32ALL key
described above. For more details about Drive List View, see the
section below entitled,
.B ADVANCED WINDOWS FEATURES.
.SS Selection Keys
This family of commands controls the selection of one or more (or no)
items in the current directory.
.TP
.B Select All Items (SELALL)
Control-Comma
Select every item in the current directory. The ".." entry at
the top of the directory listing is not included. (We almost
never want to include the parent directory when issuing a
command on "everything in this directory". If you do wish
to include the "..", do the SELALL command first, then click
on ".." while holding down the Control key.)
.TP
.B Invert Current Selection (SELINV)
Control-i
Unselects everything which was selected and selects everything which
was not. As with SELALL, and for the same reason, the ".." entry is
never selected on an inversion.
.TP
.B Unselect All Items (SELNONE)
Control-Period
Unselect everything in the current directory.
.TP
.B Select Next Item (SELNEXT)
Control-n
Select next item down in the directory.
.TP
.B Select Previous Item (SELPREV)
Control-p
Select previous item up in the directory.
.TP
.B Select Last Item (SELEND)
Control-e
Select last item in the directory.
.TP
.B Select First Item (SELTOP)
Control-a
Select first item in the directory. This will always be the
".." entry, but it is a quick way to get to the first part of
a very long directory listing which does not all fit on-screen.
.TP
.B Mouse-Based Selections
The mouse can also be used to select one or more items. A
single-click of the left mouse button selects a particular item.
Clicking and dragging selects an adjacent group of items. Clicking an
item and then clicking a second item while holding down the "Shift"
key also selects an adjacent group of items. Finally, a group of
non-adjacent items can also be selected. The first item is selected
with a single left mouse button click as usual. Each subsequent
(non-adjacent) item is then selected by holding down the "Control"
key when clicking on the item.
.SS Scrolling Commands
If a given directory's contents cannot be displayed on a single
screen, \fCtwander\fP supports both vertical and horizontal scrolling
via scrollbars. This capability is doubled on the keyboard with:
.TP
.B Scroll Page Down (PGDN)
Control-v
Scroll down one page in the directory listing.
.TP
.B Scroll Page Up (PGUP)
Control-c
Scroll up one page in the directory listing.
.TP
.B Scroll Page Right (PGRT)
Control-g
Scroll to the right one page width.
.TP
.B Scroll Page Left (PGLFT)
Control-f
Scroll to the left one page width.
.SS Command Execution Options
This family of commands causes \fCtwander\fP to actually
attempt to execute some command you've chosen:
.TP
.B Run Arbitrary Command (RUNCMD)
Control-z
This is a shortcut that allows you to run any command you'd like
without having to define it ahead of time in the Configuration File.
It is more-or-less like having a miniature command line environment at
your disposal.
You may enter a number of different things in the RUNCMD dialog. You
may type literal text or refer to any of the variable types
(User-Defined, Environment, or Built-In) supported by \fCtwander\fP just
as you do in writing Command Definitions (see below). This makes it
easy to enter complex commands without having to type everything
literally. For example, if you would like to copy all the currently
selected files to a new directory, press RUNCMD and enter (on Unix):
.ft C \" courier
.nf
cp [SELECTIONS] newdir
.fi
.ft \" revert
\fCtwander\fP understands the variable reference syntax here just as it
does in a Command Definition. This also gives you a single way of
referring to environment variables, regardless of OS platform. Recall
that in Unix-like shells, an environment variable is in the form
"$NAME", but on Windows it is in the form "%NAME%". Instead if having
to keep track of this difference, you can just use a \fCtwander\fP
Environment Variable reference. For instance, assuming the EDITOR
environment variable is set, this command works the same
on both systems:
.ft C \" courier
.nf
[$EDITOR] [SELECTIONS]
.fi
.ft \" revert
Built-in variables are most often used when manually entering commands
So, RUNCMD also understands some "shortcut" references to many of the
built-ins. You may use:
.ft C \" courier
.nf
[D] for [DIR]
[DN] for [DSELECTION]
[DS] for [DSELECTIONS]
[SN] for [SELECTION]
[SS] for [SELECTIONS]
[1] for [MEM1]
[2] for [MEM2]
[3] for [MEM3]
[4] for [MEM4]
[5] for [MEM5]
[6] for [MEM6]
[7] for [MEM7]
[8] for [MEM8]
[9] for [MEM9]
[10] for [MEM10]
[11] for [MEM11]
[12] for [MEM12]
.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
variables. This is a conscious design decision to help enforce
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
you press RUNCMD again. You can then run the command again exactly
as you last entered it, you can modify it before running the command
again, or you can delete it and enter an entirely new command. Commands
can be edited with either the arrow and keypad keys defined on your
system or by emacs editing commands like Control-a, Control-k,
Control-e, and so forth.
Also see the section below entitled,
.B Program Option Statements,
to understand the CMDSHELL option. This option
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
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,
.ft C \" courier
.nf
+mycommand
.fi
.ft \" revert
\fCtwander\fP will initiate the command, wait AFTERWAIT seconds (default: 1),
and then update the display. See the discussion below entitled,
.B Forcing Display Updates In Command Definitions
for a more complete explanation.
This feature may be used in combination with CMDSHELL escaping
(also described in the
.B Program Option Statements
section below) and the two characters may appear in any order at
the beginning of the command line you enter.
.TP
.B Run Selected File / Move To Selected Directory (SELKEY and MOUSESEL)
Return (Enter Key)
.IP
DoubleClick-Left-Mouse-Button
If the selected item is a Directory, \fCtwander\fP will move into
that directory when this command is issued. If the selected item
is a file, \fCtwander\fP will attempt to execute it. Whether or not
the file is actually executed depends on how the underlying operating
system views that file.
In the case of Unix-like operating systems, the execute permission
must be set for the user running \fCtwander\fP (or their group) for the
file to be executed.
On Windows, the file will be executed if the user has permission to do
so
.B and
that file is either executable or there is a Windows association
defined for that file type. For example, double-clicking on a
file ending with ".txt" will cause the file to be opened with
the \'notepad\' program (unless the association for ".txt" has
been changed).
If \fCtwander\fP determines that it is running on neither a Unix-like
or Windows system, double-clicking on a file does nothing.
.TP
.B Run User-Defined Command
User-Defined (Single Letter) Key
Each command defined in the Configuration File has a Command Key
associated with it. Pressing that key will cause the associated
command to be run. If no command is associated with a given
keystroke, nothing will happen when it is pressed.
.SS Directory Shortcuts
\fCtwander\fP provides a way to directly navigate into a frequently-used
directory using a single keystroke. You can define up to 12 such
"Directory Shortcuts" in the Configuration File. Each of the
definitions is associated with one of the following 12 keys:
.TP
.B Navigate Directly To A Directory (KDIRSC1 ... KDIRSC12)
F1 ... F12
Pressing one of these keys changes to the directory associated with it
in the Configuration File. For more information on this topic, see
the discussion of the Configuration File below entitled,
.B Directory Shortcut Statements
.
.TP
.B Assign Current Directory To One Of The Shortcut Keys (KSETSC1 ... KSETSC12)
Alt-q, Alt-w, ... Alt-bracketleft, Alt-bracketright
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
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.
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
directory shortcut you want to "override", the
.B current directory
is associated with that shortcut. So, for instance, \fCAlt-q\fP will
associate the current directory with shortcut #1 (Default: \fCF1\fP),
\fCAlt-w\fP associates the current directory with shortcut #2
(Default: \fCF2\fP) and so forth, all the way through
\fCAlt-bracketright\fP which associates the current directory with
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).
.SS Program Memories
If you've used GUIs before, you're probably familiar with the idea
of a program "Clipboard" - a temporary holding area which is used when
cutting, copying, and pasting files. This is a good idea, but has
several limitations. First, most systems only have a
.B single clipboard.
It would be mighty handy to have muliple Clipboard-like storage
areas for keeping track of several different operations at once.
Secondly, when you copy or paste something to a conventional Clipboard,
.B its old contents get overwritten.
There is no way to keep appending items to the Clipboard.
Finally, items usually can only be cut or copied to the Clipboard
.B from the current directory.
It would be nice if we could not only keep adding things to the
Clipboard, but be able to do so as we navigate around the filesystem.
\fCtwander\fP addresses these concerns by means of 12 separate "Program
Memories". As you use \fCtwander\fP, you can add (append) the names of
any directories or files in the currently viewed directory by
selecting them and then using the appropriate \fCtwander\fP MEMSETx key
(see below). To take advantage of this feature, you write Command
Definitions (or manually issue a command via the RUNCMD key) which
reference the contents of a Program Memory using one of the [MEMx]
Built-In Variables. (See the section below on entitled,
.B Program Memory Built-Ins
for more details in how to apply Program Memories).
\fCtwander\fP provides key combinations for selectively setting and
clearing particular Program Memories as well as a key combination
for clearing all Program Memories in a single keystroke:
.TP
.B Clear Selected Program Memory (MEMCLR1 - MEMCLR12)
Control-F1 ... Control-F12
Clear (empty) the selected Program Memory.
.TP
.B Clear All Program Memories (MEMCLRALL)
Control-m
Clear (empty) all 12 Program Memories at once.
.TP
.B Set Selected Program Memory (MEMSET1 - MEMSET12)
Alt-F1 ... Alt-F12
Append the
.B the full path names
of the currently selected files and directories to the Program Memory
desired.
.SS Sorting Options
\fCtwander\fP provides a variety of ways to sort the display. These can be
selected with either a keystroke or from the Sorting Menu (see below).
The meaning of the sort depends on whether or not you are in Drive
List View (see
.B ADVANCED WINDOWS FEATURES
below). The table below summarizes the keys associated with
sorting and their meaning in the two possible views:
.ft C \" courier
.nf
Program
Function Sort Order In Sort Order In
Key Name Normal View Drive List View
--- -------- ------------ ---------------
Shift-F10 SORTBYNONE No Sort No Sort
Shift-F1 SORTBYPERMS Permissions Label/Share String
Shift-F2 SORTBYLINKS Links Drive Type
Shift-F3 SORTBYOWNER Owner Free Space
Shift-F4 SORTBYGROUP Group Total Space
Shift-F5 SORTBYLENGTH Length Drive Letter
Shift-F6 SORTBYTIME Time Ignored
Shift-F7 SORTBYNAME Name Ignored
Shift-F11 SORTREV Reverse Order Reverse Order
Shift-F12 SORTSEP Separate Dirs Ignored
.fi
.ft \" revert
An easy way to remember these is that the function key number
for the primary sort keys corresponds to the column position
of the key in a detailed display. For instance, Shift-F1
sorts by column 1, Shift-F2 by column 2, and so forth.
These sorting options are available
.B whether or not details are currently available.
For example, you can toggle details off, but still sort by one of
the now invisible details such as Owner, Length, and so on.
SORTREV reverses the order of the sort.
SORTSEP toggles whether or not directories and files should be grouped
separately or displayed in absolute sort order. If enabled,
directories will be displayed first, then files. If the sort is
reversed via SORTREV, and SORTSEP is enabled, the directories will
appear
.B after
the files, sorted by whatever sort key has been chosen. SORTSEP
is not meaningful in Drive List View and is ignored.
You'll find the currently selected sorting options displayed in the
program title bar.
.SS Wildcard Features
Although \fCtwander\fP provides a very rich set of keyboard and mouse
selection commands, selecting a group of files out of list
of hundreds or thousands in a large directory can be tedious.
If the files/directories you want to select have some lexical commonality
.B in their names OR details
you can have \fCtwander\fP select them for you using so-called
"Regular Expressions".
You can do this in one of two ways. A wildcard "filter" only
.B displays
files that match the specified regular expression. A wildcard "selection"
.B selects
(highlights) the matching entries from the currently displayed list.
The general idea is to use filters to limit the number of files you'll
even see in the \fCtwander\fP interface and then optionally choose
from among them with a wildcard-based selection.
For example, suppose you initiate a wildcard-based selection (SELWILD)
with the text, \fCtar\fP. This would select every file or
directory in the current display where the string "tar"
.B appeared anywhere on the line for that file/directory.
This is very important: Wildcard matching takes place anywhere on the
visible line. So, if you have details turned on, the match can occur
anywhere on the permissions, links, group, owner, and so on.
Obviously, if you have details turned off, the match can only occur on
the name of the file or directory since that's all that is visible.
This is a purposeful design decision because it allows you to
make selections on more than just the name. Say you enter the
following in the FILTERWILD dialog:
.ft C \" courier
.nf
drwx------
.fi
.ft \" revert
\fCtwander\fP would display only the entries that are directories with
no permissions enabled for group or world users.
The matching string above could also filter/select other entries (not having
the permissions just described), if say, this string
appeared in their name ... a rather unlikely scenario, but not
impossible. If we want to get
.B real
specific about which entries we want selected, we need to
enter a "regular expression" in the wildcard dialog.
Regular expressions are a far more powerful pattern-matching
tool than simple text strings and will allow you to do some
fairly amazing selections. For example, this regular expression
selects all entries which contain a string beginning with "Ju"
followed by any other character, a single space, and ending
in "0":
.ft C \" courier
.nf
Ju. 0
.fi
.ft \" revert
So, for instance, this would select files with date details (or names,
or anything else on the line...) like "Jun 01", "Jul 03", and "Jul
09".
No matter what you specify, a literal matching string or a regular
expression, the ".." entry of the currently viewed directory is never
selected for wildcard processing. This is a "special" entry that is
always present regardless of filtering and never selected with
wildcard-based selections.
Notice that these regular expressions are
.B not
the same thing as the filename "globbing" wildcards commonly
used with Unix and Windows shells. If you enter constructs like
"*.txt" or "*.tar.gz", you will not get the results you expect.
In fact, these specific examples will cause \fCtwander\fP to grumble
and present a warning message.
For an excellent tutorial on Python-compliant regular
expressions, see:
.ft C \" courier
.nf
http://www.amk.ca/python/howto/regex/
.fi
.ft \" revert
By default, these wildcarding tools will select an entry when your
regular expression matches anything on the displayed line. This
allows you to make selections based on any visible column of
information. This "match anywhere on the line" semantic is possible
because \fCtwander\fP automatically massages the regular expression you
provide to make "any match on the line" true. There may be times when
you want to provide very specific regular expression definitions which
seek a match at specific locations. In that case, you can prevent
the program from fiddling with your regular expression, by beginning it
with the double-quote (") character. \fCtwander\fP understands this to mean
that your regular expression is to be treated literally without
modification. (It only throws away this leading escape character.)
Suppose we changed our example above slightly and used this
regular expression:
.ft C \" courier
.nf
"^drwx------
.fi
.ft \" revert
Now \fCtwander\fP would select
.B only
the directories without any group and world access because:
.IP \(bu 4
The leading double-quote (") forces literal interpretation of the
regular expression - i.e. It turns off "match anywhere" semantics
as just described.
.IP \(bu 4
The carat (^) at the beginning of the actual regular expression
"anchors" the match to the start of the line. For a match
to be declared (and for \fCtwander\fP to select an item) the regular
expression must be satisfied at the beginning-of-line.
.P
Because regular expressions can get complicated and tedious to type
in, any such expression you use is saved in a history available via
the Filter and Select Menus (see below). There is also provision
for pre-defining frequently used wildcards in your Configuration File
(see section below on \fCWILDFILTER=\fP and \fCWILDSELECT=\fP
configuration statements) so you don't have to type them in manually
each time you start the program - you can just select them from the
relevant menu.
A few points to keep in mind when using wildcard features:
.IP \(bu 4
By default, wildcard matching is case-insensitive on Win32 systems and
case-sensitive everywhere else. This is because Windows systems allow
case in filenames and attributes, but it is not significant - i.e., The
case of a filename or attribute is ignored on Windows systems. You
can control this explicitly with the \fCWILDNOCASE\fP configuration
option. If you set \fCWILDNOCASE=False\fP, it will force all wildcard
filters and selections to be case-sensistive. Setting it to
\fCTrue\fP makes the wildcarding case-insensitive. This option is
available for both Unix and Win32 systems so you can set the behavior
you like anywhere.
.IP \(bu 4
If you escape a wildcard to force \fCtwander\fP to treat it exactly as
you defined it, the case-sensitivity set by default or \fCWILDNOCASE\fP
is ignored. Escaped wildcards are always treated
.B exactly
as you enter them and they are matched against the filename and/or details
exactly as they appear.
.IP \(bu 4
Wildcard-based filters are applied against the
.B entire contents
of the current directory to determine which files match and should be
displayed. But, wildcard-based selections are done against the
.B currently visible
files. This is important if you do a filter and then a selection
wildcard. The first will select which files to display. The second
will select which ones to highlight from the displayed list.
.P
.TP
.B Display Files Matching A Regular Expression (FILTERWILD)
Control-equal
This will present you with a dialog to enter your regular expression
matching criteria described above. After you enter it, \fCtwander\fP
will only display the files that match. The filter is reset (to no
filtering) when you manually referesh the directory - with \fCREFRESH\fP (default: Control-l - or
change directories.
.TP
.B Toggle Active Filter (TOGFILT)
Control-minus
Pressing this once "inverts" any filter currently active. It means "show me the files
that
.B don't
match the filtering regular expression." Pressing it again returns the filter
to its normal meaning. This is handy when you want to display everything
.B except
a group of files. You first filter for the files you don't want and then
press \fCTOGFILT\fP which will display everything except these files.
.TP
.B Select Files Matching A Regular Expression \'Wildcards\' (SELWILD)
Control-\\
This will present you with a dialog to enter your regular expression
matching criteria described above. After you enter it, \fCtwander\fP will
select (highlight) the files that match.
You can also "invert" your selections by using the \fCSELINV\fP key described
previously. This is useful when you want to select everything
.B except
a group of files. Select the ones you don't want with a selection wildcard
andthen press the \fCSELINV\fP key.
Selections remain in effect until you make another manual selection,
clear all selections, or run a command that forces a directory refresh
after it runs - i.e., Commands defined with a leading "+".
.TP
.B Display Selection Wildcard Menu (MOUSEFILTERSEL)
Alt-Control-Middle-Mouse-Button
.TP
.B Display Selection Wildcard Menu (MOUSEWILDSEL)
Alt-Control-Right-Mouse-Button
(Note that on Windows you must press Alt
.B then
Control
.B then
the mouse button for this to work. Windows appears to care deeply
about keystroke order.)
These keys popup a list near the current mouse cursor of any
previously used filtering or selection wildcards respectively.
Selecting one of the entries therein pops-up a dialog that allows you
to edit the wildcard before actually doing another wildcard filter or
selection. This allows use to modify previous wildcards for new use.
.SS Hiding Dotfiles
By convention on Unix and many other systems, files or directories
whose names begin with a dot ('.') are usually used as configuration
files (directories). Unless you specifically want to edit a
configuration, you typically do little or nothing with these files.
Since there can be quite a few of them on a modern system, it's
helpful to be able to block them from view.
By default, dotfiles are not hidden, but this can be changed with
the HIDEDOTFILES configuration option.
By default, files or directories whose names begin with a period (".")
are considered dotfiles. You can change this dotfile "introducer"
string with the DOTFILE configuration option.
.TP
.B Toggle Dotfile Hiding (TOGHIDEDOT)
Control-9
This toggles dotfile hiding, on- and off. The program starts up
with dotfiles visible or hidden as defined by the HIDEDOTFILES
program option. Thereafter, TOGHIDEDOT can be used to make
these files and directories visible or not.
.P
Unlike Wildcard Filters (which test the entire displayed line),
dotfile hiding is triggered only by the
.B name
of the file or directory.
If you change DOTFILE to some other string, be aware that the test to
see if a file (or directory) name starts with this string is
.B case-sensitive.
If you set DOTFILE to "De", it will not hide files starting with "de",
for example.
The current state of dotfile hiding is displayed in the window title
bar, immediately after the Filter information.
Note that even though you cannot see the files with this option
enabled, commands you write can still operate on these files. For
example, if you define a command that does something like:
.ft C \" courier
.nf
c cleandot rm .*~
.fi
.ft \" revert
This command will remove any backup (~) files, whether or not you can
see them in the interface.
.SH MENU OPTIONS
Although \fCtwander\fP is primarily keyboard-oriented, several
menu-based features are also implemented to make the program more
convenient to use. These menus appear at the top of the \fCtwander\fP
display window, above the directory listing.
.SS Invoking A Menu
A menu can be invoked in one of several ways. You can click on it,
you can press its associated "Accelerator Key" combination, or you can
use the "Mouse Shortcut" to cause a copy of the menu to pop-up near
the mouse pointer. The Accelerator Keys are shown in
parenthesis next to the menu names below and the Mouse Shortcuts are
similarly shown below in square brackets. All menus have Accelerator Keys
defined, but only some menus have associated Mouse Shortcuts.
.SS Detaching A Menu
The first item in each menu is a dashed line ("----") which indicates
that it is a "tearoff" menu. Clicking on the dashed line will detach
the menu from \fCtwander\fP allowing it to be placed anywhere on screen.
Even when detatched, these menus remain current and in-sync with
\fCtwander\fP as it continues to run. You can also tear off multiple
instances of these menus if you'd like copies of them at several
locations on the screen simultaneously.
.SS Managing The Size Of Dynamic Menus
A number of these menus have "dynamic" content - their content changes
as the program runs. For example, the Directory, History, Filter and
Select menus all keep some sort of "history" of what the program has
done. Their content thus grows longer as the program is used.
On Windows systems, if such menus grow too long to physically fit on
screen, up- and down- scrolling arrows automatically appear at the
top- and bottom of the menu respectively. This is not a feature of
the Unix Tk implementation, so menus which grow too large are simply
truncated to fit the screen on Unix-like systems.
There are two User-Settable Options options available to help you manage
the maximum size of dynamic menus (see the section below on the Configuration File
which explains how such options are actually set. The MAXMENU option
specifies the maximum number entries
.B that will be displayed
in any dynamic menu. (\fCtwander\fP internally tracks MAXMENUBUF number of
items for each dynamic menu.) This defaults to 32 as is intended
to keep the menu size reasonable.
If you set MAXMENU=0, it means you are
.B disabling
all dynamic menus. It also means that no interactive dialog will
"remember" your last manual entry. For example, with MAXMENU set to
0, \fCtwander\fP will not keep track of your last manual entries for the
CHANGEDIR, FILTERWILD, SELWILD, and RUNCMD dialogs.
MAXMENUBUF specifies the size of the internal storage buffer for each
dynamic menu regardless of how many entries are actually displayed.
i.e. MAXMENUBUF determines how many dynamic events each menu tracks
internally regardless of how many are actually visible in the menu at
any moment in time. It defaults to 250 and probably never needs to be
changed. If you set MAXMENUBUF to be less than MAXMENU, then this
smaller value will determine the maximum size of the displayed menu.
Setting MAXMENUBUF to 0 is equivalent to setting MAXMENU to 0.
.SS Commands Menu (Alt-c) [Right-Mouse-Button]
Every command defined in the Configuration File is listed in this menu
by its Command Name. The association Command Key is also shown in
parenthesis. Clicking on an item in this menu is the same as invoking
it from the keyboard by its Command Key. This is a convenient way
to invoke an infrequently used command whose Command Key you've
forgotten. It is also handy to confirm which commands are defined
after you've edited and reloaded the Configuration File. The commands
are listed in the order in which they are defined in the configuration
file. This allows most frequently used commands to appear at the top
of the menu by defining them first in the Configuration File. If no
commands are defined, either because the Configuration File contains
no Command Definitions or because the Configuration File cannot
be opened for some reason, the Commands Menu will be disabled
(grayed out).
.SS History Menu (Alt-h) [Shift-Control-Right-Mouse-Button]
\fCtwander\fP keeps track of every command you attempt to execute,
whether it is an invocation of a Command Definition found in the
Configuration File or a manually entered command via the RUNCMD key.
(default: Control-z) This is done whether or not the command is
successfully executed.
This feature provides a quick way to re-execute a command you've
previously run. When you select a command to run this way,
a dialog box is opened, giving you an opportunity to edit
the command before running it again.
One important point of clarification is in order here. If you run
one of the commands defined in your Configuration File, it is
stored in the History
.B after all variable substitutions have been made.
But, manually entered commands are stored in the History
.B literally as typed -
i.e., Without variable substitution. This allows you easily reuse a
manually entered command in another directory or context.
(Presumably, Command Definitions in the Configuration File are written
in such a way so as to be useful across many different directories and
contexts. Running such a command again is simply a matter of pressing
its associated letter key once more. By storing the resolved version
of the command in the History, you can see what the command
actually did.)
The History Menu is emptied and grayed out when you press the
CLRHIST key. (default: Control-y)
.SS Directories Menu (Alt-d) [Shift-Right-Mouse-Button]
\fCtwander\fP keeps track of every directory visited. The previously
described command to move "Back" one directory allows directory navigation
in reverse traversal order - you can back up to where you started.
However, this feature "throws away" directories as it backs up, sort
of like an "undo" function.
The "Directories" menu provides a slightly different approach to the
same task. It keeps permanent track of every directory visited and
displays that list in sorted order. This provides another way to move
directly to a previously visited directory without having to manually
navigate to it again, back up to it, or name it explictly using the
Change Directory command.
Unless MAXMENU is set to 0, the Directory Menu shows the last MAXMENU
directories visited in alphabetically sorted order (unless you change
MAXMENUBUF to be smaller than MAXMENU). "Visited", in this case, is
stretching things a bit.
The Directory Menu is emptied and grayed out when you press the
CLRHIST key. (default: Control-y)
.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
"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 Filter Menu (Alt-f) [Alt-Control-Middle-Mouse-Button]
(Note that on Windows you must press Alt
.B then
Control
.B then
the Middle-Mouse-Button for this to work. Windows appears to care deeply
about keystroke order.)
This menu provides a list of all previously used filtering "wildcard"
regular expressions. Any regular expressions defined in the
Configuration File (see below) using the "FILTERWILD = " statement will
also appear in this menu. This saves you the tedium of constantly
having to enter complex regular expression syntax every time you
wish to do wildcard-based selections.
Selecting something from this menu brings up a dialog box which
allows you to edit the selected wildcard before using it.
Bear in mind that the size of the displayed menu is governed by the
MAXMENU and MAXMENUBUF Configuration File options (see below). i.e.,
Only the last MAXMENU number of wildcards are actually displayed on
the menu.
The Filter Menu is emptied and grayed out when you press the
CLRHIST key. (default: Control-y) This history is
.B not
cleared if the Configuration File is reloaded.
.SS Select Menu (Alt-l) [Alt-Control-Right-Mouse-Button]
(Note that on Windows you must press Alt
.B then
Control
.B then
the Right-Mouse-Button for this to work. Windows appears to care deeply
about keystroke order.)
This menu provides a list of all previously used selection "wildcard"
regular expressions. Any regular expressions defined in the
Configuration File (see below) using the "SELECTWILD = " statement will
also appear in this menu. This saves you the tedium of constantly
having to enter complex regular expression syntax every time you
wish to do wildcard-based selections.
Selecting something from this menu brings up a dialog box which
allows you to edit the selected wildcard before using it.
Bear in mind that the size of the displayed menu is governed by the
MAXMENU and MAXMENUBUF Configuration File options (see below). i.e.,
Only the last MAXMENU number of wildcards are actually displayed on
the menu.
The Select Menu is emptied and grayed out when you press the
CLRHIST key. (default: Control-y) This history is
.B not
cleared if the Configuration File is reloaded.
.SS Sorting Menu (Alt-s) [Alt-Shift-Right-Mouse-Button]
(Note that on Windows you must press Alt
.B then
Shift
.B then
the Right-Mouse-Button for this to work. Windows appears to care deeply
about keystroke order.)
This menu provides a way to select any of the available sorting
options. It is context-sensitive and will show entries appropriate to
what kind of "view" the program is currently displaying. That is, it will
show options which make sense for both "normal" view as well as "Drive
List View" (see the
.B ADVANCED WINDOWS FEATURES
section below).
You'll find the currently selected sorting options displayed in the
program title bar.
.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.
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.
.SH THE \fCtwander\fP CONFIGURATION FILE
Much of \fCtwander\fPs flexibility comes from the fact that it is
a
.B macro-programmable user interface.
The program itself does little more than provide a way to navigate
around a filesystem. It must be configured (programmed) to actually
do something with the files you specify. This is done via a
"Configuration File". This file is also used to set Program Options
and change keyboard assignments. Although the program will run
without a Configuration File present, it will warn you that it is
doing so with no commands defined.
.SH LOCATION OF CONFIGURATION FILE
By default, the program expects to find configuration information in
.B $HOME/.twander (%HOME%\\\\.twander on Windows)
but you can override this with the -c command line
option. (Recommended for Windows systems - see the section below
entitled,
.B INSTALLING \fCtwander\fP
)
Actually, \fCtwander\fP can look in a number
of places to find its Configuration File. It does this using
the following scheme (in priority order):
.IP \(bu 4
If the -c argument was given on the command line, use this argument
for a Configuration File.
.IP \(bu 4
If -c was not given on the command line, but the HOME environment
variable is set, look for the a Configuration File as $HOME/.twander.
.IP \(bu 4
If the HOME environment variable is not set
.B and
a -c command line argument was not provided, look
for a file called ".twander" in the directory from which
\fCtwander\fP was invoked.
.SH CONFIGURATION FILE FORMAT
\fCtwander\fP Configuration Files consist of freeform lines of text.
Each line is considered independently - no configuration line may
cross into the next line. Whitespace is ignored within a line as are
blank lines.
There are several possible legal lines in a \fCtwander\fP Configuration
File:
.ft C \" courier
.nf
Comments
Program Option Statements
Key Binding Statements
Directory Shortcut Statements
Wildcard Statements
Variables And Command Definitions
Conditional Processing Statements
The Include Directive
.fi
.ft \" revert
(See the ".twander" file provided with the program distribution
for examples of valid configuration statements.)
Everything else is considered invalid. \fCtwander\fP will respond with
errors or warnings as is appropriate anytime it encounters a problem
in a Configuration File. An error will cause the program to
terminate, but the program continues to run after a warning. For the
most part, \fCtwander\fP tries to be forgiving and merely ignores
invalid configuration statements (after an appropriate warning). It
only declares an error when it cannot continue. This is true both
when the program initially loads as well as during any subsequent
Configuration File reloads initiated from the keyboard while running
\fCtwander\fP.
The following sections describe each of the valid Configuration
File entires in more detail.
.SS Comments
A comment is begun with the "#" character which may be placed anywhere
on a line. Comments may appear freely within a Configuration File.
\fCtwander\fP strictly ignores everything from the "#" to the end of the
line on which it appears without exception. This means that "#"
cannot occur anywhere within a User-Defined Variable Definition, Key
Binding Statement, or Command Definition (these are described below).
Comments
.B can
be placed on the same line to the right of such statements.
It is conceivable that the "#" character might be needed in the
Command String portion of a Command Definition. \fCtwander\fP
provides a Built-In Variable, [HASH], for exactly this purpose.
See the section below entitled,
.B Variables And Command Definitions,
for a more complete description.
.SS Program Option Statements
Many of \fCtwander\fPs internal program defaults can be overriden in the
Configuration File using Program Option statements. These statements
look just like the User-Defined variables described later in this
document except \fCtwander\fP recognizes the variable name as a Program
Option rather than an arbitrary variable. Program Option Statements
thus take the form:
.ft C \" courier
.nf
Option Name = Option Value
.fi
.ft \" revert
The Option Name is case-sensitive and must be entered exactly as
described below. For instance, \fCtwander\fP understands
"AUTOREFRESH" as a Program Option, but will treat "AutoRefresh"
as a User-Defined Variable.
The Option Value is checked to make sure it conforms to the proper
type for this variable. The Type can be Boolean, Numeric, or String.
A Boolean Option must be assigned a value of True or False. These
logical values can be in any case, so TRUE, TRue, and tRue all work.
A Numeric Option must be a number 0 or greater. Numbers can
also be entered in hexadecimal format: 0xNNN, where NNN is the
numeric expression in hex.
A String Option can be any string of characters.
.B Quotation marks are treated as part of the string!
Do not include any quotation marks unless you really want
them to be assigned to the option in question (almost never
the case).
Furthermore, as described above, you cannot use the \'#\' symbol
as part of the string assignment because \fCtwander\fP always
treats this character as the beginning of a comment no matter
where it appears.
For consistency with other Configuration File entries, Program Option Statements
may have a blank Right Hand Side. Such statements are
simply ignored. This is convenient when you want to leave
a placeholder in your Configuration File but don't actually want to
activate it at the moment. However, be careful - depending
on what precedes the statement, you'll get different
settings for the option in question. For example:
.ft C \" courier
.nf
# This effectively sets BCOLOR to its default value when
# the Configuration File is reloaded
BCOLOR =
# But this means the value of BCOLOR is set to red
BCOLOR = red
BCOLOR =
.fi
.ft \" revert
In other words, you should think of Program Option Statements
with a blank Right Hand Side as comments - present but ignored.
Other than this basic type-checking, \fCtwander\fP does no further
validation of the Right Hand Side of a Program Option Statement.
It is perfectly possible to provide a RHS which passes \fCtwander\fPs
type validation but which makes no sense whatsoever to the program.
Entries like this cause everything from a mild \fCtwander\fP warning
to a spectacular program failure and Python traceback on stdout:
.ft C \" courier
.nf
# A Nice Way To Clobber \fCtwander\fP
BCOLOR = goo
.fi
.ft \" revert
The following sections document each available Program Option
using this general format:
.ft C \" courier
.nf
Option-Name [Type] (Default Value)
.fi
.ft \" revert
.TP
.B ACTUALLENGTH [Boolean] (False)
By default, file sizes , total directory size (on the title bar), and
drive sizes in Win32 Drive List view are "normalized". They are
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"
between normalized and actual size display with the TOGLENGTH key
(default: Control-0).
.TP
.B ADAPTREFRESH [Boolean] (True)
Whenever a directory is read, the time to do so is tracked. If that
time is less than the current value of REFRESHINT - i.e., The
directory read took less than REFRESHINT milliseconds to complete -
nothing special happens. But, if the actual directory read time takes
.B longer
than REFRESHINT milliseconds, \fCtwander\fP adjusts the value of
REFRESHINT upwards. That way, you're guaranteed to have time
after the read completes to actually do something.
This dynamic adjustment takes place on every directory read. If you
go to a slow directory and REFRESHINT gets dynamically adjusted to,
say, 25 seconds, when you go back to a faster/smaller directory,
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
"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
milliseconds.
.TP
.B AFTERCLEAR [Boolean] (True)
Tells \fCtwander\fP to clear any selections in the GUI if a command
forces a display refresh after it completes. (See the AFTERWAIT and
.B Forcing Display Updates In Command Definitions
sections below). This is done because a command that forces a display
update is probably changing the content of the current directory
(otherwise, why bother with the update?), and the current selections
may no longer be relevant.
Setting AFTERCLEAR to False, will leave the current selections alone
after doing a command with a forced update.
.TP
.B AFTERWAIT [Numeric] (1)
It is possible to define commands so that a display refresh is forced
after a command is invoked (see the section below entitled,
.B Forcing Display Updates In Command Definitions
). The AFTERWAIT option tells \fCtwander\fP how long to wait after the
command has been initiated before actually doing the refresh. The
idea here is to give the command some time to complete before updating
the display.
.TP
.B AUTOREFRESH [Boolean] (True)
By default, \fCtwander\fP regularly re-reads the current directory to
refresh the display with any changes. If you are running on a very
slow machine or slow connection between the X-Windows server and
client, set this option to False. You can manually force an update at
any time using the REFRESH key. (default: Control-l)
.TP
.B BCOLOR [String] (Black)
Selects the main display Background Color.
.TP
.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
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.
.TP
.B CMDSHELL [String] ()
This option is primarily intended for people running \fCtwander\fP on
Unix-like operating systems like FreeBSD and Linux. As described in
the
.B GOTCHAS
section below, running a command line program or script requires some
extra effort if you want to see the results presented in a GUI window.
Typically, you need to run these commands in some kind of \'xterm\'
context so that the results will be visible, possibly using a shell as
well. So, it's common to see Command Definitions like:
.ft C \" courier
.nf
x MyCommand xterm -l -e bash -c 'stuff-for-my-command'
.fi
.ft \" revert
In fact, on Unix, the need for this idiom is so common, it's best
to define some variables for this. If you look in the example \'.twander\'
Configuration File provided in the program distribution, you'll see
something like (comments removed):
.ft C \" courier
.nf
SHELL = bash -c
VSHELL = [XTERM] [SHELL]
XTERM = xterm -fn 9x15 -l -e
.fi
.ft \" revert
Now the Command Definition above becomes:
.ft C \" courier
.nf
x MyCommand [VSHELL] 'stuff-for-my-command'
.fi
.ft \" revert
That's all well and good for Command Definitions, but what happens
when you want to
.B manually enter a command
via the RUNCMD key? (default: Control-z) You have to manually
enter the gobbledy-gook above, or at least start your command
with [VSHELL] (since RUNCMD understands variable references).
The CMDSHELL option is a way to automate this. You can assign it
to any literal text. That text will be
.B automatically prepended to any command you enter manually.
In this case you could do either of the following in the
Configuration File:
.ft C \" courier
.nf
CMDSHELL = xterm -l -e bash -c
- or -
CMDSHELL = [VSHELL] # Assuming VSHELL is defined previously
.fi
.ft \" revert
Now every time you enter a command, this will be placed in
front of your text before command execution commences.
To disable CMDSHELL operation
.B permanently,
just remove the statement above from your Configuration File. If you
want to leave it in as a placeholder, but deactivate CMDSHELL, use the
following statement:
.ft C \" courier
.nf
CMDSHELL =
.fi
.ft \" revert
You also may want to occasionally use RUNCMD to do something without
CMDSHELL processing, even though that feature has been defined in the
Configuration File. You can disable CMDSHELL operation on a
per-RUNCMD basis. Just begin your entering your command with the
double-quote (") character. \fCtwander\fP understands this to "escape"
CMDSHELL processing.
As a general matter, CMDSHELL allows you to prepend
.B anything you like
before a manually entered command - literal text, references to
variables, or even the name of a script the system will use to execute
your command. Whatever value you use for CMDSHELL will appear in the
Command Menu history for each manually initiated command which
used this feature - i.e., All the manual commands that
.B did not
escape the feature.
.TP
.B DEBUGLEVEL [Numeric] (0)
This is another way to set the debugging level you desire (the other
way being the -d command line argument). For example, say you want to
always dump the current Command Definitions to stdout when the program
starts - perhaps you want to redirect this output to a file or
printer. Just add this line to your Configuration File:
.ft C \" courier
.nf
DEBUGLEVEL = 0x004
.fi
.ft \" revert
.TP
.B DEFAULTSEP [String] (==>)
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
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.
.TP
.B DOTFILE [String] (.)
It is a convention on Unix (and other systems) that files or
directories whose names begin with a period are program configuration
files (directories). \fCtwander\fP has the ability to hide these
so-called "dotfiles". (See the section above entitled
.B Hiding Dotfiles
for the details.) \fCtwander\fP treats any file or directory whose
name begins with the string defined by DOTFILE as a dotfile for this
purpose.
For example, if you set \fCDOTFILE=Xyz\fP, all files or
directories whose names begin with "Xyz", will be hidden when you
tell \fCtwander\fP to hide dotfiles. Notice that if you change this
option from its default, you may use any string to be the dotfile
"introducer", but it is always treated with case-sensitivity. For
instance, in our example, files beginning with "XYZ" would not be
hidden.
.TP
.B FCOLOR [String] (green)
Selects the main display Foreground (Text) Color.
.TP
.B FNAME [String] (Courier)
Selects the main display Font Name.
.TP
.B FSZ [Numeric] (12)
Selects the main display Font Size.
.TP
.B FWT [String] (bold)
Selects the main display Font Weight. This can be assigned to:
normal, bold, italic, or underlined. Depending on your system, other
values may also be possible.
.TP
.B FORCEUNIXPATH [Boolean] (False)
Ordinarily, Built-In Variables and Program Memory References in a
command definition are replaced with strings that list one or more
files and/or directories. When this substitution is made at runtime,
these strings contain the path separator character appropriate for the
underlying operating system ("/" for Unix and "\\" for Windows).
If you set FORCEUNIXPATH to True, \fCtwander\fP will
.B always
use the Unix path separator character("/") in these substitutions.
This option is primarily useful when writing command definitions
with Unix tools under Windows (such as cygwin) that are fussy about
path separator conventions.
This option is only relevant on Windows systems. It is ignored on
other operating systems.
.TP
.B HBCOLOR [String] (lightgreen)
Selects the help menu Background Color.
.TP
.B HEIGHT [Numeric] (600)
Initial vertical size of the \fCtwander\fP window in pixels.
.TP
.B HFCOLOR [String] (black)
Selects the help menu Foreground (Text) Color.
.TP
.B HFNAME [String] (Courier)
Selects the help menu Font Name.
.TP
.B HFSZ [Numeric] (10)
Selects the help menu Font Size.
.TP
.B HFWT [String] (italic)
This selects the help menu Font Weight.
.TP
.B HIDEDOTFILES [Boolean] (False)
Sets whether the program hides "dotfiles" by default. (See previous
section entitled
.B Hiding Dotfiles
for the details of this feature.) This value can be toggled with
the TOGHIDEDOT (default: Control-9) key binding.
.TP
.B MAXMENU [Numeric] (32)
Maximum number of entries to
.B display
in any dynamic menu. This keeps the menu size reasonable.
Internally, \fCtwander\fP keeps track of way more than this
number of dynamic entiries (see the MAXMENUBUF option below).
.TP
.B MAXMENUBUF [Numeric] (250)
Maximum number of items \fCtwander\fP
.B tracks internally
for each dynamic menu.
This value need normally not be changed. It is present only
to bound how much memory \fCtwander\fP consumes for this task.
.TP
.B MAXNESTING [Numeric] (32)
Number of times a Command Definition is processed to dereference
all variables. For example, suppose you have this:
.ft C \" courier
.nf
FOO = bax
BAM = x[FOO]
x mycmd [BAM] [SELECTION]
.fi
.ft \" revert
When you press the x key, the \fCtwander\fP command interpreter has to
process the line repeatedly until all variables are resolved:
.ft C \" courier
.nf
[BAM] [SELECTION] -> x[FOO] [SELECTION]
x[FOO] [SELECTION] -> xbax [SELECTION]
xbax [SELECTION] -> xbax selected-item
.fi
.ft \" revert
So, in this case, it took 3 iterations to do this. MAXNESTING
merely sets the maximum number of times this is permitted.
We have to do this to stop runaway definitions like this:
.ft C \" courier
.nf
FOO = x[FOO]
.fi
.ft \" revert
This kind of construct will cause \fCtwander\fP to iterate
MAXNESTING number of times and then give up with
a warning about exeeding the nesting (dereferencing) limit.
A 32 iteration limit should be plenty for any reasonable
Command Definitions. If you set MAXNESTING to 0, \fCtwander\fP
will not allow
.B any
variable dereferencing,
.B including the Built-In Variables.
This is probably not what you want.
.TP
.B MBARCOL [String] (beige)
Selects the Menu Bar color.
.TP
.B MBCOLOR [String] (beige)
Selects the menu Background Color.
.TP
.B MFCOLOR [String] (black)
Selects the menu Foreground (text) Color.
.TP
.B MFNAME [String] (Courier)
Selects the menu Font Name.
.TP
.B MFSZ [Numeric] (12)
Selects the menu Font Size.
.TP
.B MFWT [String] (bold)
Selects the menu Font Weight.
.TP
.B NODETAILS [Boolean] (False)
Prevents details from ever being displayed.
.TP
.B NONAVIGATE [Boolean] (False)
Prevents the user from navigating out of the starting directory.
Command Definitions and commands initiated manually via RUNCMD
(default: Control-z) can still "see" other directories, the user
just cannot move elsewhere with any of the \fCtwander\fP navigation
commands.
The NODETAILS and NONAVIGATE commands are
.B not
security features. They can easily be defeated by editing the
Configuration File. They exist to make it easy for you to create
\'twander' configurations for technically unsophisticated users.
Say you want to define a few simple commands for your boss to use
which won't challenge his or her feeble managerial mind ;) By
defining these commands and setting both NODETAILS and NONAVIGATE
to TRUE, you really limit what can be done with \fCtwander\fP.
They can't wander off into other directories and get lost, or
worse yet, clobber files they don't understand. There are no
details to confuse them. Your instructions for using the program
thus become, "Select the files you're interested in and press
P to print them, M to mail them to Headquarters.." and so on.
Again,
.B these are NOT security features.
Anyone with even very modest technical skills can thwart these
limitations. But, it is suprising just how effective these can be in
simplifying life for technically challenged users.
.TP
.B QUOTECHAR [String] (")
As described below, \fCtwander\fP ordinarily quotes most Built-In
Variables as it replaces them during command processing. This
is useful because modern operating systems allow file and
directory names to have spaces in them. Such names must be
quoted for most programs to understand them as a single entity
on a command line.
By default, the double-quote char is used for this purpose.
You can suppress quote processing by using the -t command
line argument. This does nothing more than set QUOTECHAR
to an empty string. Unfortunately, since the RHS of a
Program Option Statement cannot be blank, you cannot
disable quoting with this option. However, you
.B can
set the quotation character to be anything else you like, such as
a single-quote. In fact, you can set QUOTECHAR to any
.B string of characters
you like and they will faithfully be used on either side of
a Built-In Variable replacement.
.TP
.B REFRESHINT [Numeric] (5000)
Nominal time in milliseconds between automatic directory
refreshes (if AUTOREFRESH is True). This time is
.B really
nominal and should not be used with any accurate timing
in mind. REFRESHINT=8000 says that the refresh
interval will be nominally 8 seconds (and certainly more
than the default of 5 seconds), but it can be off this
nominal value by quite a bit.
If you run \fCtwander\fP on a slow system (or have a slow link between
X-Client and X-Server) you might want to increase this value
substantially. You can get into the situtation where just as one
refresh completes, its time to do the next one, and the \fCtwander\fP
will seem really sluggish and unresponsive. By lengthening the time
between automatic updates, the amount of unresponsive behavior is
reduced. Of course, this also means that any changes in the currently
viewed directory will also take longer to appear in the \fCtwander\fP
display.
.TP
.B SORTBYFIELD [String] (Name)
Specifies which field is to be used as the sort key. May be one of
the fields below under "Sort Key" (case-insensitive). The equivalent
field name for Drive List View (see
.B ADVANCED WINDOWS FEATURES
section below) is shown in the second column, however
these may
.B not
be used as arguments for SORTBYFIELD. For example, if you plan to
start the program in Drive List View and want to sort by Drive Type,
use: SORTBYFIELD=Links.
.ft C \" courier
.nf
Equivalent
Sort Key Drive List View Field
-------- ---------------------
No Sort No Sort
Permissions Label/Share String
Links Drive Type
Owner Free Space
Group Total Space
Length Drive Letter
Time Drive Letter
Name Drive Letter
.fi
.ft \" revert
.TP
.B SORTREVERSE [Boolean] (False)
Specifies whether to reverse the sort order or not. If True and
SORTSEPARATE is also True, then the directory list will appear at the
.B end
of the display in addition to being reverse ordered.
.TP
.B SORTSEPARATE [Boolean] (True)
Determines whether directories and files should be separated or
mingled in absolute sort order in the display. By default, they are
separated with directories sorted according to SORTBYFIELD order but
appearing before any files in the display.
This option is ignored in Drive List View.
.TP
.B STARTDIR [String] (Directory In Which Program Started)
This allows you to force a starting directory of your choice no matter
where the program actually is launched. This is useful for
day-to-day operation - perhaps you always want to start in your home
directory. STARTDIR is also handy in tandem with the NODETAILS and
NONAVIGATE options to force a user to the only directory which they
should be using.
.TP
.B STARTX [Numeric] (0)
Initial horizontal offset of the \fCtwander\fP window in pixels.
.TP
.B STARTY [Numeric] (0)
Initial vertical offset of the \fCtwander\fP window in pixels.
.TP
.B SYMDIR [Boolean] (True)
This option causes symbolic links that point to directories to be
treated as directories for purposes of sorting. This is relevant when
"separated" sorting is selected - i.e., When the directories are
sorted separately from files. If SYMDIR is set to False, then
symbolic links will be sorted as files, regardless of what the link
points to.
.TP
.B USETHREADS [Boolean] (False)
\fCtwander\fP defaults to using normal "heavy weight" processes
for running commands on Unix. Many Unix implementations
also support a "threaded" process model. Setting USETHREADS
to True on such systems will cause \fCtwander\fP to use threads, rather than
processes to launch user-defined commands. There are some
known issues with thread-based operations (hence the reason
this option defaults to False). These are discussed in the
.B GOTCHAS
section below.
This option applies only to Unix-like operating systems.
Windows commands are
.B always
run as a thread - this is the only process model Windows
supports..
.TP
.B USEWIN32ALL [Boolean] (True)
Windows only. If \'win32all\' is installed, determines whether its
features should be used (see section below entitled,
.B ADVANCED WINDOWS FEATURES
for details).
Normally, this option should be left alone. However, if you have
\'win32all\' installed on your system for some other reason, but don't
want it used by \fCtwander\fP, set this option to False.
The main reason to do this would be on a slow machine with very large
directories. The advanced features of \'win32all\' come at a
computational price. This is especially noticeable when it is
computing the attributes, ownership, and size in a directory with
hundreds (or more) of entries. Typically, you would just use the
TOGWIN32ALL key (default: Control-w) to temporarily disable these
features before entering such a directory. However, if your starting
directory is in this category, setting USEWIN32ALL=False might not
be a bad idea.
.TP
.B WARN [Boolean] (True)
Determines whether interactive warnings should be displayed
as \fCtwander\fP encounters them (while parsing a Configuration
File or just in normal execution).
Setting this option to False is the same thing as using the
-q command line option with one important difference: The
Configuration File is parsed before the command line is
parsed. Even if you have -q on the command line (or in the
TWANDER environment variable), if there is an error in
your Configuration File, you will see warning messages
at program startup time. Putting WARN=False at the
top of your Configuration File will suppress this.
It is not recommended that you operate normally with the
-q flag or with WARN=False. \fCtwander\fP is pretty
forgiving in most cases and when it does warn you about
something, there is a good reason for it - you probably
want to know what the problem is.
.TP
.B WIDTH [Numeric] (800)
Initial horizontal size of the \fCtwander\fP window in pixels.
.TP
.B WILDNOCASE [Boolean] (True On Win32 / False Elsewhere)
Set's whether or not case is significant in wildcard filtering and
selection. If True, case is ignored, if False, case is significant in
these wildcard operations.
.P
A few general notes about Program Options are worth mentioning here:
.IP \(bu 4
You can set the same option multiple times in a single
Configuration File - \fCtwander\fP pays no attention.
However, only the
.B last
(the one nearest the end of the file) instance of that Program Option
Statement actually takes effect. This is handy if you want to
temporarily change something without modifying your existing
configuration. Just add your temporary change at the end of the file.
When you're done with it, just remove it. No need to edit and re-edit
your preferred configuration...
.IP \(bu 4
The font colors, weights, and sizes available for your use will vary
somewhat by system. For instance, Windows TrueType fonts are
effectively available in every size and weight. On the other hand,
most Unix-like systems have a more limited palette of fonts and colors
with which to work. Most systems should support obvious color names
like, red, white, blue, yellow, beige, and so on. Many also support
colors like lightgreen, lightblue, etc. At a minimum, you should be
able to use normal, bold, italic, and underline for font weights.
Most systems attempt some kind of "best fit" font matching. If you
specify a font size/weight/name that does not exist, the system
will try to find what it thinks is the closest match. This is
usually ugly, so try to specify font information for things that
actually exist on your system.
If your setting in the Configuration File seems not to work, take a
look at the command window in which you started \fCtwander\fP (or start
it from one manually, if you're using a GUI shortcut to start it).
Attempts to use unavailable colors and weights will cause
Python/Tkinter to dump traceback information on stdout.
.IP \(bu 4
Although you can use proportionally spaced fonts with \fCtwander\fP,
the result is pretty ugly. \fCtwander\fP assumes a fixed width
font when it calculates display formatting. Variable-width
fonts will cause your display to be ragged and hard to read.
.IP \(bu 4
If you set MAXMENU or MAXMENUBUF to 0, it disables both dynamic menu
content
.B and
of the last manual entry in the dialogs associated with CHANGEDIR
(default: Control-x), FILTERWILD (default: Control-=), SELWILD
(default: Control-\\), and RUNCMD (default: Control-z).
.IP \(bu 4
Changing MAXMENU and then reloading the Configuration File only
changes
.B the number of items visible on the various dynamic menus.
\fCtwander\fP actually keeps track of more than this internally
(governed by the MAXMENUBUF option).
Say MAXMENU is set to 4, but you've actually visited 20 different
directories and issued 30 commands. You'll only see 4 of each on the
associated menus. But, if you edit MAXMENU to now be 32 and reload
the Configuration File, you will see all 20 directories and 30 commands on their
respective menus.
.IP \(bu 4
At first glance, the ability to set QUOTECHAR to any arbitary string
may seem silly, but it actually has a purpose. As good as the
\fCtwander\fP macro capability is, it is still a fairly simple language.
Really complex tasks will need to be handed off to some other
scripting language (like Python!). It may be useful to delimit
Built-In Variables (which indicate your selections via the \fCtwander\fP
interface) in such a way that your script knows where they came
from. So, say you set QUOTECHAR=+++ and you have a Command
Definition like this:
.ft C \" courier
.nf
x mycmd MyPythonScript [DSELECTIONS] other stuff
.fi
.ft \" revert
When MyPythonScript runs, it can immediately tell which arguments
came from \fCtwander\fP (the ones that are in the form +++dir+++
or +++file+++) and which arguments are just other stuff.
You probably won't need this often, but its nice to have.
.IP \(bu 4
STARTX and STARTY are relative to the (0,0) origin that Tk uses for
window placement. In High-School algebra most of us got used
to seeing (0,0) in the lower-left corner of a graph. Tk has
a rather different view of this and STARTX and STARTY are
relative to the
.B upper-left corner of the screen.
.SS Key Binding Statements
No program that runs in many operating environments 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. \fCtwander\fP ships from the factory with a set of default key
bindings, but it also provides a mechanism for changing these bindings
via entries in the Configuration File.
This feature is available only for
.B Keyboard Assignments.
Mouse Button Assignments may not be changed by the user. An attempt
to do so in the Configuration File will cause \fCtwander\fP to display a
warning and ignore the offending line.
It is not difficult to override the default keyboard bindings by
adding entries in the Configuration File. Doing so requires some
familiarity with how Tkinter names keystrokes. Good resources for
learning this exist abundantly on the Internet, among them:
.ft C \" courier
.nf
http://www.pythonware.com/library/tkinter/introduction/index.htm
http://www.nmt.edu/tcc/help/pubs/lang.html
http://www.cs.mcgill.ca/~hv/classes/MS/TkinterPres/
.fi
.ft \" revert
(As an aside - Tkinter is nothing more than a Python interface to
the Tcl/Tk windowing system. The "real" naming conventions for
keystokes can be found in the many sources of Tk documentation,
both in print and on the Internet.)
Keyboard binding assignments look just like variable definitions
in the Configuration File. (The \fCtwander\fP Configuration File parser
automatically distinguishes between Key Binding Statements and
Variable Definitions or other legitimate statements. This means you
can never use one of the program function names as one of your own
variable names.) Key Binding Statements thus take the form:
.ft C \" courier
.nf
Program Function Name = Tkinter Keystroke Name
.fi
.ft \" revert
Changing the default bindings is therefore nothing more than a matter
of assigning the appropriate Program Function Name (found in
parenthesis next to the description in the default descriptions above)
to the desired keystroke.
Examples of all the default key bindings are shown as comments in the
".twander" example Configuration File supplied in the program
distribution. The easiest way to rebind a particular function is to
copy the relevant line, uncomment the copy, and change the right side
of the assignment to the new key you'd like to use.
It is important to observe several rules when rebinding keys:
.IP \(bu 4
It is best if keyboard navigation commands are all Control or Function
keys. If you assign a navigation or selection function to a single
keystroke, it may conflict with a user-defined command. If you assign
it to a keypad/special key it may conflict with that key's normal GUI
behavior.
.IP \(bu 4
The Tkinter keynames should placed on the right side of the "=" symbol
.B without any quotation marks.
.ft C \" courier
.nf
# Incorrect
QUITPROG = '<F3>'
# Correct
QUITPROG = <F3>
.fi
.ft \" revert
.IP \(bu 4
The Program Function Name variables (the left side of the assignment)
may not be used as names for your own user-defined variables elsewhere
in the Configuration File. In fact, \fCtwander\fP will never even
recognize such an attempt. For example, suppose you try to do this:
.ft C \" courier
.nf
QUITPROG = something-or-other
.fi
.ft \" revert
Because you want to be able to reference [QUITPROG] in a subsequent
Command Definition. \fCtwander\fP will actually interpret this as just
another key binding command, in this case binding the program function
QUITPROG to "something-or-other" - probably not what you intended.
Moreover, if you have a Command String somewhere with [QUITPROG] in it,
\fCtwander\fP will declare and error and abort because it has no
User-Defined variable of that name in its symbol table.
.IP \(bu 4
When you're done making changes to the Configuration File, be sure to
either restart the program or reload the Configuration File to assign
the new bindings.
.IP \(bu 4
Be aware that \fCtwander\fP does no sanity testing on the assignments
you change. If you assign a particular \fCtwander\fP function to
an illegal or silly key string, the program will probably blow-up
spectacularly. At the very least, that program feature will probably
be unusable, even if \fCtwander\fP manages to run.
.SS Directory Shortcut Statements
\fCtwander\fP provides a mechanism for directly navigating into one
of 12 frequently used directories. 12 keys, KDIRSC1 ... KDIRSC12
(default: F1 ... F12) have been set aside for this purpose. Directory
Shortcut Statements are entries in the Configuration File which
associate one of these keys with a particular directory path.
These statements are in the form:
.ft C \" courier
.nf
DIRSCxx = path
where, xx is a number from 1-12
.fi
.ft \" revert
So, for example, if you want to enter "C:\\Documents And Settings"
when you press the F5 key, you would add this to your Configuration
File:
.ft C \" courier
.nf
DIRSC5 = c:\\Documents And Settings
.fi
.ft \" revert
There are several subtleties to Directory Shortcuts you should
understand:
.IP \(bu 4
You can end the path with slash or not - \fCtwander\fP
will understand the entry either way.
.IP \(bu 4
If there is no path on the righthand side of a Directory
Shortcut Statement, this is the same as having no
definition at all for that key:
.ft C \" courier
.nf
# This "undefines" shortcut #5
DIRSC5 =
.fi
.ft \" revert
.IP \(bu 4
\fCtwander\fP does absolutely no checking of what you enter
to the right of the equals sign. If you enter something
silly for the shortcut path, you will probably get a warning
that the directory cannot be opened when you try to run that
shortcut.
.IP \(bu 4
Keep the Program Function Names
.B (KDIRSC1 ... KDIRSC12)
which are used for Key Binding, distinct in your thinking from
the Directory Shortcut Names
.B (DIRSC1 ... DIRSC12)
which are used for defining the shortcuts.
.IP \(bu 4
If you enter a Directory Shortcut Name that is invalid
or out of range - examples include, DIRSC01 and DIRSC13 -
\fCtwander\fP treats them like a User-Defined Variable as
described below.
.SS Wildcard Statements
As discussed above, \fCtwander\fP provides powerful regular
expression-based "wildcard" filtering and selection capabilities via
the FILTERWILD (default: Control-=) and SELWILD (default: Control-\\)
commands. These regular expressions can be complex and tedious to
enter by hand each time you need them. You can pre-define frequently
needed wildcard strings in your Configuration File using the following
statements:
.ft C \" courier
.nf
WILDFILTER = regular-expression-string
WILDSELECT = regular-expression-string
.fi
.ft \" revert
The regular expression will then be pre-loaded into either the Filter
or Select Menus respectively when \fCtwander\fP starts. This makes it
easy to use or modify complex wildcards over and over. You may place
as many of these as you like in your Configuration File. (Though the
menus will be limited to displaying MAXMENU number of items - see the
section above on Program Option Statements.)
.SS Variables And Command Definitions
Most programs "ship from the factory" with a pre-defined
set of features or commands. \fCtwander\fP comes with
.B no built-in commands!
Instead, it comes with a mechanism which allows you to specify your
own
.B Command Definitions.
By means of a simple and very powerful macro lanuage, you "program"
\fCtwander\fP and equip it with commands of your own choosing. For
example, you might define commands to copy, delete, edit, and move the
files or directories you choose. Perhaps you have a specialized shell
script for doing backups. It's a simple matter to write a \fCtwander\fP
Command Definition that will pass the names of the files and
directories you've selected to that backup script. You might combine
this with \fCtwander\fP's Program Memory feature to keep a running list
of the files and directories you want to backup and then finally issue
the backup command when you're ready. Best of all, commands you
define this way are always a single keystroke. This means that
once you've programmed \fCtwander\fP to suit your needs, actually using
it is very fast and convenient.
Command Definitions are built out of literal text and may also have
any combination of several variable types: User-Defined Variables,
Environment Variables, Execution Variables, and Built-In Variables.
User-Defined Variables are variables you define in the configuration
file. They can hold any string of text you desire.
Environment Variables are set in the shell you use to invoke
\fCtwander\fP. This makes it easy to write a generic command
definition that acts based on something set uniquely for each user in
that user's environment. You can only read, not change, Environment
Variables in \fCtwander\fP.
Execution Variables are set by running a program - pretty much any
program will do. (Unix users will be familiar with this if they've
ever used shell "backtick" quoting.) This makes it easy to
construct a \fCtwander\fP command that is defined in whole or in part
by some external program.
Built-In Variables are a set of variables defined by \fCtwander\fP
itself. There are two general kinds of Built-Ins. The first
kind are used to let your command know (at runtime) which file or files
you have currently selected in the \fCtwander\fP interface. The other
kind of Built-Ins are used to prompt you during command execution.
There are also a few other Built-Ins described below.
.SS Just When Does A Variable Get Evaluated?
Before getting into the mechanics of variables and command definitions, it's
important to emphasize one point: Variables get "evaluated" (read)
.B when a command is actually run.
Older versions of \fCtwander\fP evaluated variables at the time a configuration
file was read. However, as we'll see below, by waiting until the command
is actually run to evaluate its variable references, we can do some nifty things.
.SS User-Defined Variables And Environment Variables
User-Defined Variables are defined using the syntax:
.ft C \" courier
.nf
Variable Name = Replacement String
.fi
.ft \" revert
Environment Variables are referenced using the syntax:
.ft C \" courier
.nf
[$VARIABLE]
.fi
.ft \" revert
Say we have a configuration line like this,
.ft C \" courier
.nf
EDITOR = emacs blah blah blah blah
.fi
.ft \" revert
Later on, when defining a command, instead of typing in "emacs blah
blah blah blah", you can just refer to the variable [EDITOR] - the
brackets indicate you are
.B referring
to a previously defined variable.
Similarly, suppose you have an environment variable called "EDITOR"
which indicates your preferred editing program. Our definition
could thus become:
.ft C \" courier
.nf
EDITOR = [$EDITOR] blah blah blah blah
.fi
.ft \" revert
Why bother with this? Because it makes maintaining complex
Configuration Files easier. If you look in the example ".twander"
Configuration File provided in the program distribution, you will see
this is mighty handy when setting up complex "xterm" sessions, for
example.
Here are several other subtleties regarding User-Defined Variables:
.IP \(bu 4
\fCtwander\fP variable definitions are nothing more than a
string substitution mechanism. Suppose you have a variable
definition that refers to another variable:
.ft C \" courier
.nf
NewVar = somestring [OldVar]
.fi
.ft \" revert
It is important to realize that this only means: "If you encounter
the string \'[NewVar]\'
.B in a subsequent Command Definition,
replace it with the string \'somestring [OldVar]\'."
In other words,
no evaluation of the right side of the expression takes
place when a variable is
.B defined.
Evaluation of a variable only takes place when the variable is
.B referenced
(in the Command String portion of a Command Definition) at the time
the command is run. The Command Definition parser will continue to
dereference variable names until they are all resolved or it has
reached the maximum nesting level (see next bullet).
.IP \(bu 4
User-Defined Variables may be
.B nested
up to 32 levels deep (this default can be changed via the
MAXNESTING Program Option). You can have constructs like:
.ft C \" courier
.nf
Var1 = Foo
Var2 = Bar
FB = [Var1][Var2]
.fi
.ft \" revert
Later on (when defining some command) when \fCtwander\fP runs into the
variable reference [FB], it will keep substituting variables until all
[...] references have been resolved or it hits the nesting limit (The
default is 32, but you can change it with the MAXNESTING option).
This limit has to be imposed to catch silly things like this:
.ft C \" courier
.nf
Var = a[Var]
.fi
.ft \" revert
This recursive definition is a no-no and will be cause \fCtwander\fP
to generate an error while parsing the Configuration File and then
terminate.
Your variable definitions can also nest other kinds of variables
(Environment and Built-Ins). So, constructs like this are perfectly
OK:
.ft C \" courier
.nf
Var1 = [$PAGER]
Var2 = command-arguments
V = [Var1] [Var2] [DSELECTION]
.fi
.ft \" revert
.IP \(bu 4
In the example above, notice that since the right-hand side of
User-Defined Variables is literally replaced, we have to make sure
there is space between the various variable references. If we used
[Var1][Var2][DSELECTION] we would get one long string back instead
of a command with arguments and a list of selected items.
.IP \(bu 4
Variable references are only significant on the right hand side of
an assignment statement:
.ft C \" courier
.nf
Var1 = Foo
My[Var1] = bar
.fi
.ft \" revert
This does
.B not
create a variable called "MyFoo". It creates a variable called "My[Var1]" and sets
its value to "bar". This is both confusing and useless because you can never
dereference this variable, because ...
.IP \(bu 4
Variable references cannot be nested. Using our example above, suppose we
later want to get the value ("bar") of variable "My[Var1]". That variable
reference would look like this: \fC[My[Var1]]\fP and this is
.B not
permitted. A variable reference may only contain a text string, not references
to other variables.
.IP \(bu 4
Variables must be
.B defined before they are referenced
(in a Command Definition). You can, however, include not-yet defined
variable name in another User-Variable Definition so long as all these
variable are defined by the time they appear in a Command String. The
following is OK because all variables are defined by the time they
are actually needed:
.ft C \" courier
.nf
Var1 = foo
Var2 = [Var3] # This is just a string substitution, not a reference
Var3 = bar
MyVar = [Var1][Var2]
# Now comes the Command Definition
# If we put this before the Variable Definitions above,
# it would be an error.
x mycommand [MyVar]
.fi
.ft \" revert
.IP \(bu 4
Variable Names are case-sensitive - [EDITOR], [Editor],
and [editor] all refer to different variables.
.IP \(bu 4
The "#" character cannot be used in either the variable name
or the replacement string since doing so begins a comment.
.IP \(bu 4
The "=" is what separates the Variable Name from the replacement
string. Therefore, the "=" cannot ever be part of a Variable Name. A
Variable Name cannot begin with "$" (see next bullet). Other than
these minor restrictions, both Variable Names and Replacement
Characters can be any string of characters of any length. Good
judgment would suggest that Variable Names should be somewhat
self-descriptive and of reasonable length - i.e., Much shorter than
the replacement string!
.IP \(bu 4
A Variable Name must never begin with "$". This is because a Command
Definition containing a string in the form [$something] is understood
by \fCtwander\fP to be a reference to an
.B Environment Variable,
named "something". If you do this:
.ft C \" courier
.nf
$MYVAR = some-string
.fi
.ft \" revert
You will never be able to subsequently reference it because,
[$MYVAR] tells \fCtwander\fP to look in the current environment,
not its own symbol table to resolve the reference. However, note
that "$" symbol may appear anywhere else but the first character
of a variable name. So, for example, MY$VAR is fine.
.IP \(bu 4
Unlike previous versions of \fCtwander\fP, Variable Names may be redefined.
This makes it more convenient to exploit the ability for \fCtwander\fP
to process the contents of a Configuration File conditionally (see the
.B Conditional Processing Statements
section below).
For example, you can set a variable to some default
value, and then override it if a condition is satisfied:
.ft C \" courier
.nf
# Assume we're running on a Unix-like system
MyEditor = [$EDITOR]
# Override this if we're on Windows
\&.if [.OS] == nt
MyEditor = write
\&.endif
.fi
.ft \" revert
.SS Execution Variables
Execution Variables are a special case of User-Defined Variables.
However, instead of setting a variable to some string of text,
you tell \fCtwander\fP to
.B run a program
and set it's results to the variable:
.ft C \" courier
.nf
TODAY = [\`date\`]
.fi
.ft \" revert
Now, suppose you define a command with \fC[TODAY]\fP in it somewhere.
When you later run that command, \fC[TODAY]\fP will be replaced
by the output of the "date" command. In other words, Execution Variables
allow you to run any external program you like, and have that program's
output substituted into the definition of a command. Several further
points are worth noting here.
.IP \(bu 4
Notice that Execution Variables are delimited by backticks, not single-quotes.
.IP \(bu 4
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.
.IP \(bu 4
Suppose you want to populate an Execution Variable with a program that
returns multiple lines of text. You'll need to strip all the newlines
out of the output in that case. To do this, you can use a second form
of an Execution Variable: \fC[\`-program\`]\fP. The leading minus sign
tells \fCtwander\fP to strip all newlines when doing the replacement.
For example, let's define a command that lists all the files in the
current directory:
.ft C \" courier
.nf
a mycommand echo "[\`-ls\`]" # We need the double-quotes
# to make echo work right
.fi
.ft \" revert
.SS Command Definitions
The heart of the \fCtwander\fP configuration process is creating
of one or more
.B Command Definitions.
These definitions are the way user-defined commands are added to a
given instance of \fCtwander\fP. A Command Definition consists of three
fields separated by whitespace:
.ft C \" courier
.nf
Command-Key Command-Name Command-String
.fi
.ft \" revert
The
.B Command Key
is any single character which can be typed on the keyboard. This is
the key that will be used to invoke the command from the keyboard.
Command Keys are case-sensitive. If "m" is used as a Command Key, "M"
will not invoke that command. Command Keys must be unique within a
given Configuration File. If \fCtwander\fP finds multiple Command
Definitions assigned to the same Command Key, it will associate the
.B last
definition it finds with that Command Key. A Command Key can
never be "#" which is always understood to be the beginning of a
comment.
The
.B Command Name
is a string of any length containing any characters. This is the name
of the command which is used to invoke the command from the Command
Menu. Command Names are case-sensitive ("command" and "Command" are
different names), but they are not required to be unique within a
given Configuration File. That is, two different Command Definitions
may have identical Command Names associated with them, though this is
not ordinarily recommended.
The
.B Command String
is any arbitrary string which is what \fCtwander\fP actually tries to
execute when the command is invoked.
.SS A Simple Command Definition
In its simplest form, a Command Definition looks like this:
.ft C \" courier
.nf
# A simple Command Definition
m MyMore more somefile
.fi
.ft \" revert
This command can be invoked pressing the "m" key on the keyboard or
selecting the "MyMore" entry from the Command Menu - either directly
from the menu or from the Command Menu Pop-Up. No matter how it is
invoked, \fCtwander\fP will then execute the command, "more somefile".
The problem is that this command as written actually will not give you
the result you'd like (...well, on X-Windows - is does work on Windows
as written). (For more details on why, see the
.B GOTCHAS
section below.) It turns out that starting a non-GUI program like
\'more\' in a new window needs some extra work. What we want to do
is run \'more\' inside a copy of \'xterm\'. Now our command looks like
this:
.ft C \" courier
.nf
# Our command setup to run as a GUI window
m MyMore xterm -l -e more somefile
.fi
.ft \" revert
.SS Forcing Display Updates In Command Definitions
You are likely to define commands that change the contents of the
currently-viewed directory somehow. For instance, commands that
rename, create, or delete files in the current directory all have this
effect. When such a command is run, it means that the \fCtwander\fP display is
"out of sync" with the actual disk contents until the next refresh
cycle - automatic if AUTORFRESH is enabled, manual otherwise.
Placing \'+\' symbol to the beginning of the Command String tells
\fCtwander\fP that, when the command is run, a display refresh should be
forced afterwards. Not immediately afterwards, but AFTERWAIT
seconds (default: 1) later. Why? To give the command in question
a chance to complete before updating the display. For instance,
.ft C \" courier
.nf
r removelogs +rm -f *log
.fi
.ft \" revert
This means that when the \'r\' key is pressed, the command,
"rm -f *.log" is run, and then, AFTERWAIT seconds later, \fCtwander\fP
will force a display update. This happens regardless of the
current AUTOREFRESH settings.
This feature is handy, but has some practical limitations. If this
feature updates the display before a command actually completes (i.e.,
the command you've launched takes longer than AFTERWAIT seconds to
complete), the final state of the directory will not be displayed.
The idea here is to use this feature for "quicky" updates between more
conventional display refreshes, whether via AUTOREFRESH or manually.
By default, anytime you run a command that uses this feature, any
selections in the GUI are cleared. This is because a forced update
presumably is required because the command changes something in the
current directory. In that case, the current selections may no longer
be relevant. If you wish to disable this behavior, set the AFTERCLEAR
program option to False.
.SS User-Defined Variables In A Command String
The last example works quite nicely. But, we're probably going to end up
using the string "xterm -l -e" over and over again for any
shell commands we'd like to see run in a new window. Why not create
a User-Defined Variable for this string so we can simplify its use
throughout the whole Configuration File? Now, our command looks
like this:
.ft C \" courier
.nf
# Our command enhanced with a User-Defined Variable.
# Remember that the variable has to be defined *before*
# it is referenced.
XTERM = xterm -l -e # This defines the variable
m MyMore [XTERM] more somefile # And the command then uses it
.fi
.ft \" revert
.SS Environment Variables In A Command String
This is all very nice, but we'd really like a command to be generic
and be easily used by a variety of users. Not everyone likes the
"more" program as a pager. In fact, on Unix-like systems there is an
environment variable ($PAGER) set by each user which names the paging
program that user prefers. We can refer to environment variables just
like any other variable as explained previously. Now our command
looks like this:
.ft C \" courier
.nf
# Our command using both a User-Defined Variable and
# an Environment Variable to make it more general
XTERM = xterm -l -e
m MyMore [XTERM] [$PAGER] somefile
.fi
.ft \" revert
.SS Execution Variables In A Command String
We can further extend the power of Command Definitions by using an
Execution Variable to define part of the command. Suppose we want a
command that will let us examine all the text files in the current
directory:
.ft C \" courier
.nf
# Our command using User-Defined, Environment, and
# Execution Variables
XTERM = xterm -l -e
m MyMore [XTERM] [$PAGER] [\`-ls *.txt\`]
.fi
.ft \" revert
.SS Built-In Variables In A Command String
It would also be really nice if the command applied to more than just
a single file called "somefile". The whole point of \fCtwander\fP
is to allow you to use the GUI to select one or more directories
and/or files and have your Command Definitions make use of those
selections. \fCtwander\fP uses a set of
.B Built-In Variables
to communicate the current directory and user selections to the
any commands you've defined. Built-In Variables are referenced
just like User-Defined Variables and Environment Variables and
may be inserted any appropriate place in the Command String.
In our example, we probably want the command to pickup whatever
item the user has selected via the GUI and examine that item
with our paging program. Now our command becomes:
.ft C \" courier
.nf
# Our command in its most generic form using
# User-Defined, Environment, and Built-In Variables
XTERM = xterm -l -e
m MyMore [XTERM] [$PAGER] [DSELECTION]
.fi
.ft \" revert
The "DSELECTION" built-in is what communicates the currently
selected item from the GUI to your command when the command
actually gets run.
.SS Selection-Related Built-Ins
\fCtwander\fP has a rich set of Built-In Variables for use in your
Command Definitions. The first group of these is used to convey your
current directory and items which you've selected to a Command
Definition:
.IP \(bu 4
.B [DIR]
[DIR] is replaced with the current directory \fCtwander\fP
is viewing.
.IP \(bu 4
.B [DSELECTION]
[DSELECTION] is replaced with the full path name of the item currently
selected in the GUI. If more than one item is selected, [DSELECTION]
refers to the last item in the group (the bottom-most, not the most
recent item you selected).
.IP \(bu 4
.B [DSELECTIONS]
[DSELECTIONS] is replaced with the full path name of
.B all
items currently selected in the GUI.
.IP \(bu 4
.B [SELECTION]
[SELECTION] is replaced with the name of the currently
selected item in the GUI. The path to that file is
.B not
included. As with [DSELECTION], if more than one item is selected in
the GUI, the name of the last item in the group is returned for this
variable.
.IP \(bu 4
.B [SELECTIONS]
[SELECTIONS] is replaced with the names of
.B all
items currently selected in the GUI. The path to those names is
not included.
.SS Prompting And Special-Purpose Built-Ins
There are also several special-purpose Built-In Variables which are used
for creating more powerful Command Definitions.
.B Note:
The PROMPT and YESNO Built-Ins use {} as delimiters, not [].
.IP \(bu 4
.B [HASH]
Because \fCtwander\fP always recognizes the "#" as the beginning of a
comment, there is no direct way to include this character in a Command
String. It is conceivable that some commands (such as \'sed\') need
to make use of this character. The [HASH] built-in is provided for
this purpose. Anywhere it appears in the Command String, it will be
replaced with the "#" at command execution time. Unlike all the other
Built-In Variables, [HASH] is never quoted when it is replaced in a
Command String (regardless of whether the -t command argument is used
or how the QUOTECHAR Program Option is defined).
.IP \(bu 4
.B {PROMPT:Prompt-String==>default}
{PROMPT:...} allows you to insert an interactive prompt for the user
anywhere you'd like in a Command String. The user is prompted
with the "Prompt String" and this variable is replaced with their
response. If they respond with nothing, it is interpreted as an
abort, and the command execution is terminated. This makes commands
extremely powerful. For instance, say you want to create a group copy
command:
.ft C \" courier
.nf
# Copy a group of items to a location set by
# the user at runtime
UnixCopy = cp -R
Win32Copy = copy
# Unix Version
c UnixCP [UnixCopy] [DSELECTIONS] {PROMPT:Enter Destination}
# Win32 Version
C Win32CP [Win32Copy] [DSELECTIONS] {PROMPT:Enter Destination}
.fi
.ft \" revert
You can also provide a default response to the question. The prompt
is separated from the default by the \'==>\' string. This default
separator string can be changed to anything you like with the
DEFAULTSEP option.
This feature is useful when you want to provide the user the most-likely
response to the prompt:
.ft C \" courier
.nf
c UnixCP [UnixCopy] [DSELECTIONS] {PROMPT:Enter Destination==>/my/home/dir}
.fi
.ft \" revert
When the prompt is presented to the user, the default value is
pre-loaded into the response field. The user can either accept or
edit that string.
.IP \(bu 4
.B {YESNO:Question-String==>Yes|No}
{YESNO:...} allows you to prompt the user with a dialog containing a
Yes/No question and buttons for their response. If the user presses
"Yes", command interpretation/execution continues. If the user
presses "No", the command is aborted. This is handy when you want to
make sure the user really wants to run the command before continuing.
For instance, suppose you define a recursive file/directory deletion
command. Before running it, it's good to prompt the user to confirm
their intentions:
.ft C \" courier
.nf
D BigDelete {YESNO:Are You Absolutely Sure About This?} rm -rf [SELECTIONS]
.fi
.ft \" revert
You can also provide a default response to the question. It must be
either "Yes" or "No" (case-insensitive). Anything else will produce
an error. The prompt is separated from the default by the \'==>\'
string. This default separator string can be changed to anything you
like with the DEFAULTSEP option.
This feature is handy because you can pre-select the most likely
response to the dialog:
.ft C \" courier
.nf
D BigDelete {YESNO:Are You Absolutely Sure About This?==>No} rm -rf [SELECTIONS]
.fi
.ft \" revert
.SS Using Variable References Within Prompting Built-Ins
You may have guessed that there is something special about the
Prompting Built-In Variables. After all, they use a different
delimiter pair than all other variables in the \fCtwander\fP
configuration language. That's because you can include references to
other variables within a Prompting Built-In like this:
.ft C \" courier
.nf
PromptYN = Are You Sure You Want To Do This?
DefaultYN = No
a mycommand {YESNO:[PromptYN]==>[DefaultYN]} SomeDangerousCommand
.fi
.ft \" revert
A more sophisticated use of this would be when creating a "rename" command.
You often want to rename a file by changing only a few of its characters,
not the whole file name. Instead of forcing the user to type the whole name
in over again, why not just do this:
.ft C \" courier
.nf
Prompt = New File Name?
r rename mv [SELECTION] {PROMPT:[Prompt]==>[SELECTION]}
.fi
.ft \" revert
Now when the user runs the command, the default string will be the
name of the file to be renamed. They can move around inside the
dialog box created by \fC{PROMPT: ...}\fP at runtime to edit the
existing file name to taste.
You can also use Execution Variables inside a prompting Built-In:
.ft C \" courier
.nf
d setdate SomeDateCommand {PROMPT:Set Date To: ===>[\`date\`]}
.fi
.ft \" revert
.SS Program Memory Built-Ins
As described previously, \fCtwander\fP implements an advanced notion of
a Clipboard called "Program Memories". There is a corresponding group
of Built-In Variables which allows the contents of these memories to
be used in a Command Definition:
.IP \(bu 4
.B [MEM1] ... [MEM12]
Return the file/directory names currently stored in the indicated memory.
For example, to move all the files/directories currently named in
the first Program Memory to the current directory we could define
a move command like this:
.ft C \" courier
.nf
m move mv [MEM1] ./
.fi
.ft \" revert
.SS Notes On Built-In Variable Use
.IP \(bu 4
Built-In Variables which return a directory name do
.B NOT
append a path separator character ("/" or "\\") to the end of the name
even though it is visible in the GUI. This provides maximum
flexibility when defining commands. It is up to the command author to
insert the appropriate path separator character where needed. (NOTE:
Earlier releases of \fCtwander\fP
.B did
include the trailing path separator and you may have to edit
older Configuration Files accordingly. This change was necessary
because certain commands like Unix \'cp\' will not work if given
a source directory with the path separator included.)
For example, another way to express the full path of the currently
selected item is:
.ft C \" courier
.nf
# Unix Path Separator
UPSEP = /
#Win32 Path Separator
WPSEP = \\
[DIR][UPSEP][SELECTION]
- or -
[DIR][WPSEP][SELECTION]
.fi
.ft \" revert
Be aware that, because of \fCtwander\fP quoting rules, such constructs
will result in strings like:
.ft C \" courier
.nf
"/mydir"/"myfile"
- or -
"C:\\mydir"\\"myfile"
.fi
.ft \" revert
This should not generally be a problem with the various Unix
shells, and may work for some Windows commands. However, some
Windows programs (noted in \'notepad\') reject this kind of
filename when passed on the command line. The workaround
(and a generally easier way to do this sort of thing), is to use
the [DSELECTION] built-in which returns the full path name of
an item as a single quoted string.
.IP \(bu 4
All User-Defined, Environment, and Execution Variables are processed
each time a command is
.B run.
This is especially important for Execution Variables. The
variable will be "executed" each time the Command Definition
in which it is referenced is run.
.IP \(bu 4
Similarly, Built-In Variables are resolved
.B on each command invocation,
i.e - at command runtime. The Built-Ins will always reflect
the current set of files selected in the user interface.
.IP \(bu 4
The results of all built-ins (except HASH) are put inside
double-quotes when they are replaced in the Command String. This
default is recommended so that any built-in substitutions of, say,
filenames with spaces in them, will be properly recognized by your
commands. You can suppress the addition of double-quotes by using the
-t command line option when starting \fCtwander\fP.
.IP \(bu 4
Any of the variable types may appear multiple times in the
same Command String. For example, suppose you want to
define a generic Unix copy command:
.ft C \" courier
.nf
g gencopy cp -R {PROMPT:Enter Source} {PROMPT:Enter Destination}
.fi
.ft \" revert
When the user presses "g" (or clicks on "gencopy" on the Command
Menu), they will be presented with two prompts, one after the other,
and then the command will run.
.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.
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
evaluates to False, all statements to the end of the block are
ignored.
A Conditional Block always begins with a "Condition Test Statement"
and ends with the ".endif" statement. Conditional Processing
Statements may be nested without limit. \fCtwander\fP keeps track of which
\&'.endif' matches which Condition Test Statement. Like all Configuration File
entries, whitespace is ignored when processing Conditional Statements
and you are free to indent (or not) as you see fit.
Condition Test Statements are one of three types:
.ft C \" courier
.nf
#####
# Existential: True if FOO or $FOO are defined
#####
\&.if [FOO]
...
\&.endif
.if [$FOO]
...
\&.endif
#####
# Equality: True if FOO or $FOO are literally
# the same as the test-string
#####
\&.if [FOO] == test-string
...
\&.endif
\&.if [$FOO] == test-string
...
\&.endif
#####
# Inequality: True if FOO or $FOO are literally
# not the same as the test-string
#####
\&.if [FOO] != test-string
...
\&.endif
\&.if [$FOO] != test-string
...
\&.endif
.fi
.ft \" revert
To make it easy to create conditional blocks based on the type of
system you're running, \fCtwander\fP automatically pre-defines two variables
which provide information about your system:
.B \&.OS
(typically: nt, posix) and
.B \&.PLATFORM
(typically: freebsd4, linux-i386, win32). You should run \fCtwander\fP and
examine the "User-Defined Variables" section of the Help Menu to see
how these variables are set on your system.
These predefined variables show up as "User Defined Variables" in the
various \fCtwander\fP Help and Debug outputs, but they begin with a period to
remind you of their intended role. They will thus also sort first in
the User-Defined Variables section of the Help Menu.
Several things about Conditional Processing Statements are worth
noting:
.IP \(bu 4
Whitespace is mandatory after the ".if" statement - \&.if[FOO] is
syntactically incorrect. However, you need no whitespace on either
side of a "==" or "!=" test.
.IP \(bu 4
All these tests involve either a User-Defined Variable or
an Environment Variable, never a Program Option or Built In Variable.
.IP \(bu 4
A Condition Test Statement always involves a variable
.B reference
("[FOO]", never just "FOO") because we want the
.B contents,
not the name, of the variable for the test.
.IP \(bu 4
The Right Hand Side of an (in)equality test is just a string
comparsion - no variable expansion is done:
.ft C \" courier
.nf
\&.if [FOO] == string[BAR]
.fi
.ft \" revert
This will not work as you might expect because the contents of
variable FOO are literally compared to the string, "string[BAR]".
Note too that this comparison is case-sensitive.
.IP \(bu 4
The ".endif" statement must appear on the line by itself. Nothing
other than whitespace may precede it, and nothing (other than whitespace or a
comment) may follow it.
.P
See the example ".twander" file provided in the distribution for some
extended examples of using conditionals in your Configuration File.
Also see the
.B GOTCHAS
section below for further discussion.
.SS The Include Directive
You may include other files in your Configuration File with the following
directive:
.ft C \" courier
.nf
\&.include path-to-file
.fi
.ft \" revert
You may place as many of these statements in your Configuration File as you wish.
The only syntactic requirement is that there must be whitespace
between the directive and the file path. \fCtwander\fP makes no attempt
to validate that path, and you will see an warning message if the
file you specify cannot be opened.
The most common reason to do this is to maintain a "standard"
configuration in a separate file which is controlled by the system
administrator. This is especially handy on larger systems with
multiple users. The system administrator provides a read-only copy of
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
system:
.ft C \" courier
.nf
# Contents of /usr/local/etc/.twander.global
SHELL = bash -c
XTERM = xterm -fn 9x15 -l
VSHELL = [XTERM] -e [SHELL]
DIRSC1 = /usr/local
DIRSC2 = /usr/sbin
t terminal [XTERM]
.fi
.ft \" revert
Now, you can create your own personal Configuration File which takes advantage
of this standard file, but augments it with additional configuration
information of your choosing:
.ft C \" courier
.nf
# Contents of $HOME/.twander
\&.include /usr/local/etc/.twander.global
DIRSC2 = /etc
l ls [VSHELL] 'ls -al | [$PAGER]'
.fi
.ft \" revert
Keep in mind that \fCtwander\fP reads the contents of its Configuration File
.B in order.
In this case, it means that all of "/usr/local/etc/.twander.global"
is read and
.B then
the rest of "$HOME/.twander" is read. If something is defined more
than once, the
.B last definition
is what is used. In this case, DIRSC2 is overriden in the local
Configuration File and is ultimately assigned to "/etc". Similarly, you
can override previous definitions for User-Defined Variables
and even Command Definitions.
The program checks to see if you attempt to do a "circular" include.
For example, say file "A" \fC.include\fPs file "B" and file "B" then
\fC.include\fPs file "A". This wold create a neverending "circle" of
included files. If \fCtwander\fP detects this, it will display an error
describing the problem and skip the offending line.
.SH ADVANCED WINDOWS FEATURES
As shipped from the factory, \fCtwander\fP runs pretty much identically on
various Unix variants (FreeBSD, Linux) and Windows. However, \fCtwander\fP is
written to take advantage of Mark Hammond's \'win32all\' Python extensions if
they are present on the system. These extensions add many
Windows-specific features to Python and allow \fCtwander\fP to provide quite a
bit more Windows-centric information about files, directories, and
drives. You do
.B not
have to install \'win32all\' for \fCtwander\fP to operate properly
on your Windows system. Installing this package just means you'll
get even more \fCtwander\fP features on Windows than you would otherwise.
If you've installed \'win32all\', you can toggle these features
on- and off with the TOGWIN32ALL key described above.
.SS Getting \'win32all\'
You can get the \'win32all\' extensions one of two ways. If you've
installed the Active State version of Python for Windows,
(http://www.activestate.com/Products/ActivePython/) \'win32all\' is
already installed on your system. If you installed the standard
Python release for Windows
(http://www.python.org/download/download_windows.html), you must add
\'win32all\' to your installation. You'll find the extensions and
painless installation instructions at:
http://starship.python.net/crew/mhammond/
.SS New Features Supported With \'win32all\'
One important note is in order here: The features enabled by
\'win32all\' are only available on "true" Windows systems like Windows
2000 and Windows XP. Earlier versions of Windows like Win98 and WinME
emulate portions of the Win32 API and do not implement the advanced
security features found in the NTFS file system. Therefore, as noted
below, some of these features will not work on any of the older 16-bit
Windows operating systems. \fCtwander\fP handles this gracefully
without blowing-up so you can safely have \'win32all\' installed on
one of these older systems to take advantage of the features that
do work.
Once you have these extensions installed, \fCtwander\fP will
automatically enable three new features otherwise unavailable.
.IP \(bu 4
When viewing file/directory detail information, the owner and group
names will be the actual names reported by the operating system rather
than the filler values normally seen in those fields (\'win32owner\'
and \'win32group\'). (Does not work on older Windows systems like
Win98.)
.IP \(bu 4
Instead of showing Unix-style file permissions (which don't mean much
under Windows), systems with \'win32all\' installed will show the
so-called "file attributes" maintained by the operating system. Each
detailed entry in the display will have one or more of the following
attributes displayed in what is normally the Unix permissions field:
.ft C \" courier
.nf
d - Directory
A - Archive
C - Compressed
H - Hidden
N - Normal
R - Read-Only
S - System
.fi
.ft \" revert
.IP \(bu 4
A top-level "Drive List View" is enabled if \'win32all\' is installed. This
shows you a list of all currently available drives reachable by the
system, and information about those drives. For locally attached
drives, the drive label is shown. For network-attached drives, the
share string is shown. The drive type (CD/DVD, Fixed, Ramdisk,
Remote, Removable) is shown as are the free, and total space
statistics. As is the case with other \fCtwander\fP displays, these details
can be toggled on- and off via the TOGDETAIL key.
You can enter the Drive List View in a number of ways:
.nf
1) Select the ".." from the root directory of any drive.
2) Enter the string "\\\\" from the CHANGDIR dialog.
3) Press the DRIVELIST key. (default: Control-k)
4) Start \fCtwander\fP using "\\\\" as the starting directory
argument, either on the command line or using the
Configuration File STARTDIR option.
.fi
The "Drive List View" is available on all Windows variants, however the
free/total space values will be incorrect on older systems like Win98.
.SS Notes On Drive List View
The Drive List View is a little different than the usual
file/directory view. Program behavior (semantics) is thus also slightly
different than usual in several ways:
.IP \(bu 4
While in Drive List View, the various Built-In Variables which return
the current selections will return
.B the name or names of the selected drive(s)
(without a trailing slash) just as you would expect them to
in a normal file/directory view. This allows you to write
commands which take drive names (letters) as an argument.
The [DIR] Built-In returns an empty string in this view.
.IP \(bu 4
Normally, as you navigate around a file system, \fCtwander\fP sets its
own program context to the current directory. This is why you can
write Command Definitions using only the file/directory name currently
selected - \fCtwander\fP knows the current directory. When you are in
Drive List View, the notion of "current directory" has no real
meaning. So, \fCtwander\fP treats the directory from which you entered
Drive List View as the "current directory" while in that view.
.IP \(bu 4
By default, \fCtwander\fP automatically rereads the current view
about every 3 seconds. This is fine for a file/directory view
but would be annoyingly slow in the Drive List View since
it takes a moment or two to get the status of any floppy disk
drives attached to the system. Instead of forcing the user to
listen to (and wait for) the floppy drive status to be determined
every 3 seconds, \fCtwander\fP
.B only reads the drive information once when it enters Drive List View.
This means if a drive is connected or a floppy is inserted into the
system while in Drive List View, this fact will not be automatically
noted. You can force a manual update of the Drive List View by
pressing the REFRESH key. (default: Control-l)
.IP \(bu 4
The TOGWIN32ALL key (default: Control-w) is disabled in Drive List
View. Drive List View is only available in \'win32all\' mode and
toggling that mode off makes no sense here.
.IP \(bu 4
The SELALL (default: Control-comma) and SELINV (default: Control-i)
features work slightly differently in Drive List View than they
do otherwise. Ordinarily, these features never select the first
item of a file/directory display because it is always the ".."
entry pointing to the directory parent. In Drive List View,
the first entry
.B is
an entry of interest - usually, but not always, Drive A: - so
these two keys
.B do
select it as is appropriate.
.SS Disabling \'win32all\' Features
You can toggle these features on-and off using the TOGWIN32ALL key.
(default: Control-w) You can also permanently disable them by
setting the USEWIN32ALL option to False in the Configuration File.
This allows you to leave \'win32all\' installed on your system
if you need it for other reasons but don't want these features
enabled in \fCtwander\fP
.SH GOTCHAS
There are several tricky corners of \fCtwander\fP which need
further explanation:
.SS Program Starts Very Slowly
\fCtwander\fP attempts to determine the name of the host on which it is
running at program startup. This is used in the title bar display.
It first looks to see if the environment variable HOSTNAME is set, and
uses that value if it is. If this variable is not set, \fCtwander\fP
does a socket call to see if it can determine the hostname that way.
Either of these methods works fine, but the socket call can be very
slow if the network is misconfigured or malfunctioning. If
\fCtwander\fP is starting very slowly, try setting HOSTNAME explicitly
in your environment - this will prevent the socket call from ever
taking place. A simple way to do this with \'ksh\' or \'bash\' is:
.ft C \" courier
.nf
export HOSTNAME=\`hostname\`
.fi
.ft \" revert
(Note the backticks used to execute the \'hostname\' program
and assign its results to HOSTNAME.)
Be aware that \'bash\' claims to automatically set this variable when
it starts. However, it does not appear to export it properly on some
systems (noted on FreeBSD 4.7 with \'bash\' 2.05b). In this case, you
have to do this manually as just described even when using \'bash\'
On Windows, environment variables are set via the System Properties
menu.
.SS Program Loads Slowly
\fCtwander\fP is a fairly large Python program and can take a few seconds to
load and initialize, especially on older, slower systems. You can
speed this up a bit by creating an optimized byte-code version of
the program as follows (make sure you have appropriate administrative
permission to do this):
.nf
1) Go to the directory where the twander.py file is located.
2) Type the following command: python -O
3) Once Python is loaded type: import twander
4) Exit \fCtwander\fP.
5) Exit Python by pressing Control-d on Unix or
Control-z on Windows.
6) You will now see a new file in this directory: twander.pyo
This file should be significantly smaller than twander.py.
7) Now you can run the program by entering: python twander.pyo
on Unix/Windows or pythonw twander.pyo on Windows.
8) You have to repeat this procedure each time you install
a new version of twander.py
.fi
.SS Cannot Enter Certain Directories On Windows
Windows allows file/directory names to contain non-ASCII
characters. Python, as shipped, defaults to ASCII only
and grumbles mightily when it is asked to deal with a string
containing characters with ordinal values greater than
127 (i.e., 8-Bit "extended" ASCII). The solution to this
problem is to enable Python to handle non-ASCII strings.
This is done by editing a file called "site.py". This
file is normally found in:
.ft C \" courier
.nf
C:\\Program Files\\PythonXX\\Lib
.fi
.ft \" revert
Where "XX" is the actual version of Python you're running.
Open this file with an editor and look for the following
text:
.ft C \" courier
.nf
encoding = "ascii" # Default value set by _PyUnicode_Init()
if 0:
# Enable to support locale aware default string encodings.
import locale
.fi
.ft \" revert
Change the
.B if 0:
statement to
.B if 1:
and the problem will disappear.
.SS Getting Command Results Displayed In A New Window
When you invoke a command via \fCtwander\fP (whether via a command
definition in the Configuration File or the keyboard shortcut), you
generally want it to run in a new window. This turns out to be tricky
on Unix-like systems. If the program you are running is GUI-aware,
this should not be a problem. However, if you are using \fCtwander\fP
to run a command line program or script, you have to take extra care
in the formulation of the Command String. 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:
.ft C \" courier
.nf
V view less [DSELECTIONS]
.fi
.ft \" revert
Sadly, this will not work, at least not the way you expect.
If you started \fCtwander\fP 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 \fCtwander\fP
from a GUI or disconnected it from the initiating terminal with
a \'nohup\' ... & invocation, you will get
.B no
output. This is not a \fCtwander\fP problem, it is innate to how
command line programs run under Unix shell control.
To achieve the desired results, you have to create a new GUI window in
which your command can run and display results. The easiest way to do
this is to run your command in a new \'xterm\' window like this:
.ft C \" courier
.nf
V view xterm -l -e less [DSELECTIONS]
.fi
.ft \" revert
Some program further require you to provide a shell so they
can execute correctly. For instance, running \'ls\' in a
command definition requires something like this:
.ft C \" courier
.nf
L lshome xterm -l -e bash -c 'ls / | [$PAGER]'
.fi
.ft \" revert
In fact, this idiom is so common, you will see variables
defined in the example ".twander" file to simplify
such definitions (comments removed):
.ft C \" courier
.nf
SHELL = bash -c
VSHELL = [XTERM] [SHELL]
XTERM = xterm -fn 9x15 -l -e
.fi
.ft \" revert
Now you can write the command above like this:
.ft C \" courier
.nf
L lshome [VSHELL] 'ls / | [$PAGER]'
.fi
.ft \" revert
This causes your command line program to execute in an \'xterm\'
context
.B and
under a shell interpreter.
This is not as much an issue on Windows systems where the first
form of the command above works fine. Windows appears to have
no problem invoking a new window whether the command is GUI-aware
or not.
However,
.B which
terminal window is used for output can be confusing. If you
start \fCtwander\fP from a terminal session,
all terminal output will be sent to
.B the terminal session you used to invoke the program.
The way to work around this is to start \fCtwander\fP from a Windows
shortcut, using \'pythonw.exe\' rather than \'python.exe\'. Now
each time you run a command that needs a terminal session for
output, Windows will automatically create that session for you.
.SS Using Shell Wildcards In Command Definitions
The {PROMPT:...} Built-In Variable is provided to make
it possible to write general-purpose commands which
interact with the user. For example, you might want to
define a directory listing command for Windows like this:
.ft C \" courier
.nf
L DirList dir {PROMPT:Directory Of What?} | more
.fi
.ft \" revert
When the user presses the "L", they are presented with a
dialog box into which they enter their directory name
or wildcard pattern such as "\\*.bat" and everything
works as expected.
On Unix-like systems, however, this does not work as expected.
Suppose we define the command for these systems to be:
.ft C \" courier
.nf
L DirList [VSHELL] 'ls -l {PROMPT:Directory Of What?} | [$PAGER]'
.fi
.ft \" revert
This works fine
.B so long as the user does not enter a wildcard pattern
in response to the prompt. Why? Recall that \fCtwander\fP
quotes all Built-In Variable substitutions by default.
If the user enters this at the prompt:
.ft C \" courier
.nf
/kern*
.fi
.ft \" revert
The command \fCtwander\fP tries to execute is:
.ft C \" courier
.nf
VSHELL Stuff ... 'ls -l "/kern*" | ... pager stuff
.fi
.ft \" revert
The argument to \'ls\' is double-quoted. The Unix shells
understands this kind of quoting to mean
.B no expansion of wildcard characters is to be done,
which is the exact opposite of what we want.
You might think that the easy way to solve this problem is to turn off
argument quoting with the -t command line flag. However, this is not
really practical. Quoting is on or off globally in the program.
Turning it off means no Built-In Variable substitutions will be
quoted. That's fine so long as no directory/file you select via the
user interface has a space in the name. However, you are almost
certain to run into such files sooner or later. (Recall that the only
way to deal a directory/filename with spaces in it as a single
argument is to quote that name.)
So, we need a way to leave quoting on but also properly deal with
wildcard string entries from the user. Fortunately, because of
the richness of Unix shells, there is a simple way to do this:
we'll use a "shell variable" to hold the user's response and the
shell's ability to handle multiple commands on one line separated
by semi-colons:
.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
L DirList [VSHELL] 'UsrResp={PROMPT:Directory Of What?} ;
ls -l $UsrResp | [$PAGER]'
.fi
.ft \" revert
Why does this work? Because the shell interprets (and drops) the double-quotes,
when the results of the {PROMPT:...} are
.B assigned to "UsrResp".
The later reference to "$UsrResp" returns just the string the user
entered without the quotes and the command works as expected.
Interestingly, this problem does not occur when entering text
via the RUNCMD dialog. (default: Control-z) Here the text
you enter is
.B not
part of a Built-In Variable substitution, so it is not quoted. (The
exception, of course, would be if you entered a {PROMPT:...} reference
in the RUNCMD dialog. In this case, the same problem we've just
described could occur.)
.SS Modal Operation Of New Windows
Notice our example commands above do not end with "&". These should
not be needed on either Unix-like or Windows operating systems. When a
command is executed, \fCtwander\fP starts a process which runs concurrently
with \fCtwander\fP itself. This means you should be able to continue using
\fCtwander\fP while the new command executes.
If you enable the use of threads by setting USETHREADS to True, you
may see \fCtwander\fP locked out while the new command runs - so-called
"modal" operation. If this happens, it means your system does not
completely or correctly implement threading and you must use
conventional "heavy weight" processes (the default) rather than
threads.
.SS Windows Don't Disappear On Command Completion
It appears that some X Windows implementations (noted on XFree86 /
FreeBSD) do not correctly destroy an \'xterm\' window after a command
initiated with -e terminates. This is not a \fCtwander\fP problem - it is
an artifact of thread behavior on such systems and only happens
if you set USETHREADS=True. The workaround is to use the default
USETHREADS=False setting.
.SS Program Behavior Incorrect When A Window Is Resized
Certain Unix programs such as \'less\' appear to not work correctly
when the window in which they are running is resized. The program
seems to not be properly informed that the window size has changed.
This seems to be an interaction caused by running such programs as
threads rather than processes. Once again, the workaround here is
to not change the USETHREADS=False default setting.
.SS Really Slow Response Times When Changing To A New Directory
You may occasionally see
.B really
slow response times when you change to a new directory. This occurs
when you enter a huge directory with thousands of file or subdirectory
entries. \fCtwander\fP has to to compute the detail information for
each of these entries and this can take a lot of time. On a fast
machine with modern hard drives and controllers, \fCtwander\fP is able
to process several thousand entries in just a second or two. However,
a number of factors can significantly slow down this process:
.IP \(bu 4
The Autorefresh interval is set too low. Processing the directory
takes so long that as soon as one refresh finishes, the next starts
right away. The program will appear to hang. There are two
possibilities here. Either disable autorefreshing (via the -r command
line option or the AUTOREFRESH Configuration File option), or set the
REFRESHINT value to some high number so that \fCtwander\fP has plenty
of time to process a directory before the next refresh occurs.
.IP \(bu 4
Slow disk drives. You can really watch \fCtwander\fP grind if you
change to a large directory on a CDROM, for instance. There is no
good solution here. These drives are inherently slower than hard
drives, and you just have to wait. Make sure you lengthen your
refresh interval as described in the previous bullet.
.IP \(bu 4
By far the worst culprit here, though, is when running Windows
with \'win32all\' options enabled. It takes a lot more work
to get win32all-style information about each directory entry,
than the default Unix-style information. Simply turning
off \'win32all\' features alone can speed up directory processing
by a factor as high as 4X.
.P
When you combine these factors, it is possible to get really
long processing times. One test situation we observed was
reading a directory with over 4000 entries on a Windows CDROM.
With \'win32all\' processing enabled this took over a minute.
By disabling these features, the time came down to under 30 seconds.
.IP \(bu 4
For all these reasons, \fCtwander\fP implements an "adaptive refresh"
scheme by default. Whenever a directory is read, the time to do
so is tracked. If that time is less than the current value of
REFRESHINT - i.e., The directory read took less than REFRESHINT
milliseconds to complete - nothing special happens. But, if the
actual directory read time takes
.B longer
than REFRESHINT milliseconds, \fCtwander\fP adjusts the value of
REFRESHINT upwards. That way, you're guaranteed to have time
after the read completes to actually do something.
.P
This dynamic adjustment takes place on every directory read. If you
go to a slow directory and REFRESHINT gets dynamically adjusted to,
say, 25 seconds, when you go back to a faster/smaller directory,
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
"base" value for REFRESHINT.
.P
If you don't like this adaptive refresh interval business, set
the ADAPTREFRESH program option to False. In that case,
REFRESHINT will be strictly observed.
.SS Your Configuration File Does Not Produce The Desired Results
It's easy to fall into the trap of treating the \fCtwander\fP
configuration capabilities as a real "programming language".
It is not, it is a fairly simple macro language that does
very little more than string substitutions.
Keep the following rules in mind as you edit your configuration:
.IP \(bu 4
Except for conditional tests, Environment Variables and User-Defined
Variables are never resolved
.B until they appear in a Command Definition.
.IP \(bu 4
The Right Hand Side of Option Statements, Key Binding Statements, Directory Shortcut
Statements, Wildcard Statements, and Condition Test Statements
.B are treated literally -
No variable substitution is ever done there.
.IP \(bu 4
A Condition Test Statement always involves a variable
.B reference,
never just a variable name.
.IP \(bu 4
For a Condition Test Statement to be true, the referenced variable
.B must be defined
and any equality test must be satisfied.
.IP \(bu 4
When testing for the existence of a User-Defined or Environment
Variable, \fCtwander\fP does not care what
.B value
the variable contains. It is perfectly permissible to have
either type of variable set to an empty string. The fact
that the variable exists at all is what makes the following
construct true:
.ft C \" courier
.nf
CondVar =
\&.if [CondVar]
....
\&.endif
.fi
.ft \" revert
.IP \(bu 4
You have to be careful when overriding variable or command
definitions. User-Defined Variables referenced in
a Command Definition are de-referenced
.B at the time the Command Definition is encountered in the Configuration File.
This means that if you change a User-Defined Variable after
it has already been used in a Command Definition, only
future references to that variable will reflect the change:
.ft C \" courier
.nf
FOO = bar
x cmd1 command [FOO]
FOO = baz
y cmd2 command [FOO]
.fi
.ft \" revert
In this example, the first command will be defined as "command bar",
but the second will be defined as "command baz".
Watch for this, especially, when using the ".include" directive
and then overriding a variable defined in that file.
.P
Common mistakes include:
.ft C \" courier
.nf
#####
# Trying to embed a variable where it will never be resolved
#####
DIRSC03 = [$SystemDrive]\\Program Files
MYCOLOR = blue
FCOLOR = [MYCOLOR]
#####
# Expecting a conditional variable to be resolved before the test
# Suppose $EDITOR is set to "/usr/local/bin/emacs" ...
#
# The following will be False because [EDT] equals
# the string "[$EDITOR]". It is not replaced
# with "/usr/local/bin/emacs" until [EDT] appears
# in a Command Definition
#####
EDT = [$EDITOR]
\&.if [EDT] == /usr/local/bin/emacs
...
\&.endif
# Note, however, that *this* would work because
# Environment Variables are permitted in conditionals ...
\&.if [$EDITOR] == /usr/local/bin/emacs
...
\&.endif
#####
# A badly formed condition is ignored (after a warning)
# which means *all the lines following will be processed*
# (until a valid condition statement which is False is
# encountered).
#####
PROCESS = no
SUBPART = no
# We meant not to process the following but all the
# lines up to the next .if statement *are* processed
# because the bad syntax on the next line means it's ignored
\&.if PROCESS != no
... # Processed!
\&.if [SUBPART] == yes # *Now* we'll stop
...
\&.endif
\&.endif
.fi
.ft \" revert
.SH OTHER
File/Directory name sorting is done without-case sensitivity on
Windows systems because the underlying operating system does not
observe case.
Because this program has not been tested on anything other than
Unix-like and Windows systems, command execution by double-click
or pressing Enter is inhibited on all other operating systems
by default.
You must have Python 2.2 or later installed as well as Tkinter support
installed for that release. In the case of Windows, Tkinter is bundled
with the standard Windows Python distribution. In the case of
Unix-like systems, you may have to first install Python and then the
appropriate release of Tkinter. This is the case, for example, with
FreeBSD.
You must install the \'win32all\' extensions if you want to use
the advanced Windows features.
You'll find the latest version and, occasionally, Release Candidates
of the next version of \fCtwander\fP at:
.ft C \" courier
.nf
http://www.tundraware.com/Software/twander
.fi
.ft \" revert
You should check this site regularly for updates and bug-fixes. The
\'WHATSNEW.txt\' file describes changes since the last public release
of the program.
.SH BUGS AND MISFEATURES
As of this release, a number of problems relating to \fCtwander\fP
use have been noted:
.IP \(bu 4
The Configuration File parser does no validation to check the sanity
of its various entries for Program Options, Key Bindings, Directory
Shortcuts, Variable Definitions, and Command Definitions. It is
entirely possible to edit something into this file that makes no sense
at all and causes \fCtwander\fP to misbehave.
.IP \(bu 4
There appears to be a Tkinter/Tk bug on Unix which sometimes inhibits
the correct title display when you tear-off a menu. This is a
cosmetic defect and may disappear in future releases of
Tkinter/Tk/X-Windows.
.IP \(bu 4
Some \'win32all\' features do not work correctly or at all on
older Windows OSs. For example, the free/total space available in the
Drive List View has been noted to display incorrect values on Win98.
Similarly, the owner and group names are displayed as "Unavailable" on
pre-NTFS file systems. These are OS limitations which \fCtwander\fP
handles gracefully.
.IP \(bu 4
If you are using \'bash\' as your Unix shell, be aware that,
although it sets HOSTNAME automatically, this environment variable
appears to not be exported consistently on all systems.
.IP \(bu 4
If you are running Windows and have file or directory names with
non-ASCII characters in them, you must configure Python to
properly deal with such characters. This is described above in
the section entitled,
.B GOTCHAS.
.IP \(bu 4
This program has not been tested on MacOS. It has been reported that
Python on MacOS X returns \'posix\' as its OS name. If true, \fCtwander\fP
should work as written, though we've not verified this. Please let us
know how/if it works there and any issues you discover.
.SH INSTALLING \fCtwander\fP
Installation of \fCtwander\fP is fairly simple and takes only a few
moments. The most important thing before installing the program is to
make sure you have Python 2.2 (or later) with Tkinter support
installed on your system.
One other note: However you install the program, it is probably
easiest to get started by editing the example ".twander" file to
taste. Be aware that this file is shipped with everything commented
out. You have to uncomment/edit the section relevant to your
operating system: Unix-like or Windows.
.SS Installing Using The FreeBSD Port
If you've installed \fCtwander\fP using the FreeBSD port, all you have
to do is copy the example Configuration File, ".twander" found in
/usr/local/share/doc/twander to your home directory and edit it to
taste. (You'll also find documentation for \fCtwander\fP in various formats in
this directory as well.)
Make sure that /usr/local/bin is in your path. To start the program,
just type "twander.py" from the shell prompt.
.SS Installing Manually On A Unix-like System
Copy the "twander.py" file to a directory somewhere on your path.
(/usr/local/bin is a good candidate). Make sure this file has
permissions 755 and owner/group appropriate for your system
(root/wheel, root/root, or bin/bin). Copy the ".twander" file
to your home directory and edit to taste.
To run the program, just type "twander.py" from a shell prompt.
.B Red Hat Linux Users Please Note:
RH Linux (and possibly other Linux systems) installs two versions of
Python. Version 1.52 is called \'python\', and Version 2.2 is called
\'python2\'. \fCtwander\fP requires the latter and will not run on the
former. As shipped, \fCtwander\fP invokes Python with the Unix shell
"#!" mechanism using the name \'python\' - which in this case is the
wrong version. You can work around this problem one of several ways:
.IP \(bu 4
Rename \'python\' to \'python1\' and then rename \'python2\'
to \'python\'. (Not Recommended - could break other programs.)
.IP \(bu 4
Write an alias or shell script which explicity starts
\fCtwander\fP with the correct version of Python:
.ft C \" courier
.nf
#!/bin/sh
python2 twander.py $*
.fi
.ft \" revert
.IP \(bu 4
Change the first line of the \fCtwander\fP code to refer
to \'python2\' instead of \'python\'.
.P
Red Hat users who have upgraded from earlier Linux versions should
also note that you may have files in your home directories owned by
owners and groups which are no longer defined in the system!
\fCtwander\fP shows the owner and group fields for such files as numbers
rather than names. As best as we can determine, this is caused when
an RH installation is updated from an older version.
.SS Installing Manually On A Windows System
Copy the "twander.py" file to a directory somewhere on your path, or
create a new directory to hold this file and add that directory path
to the PATH environment variable.
.B IMPORTANT NOTE TO WINDOWS USERS:
Windows has the old MS-DOS legacy of assuming that a "." begins a file
"extension". Although you can create and read files in the form
".something", it is not recommended because many Windows programs get
confused when they see this. It is also difficult to remove files
named this way with the standard Windows programs and utilities. This
is especially the case for older Windows operating systems like Win98.
For this reason, it is recommended that you rename the ".twander"
default Configuration File provided in the program distribution to
something else like "twander.conf" and use the \fCtwander\fP -c command
line option to point to this Configuration File.
On Windows, where to put the Configuration File raises an interesting
question. Microsoft operating systems normally do not set the "HOME"
environment variable, because they have no notion of a "home"
directory - Well, they do, but it is called "USERPROFILE" not "HOME".
So, you can either create a new user-specific environment variable
called HOME yourself (which points to your desired home directory) or
you can invoke \fCtwander\fP with the -c argument to explictly declare
where it can find its Configuration File.
You can run the program several ways on Windows systems:
.IP \(bu 4
Create a Windows shortcut which points to the "twander.py" file using
the "pythonw" command to invoke it. Normally, starting a Python
program from the Windows GUI creates a parent window which persists as
long as the program runs. Using "pythonw" instead of "python" to run
your program suppresses the creation of this blank parent window. For
example, you might have something like this in the "Target:" field of
your shortcut:
.ft C \" courier
.nf
"C:\\Program Files\\Python22\\pythonw.exe" C:\\twander.py \\
.fi
.ft \" revert
This runs the program starting at the root directory of
the current drive (assuming "twander.py" is located in C:\\.
.IP \(bu 4
Start a command line window and issue a command like the one
above directly from the command line.
.IP \(bu 4
Use Windows Explorer (or better still, an already running instance
of \fCtwander\fP!) to navigate to the directory where "twander.py"
is located. Double-click on the file. If Python is properly
installed, there should be an association for ".py" file types
and \fCtwander\fP should start automatically.
.SH GETTING HELP: THE \fCtwander\fP MAILING LIST
TundraWare Inc. maintains an email list for \fCtwander\fP
users to get help and exchange ideas. To subscribe,
send mail to:
.ft C \" courier
.nf
majordomo@tundraware.com
.fi
.ft \" revert
In the body (not the subject line) of the email, enter
the following text, substituting your own email address
as indicated:
.ft C \" courier
.nf
subscribe twander-users your-email-address
.fi
.ft \" revert
.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.
\fCtwander\fP is another 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)
\fCtwander\fP 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. Some (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 \fCtwander\fP 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 \fCtwander\fP is written in Python using Tkinter, the same
program runs essentially identically on many Unix-like and Windows
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 \fCtwander\fP 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
\fCtwander\fP is Copyright(c) \*(CP TundraWare Inc. For terms of
use, see the twander-license.txt file in the program distribution. If
you install \fCtwander\fP on a FreeBSD system using the 'ports'
mechanism, you will also find this file in
/usr/local/share/doc/twander.
.SH AUTHOR
.ft C \" courier
.nf
Tim Daneliuk
twander@tundraware.com
.fi
.ft \" revert
.SH DOCUMENT REVISION INFORMATION
$Id: twander.1,v 1.130 2006/12/14 07:37:38 tundra Exp $
tundra