diff --git a/twander.1 b/twander.1 index 46d3dde..ded0ce7 100644 --- a/twander.1 +++ b/twander.1 @@ -7,8 +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. Similarly, there is a -section towards the end of this document entitled +toward the end of this document first. + +Similarly, if this is the first time you've worked with \'twander\', +there is a section towards the end of this document entitled .B "INSTALLING \'twander\'" which describes how the program should be installed. @@ -44,13 +46,13 @@ The program runs, but does not actually execute any commands. Instead, the contents of various internal tables such as the Symbol -Table and Command Table are listed on standard output. If the user -presses a defined command key, the command that would have been -executed is printed to standard output, but no command is actually -performed. This option is mildly useful in debugging configuration -files insfar as it will display the command string after all -substitutions of variables (both built-ins and user-defined) has been -done. +Table and Command Table are listed on standard output. The Key +Bindings are also listed. If the user presses a defined command key, +the command that would have been executed is printed to standard +output, but no command is actually performed. This option is mildly +useful in debugging configuration files insfar as it will display the +command string after all substitutions of variables (both built-ins +and user-defined) has been done. .TP .B -f forecolor @@ -114,71 +116,63 @@ .B -y width Set window width. (default: 25) -.SH KEYBOARD BINDINGS AND HOW TO CHANGE THEM +.SH KEYBOARD USE -No program that runs on many operating systems can satisfy -everyone's (anyone's!) idea of what the "correct" key bindings -should be. An emacs user, vi user, BSD user, and Windows user -are going to differ considerably on what keys should be bound -to what feature. +By design, \'twander\' allows you to do almost everything of interest +using only the keyboard. Various \'twander\' 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. -So, what follows is documentation on -the -.B default -key bindings. However, it is not difficult to change the -defaults. They are listed near the top of the program -file (twander.py) to allow people to tailor them as they -wish. The only thing you need to know is the Tkinter -nomenclature for keystroke names. You can get a pretty -good idea of this from reading the first part of the -program, and failing that, there is abundant documentation -of this topic on The Net. - -The only convention that ought to be observed here (to keep -the program sane - it assumes this convention throughout), is -that -.B keyboard navigation and selection commands are Control keys. - -The obvious question here is, "Why isn't this a configuration option -maintained in the configuration file?" The answer is that it would -make the configuration file parser overly complex to handle something -which should be changed very rarely, if at all. The downside to this -approach is that per-user customization requires each user to keep a -copy of \'twander.py\' in their own directory space. - - -.SH ARROW AND KEYPAD BEHAVIOR +.SH A NOTE ON KEYBOARD ARROW AND KEYPAD BEHAVIOR Generally, the arrow and keypad keys should do what you would expect on the system in question. On Win32 systems, particularly, there ought to be no odd arrow/keypad behavior. X-Windows is somewhat more problematic in this area. Just what an -arrow key is "supposed" to do depends on how its been mapped in your X +arrow key is "supposed" to do depends on how it's been mapped in your X server software. Testing \'twander\' on various X servers showed -quite a bit of variability on how they handled the arrows and keypad. +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 \'twander\'. + .SH DEFAULT KEYBOARD AND MOUSE BINDINGS - Here, ordered by category, are the default keyboard and mouse -bindings for \'twander\': +bindings for \'twander\'. The general format is: + +.TP +.B Description (Program Function Name) +.PD 000 +Default Key Assignment +.IP +Default Mouse Assignment (if any) +.PD +.P + +The "Program Function Name" is the internal variable \'twander\' +uses to associate a particular feature with a particular keystroke +or mouse action. You can ignore it unless you intend to override +the default assignments. This use is described below in the +section entitled, +.B CHANGING KEYBOARD BINDINGS VIA THE CONFIGURATION FILE. + .SS GENERAL PROGRAM COMMANDS This family of commands controls the operation of \'twander\' itself. .TP -.B Quit Program +.B Quit Program (QUITPROG) Control-q Exit the program. .TP -.B Re-Read Configuration File +.B Re-Read Configuration File (READCONF) Control-r Re-read the configuration file. This allows you to edit the @@ -190,7 +184,7 @@ program with a bad configuration file). .TP -.B Refresh Display +.B Refresh Display (REFRESH) Control-l Re-read the current directory's contents and display it. This is most useful @@ -198,7 +192,7 @@ line flag. .TP -.B Toggle Details +.B Toggle Details (TOGDETAIL) Control-t Toggle between detailed and filename-only views of the directory. @@ -216,7 +210,7 @@ is first started. In that case, \'twander\' reports the error and aborts. .TP -.B Change Directory +.B Change Directory (CHANGEDIR) Control-x This is a shortcut that allows you to directly move to a new directory/path - @@ -224,7 +218,7 @@ .TP -.B Go To Home Directory +.B Go To Home Directory (DIRHOME) Control-h If the "HOME" environment variable is defined on your system, this will move @@ -232,7 +226,7 @@ this command will move to the original starting directory. .TP -.B Go Back One Directory +.B Go Back One Directory (DIRBACK and MOUSEBACK) .PD 000 Control-b .IP @@ -249,13 +243,13 @@ all directories visited regardless of order, never discarding any entry. .TP -.B Go To Starting Directory +.B Go To Starting Directory (DIRSTART) Control-s Go back to the original directory in which \'twander\' was started. .TP -.B Go Up To Parent Directory +.B Go Up To Parent Directory (DIRUP and MOUSEUP) .PD 000 Control-u .IP @@ -271,37 +265,37 @@ items in the current directory. .TP -.B Select All Items +.B Select All Items (SELALL) Control-Comma Select every item in the current directory. .TP -.B Unselect All Items (Select Nothing) +.B Unselect All Items (SELNONE) Control-Period Unselect everything in the current directory. .TP -.B Select Next Item +.B Select Next Item (SELNEXT) Control-n Select next item down in the directory. .TP -.B Select Previous Item +.B Select Previous Item (SELPREV) Control-p Select previous item up in the directory. .TP -.B Select Last Item +.B Select Last Item (SELEND) Control-e Select last item in the directory. .TP -.B Select First Item +.B Select First Item (SELTOP) Control-a Select first item in the directory. This will always be the @@ -326,13 +320,13 @@ via scrollbars. This capability is doubled on the keyboard with: .TP -.B Scroll Page Down +.B Scroll Page Down (PGDN) Control-v Scroll down one page in the directory listing. .TP -.B Scroll Page Up +.B Scroll Page Up (PGUP) Control-c Scroll up one page in the directory listing. @@ -344,7 +338,7 @@ attempt to execute some command you've chosen: .TP -.B Run Arbitrary Command +.B Run Arbitrary Command (RUNCMD) Control-z This is a shortcut that allows you to run any command you'd like @@ -353,7 +347,7 @@ your disposal. .TP -.B Run Selected File / Move To Selected Directory +.B Run Selected File / Move To Selected Directory (SELKEY and SELMOUSE) .PD 000 Control-space .IP @@ -434,11 +428,12 @@ .SH LOCATION OF CONFIGURATION FILE -\'twander\' -.B requires -a startup configuration file in order to run. It is in this file that -the user defines the commands which can be applied to the files and -directories selected in the program GUI. +\'twander\' needs a configuration file in order to define commands +available to be run. Although the program will run without a configuration +file present, it will warn you that it is doing so without any commands +defined. Not only are commands defined in this configuration file, +but keyboard bindings can optionally be assigned (changed from their +defaults) in this file. By default, the program expects to find configuration information in .B $HOME/.twander @@ -485,6 +480,77 @@ initiated from the keyboard while running \'twander\'. +.SH CHANGING KEYBOARD BINDINGS VIA THE CONFIGURATION FILE + +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. + +It is not difficult to override the default keyboard bindings by +adding entries in the configuration file. Doing so requires some +familiary with how Tkinter names keystrokes. Good resources for +learning this exist abundantly on the Internet, among them: + +.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 + +Keyboard binding assignments look just like a local variable +definition in the configuration file. They take the form: + +.nf +PROGRAM-FUNCTION-NAME = KEYSTROKE +.fi + +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. However, several important rules need to be +observed when doing so: + +.IP +It is best if keyboard commands are all Control or Function keys. If +you assign anything to a simple key it may conflict with a +user-defined command. If you assign anything to a keypad/special key +it may conflict with that key's normal GUI behavior. + +.IP +The Tkinter keynames should placed on the right side of the "=" symbol +.B without any quotation marks. + +So, this is correct: + +.nf +QUITPROG = +.fi + +But, this is not correct: + +.nf +QUITPROG = '' +.fi + +.IP +The key binding variables (the left side of the assignments) are +RESERVED and may not be used as names for your own user-defined +variables elsewhere in the configuration file. + +.IP +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. + +Be aware that \'twander\' does no sanity testing on the assignments +you change. If you assign a particular \'twander\' 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 \'twander\' manages to run. + + .SH GOTCHAS There are several tricky corners of \'twander\' which need @@ -530,7 +596,7 @@ This is not so much of an issue on Win32 systems where the first form of the command above works fine. -.B 2) Non-Modal Operation Of New Windows +.B 2) Modal Operation Of New Windows Notice our example commands above do not end with "&". These should not be needed on either Unix-like or Win32 @@ -544,6 +610,14 @@ if you want non-modal command operation, try adding a "&" at the end of your command definition. +.B 3) Windows That 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 \'twander\' problem. The +workaround is to manually kill the window or press enter once when +the command is complete and the window has focus. + .SH OTHER You must have Python 2.2 or later installed as well as Tkinter @@ -564,11 +638,21 @@ interesting and entertaining error messages. The program could be more gracious about this. +The configuration file parser does no validation of key binding +override values. It is entirely possible to bind a \'twander\' +feature to a bogus key definition. This will cause either a +spectacular prgram failure or, at the very least, that feature will +not work correctly or at all. The assumption here is that if you are +smart enough to want to change key bindings, you're smart enough to +learn how Tkinter names keys. You have been warned. + 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\' +Installation of \'twander\' is fairly simple. + .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