diff --git a/twander.1 b/twander.1 index 46eb218..e441234 100644 --- a/twander.1 +++ b/twander.1 @@ -158,7 +158,7 @@ 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. +.B CHANGING KEYBOARD BINDINGS. .SS GENERAL PROGRAM COMMANDS @@ -480,7 +480,7 @@ initiated from the keyboard while running \'twander\'. -.SH CHANGING KEYBOARD BINDINGS VIA THE CONFIGURATION FILE +.SH CHANGING KEYBOARD BINDINGS No program that runs in many operating environments can satisfy everyone's (anyone's!) idea of what the "correct" key bindings @@ -499,51 +499,70 @@ 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: +Keyboard binding assignments look just like local variable definitions +in the configuration file. (The \'twander\' configuration file parser +automatically distinguishes between key binding statements and user +variable definitions. 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: .nf -PROGRAM-FUNCTION-NAME = KEYSTROKE +PROGRAM-FUNCTION-NAME = TKINTER-KEYSTROKE-NAME .fi Changing the default bindings is therefore nothing more than a matter -of assigning the appropriate program function name (found in +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: +to the desired keystroke. -.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. +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 +uncomment the relevant line and change the right side of the +assignment to the new key you'd like to use. More detailed +instructions on what to do are found in the example ".twander" file +itself. -.IP +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. -So, this is correct: - .nf -QUITPROG = +So, this is correct: QUITPROG = + +But, this is not: QUITPROG = '' .fi -But, this is not correct: +.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, \'twander\' will never even +recognize such an attempt. For example, suppose you try to do this: .nf -QUITPROG = '' +QUITPROG = something-or-other .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. +Because you want to be able to reference [QUITPROG] in a subsequent +command definition. \'twander\' 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. -.IP +.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 \'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 @@ -618,7 +637,6 @@ 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 support installed for that release. In the case of Win32, Tkinter @@ -667,11 +685,14 @@ If you've installed \'twander\' 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. +taste. + +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 "wander.py" file to a directory somewhere on your path. +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 @@ -681,42 +702,47 @@ .SS Installing Manually On A Win32 System -Copy the "twander.py" file to a directory somewhere on your path. or +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. -Where to copy the ".twander" configuration file is an interesting -question on Win32. Microsoft operating systems normally do not set +On Win32, where to put the ".twander" 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 systemwide environment -variable called HOME yourself, which points to your desired home -directory, or you can invoke \'twander\' with the -c argument -to explictly declare where it can find its configuration file. +"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 \'twander\' with the -c argument to +explictly declare where it can find its configuration file. You can run the program several ways on Win32 systems: -.IP -Create a Win32 shortcut which points to the "twander.py" file -using the "pythonw" command to invoke it. This suppresses -the creation of a blank invocation window. For example, -you might have something like this in the "Target:" field -of your shortcut: +.IP \(bu 4 +Create a Win32 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: .nf -"C:\\Program Files\\Python\\pythonw.exe" C:\\twander.py / +"C:\\Program Files\\Python22\\pythonw.exe" C:\\twander.py / .fi -.IP +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 +.IP \(bu 4 Use Windows Explorer (or better still, an already running instance of \'twander\'!) 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 all should run just fine. +and all should start automatically. .SH DESIGN PHILOSOPHY