diff --git a/twander.1 b/twander.1 index 9ee8225..60eb559 100644 --- a/twander.1 +++ b/twander.1 @@ -7,7 +7,10 @@ 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. +toward the end of this document first. Similarly, there is a +section towards the end of this document entitled +.B "INSTALLING \'twander\'" +which describes how the program should be installed. .SH SYNOPSIS twander [-bcdfhnqrstvwxy] [startdir] @@ -17,6 +20,9 @@ .B startdir Directory in which to begin. (default: ./) +If this directory does not exist or cannot be opened, \'twander\' +will display an error message and abort. + .TP .B -b backcolor Desired background color. (default: black) @@ -155,90 +161,257 @@ Here, ordered by category, are the default keyboard and mouse bindings for \'twander\': -.SS General Program Commands +.SS GENERAL PROGRAM COMMANDS -.PP +This family of commands controls the operation of \'twander\' itself: .TP -.B KEYPRESS KeyPress +.B Quit Program +Control-q + +Exit the program. .TP -.B QUITPROG Control-q +.B Re-Read Configuration File +Control-r + +Re-read the configuration file. This allows you to edit the +configuration file while \'twander\' is running and then read your +changes in without having to exit the program. This is handy when +editing or changing command definitions. However, if you edit the +configuration file and introduce an error, \'twander\' will terminate +when you try to re-read it (just as it will if you try to start the +program with a bad configuration file). .TP -.B READCONF Control-r +.B Refresh Display +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 the -r command +line flag. .TP -.B REFRESH Control-l +.B Toggle Details +Control-t + +Toggle between detailed and filename-only views of the directory. + + +.SS DIRECTORY NAVIGATION + +This family of commands controls movement between directories. If at any point, +you attempt to navigate into a directory that does not exist or which +does not have appropriate permissions, \'twander\' will issue an appropriate +message, and remain in the original directory where the request was issued. +This is +.B unlike +the case of a non-existent or unreadable directory specified when the program +is first started. In that case, \'twander\' reports the error and aborts. .TP -.B RUNCMD Control-z +.B Change Directory +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. + .TP -.B TOGDETAILControl-t +.B Go To Home Directory +Control-h - -.SS Directory Navigation +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 CHANGEDIR Control-x +.B Go Back One Directory +.PD 000 +Control-b +.IP +Control-DoubleClick-Left-Mouse-Button +.PD + +\'twander\' 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, never discarding any entry. .TP -.B DIRHOME Control-h +.B Go To Starting Directory +Control-s + +Go back to the original directory in which \'twander\' was started. .TP -.B DIRBACK Control-b +.B Go Up To Parent Directory +.PD 000 +Control-u +.IP +Control-DoubleClick-Right-Mouse-Button +.PD + +Move to the parent of the current directory (".."). + + +.SS SELECTION KEYS + +This family of commands controls the selection of one or more (or no) +items in the current directory: .TP -.B DIRSTART Control-s +.B Select All Items +Control-Comma + +Select every item in the current directory. .TP -.B DIRUP Control-u +.B Unselect All Items (Select Nothing) +Control-Period + +Unselect everything in the current directory. .TP -.B MSEBACK Control-Double-ButtonRelease-1 +.B Select Next Item +Control-n + +Select next item down in the directory. .TP -.B MSEUP Control-Double-ButtonRelease-3 +.B Select Previous Item +Control-p -.SS Selection Keys +Select previous item up in the directory. .TP -.B SELALL Control-comma +.B Select Last Item +Control-e + +Select last item in the directory. .TP -.B SELNEXT Control-n +.B Select First Item +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. + +.SS SCROLLING COMMANDS + +If a given directory's contents cannot be displayed on a single +screen, \'twander\' supports both vertical and horizontal scrolling +via scrollbars. This capability is doubled on the keyboard with: .TP -.B SELNONE Control-period +.B Scroll Page Down +Control-v + +Scroll down one page in the directory listing. .TP -.B SELPREV Control-p +.B Scroll Page Up +Control-c + +Scroll up one page in the directory listing. + + +.SS COMMAND EXECUTION OPTIONS + +This family of commands causes \'twander\' to actually +attempt to execute some command you've chosen: .TP -.B SELEND Control-e +.B Run Arbitrary Command +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. .TP -.B SELTOP Control-a +.B Run Selected File / Move To Selected Directory +.PD 000 +Control-space +.IP +DoubleClick-Left-Mouse-Button +.PD + +If the selected item is a Directory, \'twander\' will move into +that directory when this command is issued. If the selected item +is a file, \'twander\' 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 \'twander\' (or their group) for the +file to be executed. + +On Win32, 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). .TP -.B SELKEY Control-space +.B Run User-Defined Command +User-Defined (Single Letter) Key -.TP -.B SELMOUSE Double-ButtonRelease-1 - - -.SS Intra-Display Movement - -.TP -.B PGDN Control-v - -.TP -.B PGUP Control-c +Each command defined in the configuration file has both a "Command +Key" and a "Command Name" associated with it. Pressing that key +will cause the command associated with it to be run. If no command +is associated with a given key, nothing will happen. .SH MENU OPTIONS +Although \'twander\' 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 +\'twander\' display window, above the directory listing. + +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 \'twander\' allowing it to be placed anywhere on screen. +Even when detatched, these menus remain current and in-sync with +\'twander\' 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 Commands MENU + +Every command defined in the configuration file is listed in this menu +by its "Command Name". 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'e forgotten. It is also handy to confirm which commands +are defined after you've edited and reloaded the configuration file. + +.SS Directories MENU + +\'twander\' keeps track of every directory visited. The previously +described command to move "Back" one directory allows directory naviation +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 explictly +navigate to it again, back up to it, or name it explictly using the +"Change Directory" command. + + .SH LOCATION OF CONFIGURATION FILE \'twander\' @@ -354,6 +527,8 @@ This program has not been tested on MacOS. Please let me know how/if it works there and any issues you discover. +.SH INSTALLING \'twander\' + .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