.TH twander 1 "TundraWare Inc." .SH twander Wander around a filesystem executing commands of your choice on selected files. .SH SYNOPSIS twander [-bcdfhnqrswvxy] [startdir] .SH DESCRIPTION \'twander\' is a GUI-based file tree navigation tool. It lets you "wander" through your file system at will. Unlike other similar programs, .B YOU define what features or commands are available to manipulate selected files. You do this via a configuration file. This gives you the convenience of a GUI-driven file navigator with the flexibility of defining almost any kind of command you'd like at your disposal. .SH OPTIONS .TP .B startdir Directory in which to begin. (default: ./) .TP .B -b backcolor Desired background color. (default: black) .TP .B -c path/name of configuration file Specify the location and name of the configuration file. (default is ~/.twander) .TP .B -d Start in debug mode. The program runs, but does not actually execute any commands. Instead, the contents of various internal tables such as the Symbol Table and Command Table are listed on standard output. If the user presses a defined command key, the command that would have been executed is printed to standard output, but no command is actually performed. This option is mildly useful in debugging configuration files insfar as it will display the command string after all substitutions of variables (both builtins and user-defined) has been done. .TP .B -f forecolor Desired foreground color. (default: green) .TP .B -h Print this help information. .TP .B -n fontname Name of desired font family. (e.g., courier, times, helvetica) (default: courier) .TP .B -q Quiet mode - suppresses warnings. (default: warnings on) .TP .B -r Turn off automatic refreshing of directory display. (default: refresh on) This is useful on slow machines (or slow X connections) and/or when working with very large directories. In this situtation, the frequent updating of the \'twander\' display can make the program unacceptably slow and unresponsive. In this case you can still force an update manually with the \'Control-l\' key. .TP .B -s fontsize Font size in points. (default: 12) .TP .B -v Print detailed version information. .TP .B -w fontweight One of: bold, italic, underline, overstrike. (default: bold) .TP .B -x width Set window width. (default: 60) .TP .B -y width Set window width. (default: 25) .SH PREASSIGNED KEYS A few of the keys on the keyboard are preassigned to special functions: .TP .B Arrow Keys and Spacebar The Left- and Right-Arrow keys are used for horizontal scrolling, if needed. The Up- and Down-Arrow keys move up and down through the currently displayed directory listing. Pressing the Spacebar will cause the currently underlined item to be selected just as if you had clicked on it. .TP .B Backspace Move .B up one directory ("..") in the filesystem hierarchy. .TP .B Esc Exit \'twander\' .TP .B Home Return to the original starting directory .TP .B Ctrl-L Redraw/update the directory listing. .TP .B Ctrl-Left Arrow Move .B back to previously visited directory. This can be done repeatedly until you end up in the original starting directory. .SH CONFIGURATION FILE FORMAT \'twander\' .B requires a startup configuration file in order to run. It is the only way the program knows what features you wish to enable and what commands are required to implement each feature. By default, the program expects to find configuration information in .B ~/.twander but you can override this with the .B -c command line option. \'twander\' configuration files consist of freeform lines of text. Whitespace is ignored, and a comment may be inserted anywhere. Comments must begin with the .B # character. Each line of configuration information consists of two parts, the .B Command Name and the .B Command String. The Command Name is nothing more than your name for a given command. The Command String tells \'twander\' what to do when you issue the command in question. Within the Command Name you can specify a single letter to be the .B Command Key by placing the .B & character before letter you wish to use. This letter will be a keyboard shortcut to the command. If you select a file via the \`twander\` interface and then press this key, the command associated with that key will be executed. The case of the Command Key is ignored, so \'X\' and \'x\' will both invoke the same command, if any. Within the Command String you can specify several different kinds of information: literal text which \'twander\' will not touch, words beginning with the .B $ symbol, which are interpreted as environment variables, the special symbol .B [FILE], and the special symbol .B [DIRECTORY]. When you decide to run a command, \'twander\' will replace [FILE] with the currently selected file name. This will be the .B fully qualified name of the file - i.e., it will include the full path name. Similarly, [DIRECTORY] is replaced with the current directory name (ending with a path separator character). Here is an example .twander file: .nf # 'twander' configuration file example &edit $EDITOR [FILE] vie&w $PAGER [FILE] ls /bin/ls -al [FILE] | $PAGER .fi The first line is a comment and is completely ignored. The second line is blank (all whitespace) and is also ignored. Line 3 means this: Invoke the \'edit\' command using \'e\' as the command key. Use the $EDITOR environment variable to determine which program to use for editing and place the current directory/file name immediately after the program name to invoke the editing session. Similarly, Line 4 means: Use the program defined in he $PAGER environment variable when invoking the \'view\' command via the \'w\' key. Pass the currently selected directory or file name to that program as its only argument. Line 5 is similar except for one thing: There is no Command Key shortcut defined for that command. \'twander\' will permit this, but it will warn you about it when the program starts. If you specify an environment variable in the configuration file which is not actually defined, \'twander\' will print an error to that effect and refuse to run. In other words, every environment variable referenced in your configuration file must be defined in order for the program to run at all. This is an intentional design choice to force the creation of sane and meaningful configuration files. .SH GOTCHAS There are several tricky corners of \'twander\' which need further explanation: .B 1) Getting Command Results Displayed In A New Window When you invoke a command via \'twander\', you generally want it to run in a new window. If the program you are running is GUI-aware, this should not be a problem. However, if you are using \'twander\' to run a command line program or script, you have to take extra care in the formulation of the configuration file entry. In the case of Unix-like systems you have to invoke the command so that it runs in some GUI context. Say you want to use a pager like \'less\' to view files. You would expect that this entry might do it: &View less [FILE] & Sadly, this will not work, at least not the way you expect. If you started \'twander\' from a terminal session and use the command above, it will work, but the results will appear in the invoking terminal window, .B not in a new window as you might expect. If you started \'twander\' from a GUI or disconnected it from the initating terminal with a \'nohup\' ... & invocation, you will get .B no output. This is not a \'twander\' problem, it is innate to how command line programs run under shell control. To achieve the desired results, you'll need something like this in your configuration file: .nf &View xterm -fn 9x15 -e $PAGER [FILE] & .fi This causes your command line program to execute in an \'xterm\' context. Note also that the command ends with \'&\'. If you do not have this, \'twander\' will execute the command of interest and hang waiting until the command completes. This so-called "modal" operation may be useful sometimes, but usually it is not what you want. For Win32, the issue is a bit simpler. Just make sure that you run \'twander\' with the \'pythonw\' version of the python binary. This version is specifically intended for running Python programs with no controlling command line window open. In this case, our example looks like: .nf &view cmd /c " less [FILE] " .fi .B 2) File- Or Directory Names Which Contain Whitespace [FILE] and [DIRECTORY] faithfully return the name of the item you select, whitespace and all. The shells of some operating systems, notably the Unix-like systems (FreeBSD, Linux...), require special handling for this sort of thing. Here is our example again, with this taken into account: .nf &View xterm -e bash -c ' cat "[FILE]" | less ' & .fi .SH OTHER You must have \'python\' 2.2 or later installed as well as \'Tkinter\' support installed for that release. In the case of Win32, \'Tkinter\' is bundled with the standard Windows \'python\' distribution. In the case of Unix, you may have to first install \'python\' and then the appropriate release of \'Tkinter\'. This is the case, for example, with FreeBSD. .SH BUGS AND MISFEATURES The color options (-b, -f), font options (-n, -s, -w), and size option (-x, -y) are .B not checked for validity when the command line is initially read. If you enter something unreasonable for these options, \'twander\' will refuse to run with some .B really interesting and entertaining error messages. The program could be more gracious about this. This program has not been tested on MacOS. Please let me know how/if it works there and any issues you discover. .SH COPYRIGHT AND LICENSING \'twander\' is Copyright(c) 2002 TundraWare Inc. For terms of use, see the twander-license.txt file in the program distribution. If you install \'twander\' on a FreeBSD system using the 'ports' mechanism, you will also find this file in /usr/local/share/doc/twander. .SH AUTHOR .nf Tim Daneliuk twander@tundraware.com