"Fossies" - the Fresh Open Source Software Archive 
Member "twander-3.231/twander.txt" (1 Jul 2009, 219015 Bytes) of package /linux/privat/old/twander-3.231.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 twander(1) twander(1)
2
3
4
5 NAME
6 twander - File Browser
7
8
9
10 OVERVIEW
11 Wander around a filesystem executing commands of your choice on
12 selected files and directories. The general idea here is that twander
13 provides GUI facilities for navigating around your filesystem, but you
14 define the commands you want available via "Command Definitions" (in
15 the Configuration File). In other words, twander can't do anything
16 useful until you've defined some commands. This document describes
17 how to install and start twander as well as it's various startup
18 options.
19
20 This document also describes the format and content of a twander Con-
21 figuration File. You will find an example Configuration File called
22 .twander in the distribution tarball. All the entries in that file are
23 commented out, so you'll need to uncomment and edit the ones you want
24 to work with.
25
26 If you're new to twander and want to know why this program is better
27 and different than whatever you're using at the moment, take a moment
28 to read the section called DESIGN PHILOSOPHY toward the end of this
29 document first.
30
31 Similarly, if this is the first time you've worked with twander, there
32 is a section near the end of this document entitled INSTALLING twander
33 which describes how the program should be installed.
34
35 You can get the latest version of the program and documentation from
36 the twander homepage:
37
38 http://www.tundraware.com/Software/twander/
39
40
41 You should check this site periodically for program updates, bug fixes,
42 and enhancements.
43
44 Also, you are strongly encouraged to join the twander mailing list
45 where you'll find help and answers to questions you have about this
46 program. Details of how to do this can be found toward the end of this
47 document in the section entitled, GETTING HELP: THE twander MAILING
48 LIST.
49
50
51
52 SYNOPSIS
53 twander [-cdhqrtv] [startdir]
54
55
56
57 OPTIONS
58 startdir
59 Directory in which to begin. (default: directory in which pro-
60 gram was started)
61
62 If this directory does not exist or cannot be opened, twander
63 will display an error message and abort.
64
65
66 -c path/name of Configuration File
67 Specify the location and name of the configuration file.
68 (default is ~/.twander)
69
70 If this file does not exist or cannot be opened, twander will
71 display a warning to that effect but continue to run. This is
72 reasonable behavior because twander provides a command to reload
73 the Configuration File without exiting the program (which you
74 would presumably do after fixing the Configuration File prob-
75 lem).
76
77
78 -d debuglevel
79 Start in debug mode dumping the items specified in the debu-
80 glevel. (default: debuglevel=0/debug off)
81
82 twander is able to selectively dump debugging information to
83 stdout. 'debuglevel' is understood to be a bitfield in which
84 each bit specifies some kind of debugging information or behav-
85 ior. 'debuglevel' can be specified in either decimal or hex
86 (using the form 0x#) formats. The bits in the bitfield are
87 defined as follows:
88
89 Bit Hex Value Meaning
90 --- --------- -------
91
92 0 0x001 Dump Internal Options & User-Settable Options
93 1 0x002 Dump User-Defined Variables
94 2 0x004 Dump Command Definitions
95 3 0x008 Dump Key Bindings
96 4 0x010 Display, Do Not Execute, Commands When Invoked
97 5 0x020 Dump Directory Stack As It Changes
98 6 0x040 Dump Command History Stack After Command Executes
99 7 0x080 Dump Contents Of Program Memories As They Change
100 8 0x100 Dump Contents Of Filter/Selection Wildcard Lists As They Change (0x100)
101 9 0x200 Dump Associations Table
102 10 0x400 Reserved/Unused
103 11 0x800 Dump Requested Debug Information And Exit Immediately
104
105 These bits can be combined to provided very specific debugging
106 information. For example, '-d 0x80f' will dump (to stdout) all
107 the Internal Options, User-Settable Options, User-Defined
108 Options, Command Definitions, and Key Bindings and then termi-
109 nate the program.
110
111
112 -h Print help information on stdout.
113
114
115 -q Quiet mode - suppresses warnings. (default: warnings on)
116
117
118 -r Turn off automatic refreshing of directory display. (default:
119 refresh on)
120
121 Normally twander re-reads and displays the current directory
122 every few seconds to reflect any changes that might have
123 occurred to that directory's contents. This option is useful on
124 slow machines (or slow X connections) and/or when working with
125 very large directories. In this situation, the frequent updat-
126 ing of the twander display can make the program unacceptably
127 slow and unresponsive. In this case you can still force an
128 update manually with the REFRESH function (default assignment is
129 to the Control-l key).
130
131
132 -t Turn off quoting when substituting built-in variables. (default:
133 quoting on)
134
135 Anytime twander encounters a reference to one of the built-in
136 variables which do string replacement (DIR, DSELECTION, DSELEC-
137 TIONS, MEM1-12, PROMPT:, SELECTION, SELECTIONS) in a command, it
138 will replace them with double quoted strings. This is necessary
139 because any of these can return values which have embedded spa-
140 ces in them. By quoting them, they can be passed to a command
141 or script as a single item. The -t option disables this behav-
142 ior and replaces the built-in variable with unquoted literals.
143
144
145 -v Print detailed version information.
146
147
148
149 OTHER WAYS TO SET twander OPTIONS
150 In addition to these command line options, there are two other ways you
151 can set twander program features. If you prefer, you can set the com-
152 mand line options via the environment variable, TWANDER. That way you
153 don't have to type them in each time you start the program. Say you
154 set the environment variable this way on Unix:
155
156 export TWANDER=-qt
157
158 From then on, every time you run the program, the -q and -t options
159 would be invoked (No Quoting, No Warnings) just as if you had typed
160 them in on the command line.
161
162 The second way to set these (and MANY more) Program Options is by set-
163 ting the appropriate entries in the Configuration File. This is cov-
164 ered later in this document.
165
166 twander evaluates options in the following order (from first to last):
167
168
169 o Internally set default value of options
170
171
172 o Options set in the Configuration File
173
174
175 o Options set in the TWANDER environment variable
176
177
178 o Options set on the command line
179
180
181
182 This means, for example, that the environment variable overrides a cor-
183 responding setting in the Configuration File, but the command line
184 overrides the environment variable. Furthermore, there are many Pro-
185 gram Options which can only be set/changed the Configuration File and
186 are not available in either the environment variable or on the command
187 line.
188
189 This also means that options set on the command line are not read until
190 after the Configuration File has been processed. So, the -q argument
191 on the command line will not inhibit warnings generated during the
192 reading of the Configuration File. This is best done by adding the
193 statement, WARN=False, at the top of the Configuration File.
194
195 If the Configuration File is reloaded while the program is running (see
196 the READCONF key below), any options set in the file will have the last
197 word. This allows you to edit the Configuration File and have your
198 changes reflected in a running instance of twander, but it also means
199 that the environment variable/command line arguments are ignored after
200 initial program startup.
201
202
203
204 THE TITLE BAR
205 twander displays a lot of information about the state of the running
206 program in the main window title bar. From left to right you will see:
207
208
209 o Program name and version number.
210
211
212 o Login name and machine/domain of current user.
213
214
215 o The path of the directory you are currently viewing. If this path
216 length is greater than 60 characters, twander will show the last 60
217 characters of the path length, prepended with "..." to show that it
218 is truncated.
219
220 Directories relative to your home directory will have the home
221 directory string replaced with "~" (a common Unix shorthand for
222 "home directory" in order to save title bar space.
223
224
225
226 o The status of various symbolic link processing options. See the
227 program options, SYMDIR, SYMEXPAND, and SYMRESOLV for a more com-
228 plete explanation.
229
230
231 o Any "filter" that is limiting which files you see. If you've tog-
232 gled the filter, you will see the word "NOT" before the filter
233 string.
234
235
236 o An indication of whether or not "dotfiles" are currently hidden.
237
238
239 o The total number of files in this directory. The ".." entry is not
240 included in this count.
241
242
243 o The total size of all the files in this directory. The size of the
244 ".." directory is not included in this total.
245
246
247 o They key used to sort the display. If a reverse sort is selected,
248 you will see "-" appended to the end of the key to indicated this.
249 "Sort By: NAME-" means you are doing a reverse sort by name.
250
251
252 o An indication of whether or not directories and ordinary files are
253 being separated in the display.
254
255
256 o An indication of whether or not automatic refreshing is enabled.
257 Anytime refreshing is actually underway, whether automatic, manual,
258 because you are executing a command that forces a refresh, or just
259 because you changed directories, you will see the '*' character
260 appended to this field. Ordinarily, this happens so quickly you
261 will not see it. However, on really large directories and/or very
262 slow disks like CDROMs, you'll see the asterisk stay on for some
263 time. During refresh, the program is locked from user input. On
264 very long refreshes, it can appear to be "hung". This indicator is
265 there just to let you know the program is busy refreshing and all
266 is well.
267
268
269 KEYBOARD USE
270 By design, twander allows you to do almost everything of interest using
271 only the keyboard. Various twander features are thus associated with
272 particular keystrokes which are described below. It is also very sim-
273 ple to change the default key assignments with entries in the Configu-
274 ration File, also described below.
275
276
277
278 NOTES ON KEYBOARD ARROW/KEYPAD BEHAVIOR AND TEXT DIALOG EDITS
279 Generally, the arrow and keypad keys should do what you would expect on
280 the system in question. On Windows systems, particularly, there ought
281 to be no odd arrow/keypad behavior.
282
283 X-Windows is somewhat more problematic in this area. Just what an
284 arrow key is "supposed" to do depends on how it's been mapped in your X
285 server software. Testing twander on various X servers showed quite a
286 bit of variability in how they handled the arrows and keypad. So ...
287 if you're running in an X Windows universe and arrows or keypad do
288 nothing, or do strange things, look into your key maps, don't blame
289 twander.
290
291 There are several features of twander that will present the user a text
292 entry dialog. These include the CHANGEDIR and RUNCMD features as well
293 as the {PROMPT:...} Built-In Variable (all described below).
294
295 Any time you are entering text in such a dialog, be aware that the text
296 can be edited several ways - You can edit it using the arrow/keypad
297 editing assignments which are enabled/normal for your operating system,
298 OR you can use emacs-style commands to edit the text. For instance,
299 Control-a, Control-k will erase the text currently entered in the dia-
300 log.
301
302
303
304 DEFAULT KEYBOARD AND MOUSE BINDINGS
305 Here, ordered by category, are the default keyboard and mouse bindings
306 for twander. The general format is:
307
308
309 Description (Program Function Name)
310 Default Key Assignment
311
312 Default Mouse Assignment (if any)
313
314
315 The "Program Function Name" is the internal variable twander uses to
316 associate a particular feature with a particular keystroke or mouse
317 action. You can ignore it unless you intend to override the default
318 key assignments. This use is described below in the section entitled,
319 Key Binding Statements.
320
321 It is important to realize that twander key-bindings are case-sensi-
322 tive. This means that 'Control-b' and 'Control-B' are different. This
323 was a conscious design decision because it effectively doubles the num-
324 ber of Control/Alt key combinations available for the addition of
325 future features.
326
327 The default bindings chosen for twander features are all currently
328 lower-case. If your program suddenly stops responding to keyboard com-
329 mands, check to make sure you don't have CapsLock turned on.
330
331 NOTE: Some twander features are doubled on the mouse. These mouse but-
332 ton assignments are documented below for the sake of completeness.
333 However, mouse button assignments cannot be changed by the user, even
334 in the Configuration File.
335
336
337 General Program Commands
338 This family of commands controls the operation of twander itself.
339
340
341 Clear History (CLRHIST)
342 Control-y
343
344 Clears out various program histories including the All Visited
345 Directories list, the Directory Stack, the Command History, and
346 the last manually-entered values for CHANGEDIR and RUNCMD. The
347 12 Program Memories are not cleared - they have specially dedi-
348 cated key bindings for this purpose.
349
350
351 Decrement Font Size (FONTDECR)
352 Control-[
353
354 Decrease font size.
355
356
357 Increment Font Size (FONTINCR)
358 Control-]
359
360 Increase font size.
361
362 These two features allow you to change the display font sizes
363 while twander is running. But, you may not immediately get the
364 results you expect. twander internally keeps track of separate
365 font sizes for the main display, the main menu text, and the
366 help menu text. When you use the two font sizing commands
367 above, twander subtracts or adds 1 to each of these three values
368 respectively. On systems like Windows using TrueType fonts,
369 this works as you would expect, because every font is effec-
370 tively available in every size. However, in systems like X-Win-
371 dows or Windows using fixed-size fonts, you may have to press
372 these keys repeatedly until twander finds a font matching the
373 requested size.
374
375 This can also cause some parts of the display to change but not
376 others. Suppose you are running on X-Windows and have specified
377 that the main display is to use a 12 point font, and that menus
378 and help should use 10 point font. Let's also suppose that the
379 next font available larger than 12 point is 16 point. If you
380 press FONTINCR twice, both the menu text and help text will jump
381 to 12 point, but the main display text will remain unchanged.
382 Why? Because pressing FONTINCR twice tells twander to set the
383 main display to 14 point (12+1+1) which does not exist, and the
384 menu and help text to 12 point (10+1+1) which does exist, so
385 that change is visible.
386
387 The "User-Settable Options" Help Menu displays the font metrics
388 (name, size, weight) you've currently specified. Pressing FONT-
389 DECR/FONTINCR changes the size specification and this will be
390 reflected in that menu. However, most systems do some form of
391 "best match" font substitution - if you ask for a font that does
392 not exist, the system will use the "closest matching" font as a
393 substitute. This means the font you see specified in the Help
394 Menu is not necessarily the font you're actually using. You're
395 more likely to run into this when running on a Unix/X-Windows
396 system (where not all the fonts are available in all
397 sizes/weights like they are on Windows TrueType) as you change
398 the font size with FONTDECR/FONTINCR.
399
400 Reloading the Configuration File (READCONF) will reset the fonts
401 to either their default values or any font sizes specified in
402 the Configuration File.
403
404
405 Display Command Menu (MOUSECTX)
406 Right-Mouse-Button
407
408 Displays a list of all available commands in a pop-up menu near
409 the mouse pointer. If no commands are defined, this feature
410 does nothing at all. This means commands can be invoked one of
411 three ways: Directly via the Command Key defined in the Configu-
412 ration File, via selection in the Command Menu at the top of the
413 GUI, or via selection from the Command Menu.
414
415 Windows users should note that, unlike Windows Explorer, the
416 twander Command Menu does not change the set of currently
417 selected items. It merely provides a list of available com-
418 mands. This allows the command chosen via the Command Menu to
419 operate on a previously selected set of items.
420
421
422 Display Directory Menu (MOUSEDIR)
423 Shift-Right-Mouse-Button
424
425 Displays a list of all the directories visited so far in a pop-
426 up menu near the mouse. This means that you can navigate to a
427 previously visited directory in one of two ways: Via a selection
428 in the Directory Menu at the top of the GUI or via a selection
429 from this pop-up menu.
430
431
432 Display History Menu (MOUSEHIST)
433 Control-Shift-Right-Mouse-Button
434
435 Displays a list of all commands executed so far (including those
436 entered manually) in a pop-up menu near the mouse pointer. If
437 the Command History is empty, this command does nothing. This
438 means you can repeat a previously entered command via the His-
439 tory Menu or this mouse command. (You can also repeat the last
440 manually entered command by pressing RUNCMD - it will preload
441 its text entry area with the last command you entered by hand.)
442
443
444 Display Shortcut Menu (MOUSESC)
445 Alt-Control-Left-Mouse-Button
446
447 Displays a list of all user-defined directory shortcuts in a
448 pop-up menu near the mouse. The menu also has "canned" naviga-
449 tion shortcuts to go up a directory, back a directory, to the
450 home directory, to the starting directory, and to the root
451 directory. On Windows systems with the Win32All extensions,
452 there is also a shortcut to the Drive List View.
453
454
455 Display Sorting Menu (MOUSESORT)
456 Alt-Shift-Right-Mouse-Button
457
458 (Note that on Windows you must press Alt then Shift then the
459 Right-Mouse-Button for this to work. Windows appears to care
460 deeply about keystroke order.)
461
462 Displays a list of all the sorting options in a pop-up menu near
463 the mouse.
464
465
466 Quit Program (QUITPROG)
467 Control-q
468
469 Exit the program.
470
471
472 Re-Read Configuration File (READCONF)
473 Control-r
474
475 Re-read the Configuration File. This allows you to edit the
476 Configuration File while twander is running and then read your
477 changes in without having to exit the program. This is handy
478 when editing or changing Command Definitions.
479
480
481 Program Options are set back to their default each time a Con-
482 figuration File is about to be read (initially or on reload)
483 just before the Configuration File is parsed. This means com-
484 menting out or removing a Program Option Statement (see relevant
485 section below) in the Configuration File and then pressing READ-
486 CONF causes that option to be reset to its default value.
487 STARTDIR defaults to either its internal default ($HOME or ./)
488 or to the value given in the Environment Variable/Command line.
489
490
491 Refresh Display (REFRESH)
492 Control-l
493
494 Re-read the current directory's contents and display it. This
495 is most useful if you have turned off automatic directory
496 refreshing with either the -r command line flag or setting the
497 AUTOREFRESH Program Option to False.
498
499
500 Toggle Autorefreshing (TOGAUTO)
501 Control-o
502
503 Toggle Autorefreshing on- and off. This is handy if you are
504 about to enter a very large directory and/or a very slow disk
505 (like a CDROM). With very large or slow directory reads, twan-
506 der can end up spending all its time doing re-reads of the
507 directory and never give you time to do anything there. If you
508 find this is consistently the case, then you need to increase
509 REFRESHINT. But for the occasional adventure into very
510 large/slow directories, just toggling Autorefresh off is more
511 convenient.
512
513 The state of the Autorefresh feature is displayed on the main
514 window title bar.
515
516
517 Toggle Details (TOGDETAIL)
518 Control-t
519
520 Toggle between detailed and filename-only views of the direc-
521 tory.
522
523
524 Toggle Between Normalized And Actual File Length Display (TOGLENGTH)
525 Control-0
526
527 By default, the program "normalizes" file sizes and expresses
528 them in bytes, Kilobytes, Megabytes, or Gigabytes rather than
529 showing their actual size. This is done everywhere a file size
530 is displayed: on individual files, the total files size dis-
531 played on the title bar, and the drive sizes in Win32 Drive List
532 View. This key binding invokes a feature that toggles these
533 size displays between normalized and actual. See the ACTUAL-
534 LENGTH configuration option below to set the default as you pre-
535 fer it.
536
537
538 Toggle Sorting Of Symbolic Link Directories (TOGSYMDIR)
539 Control-~
540
541 Toggles whether symbolic links pointing to directories should be
542 sorted as directories or as files. This changes the state of
543 the SYMDIR program option (default: True) and updates the title
544 bar "Symlinks:" status field. This is only meaningful if you've
545 selected "separated" sorting (SORTSEP) to cluster directories
546 and then files together in the display.
547
548
549 Toggle The Display Of Symbolic Link Targets (TOGSYMEXPAND)
550 Control-!
551
552 Toggles whether or not to display the targets of symbolic links
553 or to just display the link name by itself. This changes the
554 state of the SYMEXPAND program option (default: True) and
555 updates the title bar "Symlinks:" status field.
556
557
558 Toggle The Display Of Absolute Symbolic Link Targets(TOGSYMRESOLV)
559 Control-@
560
561 Toggles whether the targets of symbolic links should be dis-
562 played as defined or in absolute path format. This changes the
563 state of the SYMRESOLV program option (default: False) and
564 updates the title bar "Symlinks:" status field. Pressing this
565 key implies you want to see symbolic link targets (either as
566 defined or as "resolved" absolute paths) so this keypress also
567 forces SYMEXPAND to True.
568
569
570 Toggle 'win32all' Features (TOGWIN32ALL)
571 Control-w
572
573 As described later in this document, twander provides enhanced
574 features for Windows users who also install Mark Hammond's
575 'win32all' extensions for Python on Windows. This key binding
576 will toggle those advanced features on- and off. This is useful
577 if you happen to be examining a very large directory. The
578 'win32all' features, while handy, can be computationally expen-
579 sive and make updates of a directory with many entries somewhat
580 slow. This toggle is provided as a means to temporarily disable
581 the advanced features when viewing such a directory.
582
583
584 Directory Navigation
585 This family of commands controls movement between directories. If you
586 attempt to navigate into a directory that does not exist or which does
587 not have appropriate permissions, twander will display a warning mes-
588 sage and remain in the current directory. This is unlike the case of a
589 non-existent or unreadable directory specified when the program is
590 first started. In that case, twander reports the error and aborts.
591
592
593 Change Directory (CHANGEDIR)
594 Control-x
595
596 This is a shortcut that allows you to directly move to a new
597 directory/path - i.e., Without having to navigate to it.
598
599 Unless you have set the MAXMENU option to 0, CHANGEDIR keeps
600 track of your last manually entered directory and presents it as
601 a default when you press CHANGEDIR again. You can then move to
602 that directory, edit the string to specify another directory, or
603 delete it and enter an entirely new directory. Directories can
604 be edited with either the arrow and keypad keys defined on your
605 system or by emacs editing commands like Control-a, Control-k,
606 Control-e, and so forth.
607
608
609 Go To Home Directory (DIRHOME)
610 Control-h
611
612 If the "HOME" environment variable is defined on your system,
613 this will move you to that directory. If the "HOME" environment
614 variable is not defined, this command will move to the original
615 starting directory.
616
617
618 Go Back One Directory (DIRBACK and MOUSEBACK)
619 Control-b
620
621 Control-DoubleClick-Left-Mouse-Button
622
623 twander keeps track of every directory visited and the order in
624 which they are visited. This command allows you to move back
625 successively until you get to the directory in which you
626 started. This feature is implemented as a stack - each "backing
627 up" removes the directory name from the visited list. The
628 "Directory" menu (see MENU OPTIONS below) implements a similar
629 feature in a different way and keeps track of all directories
630 visited regardless of order.
631
632
633 Go To Root Directory (DIRROOT)
634 Control-j
635
636 Go to the root directory.
637
638
639 Go To Starting Directory (DIRSTART)
640 Control-s
641
642 Go back to the original directory in which twander was started.
643
644
645 Go Up To Parent Directory (DIRUP and MOUSEUP)
646 Control-u
647
648 Control-DoubleClick-Right-Mouse-Button
649
650 Move to the parent of the current directory ("..").
651
652
653 Display Drive List View (DRIVELIST)
654 Control-k
655
656 This is a Windows-only feature which displays a list of all
657 available disk drives. Details about each drive are also dis-
658 played if you have details enabled. In order for this feature
659 to work, you must be running on Windows AND have the 'win32all'
660 package installed, AND the USEWIN32ALL Program Option must be
661 True (default condition,) AND you must not have toggled these
662 features off with the TOGWIN32ALL key described above. For more
663 details about Drive List View, see the section below entitled,
664 ADVANCED WINDOWS FEATURES.
665
666
667 Selection Keys
668 This family of commands controls the selection of one or more (or no)
669 items in the current directory.
670
671
672 Select All Items (SELALL)
673 Control-Comma
674
675 Select every item in the current directory. The ".." entry at
676 the top of the directory listing is not included. (We almost
677 never want to include the parent directory when issuing a com-
678 mand on "everything in this directory". If you do wish to
679 include the "..", do the SELALL command first, then click on
680 ".." while holding down the Control key.)
681
682
683 Invert Current Selection (SELINV)
684 Control-i
685
686 Unselects everything which was selected and selects everything
687 which was not. As with SELALL, and for the same reason, the
688 ".." entry is never selected on an inversion.
689
690
691
692 Unselect All Items (SELNONE)
693 Control-Period
694
695 Unselect everything in the current directory.
696
697
698 Select Next Item (SELNEXT)
699 Control-n
700
701 Select next item down in the directory.
702
703
704 Select Previous Item (SELPREV)
705 Control-p
706
707 Select previous item up in the directory.
708
709
710 Select Last Item (SELEND)
711 Control-e
712
713 Select last item in the directory.
714
715
716 Select First Item (SELTOP)
717 Control-a
718
719 Select first item in the directory. This will always be the
720 ".." entry, but it is a quick way to get to the first part of a
721 very long directory listing which does not all fit on-screen.
722
723
724 Mouse-Based Selections
725
726 The mouse can also be used to select one or more items. A sin-
727 gle-click of the left mouse button selects a particular item.
728 Clicking and dragging selects an adjacent group of items.
729 Clicking an item and then clicking a second item while holding
730 down the "Shift" key also selects an adjacent group of items.
731 Finally, a group of non-adjacent items can also be selected.
732 The first item is selected with a single left mouse button click
733 as usual. Each subsequent (non-adjacent) item is then selected
734 by holding down the "Control" key when clicking on the item.
735
736
737
738 Scrolling Commands
739 If a given directory's contents cannot be displayed on a single screen,
740 twander supports both vertical and horizontal scrolling via scrollbars.
741 This capability is doubled on the keyboard with:
742
743
744 Scroll Page Down (PGDN)
745 Control-v
746
747 Scroll down one page in the directory listing.
748
749
750 Scroll Page Up (PGUP)
751 Control-c
752
753 Scroll up one page in the directory listing.
754
755
756 Scroll Page Right (PGRT)
757 Control-g
758
759 Scroll to the right one page width.
760
761
762 Scroll Page Left (PGLFT)
763 Control-f
764
765 Scroll to the left one page width.
766
767
768 Command Execution Options
769 This family of commands causes twander to actually attempt to execute
770 some command you've chosen:
771
772
773 Run Arbitrary Command (RUNCMD)
774 Control-z
775
776 This is a shortcut that allows you to run any command you'd like
777 without having to define it ahead of time in the Configuration
778 File. It is more-or-less like having a miniature command line
779 environment at your disposal.
780
781 You may enter a number of different things in the RUNCMD dialog.
782 You may type literal text or refer to any of the variable types
783 (User-Defined, Environment, or Built-In) supported by twander
784 just as you do in writing Command Definitions (see below). This
785 makes it easy to enter complex commands without having to type
786 everything literally. For example, if you would like to copy
787 all the currently selected files to a new directory, press
788 RUNCMD and enter (on Unix):
789
790 cp [SELECTIONS] newdir
791
792 twander understands the variable reference syntax here just as
793 it does in a Command Definition. This also gives you a single
794 way of referring to environment variables, regardless of OS
795 platform. Recall that in Unix-like shells, an environment vari-
796 able is in the form "$NAME", but on Windows it is in the form
797 "%NAME%". Instead if having to keep track of this difference,
798 you can just use a twander Environment Variable reference. For
799 instance, assuming the EDITOR environment variable is set, this
800 command works the same on both systems:
801
802 [$EDITOR] [SELECTIONS]
803
804
805 Built-in variables are most often used when manually entering
806 commands So, RUNCMD also understands some "shortcut" references
807 to many of the built-ins. You may use:
808
809 [D] for [DIR]
810 [DN] for [DSELECTION]
811 [DS] for [DSELECTIONS]
812 [SN] for [SELECTION]
813 [SS] for [SELECTIONS]
814 [1] for [MEM1]
815 [2] for [MEM2]
816 [3] for [MEM3]
817 [4] for [MEM4]
818 [5] for [MEM5]
819 [6] for [MEM6]
820 [7] for [MEM7]
821 [8] for [MEM8]
822 [9] for [MEM9]
823 [10] for [MEM10]
824 [11] for [MEM11]
825 [12] for [MEM12]
826
827 Of course, the full form is also fine as well.
828
829 This shortcut feature is only supported in RUNCMD!!! Configura-
830 tion File entries must use the full form of all built-in vari-
831 ables. This is a conscious design decision to help enforce some
832 consistency and clarity in the Configuration Files.
833
834
835 Unless you have set the MAXMENU option to 0, RUNCMD keeps track
836 of your last manually entered command and presents it as a
837 default when you press RUNCMD again. You can then run the com-
838 mand again exactly as you last entered it, you can modify it
839 before running the command again, or you can delete it and enter
840 an entirely new command. Commands can be edited with either the
841 arrow and keypad keys defined on your system or by emacs editing
842 commands like Control-a, Control-k, Control-e, and so forth.
843
844 Also see the section below entitled, Program Option Statements,
845 to understand the CMDSHELL option. This option greatly simpli-
846 fies running command-line programs from RUNCMD so their output
847 can been seen in a GUI window. This is particularly handy on
848 Unix.
849
850 As with command definitions in a Configuration File, you can
851 tell twander to force a display refresh after the command has
852 been initiated. You do this by beginning the command with the
853 '+' symbol. So, for example, if you enter,
854
855 +mycommand
856
857 twander will initiate the command, wait AFTERWAIT seconds
858 (default: 1), and then update the display. See the discussion
859 below entitled, Forcing Display Updates In Command Definitions
860 for a more complete explanation.
861
862 This feature may be used in combination with CMDSHELL escaping
863 (also described in the Program Option Statements section below)
864 and the two characters may appear in any order at the beginning
865 of the command line you enter.
866
867
868
869 Run Selected File / Move To Selected Directory (SELKEY and MOUSESEL)
870 Return (Enter Key)
871
872 DoubleClick-Left-Mouse-Button
873
874 If the selected item is a Directory, twander will move into that
875 directory when this command is issued. If the selected item is
876 a file, twander will attempt to execute it. Whether or not the
877 file is actually executed depends on how the underlying operat-
878 ing system views that file.
879
880 In the case of Unix-like operating systems, the execute permis-
881 sion must be set for the user running twander (or their group)
882 for the file to be executed.
883
884 On Windows, the file will be executed if the user has permission
885 to do so and that file is either executable or there is a Win-
886 dows association defined for that file type. For example, dou-
887 ble-clicking on a file ending with ".txt" will cause the file to
888 be opened with the 'notepad' program (unless the association for
889 ".txt" has been changed).
890
891 If twander determines that it is running on neither a Unix-like
892 or Windows system, double-clicking on a file does nothing.
893
894
895 Run User-Defined Command
896 User-Defined (Single Letter) Key
897
898 Each command defined in the Configuration File has a Command Key
899 associated with it. Pressing that key will cause the associated
900 command to be run. If no command is associated with a given
901 keystroke, nothing will happen when it is pressed.
902
903
904 Directory Shortcuts
905 twander provides a way to directly navigate into a frequently-used
906 directory using a single keystroke. You can define up to 12 such
907 "Directory Shortcuts" in the Configuration File. Each of the defini-
908 tions is associated with one of the following 12 keys:
909
910
911 Navigate Directly To A Directory (KDIRSC1 ... KDIRSC12)
912 F1 ... F12
913
914 Pressing one of these keys changes to the directory associated
915 with it in the Configuration File. For more information on this
916 topic, see the discussion of the Configuration File below enti-
917 tled, Directory Shortcut Statements
918
919
920 Assign Current Directory To One Of The Shortcut Keys (KDIRSCSET)
921 Control-8
922
923 As discussed in Directory Shortcut Statements , the directory
924 shortcut keys are associated with particular directories in the
925 twander Configuration File. However, it is possible to tempo-
926 rarily assign them to something else while the program is run-
927 ning. This is handy if you need to temporarily "remember" one
928 or more directories so you can jump back to them with a single
929 keystroke. Think of it as a way to "override" the directory
930 shortcut assignments defined in the Configuration File.
931
932 To do this, press the KDIRSCSET key (Default: Control-8). You
933 will be presented with a dialog that asks you to specify which
934 Directory Shortcut you want overwritten with the current direc-
935 tory. You may only enter a number from 1 to 12. You will see
936 an error message if you try to enter anything else.
937
938 Any such reassociation of a directory shortcut is temporary.
939 Directory shortcuts are set back to the values specified in the
940 Configuration File if you restart the program or reload the Con-
941 figuration File (Default: Control-r).
942
943
944
945 Program Memories
946 If you've used GUIs before, you're probably familiar with the idea of a
947 program "Clipboard" - a temporary holding area which is used when cut-
948 ting, copying, and pasting files. This is a good idea, but has several
949 limitations. First, most systems only have a single clipboard. It
950 would be mighty handy to have muliple Clipboard-like storage areas for
951 keeping track of several different operations at once. Secondly, when
952 you copy or paste something to a conventional Clipboard, its old con-
953 tents get overwritten. There is no way to keep appending items to the
954 Clipboard. Finally, items usually can only be cut or copied to the
955 Clipboard from the current directory. It would be nice if we could not
956 only keep adding things to the Clipboard, but be able to do so as we
957 navigate around the filesystem.
958
959 twander addresses these concerns by means of 12 separate "Program Memo-
960 ries". As you use twander, you can add (append) the names of any
961 directories or files in the currently viewed directory by selecting
962 them and then using the appropriate twander MEMSETx key (see below).
963 To take advantage of this feature, you write Command Definitions (or
964 manually issue a command via the RUNCMD key) which reference the con-
965 tents of a Program Memory using one of the [MEMx] Built-In Variables.
966 (See the section below on entitled, Program Memory Built-Ins for more
967 details in how to apply Program Memories).
968
969 twander provides key combinations for selectively setting and clearing
970 particular Program Memories as well as a key combination for clearing
971 all Program Memories in a single keystroke:
972
973
974 Clear Selected Program Memory (MEMCLR1 - MEMCLR12)
975 Control-F1 ... Control-F12
976
977 Clear (empty) the selected Program Memory.
978
979
980 Clear All Program Memories (MEMCLRALL)
981 Control-m
982
983 Clear (empty) all 12 Program Memories at once.
984
985
986 Set Selected Program Memory (MEMSET1 - MEMSET12)
987 Alt-F1 ... Alt-F12
988
989 Append the the full path names of the currently selected files
990 and directories to the Program Memory desired.
991
992
993 Sorting Options
994 twander provides a variety of ways to sort the display. These can be
995 selected with either a keystroke or from the Sorting Menu (see below).
996 The meaning of the sort depends on whether or not you are in Drive List
997 View (see ADVANCED WINDOWS FEATURES below). The table below summarizes
998 the keys associated with sorting and their meaning in the two possible
999 views:
1000
1001 Program
1002 Function Sort Order In Sort Order In
1003 Key Name Normal View Drive List View
1004 --- -------- ------------ ---------------
1005
1006 Shift-F10 SORTBYNONE No Sort No Sort
1007 Shift-F1 SORTBYPERMS Permissions Label/Share String
1008 Shift-F2 SORTBYLINKS Links Drive Type
1009 Shift-F3 SORTBYOWNER Owner Free Space
1010 Shift-F4 SORTBYGROUP Group Total Space
1011 Shift-F5 SORTBYLENGTH Length Drive Letter
1012 Shift-F6 SORTBYTIME Time Ignored
1013 Shift-F7 SORTBYNAME Name Ignored
1014 Shift-F11 SORTREV Reverse Order Reverse Order
1015 Shift-F12 SORTSEP Separate Dirs Ignored
1016
1017 An easy way to remember these is that the function key number for the
1018 primary sort keys corresponds to the column position of the key in a
1019 detailed display. For instance, Shift-F1 sorts by column 1, Shift-F2
1020 by column 2, and so forth.
1021
1022 These sorting options are available whether or not details are cur-
1023 rently available. For example, you can toggle details off, but still
1024 sort by one of the now invisible details such as Owner, Length, and so
1025 on.
1026
1027 SORTREV reverses the order of the sort.
1028
1029 SORTSEP toggles whether or not directories and files should be grouped
1030 separately or displayed in absolute sort order. If enabled, directo-
1031 ries will be displayed first, then files. If the sort is reversed via
1032 SORTREV, and SORTSEP is enabled, the directories will appear after the
1033 files, sorted by whatever sort key has been chosen. SORTSEP is not
1034 meaningful in Drive List View and is ignored.
1035
1036 You'll find the currently selected sorting options displayed in the
1037 program title bar.
1038
1039
1040
1041 Wildcard Features
1042 Although twander provides a very rich set of keyboard and mouse selec-
1043 tion commands, selecting a group of files out of list of hundreds or
1044 thousands in a large directory can be tedious. If the files/directo-
1045 ries you want to select have some lexical commonality in their names OR
1046 details you can have twander select them for you using so-called "Regu-
1047 lar Expressions".
1048
1049 You can do this in one of two ways. A wildcard "filter" only displays
1050 files that match the specified regular expression. A wildcard "selec-
1051 tion" selects (highlights) the matching entries from the currently dis-
1052 played list. The general idea is to use filters to limit the number of
1053 files you'll even see in the twander interface and then optionally
1054 choose from among them with a wildcard-based selection.
1055
1056 For example, suppose you initiate a wildcard-based selection (SELWILD)
1057 with the text, tar. This would select every file or directory in the
1058 current display where the string "tar" appeared anywhere on the line
1059 for that file/directory. This is very important: Wildcard matching
1060 takes place anywhere on the visible line. So, if you have details
1061 turned on, the match can occur anywhere on the permissions, links,
1062 group, owner, and so on. Obviously, if you have details turned off,
1063 the match can only occur on the name of the file or directory since
1064 that's all that is visible.
1065
1066 This is a purposeful design decision because it allows you to make
1067 selections on more than just the name. Say you enter the following in
1068 the FILTERWILD dialog:
1069
1070 drwx------
1071
1072 twander would display only the entries that are directories with no
1073 permissions enabled for group or world users.
1074
1075
1076 The matching string above could also filter/select other entries (not
1077 having the permissions just described), if say, this string appeared in
1078 their name ... a rather unlikely scenario, but not impossible. If we
1079 want to get real specific about which entries we want selected, we need
1080 to enter a "regular expression" in the wildcard dialog. Regular
1081 expressions are a far more powerful pattern-matching tool than simple
1082 text strings and will allow you to do some fairly amazing selections.
1083 For example, this regular expression selects all entries which contain
1084 a string beginning with "Ju" followed by any other character, a single
1085 space, and ending in "0":
1086
1087 Ju. 0
1088
1089 So, for instance, this would select files with date details (or names,
1090 or anything else on the line...) like "Jun 01", "Jul 03", and "Jul 09".
1091
1092 No matter what you specify, a literal matching string or a regular
1093 expression, the ".." entry of the currently viewed directory is never
1094 selected for wildcard processing. This is a "special" entry that is
1095 always present regardless of filtering and never selected with wild-
1096 card-based selections.
1097
1098 Notice that these regular expressions are not the same thing as the
1099 filename "globbing" wildcards commonly used with Unix and Windows
1100 shells. If you enter constructs like "*.txt" or "*.tar.gz", you will
1101 not get the results you expect. In fact, these specific examples will
1102 cause twander to grumble and present a warning message.
1103
1104 For an excellent tutorial on Python-compliant regular expressions, see:
1105
1106 http://www.amk.ca/python/howto/regex/
1107
1108 By default, these wildcarding tools will select an entry when your reg-
1109 ular expression matches anything on the displayed line. This allows
1110 you to make selections based on any visible column of information.
1111 This "match anywhere on the line" semantic is possible because twander
1112 automatically massages the regular expression you provide to make "any
1113 match on the line" true. There may be times when you want to provide
1114 very specific regular expression definitions which seek a match at spe-
1115 cific locations. In that case, you can prevent the program from fid-
1116 dling with your regular expression, by beginning it with the double-
1117 quote (") character. twander understands this to mean that your regu-
1118 lar expression is to be treated literally without modification. (It
1119 only throws away this leading escape character.)
1120
1121 Suppose we changed our example above slightly and used this regular
1122 expression:
1123
1124 "^drwx------
1125
1126 Now twander would select only the directories without any group and
1127 world access because:
1128
1129
1130 o The leading double-quote (") forces literal interpretation of the
1131 regular expression - i.e. It turns off "match anywhere" semantics
1132 as just described.
1133
1134
1135 o The carat (^) at the beginning of the actual regular expression
1136 "anchors" the match to the start of the line. For a match to be
1137 declared (and for twander to select an item) the regular expression
1138 must be satisfied at the beginning-of-line.
1139
1140
1141 Because regular expressions can get complicated and tedious to type in,
1142 any such expression you use is saved in a history available via the
1143 Filter and Select Menus (see below). There is also provision for pre-
1144 defining frequently used wildcards in your Configuration File (see sec-
1145 tion below on WILDFILTER= and WILDSELECT= configuration statements) so
1146 you don't have to type them in manually each time you start the program
1147 - you can just select them from the relevant menu.
1148
1149 A few points to keep in mind when using wildcard features:
1150
1151
1152 o By default, wildcard matching is case-insensitive on Win32 systems
1153 and case-sensitive everywhere else. This is because Windows sys-
1154 tems allow case in filenames and attributes, but it is not signifi-
1155 cant - i.e., The case of a filename or attribute is ignored on Win-
1156 dows systems. You can control this explicitly with the WILDNOCASE
1157 configuration option. If you set WILDNOCASE=False, it will force
1158 all wildcard filters and selections to be case-sensistive. Setting
1159 it to True makes the wildcarding case-insensitive. This option is
1160 available for both Unix and Win32 systems so you can set the behav-
1161 ior you like anywhere.
1162
1163
1164 o If you escape a wildcard to force twander to treat it exactly as
1165 you defined it, the case-sensitivity set by default or WILDNOCASE
1166 is ignored. Escaped wildcards are always treated exactly as you
1167 enter them and they are matched against the filename and/or details
1168 exactly as they appear.
1169
1170
1171 o Wildcard-based filters are applied against the entire contents of
1172 the current directory to determine which files match and should be
1173 displayed. But, wildcard-based selections are done against the
1174 currently visible files. This is important if you do a filter and
1175 then a selection wildcard. The first will select which files to
1176 display. The second will select which ones to highlight from the
1177 displayed list.
1178
1179
1180
1181
1182 Display Files Matching A Regular Expression (FILTERWILD)
1183 Control-equal
1184
1185 This will present you with a dialog to enter your regular
1186 expression matching criteria described above. After you enter
1187 it, twander will only display the files that match. The filter
1188 is reset (to no filtering) when you manually referesh the direc-
1189 tory - with REFRESH (default: Control-l - or change directories.
1190
1191
1192 Toggle Active Filter (TOGFILT)
1193 Control-minus
1194
1195 Pressing this once "inverts" any filter currently active. It
1196 means "show me the files that don't match the filtering regular
1197 expression." Pressing it again returns the filter to its normal
1198 meaning. This is handy when you want to display everything
1199 except a group of files. You first filter for the files you
1200 don't want and then press TOGFILT which will display everything
1201 except these files.
1202
1203
1204 Select Files Matching A Regular Expression 'Wildcards' (SELWILD)
1205 Control-\
1206
1207 This will present you with a dialog to enter your regular
1208 expression matching criteria described above. After you enter
1209 it, twander will select (highlight) the files that match.
1210
1211 You can also "invert" your selections by using the SELINV key
1212 described previously. This is useful when you want to select
1213 everything except a group of files. Select the ones you don't
1214 want with a selection wildcard andthen press the SELINV key.
1215
1216 Selections remain in effect until you make another manual selec-
1217 tion, clear all selections, or run a command that forces a
1218 directory refresh after it runs - i.e., Commands defined with a
1219 leading "+".
1220
1221
1222 Display Selection Wildcard Menu (MOUSEFILTERSEL)
1223 Alt-Control-Middle-Mouse-Button
1224
1225 Display Selection Wildcard Menu (MOUSEWILDSEL)
1226 Alt-Control-Right-Mouse-Button
1227
1228 (Note that on Windows you must press Alt then Control then the
1229 mouse button for this to work. Windows appears to care deeply
1230 about keystroke order.)
1231
1232 These keys popup a list near the current mouse cursor of any
1233 previously used filtering or selection wildcards respectively.
1234 Selecting one of the entries therein pops-up a dialog that
1235 allows you to edit the wildcard before actually doing another
1236 wildcard filter or selection. This allows use to modify previ-
1237 ous wildcards for new use.
1238
1239
1240 Hiding Dotfiles
1241 By convention on Unix and many other systems, files or directories
1242 whose names begin with a dot ('.') are usually used as configuration
1243 files (directories). Unless you specifically want to edit a configura-
1244 tion, you typically do little or nothing with these files. Since there
1245 can be quite a few of them on a modern system, it's helpful to be able
1246 to block them from view.
1247
1248 By default, dotfiles are not hidden, but this can be changed with the
1249 HIDEDOTFILES configuration option.
1250
1251 By default, files or directories whose names begin with a period (".")
1252 are considered dotfiles. You can change this dotfile "introducer"
1253 string with the DOTFILE configuration option.
1254
1255
1256 Toggle Dotfile Hiding (TOGHIDEDOT)
1257 Control-9
1258
1259 This toggles dotfile hiding, on- and off. The program starts up
1260 with dotfiles visible or hidden as defined by the HIDEDOTFILES
1261 program option. Thereafter, TOGHIDEDOT can be used to make
1262 these files and directories visible or not.
1263
1264
1265 Unlike Wildcard Filters (which test the entire displayed line), dotfile
1266 hiding is triggered only by the name of the file or directory.
1267
1268 If you change DOTFILE to some other string, be aware that the test to
1269 see if a file (or directory) name starts with this string is case-sen-
1270 sitive. If you set DOTFILE to "De", it will not hide files starting
1271 with "de", for example.
1272
1273 The current state of dotfile hiding is displayed in the window title
1274 bar, immediately after the Filter information.
1275
1276 Note that even though you cannot see the files with this option
1277 enabled, commands you write can still operate on these files. For
1278 example, if you define a command that does something like:
1279
1280 c cleandot rm .*~
1281
1282
1283 This command will remove any backup (~) files, whether or not you can
1284 see them in the interface.
1285
1286
1287
1288 MENU OPTIONS
1289 Although twander is primarily keyboard-oriented, several menu-based
1290 features are also implemented to make the program more convenient to
1291 use. These menus appear at the top of the twander display window,
1292 above the directory listing.
1293
1294
1295 Invoking A Menu
1296 A menu can be invoked in one of several ways. You can click on it, you
1297 can press its associated "Accelerator Key" combination, or you can use
1298 the "Mouse Shortcut" to cause a copy of the menu to pop-up near the
1299 mouse pointer. The Accelerator Keys are shown in parenthesis next to
1300 the menu names below and the Mouse Shortcuts are similarly shown below
1301 in square brackets. All menus have Accelerator Keys defined, but only
1302 some menus have associated Mouse Shortcuts.
1303
1304
1305 Detaching A Menu
1306 The first item in each menu is a dashed line ("----") which indicates
1307 that it is a "tearoff" menu. Clicking on the dashed line will detach
1308 the menu from twander allowing it to be placed anywhere on screen.
1309 Even when detatched, these menus remain current and in-sync with twan-
1310 der as it continues to run. You can also tear off multiple instances
1311 of these menus if you'd like copies of them at several locations on the
1312 screen simultaneously.
1313
1314
1315
1316 Managing The Size Of Dynamic Menus
1317 A number of these menus have "dynamic" content - their content changes
1318 as the program runs. For example, the Directory, History, Filter and
1319 Select menus all keep some sort of "history" of what the program has
1320 done. Their content thus grows longer as the program is used.
1321
1322 On Windows systems, if such menus grow too long to physically fit on
1323 screen, up- and down- scrolling arrows automatically appear at the top-
1324 and bottom of the menu respectively. This is not a feature of the Unix
1325 Tk implementation, so menus which grow too large are simply truncated
1326 to fit the screen on Unix-like systems.
1327
1328 There are two User-Settable Options options available to help you man-
1329 age the maximum size of dynamic menus (see the section below on the
1330 Configuration File which explains how such options are actually set.
1331 The MAXMENU option specifies the maximum number entries that will be
1332 displayed in any dynamic menu. (twander internally tracks MAXMENUBUF
1333 number of items for each dynamic menu.) This defaults to 32 as is
1334 intended to keep the menu size reasonable.
1335
1336 If you set MAXMENU=0, it means you are disabling all dynamic menus. It
1337 also means that no interactive dialog will "remember" your last manual
1338 entry. For example, with MAXMENU set to 0, twander will not keep track
1339 of your last manual entries for the CHANGEDIR, FILTERWILD, SELWILD, and
1340 RUNCMD dialogs.
1341
1342 MAXMENUBUF specifies the size of the internal storage buffer for each
1343 dynamic menu regardless of how many entries are actually displayed.
1344 i.e. MAXMENUBUF determines how many dynamic events each menu tracks
1345 internally regardless of how many are actually visible in the menu at
1346 any moment in time. It defaults to 250 and probably never needs to be
1347 changed. If you set MAXMENUBUF to be less than MAXMENU, then this
1348 smaller value will determine the maximum size of the displayed menu.
1349 Setting MAXMENUBUF to 0 is equivalent to setting MAXMENU to 0.
1350
1351
1352 Commands Menu (Alt-c) [Right-Mouse-Button]
1353 Every command defined in the Configuration File is listed in this menu
1354 by its Command Name. The association Command Key is also shown in
1355 parenthesis. Clicking on an item in this menu is the same as invoking
1356 it from the keyboard by its Command Key. This is a convenient way to
1357 invoke an infrequently used command whose Command Key you've forgotten.
1358 It is also handy to confirm which commands are defined after you've
1359 edited and reloaded the Configuration File. The commands are listed in
1360 the order in which they are defined in the configuration file. This
1361 allows most frequently used commands to appear at the top of the menu
1362 by defining them first in the Configuration File. If no commands are
1363 defined, either because the Configuration File contains no Command Def-
1364 initions or because the Configuration File cannot be opened for some
1365 reason, the Commands Menu will be disabled (grayed out).
1366
1367
1368 History Menu (Alt-h) [Shift-Control-Right-Mouse-Button]
1369 twander keeps track of every command you attempt to execute, whether it
1370 is an invocation of a Command Definition found in the Configuration
1371 File or a manually entered command via the RUNCMD key. (default: Con-
1372 trol-z) This is done whether or not the command is successfully exe-
1373 cuted.
1374
1375 This feature provides a quick way to re-execute a command you've previ-
1376 ously run. When you select a command to run this way, a dialog box is
1377 opened, giving you an opportunity to edit the command before running it
1378 again.
1379
1380 One important point of clarification is in order here. If you run one
1381 of the commands defined in your Configuration File, it is stored in the
1382 History after all variable substitutions have been made. But, manually
1383 entered commands are stored in the History literally as typed - i.e.,
1384 Without variable substitution. This allows you easily reuse a manually
1385 entered command in another directory or context. (Presumably, Command
1386 Definitions in the Configuration File are written in such a way so as
1387 to be useful across many different directories and contexts. Running
1388 such a command again is simply a matter of pressing its associated let-
1389 ter key once more. By storing the resolved version of the command in
1390 the History, you can see what the command actually did.)
1391
1392
1393 The History Menu is emptied and grayed out when you press the CLRHIST
1394 key. (default: Control-y)
1395
1396
1397
1398 Directories Menu (Alt-d) [Shift-Right-Mouse-Button]
1399 twander keeps track of every directory visited. The previously
1400 described command to move "Back" one directory allows directory naviga-
1401 tion in reverse traversal order - you can back up to where you started.
1402 However, this feature "throws away" directories as it backs up, sort of
1403 like an "undo" function.
1404
1405 The "Directories" menu provides a slightly different approach to the
1406 same task. It keeps permanent track of every directory visited and
1407 displays that list in sorted order. This provides another way to move
1408 directly to a previously visited directory without having to manually
1409 navigate to it again, back up to it, or name it explictly using the
1410 Change Directory command.
1411
1412 Unless MAXMENU is set to 0, the Directory Menu shows the last MAXMENU
1413 directories visited in alphabetically sorted order (unless you change
1414 MAXMENUBUF to be smaller than MAXMENU). "Visited", in this case, is
1415 stretching things a bit.
1416
1417 The Directory Menu is emptied and grayed out when you press the CLRHIST
1418 key. (default: Control-y)
1419
1420
1421 Shortcut Menu (Alt-u) [Alt-Control-Left-Mouse-Button]
1422 This menu provides a way to access any of the Directory Shortcuts
1423 defined in the Configuration File. It also provides a number of
1424 "canned" navigation shortcuts to go up a directory, back a directory,
1425 to the home directory, to the starting directory, and to the root
1426 directory. On Windows systems using the Win32All extensions, there is
1427 also a shortcut to the Drive List View.
1428
1429
1430 Filter Menu (Alt-f) [Alt-Control-Middle-Mouse-Button]
1431 (Note that on Windows you must press Alt then Control then the Middle-
1432 Mouse-Button for this to work. Windows appears to care deeply about
1433 keystroke order.)
1434
1435 This menu provides a list of all previously used filtering "wildcard"
1436 regular expressions. Any regular expressions defined in the Configura-
1437 tion File (see below) using the "FILTERWILD = " statement will also
1438 appear in this menu. This saves you the tedium of constantly having to
1439 enter complex regular expression syntax every time you wish to do wild-
1440 card-based selections.
1441
1442 Selecting something from this menu brings up a dialog box which allows
1443 you to edit the selected wildcard before using it.
1444
1445 Bear in mind that the size of the displayed menu is governed by the
1446 MAXMENU and MAXMENUBUF Configuration File options (see below). i.e.,
1447 Only the last MAXMENU number of wildcards are actually displayed on the
1448 menu.
1449
1450 The Filter Menu is emptied and grayed out when you press the CLRHIST
1451 key. (default: Control-y) This history is not cleared if the Configu-
1452 ration File is reloaded.
1453
1454
1455 Select Menu (Alt-l) [Alt-Control-Right-Mouse-Button]
1456 (Note that on Windows you must press Alt then Control then the Right-
1457 Mouse-Button for this to work. Windows appears to care deeply about
1458 keystroke order.)
1459
1460 This menu provides a list of all previously used selection "wildcard"
1461 regular expressions. Any regular expressions defined in the Configura-
1462 tion File (see below) using the "SELECTWILD = " statement will also
1463 appear in this menu. This saves you the tedium of constantly having to
1464 enter complex regular expression syntax every time you wish to do wild-
1465 card-based selections.
1466
1467 Selecting something from this menu brings up a dialog box which allows
1468 you to edit the selected wildcard before using it.
1469
1470 Bear in mind that the size of the displayed menu is governed by the
1471 MAXMENU and MAXMENUBUF Configuration File options (see below). i.e.,
1472 Only the last MAXMENU number of wildcards are actually displayed on the
1473 menu.
1474
1475 The Select Menu is emptied and grayed out when you press the CLRHIST
1476 key. (default: Control-y) This history is not cleared if the Configu-
1477 ration File is reloaded.
1478
1479
1480 Sorting Menu (Alt-s) [Alt-Shift-Right-Mouse-Button]
1481 (Note that on Windows you must press Alt then Shift then the Right-
1482 Mouse-Button for this to work. Windows appears to care deeply about
1483 keystroke order.)
1484
1485 This menu provides a way to select any of the available sorting
1486 options. It is context-sensitive and will show entries appropriate to
1487 what kind of "view" the program is currently displaying. That is, it
1488 will show options which make sense for both "normal" view as well as
1489 "Drive List View" (see the ADVANCED WINDOWS FEATURES section below).
1490
1491 You'll find the currently selected sorting options displayed in the
1492 program title bar.
1493
1494
1495 Help Menu (Alt-l) [No Mouse Shortcut]
1496 This menu provides information about various internal settings of twan-
1497 der including Internal Program Variables, User-Settable Options, Key-
1498 board Assignments, User-Defined Variables, Command Definitions, and
1499 Associations. It also has an About feature which provides version and
1500 copyright information about the program.
1501
1502 For the most part, this help information should fit on screen easily.
1503 However, very long Command Definitions will probably not fit on-screen.
1504 In this case, if you are curious about just how twander is interpreting
1505 your Command Definitions, invoke the program with the relevant debug
1506 bit turned on and watch the output on stdout as twander runs.
1507
1508
1509
1510 THE twander CONFIGURATION FILE
1511 Much of twanders flexibility comes from the fact that it is a macro-
1512 programmable user interface. The program itself does little more than
1513 provide a way to navigate around a filesystem. It must be configured
1514 (programmed) to actually do something with the files you specify. This
1515 is done via a "Configuration File". This file is also used to set Pro-
1516 gram Options and change keyboard assignments. Although the program
1517 will run without a Configuration File present, it will warn you that it
1518 is doing so with no commands defined.
1519
1520
1521
1522 LOCATION OF CONFIGURATION FILE
1523 By default, the program expects to find configuration information in
1524 $HOME/.twander (%HOME%\.twander on Windows) but you can override this
1525 with the -c command line option. (Recommended for Windows systems - see
1526 the section below entitled, INSTALLING twander )
1527
1528 Actually, twander can look in a number of places to find its Configura-
1529 tion File. It does this using the following scheme (in priority
1530 order):
1531
1532
1533 o If the -c argument was given on the command line, use this argument
1534 for a Configuration File.
1535
1536
1537 o If -c was not given on the command line, but the HOME environment
1538 variable is set, look for the a Configuration File as $HOME/.twan-
1539 der.
1540
1541
1542 o If the HOME environment variable is not set and a -c command line
1543 argument was not provided, look for a file called ".twander" in the
1544 directory from which twander was invoked.
1545
1546
1547
1548 CONFIGURATION FILE FORMAT
1549 twander Configuration Files consist of freeform lines of text. Each
1550 line is considered independently - no configuration line may cross into
1551 the next line. Whitespace is ignored within a line as are blank lines.
1552
1553 There are several possible legal lines in a twander Configuration File:
1554
1555 Comments
1556 Program Option Statements
1557 Key Binding Statements
1558 Directory Shortcut Statements
1559 Wildcard Statements
1560 Variables And Command Definitions
1561 Associations
1562 Conditional Processing Statements
1563 The Include Directive
1564
1565 (See the ".twander" file provided with the program distribution for
1566 examples of valid configuration statements.)
1567
1568 Everything else is considered invalid. twander will respond with
1569 errors or warnings as is appropriate anytime it encounters a problem in
1570 a Configuration File. An error will cause the program to terminate,
1571 but the program continues to run after a warning. For the most part,
1572 twander tries to be forgiving and merely ignores invalid configuration
1573 statements (after an appropriate warning). It only declares an error
1574 when it cannot continue. This is true both when the program initially
1575 loads as well as during any subsequent Configuration File reloads ini-
1576 tiated from the keyboard while running twander.
1577
1578 The following sections describe each of the valid Configuration File
1579 entires in more detail.
1580
1581
1582 Comments
1583 A comment is begun with the "#" character which may be placed anywhere
1584 on a line. Comments may appear freely within a Configuration File.
1585 twander strictly ignores everything from the "#" to the end of the line
1586 on which it appears without exception. This means that "#" cannot
1587 occur anywhere within a User-Defined Variable Definition, Key Binding
1588 Statement, or Command Definition (these are described below). Comments
1589 can be placed on the same line to the right of such statements.
1590
1591 It is conceivable that the "#" character might be needed in the Command
1592 String portion of a Command Definition. twander provides a Built-In
1593 Variable, [HASH], for exactly this purpose. See the section below
1594 entitled, Variables And Command Definitions, for a more complete
1595 description.
1596
1597
1598 Program Option Statements
1599 Many of twanders internal program defaults can be overriden in the Con-
1600 figuration File using Program Option statements. These statements look
1601 just like the User-Defined variables described later in this document
1602 except twander recognizes the variable name as a Program Option rather
1603 than an arbitrary variable. Program Option Statements thus take the
1604 form:
1605
1606 Option Name = Option Value
1607
1608 The Option Name is case-sensitive and must be entered exactly as
1609 described below. For instance, twander understands "AUTOREFRESH" as a
1610 Program Option, but will treat "AutoRefresh" as a User-Defined Vari-
1611 able.
1612
1613 The Option Value is checked to make sure it conforms to the proper type
1614 for this variable. The Type can be Boolean, Numeric, or String.
1615
1616 A Boolean Option must be assigned a value of True or False. These log-
1617 ical values can be in any case, so TRUE, TRue, and tRue all work.
1618
1619 A Numeric Option must be a number 0 or greater. Numbers can also be
1620 entered in hexadecimal format: 0xNNN, where NNN is the numeric expres-
1621 sion in hex.
1622
1623 A String Option can be any string of characters. Quotation marks are
1624 treated as part of the string! Do not include any quotation marks
1625 unless you really want them to be assigned to the option in question
1626 (almost never the case).
1627
1628 Furthermore, as described above, you cannot use the '#' symbol as part
1629 of the string assignment because twander always treats this character
1630 as the beginning of a comment no matter where it appears.
1631
1632 For consistency with other Configuration File entries, Program Option
1633 Statements may have a blank Right Hand Side. Such statements are sim-
1634 ply ignored. This is convenient when you want to leave a placeholder
1635 in your Configuration File but don't actually want to activate it at
1636 the moment. However, be careful - depending on what precedes the
1637 statement, you'll get different settings for the option in question.
1638 For example:
1639
1640 # This effectively sets BCOLOR to its default value when
1641 # the Configuration File is reloaded
1642 BCOLOR =
1643
1644 # But this means the value of BCOLOR is set to red
1645
1646 BCOLOR = red
1647 BCOLOR =
1648
1649 In other words, you should think of Program Option Statements with a
1650 blank Right Hand Side as comments - present but ignored.
1651
1652 Other than this basic type-checking, twander does no further validation
1653 of the Right Hand Side of a Program Option Statement. It is perfectly
1654 possible to provide a RHS which passes twanders type validation but
1655 which makes no sense whatsoever to the program. Entries like this
1656 cause everything from a mild twander warning to a spectacular program
1657 failure and Python traceback on stdout:
1658
1659 # A Nice Way To Clobber twander
1660 BCOLOR = goo
1661
1662 The following sections document each available Program Option using
1663 this general format:
1664
1665 Option-Name [Type] (Default Value)
1666
1667
1668 ACTUALLENGTH [Boolean] (False)
1669
1670 By default, file sizes , total directory size (on the title
1671 bar), and drive sizes in Win32 Drive List view are "normalized".
1672 They are expressed in bytes, Kilobytes, Megabytes, or Gigabytes.
1673 This keeps the display from getting cluttered with the longer
1674 strings required to display the actual lengths in bytes. If you
1675 want the program to display the actual lengths for these items
1676 by default, set ACTUALLENGTH=True in your Configuration File.
1677 You can also "toggle" between normalized and actual size display
1678 with the TOGLENGTH key (default: Control-0).
1679
1680
1681 ADAPTREFRESH [Boolean] (True)
1682
1683 Whenever a directory is read, the time to do so is tracked. If
1684 that time is less than the current value of REFRESHINT - i.e.,
1685 The directory read took less than REFRESHINT milliseconds to
1686 complete - nothing special happens. But, if the actual direc-
1687 tory read time takes longer than REFRESHINT milliseconds, twan-
1688 der adjusts the value of REFRESHINT upwards. That way, you're
1689 guaranteed to have time after the read completes to actually do
1690 something.
1691
1692 This dynamic adjustment takes place on every directory read. If
1693 you go to a slow directory and REFRESHINT gets dynamically
1694 adjusted to, say, 25 seconds, when you go back to a
1695 faster/smaller directory, REFRESHINT will be reset to its
1696 default value. The changing value of REFRESHINT is not shown in
1697 the program options help menu. The value there is the one set
1698 by default or set in the Configuration File. Think of this as
1699 the "base" value for REFRESHINT.
1700
1701 If ADAPTREFRESH is set to False, then adaptive refresh timing is
1702 disabled and a directory refresh will be attempted every
1703 REFRESHINT milliseconds.
1704
1705
1706
1707 AFTERCLEAR [Boolean] (True)
1708
1709 Tells twander to clear any selections in the GUI if a command
1710 forces a display refresh after it completes. (See the AFTERWAIT
1711 and Forcing Display Updates In Command Definitions sections
1712 below). This is done because a command that forces a display
1713 update is probably changing the content of the current directory
1714 (otherwise, why bother with the update?), and the current selec-
1715 tions may no longer be relevant.
1716
1717 Setting AFTERCLEAR to False, will leave the current selections
1718 alone after doing a command with a forced update.
1719
1720
1721
1722 AFTERWAIT [Numeric] (1)
1723
1724 It is possible to define commands so that a display refresh is
1725 forced after a command is invoked (see the section below enti-
1726 tled, Forcing Display Updates In Command Definitions ). The
1727 AFTERWAIT option tells twander how long to wait after the com-
1728 mand has been initiated before actually doing the refresh. The
1729 idea here is to give the command some time to complete before
1730 updating the display.
1731
1732
1733
1734 AUTOREFRESH [Boolean] (True)
1735
1736 By default, twander regularly re-reads the current directory to
1737 refresh the display with any changes. If you are running on a
1738 very slow machine or slow connection between the X-Windows
1739 server and client, set this option to False. You can manually
1740 force an update at any time using the REFRESH key. (default:
1741 Control-l)
1742
1743
1744
1745 BCOLOR [String] (Black)
1746
1747 Selects the main display Background Color.
1748
1749
1750 CMDMENUSORT [Boolean] (False)
1751
1752 By default, twander populates the command menu on the menu bar
1753 (and the popup command menu) with commands in the order in which
1754 they are defined in the Configuration File. This was done so
1755 that you could define the most important or most frequently used
1756 commands first and they would thus conveniently appear at the
1757 top of the menu list. However, if you prefer your command list
1758 to be sorted, set the CMDMENUSORT option to True.
1759
1760 Note that the Command Definitions help menu ignores CMDMENUSORT
1761 and is always presented in sorted order.
1762
1763
1764
1765 CMDSHELL [String] ()
1766
1767 This option is primarily intended for people running twander on
1768 Unix-like operating systems like FreeBSD and Linux. As
1769 described in the GOTCHAS section below, running a command line
1770 program or script requires some extra effort if you want to see
1771 the results presented in a GUI window. Typically, you need to
1772 run these commands in some kind of 'xterm' context so that the
1773 results will be visible, possibly using a shell as well. So,
1774 it's common to see Command Definitions like:
1775
1776 x MyCommand xterm -l -e bash -c 'stuff-for-my-command'
1777
1778 In fact, on Unix, the need for this idiom is so common, it's
1779 best to define some variables for this. If you look in the
1780 example '.twander' Configuration File provided in the program
1781 distribution, you'll see something like (comments removed):
1782
1783 SHELL = bash -c
1784 VSHELL = [XTERM] [SHELL]
1785 XTERM = xterm -fn 9x15 -l -e
1786
1787 Now the Command Definition above becomes:
1788
1789 x MyCommand [VSHELL] 'stuff-for-my-command'
1790
1791 That's all well and good for Command Definitions, but what hap-
1792 pens when you want to manually enter a command via the RUNCMD
1793 key? (default: Control-z) You have to manually enter the gob-
1794 bledy-gook above, or at least start your command with [VSHELL]
1795 (since RUNCMD understands variable references).
1796
1797 The CMDSHELL option is a way to automate this. You can assign
1798 it to any literal text. That text will be automatically
1799 prepended to any command you enter manually. In this case you
1800 could do either of the following in the Configuration File:
1801
1802 CMDSHELL = xterm -l -e bash -c
1803
1804 - or -
1805
1806 CMDSHELL = [VSHELL] # Assuming VSHELL is defined previously
1807
1808 Now every time you enter a command, this will be placed in front
1809 of your text before command execution commences.
1810
1811 To disable CMDSHELL operation permanently, just remove the
1812 statement above from your Configuration File. If you want to
1813 leave it in as a placeholder, but deactivate CMDSHELL, use the
1814 following statement:
1815
1816 CMDSHELL =
1817
1818 You also may want to occasionally use RUNCMD to do something
1819 without CMDSHELL processing, even though that feature has been
1820 defined in the Configuration File. You can disable CMDSHELL
1821 operation on a per-RUNCMD basis. Just begin your entering your
1822 command with the double-quote (") character. twander under-
1823 stands this to "escape" CMDSHELL processing.
1824
1825 As a general matter, CMDSHELL allows you to prepend anything you
1826 like before a manually entered command - literal text, refer-
1827 ences to variables, or even the name of a script the system will
1828 use to execute your command. Whatever value you use for CMD-
1829 SHELL will appear in the Command Menu history for each manually
1830 initiated command which used this feature - i.e., All the manual
1831 commands that did not escape the feature.
1832
1833
1834 DEBUGLEVEL [Numeric] (0)
1835
1836 This is another way to set the debugging level you desire (the
1837 other way being the -d command line argument). For example, say
1838 you want to always dump the current Command Definitions to std-
1839 out when the program starts - perhaps you want to redirect this
1840 output to a file or printer. Just add this line to your Config-
1841 uration File:
1842
1843 DEBUGLEVEL = 0x004
1844
1845
1846
1847 DEFAULTSEP [String] (==>)
1848
1849 This is the string that separates the prompting text and the
1850 default response in {PROMPT: ...} and {YESNO: ...} Built-In
1851 Variables. You may change this to any string you like, though
1852 doing so is not recommended. Changing DEFAULTSEP will require
1853 you to edit any Configuration Files that use these Built-Ins
1854 with default responses. In no case should the delimiter string
1855 include any of the characters, [ ]{ } since these are used as
1856 delimiters in the twander configuration language.
1857
1858
1859
1860 DOTFILE [String] (.)
1861
1862 It is a convention on Unix (and other systems) that files or
1863 directories whose names begin with a period are program configu-
1864 ration files (directories). twander has the ability to hide
1865 these so-called "dotfiles". (See the section above entitled Hid-
1866 ing Dotfiles for the details.) twander treats any file or
1867 directory whose name begins with the string defined by DOTFILE
1868 as a dotfile for this purpose.
1869
1870 For example, if you set DOTFILE=Xyz, all files or directories
1871 whose names begin with "Xyz", will be hidden when you tell twan-
1872 der to hide dotfiles. Notice that if you change this option
1873 from its default, you may use any string to be the dotfile
1874 "introducer", but it is always treated with case-sensitivity.
1875 For instance, in our example, files beginning with "XYZ" would
1876 not be hidden.
1877
1878
1879
1880 FCOLOR [String] (green)
1881
1882 Selects the main display Foreground (Text) Color.
1883
1884
1885 FNAME [String] (Courier)
1886
1887 Selects the main display Font Name.
1888
1889
1890 FSZ [Numeric] (12)
1891
1892 Selects the main display Font Size.
1893
1894
1895 FWT [String] (bold)
1896
1897 Selects the main display Font Weight. This can be assigned to:
1898 normal, bold, italic, or underlined. Depending on your system,
1899 other values may also be possible.
1900
1901
1902 FORCEUNIXPATH [Boolean] (False)
1903
1904 Ordinarily, Built-In Variables and Program Memory References in
1905 a command definition are replaced with strings that list one or
1906 more files and/or directories. When this substitution is made
1907 at runtime, these strings contain the path separator character
1908 appropriate for the underlying operating system ("/" for Unix
1909 and "\" for Windows).
1910
1911 If you set FORCEUNIXPATH to True, twander will always use the
1912 Unix path separator character("/") in these substitutions.
1913
1914 This option is primarily useful when writing command definitions
1915 with Unix tools under Windows (such as cygwin) that are fussy
1916 about path separator conventions.
1917
1918 This option is only relevant on Windows systems. It is ignored
1919 on other operating systems.
1920
1921
1922
1923 HBCOLOR [String] (lightgreen)
1924
1925 Selects the help menu Background Color.
1926
1927
1928 HEIGHT [Numeric] (600)
1929
1930 Initial vertical size of the twander window in pixels.
1931
1932
1933 HFCOLOR [String] (black)
1934
1935 Selects the help menu Foreground (Text) Color.
1936
1937
1938 HFNAME [String] (Courier)
1939
1940 Selects the help menu Font Name.
1941
1942
1943 HFSZ [Numeric] (10)
1944
1945 Selects the help menu Font Size.
1946
1947
1948 HFWT [String] (italic)
1949
1950 This selects the help menu Font Weight.
1951
1952
1953
1954 HIDEDOTFILES [Boolean] (False)
1955
1956 Sets whether the program hides "dotfiles" by default. (See pre-
1957 vious section entitled Hiding Dotfiles for the details of this
1958 feature.) This value can be toggled with the TOGHIDEDOT
1959 (default: Control-9) key binding.
1960
1961
1962 INVERTFILTER [Boolean] (False)
1963
1964 Invert wildcard filtering. That is, display the entries that do
1965 not match the wildcard filtering criteria. You can preset this
1966 in the Configuration File as you wish, but the more usual way to
1967 change it is via the TOGFILT (default: Control-minus) key bind-
1968 ing.
1969
1970
1971 ISODATE [Boolean] (False)
1972
1973 Set this to True to display file/directory date and time in ISO
1974 8601 format instead of the default US localized format.
1975
1976
1977 MAXMENU [Numeric] (32)
1978
1979 Maximum number of entries to display in any dynamic menu. This
1980 keeps the menu size reasonable. Internally, twander keeps track
1981 of way more than this number of dynamic entiries (see the MAX-
1982 MENUBUF option below).
1983
1984
1985 MAXMENUBUF [Numeric] (250)
1986 Maximum number of items twander tracks internally for each
1987 dynamic menu. This value need normally not be changed. It is
1988 present only to bound how much memory twander consumes for this
1989 task.
1990
1991
1992 MAXNESTING [Numeric] (32)
1993
1994 Number of times a Command Definition is processed to dereference
1995 all variables. For example, suppose you have this:
1996
1997 FOO = bax
1998 BAM = x[FOO]
1999
2000 x mycmd [BAM] [SELECTION]
2001
2002 When you press the x key, the twander command interpreter has to
2003 process the line repeatedly until all variables are resolved:
2004
2005 [BAM] [SELECTION] -> x[FOO] [SELECTION]
2006 x[FOO] [SELECTION] -> xbax [SELECTION]
2007 xbax [SELECTION] -> xbax selected-item
2008
2009 So, in this case, it took 3 iterations to do this. MAXNESTING
2010 merely sets the maximum number of times this is permitted. We
2011 have to do this to stop runaway definitions like this:
2012
2013 FOO = x[FOO]
2014
2015 This kind of construct will cause twander to iterate MAXNESTING
2016 number of times and then give up with a warning about exeeding
2017 the nesting (dereferencing) limit.
2018
2019 A 32 iteration limit should be plenty for any reasonable Command
2020 Definitions. If you set MAXNESTING to 0, twander will not allow
2021 any variable dereferencing, including the Built-In Variables.
2022 This is probably not what you want.
2023
2024
2025 MBARCOL [String] (beige)
2026
2027 Selects the Menu Bar color.
2028
2029
2030 MBCOLOR [String] (beige)
2031
2032 Selects the menu Background Color.
2033
2034
2035 MFCOLOR [String] (black)
2036
2037 Selects the menu Foreground (text) Color.
2038
2039
2040 MFNAME [String] (Courier)
2041
2042 Selects the menu Font Name.
2043
2044
2045 MFSZ [Numeric] (12)
2046
2047 Selects the menu Font Size.
2048
2049
2050 MFWT [String] (bold)
2051
2052 Selects the menu Font Weight.
2053
2054
2055 NODETAILS [Boolean] (False)
2056
2057 Prevents details from ever being displayed.
2058
2059
2060 NONAVIGATE [Boolean] (False)
2061
2062 Prevents the user from navigating out of the starting directory.
2063 Command Definitions and commands initiated manually via RUNCMD
2064 (default: Control-z) can still "see" other directories, the user
2065 just cannot move elsewhere with any of the twander navigation
2066 commands.
2067
2068 The NODETAILS and NONAVIGATE commands are not security features.
2069 They can easily be defeated by editing the Configuration File.
2070 They exist to make it easy for you to create 'twander' configu-
2071 rations for technically unsophisticated users.
2072
2073 Say you want to define a few simple commands for your boss to
2074 use which won't challenge his or her feeble managerial mind ;)
2075 By defining these commands and setting both NODETAILS and NONAV-
2076 IGATE to TRUE, you really limit what can be done with twander.
2077 They can't wander off into other directories and get lost, or
2078 worse yet, clobber files they don't understand. There are no
2079 details to confuse them. Your instructions for using the pro-
2080 gram thus become, "Select the files you're interested in and
2081 press P to print them, M to mail them to Headquarters.." and so
2082 on.
2083
2084 Again, these are NOT security features. Anyone with even very
2085 modest technical skills can thwart these limitations. But, it
2086 is suprising just how effective these can be in simplifying life
2087 for technically challenged users.
2088
2089
2090 QUOTECHAR [String] (double-quote symbol)
2091
2092 As described below, twander ordinarily quotes most Built-In
2093 Variables as it replaces them during command processing. This
2094 is useful because modern operating systems allow file and direc-
2095 tory names to have spaces in them. Such names must be quoted
2096 for most programs to understand them as a single entity on a
2097 command line.
2098
2099 By default, the double-quote char is used for this purpose. You
2100 can suppress quote processing by using the -t command line argu-
2101 ment. This does nothing more than set QUOTECHAR to an empty
2102 string. Unfortunately, since the RHS of a Program Option State-
2103 ment cannot be blank, you cannot disable quoting with this
2104 option. However, you can set the quotation character to be any-
2105 thing else you like, such as a single-quote. In fact, you can
2106 set QUOTECHAR to any string of characters you like and they will
2107 faithfully be used on either side of a Built-In Variable
2108 replacement.
2109
2110
2111 REFRESHINT [Numeric] (5000)
2112
2113 Nominal time in milliseconds between automatic directory
2114 refreshes (if AUTOREFRESH is True). This time is really nominal
2115 and should not be used with any accurate timing in mind.
2116 REFRESHINT=8000 says that the refresh interval will be nominally
2117 8 seconds (and certainly more than the default of 5 seconds),
2118 but it can be off this nominal value by quite a bit.
2119
2120 If you run twander on a slow system (or have a slow link between
2121 X-Client and X-Server) you might want to increase this value
2122 substantially. You can get into the situtation where just as
2123 one refresh completes, its time to do the next one, and the
2124 twander will seem really sluggish and unresponsive. By length-
2125 ening the time between automatic updates, the amount of unre-
2126 sponsive behavior is reduced. Of course, this also means that
2127 any changes in the currently viewed directory will also take
2128 longer to appear in the twander display.
2129
2130
2131 SCALEPRECISION [Numeric] (1)
2132
2133 This specifies the number of digits of precision to display when
2134 scaling file lengths (i.e., when ACTUALENGTH is set or toggled
2135 to False). SCALEPRECISION sets how many digits to the right of
2136 the decimal point to display in the scaled length. Notice that
2137 this does not do proper rounding and thus the rightmost digit
2138 can be off by -1.
2139
2140
2141
2142 SORTBYFIELD [String] (Name)
2143
2144 Specifies which field is to be used as the sort key. May be one
2145 of the fields below under "Sort Key" (case-insensitive). The
2146 equivalent field name for Drive List View (see ADVANCED WINDOWS
2147 FEATURES section below) is shown in the second column, however
2148 these may not be used as arguments for SORTBYFIELD. For exam-
2149 ple, if you plan to start the program in Drive List View and
2150 want to sort by Drive Type, use: SORTBYFIELD=Links.
2151
2152 Equivalent
2153 Sort Key Drive List View Field
2154 -------- ---------------------
2155 No Sort No Sort
2156 Permissions Label/Share String
2157 Links Drive Type
2158 Owner Free Space
2159 Group Total Space
2160 Length Drive Letter
2161 Time Drive Letter
2162 Name Drive Letter
2163
2164
2165 SORTREVERSE [Boolean] (False)
2166
2167 Specifies whether to reverse the sort order or not. If True and
2168 SORTSEPARATE is also True, then the directory list will appear
2169 at the end of the display in addition to being reverse ordered.
2170
2171
2172 SORTSEPARATE [Boolean] (True)
2173
2174 Determines whether directories and files should be separated or
2175 mingled in absolute sort order in the display. By default, they
2176 are separated with directories sorted according to SORTBYFIELD
2177 order but appearing before any files in the display.
2178
2179 This option is ignored in Drive List View.
2180
2181
2182 STARTDIR [String] (Directory In Which Program Started)
2183
2184 This allows you to force a starting directory of your choice no
2185 matter where the program actually is launched. This is useful
2186 for day-to-day operation - perhaps you always want to start in
2187 your home directory. STARTDIR is also handy in tandem with the
2188 NODETAILS and NONAVIGATE options to force a user to the only
2189 directory which they should be using.
2190
2191
2192 STARTX [Numeric] (0)
2193
2194 Initial horizontal offset of the twander window in pixels.
2195
2196
2197 STARTY [Numeric] (0)
2198
2199 Initial vertical offset of the twander window in pixels.
2200
2201
2202 SYMDIR [Boolean] (True)
2203
2204 This option causes symbolic links that point to directories to
2205 be treated as directories for purposes of sorting. This is rel-
2206 evant when "separated" sorting is selected - i.e., When the
2207 directories are sorted separately from files. If SYMDIR is set
2208 to False, then symbolic links will be sorted as files, regard-
2209 less of what the link points to. This option can be set in the
2210 Configuration file or toggled from the keyboard with the
2211 TOGSYMDIR (default: Control-~) key binding. The status of this
2212 variable is displayed on the title bar in the "Symlinks:" field
2213 as either a "D" or "F" for directory and file sorting respec-
2214 tively.
2215
2216
2217 SYMEXPAND [Boolean] (True)
2218
2219 When displaying symbolic links, twander ordinarily shows both
2220 the link name and its target. If you set SYMEXPAND=False, only
2221 the name of the symbolic link, not its target will be shown.
2222 This effectively causes a symbolic link to be displayed like any
2223 other file or directory. This option can be set in the Configu-
2224 ration file or toggled from the keyboard with the TOGSYMEXPAND
2225 (default: Control-!) key binding. The title bar status field,
2226 "Symlinks:" will display an "E" if this option is True.
2227
2228
2229
2230 SYMRESOLV [Boolean] (False)
2231
2232 twander ordinarily displays symbolic link targets as they were
2233 defined. That is, targets that were defined relative to the
2234 current (or some other) directory, or targets that point to
2235 other symbolic links will not be "resolved" to show their abso-
2236 lute path. Instead, the path as defined when the symbolic link
2237 was created will be shown. Setting SYMRESOLV=True will cause
2238 the absolute path of symbolic link targets to be displayed.
2239 This option can be set in the Configuration file or toggled from
2240 the keyboard with the TOGSYMRESOLV (default: Control-@) key
2241 binding. If you toggle this option with TOGSYMRESOLV, it
2242 implies you want to see symbolic link targets in some form
2243 (either in resolved or unresolved form), so this keyboard action
2244 will also force SYMEXPAND to be True. The title bar status
2245 field, "Symlinks:" will display an "R" if this option is True.
2246
2247
2248
2249 USETHREADS [Boolean] (False)
2250
2251 twander defaults to using normal "heavy weight" processes for
2252 running commands on Unix. Many Unix implementations also sup-
2253 port a "threaded" process model. Setting USETHREADS to True on
2254 such systems will cause twander to use threads, rather than pro-
2255 cesses to launch user-defined commands. There are some known
2256 issues with thread-based operations (hence the reason this
2257 option defaults to False). These are discussed in the GOTCHAS
2258 section below.
2259
2260 This option applies only to Unix-like operating systems. Win-
2261 dows commands are always run as a thread - this is the only
2262 process model Windows supports..
2263
2264
2265 USEWIN32ALL [Boolean] (True)
2266
2267 Windows only. If 'win32all' is installed, determines whether
2268 its features should be used (see section below entitled,
2269 ADVANCED WINDOWS FEATURES for details).
2270
2271 Normally, this option should be left alone. However, if you
2272 have 'win32all' installed on your system for some other reason,
2273 but don't want it used by twander, set this option to False.
2274
2275 The main reason to do this would be on a slow machine with very
2276 large directories. The advanced features of 'win32all' come at
2277 a computational price. This is especially noticeable when it is
2278 computing the attributes, ownership, and size in a directory
2279 with hundreds (or more) of entries. Typically, you would just
2280 use the TOGWIN32ALL key (default: Control-w) to temporarily dis-
2281 able these features before entering such a directory. However,
2282 if your starting directory is in this category, setting
2283 USEWIN32ALL=False might not be a bad idea.
2284
2285
2286 WARN [Boolean] (True)
2287
2288 Determines whether interactive warnings should be displayed as
2289 twander encounters them (while parsing a Configuration File or
2290 just in normal execution).
2291
2292 Setting this option to False is the same thing as using the -q
2293 command line option with one important difference: The Configu-
2294 ration File is parsed before the command line is parsed. Even
2295 if you have -q on the command line (or in the TWANDER environ-
2296 ment variable), if there is an error in your Configuration File,
2297 you will see warning messages at program startup time. Putting
2298 WARN=False at the top of your Configuration File will suppress
2299 this.
2300
2301 It is not recommended that you operate normally with the -q flag
2302 or with WARN=False. twander is pretty forgiving in most cases
2303 and when it does warn you about something, there is a good rea-
2304 son for it - you probably want to know what the problem is.
2305
2306
2307 WIDTH [Numeric] (800)
2308
2309 Initial horizontal size of the twander window in pixels.
2310
2311
2312 WILDNOCASE [Boolean] (True On Win32 / False Elsewhere)
2313
2314 Set's whether or not case is significant in wildcard filtering
2315 and selection. If True, case is ignored, if False, case is sig-
2316 nificant in these wildcard operations.
2317
2318
2319
2320 A few general notes about Program Options are worth mentioning here:
2321
2322
2323 o You can set the same option multiple times in a single Configura-
2324 tion File - twander pays no attention. However, only the last (the
2325 one nearest the end of the file) instance of that Program Option
2326 Statement actually takes effect. This is handy if you want to tem-
2327 porarily change something without modifying your existing configu-
2328 ration. Just add your temporary change at the end of the file.
2329 When you're done with it, just remove it. No need to edit and re-
2330 edit your preferred configuration...
2331
2332
2333 o The font colors, weights, and sizes available for your use will
2334 vary somewhat by system. For instance, Windows TrueType fonts are
2335 effectively available in every size and weight. On the other hand,
2336 most Unix-like systems have a more limited palette of fonts and
2337 colors with which to work. Most systems should support obvious
2338 color names like, red, white, blue, yellow, beige, and so on. Many
2339 also support colors like lightgreen, lightblue, etc. At a minimum,
2340 you should be able to use normal, bold, italic, and underline for
2341 font weights.
2342
2343 Most systems attempt some kind of "best fit" font matching. If you
2344 specify a font size/weight/name that does not exist, the system
2345 will try to find what it thinks is the closest match. This is usu-
2346 ally ugly, so try to specify font information for things that actu-
2347 ally exist on your system.
2348
2349 If your setting in the Configuration File seems not to work, take a
2350 look at the command window in which you started twander (or start
2351 it from one manually, if you're using a GUI shortcut to start it).
2352 Attempts to use unavailable colors and weights will cause
2353 Python/Tkinter to dump traceback information on stdout.
2354
2355
2356 o Although you can use proportionally spaced fonts with twander, the
2357 result is pretty ugly. twander assumes a fixed width font when it
2358 calculates display formatting. Variable-width fonts will cause
2359 your display to be ragged and hard to read.
2360
2361
2362 o If you set MAXMENU or MAXMENUBUF to 0, it disables both dynamic
2363 menu content and of the last manual entry in the dialogs associated
2364 with CHANGEDIR (default: Control-x), FILTERWILD (default: Con-
2365 trol-=), SELWILD (default: Control-\), and RUNCMD (default: Con-
2366 trol-z).
2367
2368
2369 o Changing MAXMENU and then reloading the Configuration File only
2370 changes the number of items visible on the various dynamic menus.
2371 twander actually keeps track of more than this internally (governed
2372 by the MAXMENUBUF option).
2373
2374 Say MAXMENU is set to 4, but you've actually visited 20 different
2375 directories and issued 30 commands. You'll only see 4 of each on
2376 the associated menus. But, if you edit MAXMENU to now be 32 and
2377 reload the Configuration File, you will see all 20 directories and
2378 30 commands on their respective menus.
2379
2380
2381 o At first glance, the ability to set QUOTECHAR to any arbitary
2382 string may seem silly, but it actually has a purpose. As good as
2383 the twander macro capability is, it is still a fairly simple lan-
2384 guage. Really complex tasks will need to be handed off to some
2385 other scripting language (like Python!). It may be useful to
2386 delimit Built-In Variables (which indicate your selections via the
2387 twander interface) in such a way that your script knows where they
2388 came from. So, say you set QUOTECHAR=+++ and you have a Command
2389 Definition like this:
2390
2391 x mycmd MyPythonScript [DSELECTIONS] other stuff
2392
2393 When MyPythonScript runs, it can immediately tell which arguments
2394 came from twander (the ones that are in the form +++dir+++ or
2395 +++file+++) and which arguments are just other stuff.
2396
2397 You probably won't need this often, but its nice to have.
2398
2399
2400 o STARTX and STARTY are relative to the (0,0) origin that Tk uses for
2401 window placement. In High-School algebra most of us got used to
2402 seeing (0,0) in the lower-left corner of a graph. Tk has a rather
2403 different view of this and STARTX and STARTY are relative to the
2404 upper-left corner of the screen.
2405
2406
2407 Key Binding Statements
2408 No program that runs in many operating environments can satisfy every-
2409 one's (anyone's!) idea of what the "correct" key bindings should be.
2410 An emacs user, vi user, BSD user, and Windows user are going to differ
2411 considerably on what keys should be bound to what feature. twander
2412 ships from the factory with a set of default key bindings, but it also
2413 provides a mechanism for changing these bindings via entries in the
2414 Configuration File.
2415
2416 This feature is available only for Keyboard Assignments. Mouse Button
2417 Assignments may not be changed by the user. An attempt to do so in the
2418 Configuration File will cause twander to display a warning and ignore
2419 the offending line.
2420
2421 It is not difficult to override the default keyboard bindings by adding
2422 entries in the Configuration File. Doing so requires some familiarity
2423 with how Tkinter names keystrokes. Good resources for learning this
2424 exist abundantly on the Internet, among them:
2425
2426 http://www.pythonware.com/library/tkinter/introduction/index.htm
2427 http://www.nmt.edu/tcc/help/pubs/lang.html
2428 http://www.cs.mcgill.ca/~hv/classes/MS/TkinterPres/
2429
2430 (As an aside - Tkinter is nothing more than a Python interface to the
2431 Tcl/Tk windowing system. The "real" naming conventions for keystokes
2432 can be found in the many sources of Tk documentation, both in print and
2433 on the Internet.)
2434
2435 Keyboard binding assignments look just like variable definitions in the
2436 Configuration File. (The twander Configuration File parser automati-
2437 cally distinguishes between Key Binding Statements and Variable Defini-
2438 tions or other legitimate statements. This means you can never use one
2439 of the program function names as one of your own variable names.) Key
2440 Binding Statements thus take the form:
2441
2442 Program Function Name = Tkinter Keystroke Name
2443
2444 Changing the default bindings is therefore nothing more than a matter
2445 of assigning the appropriate Program Function Name (found in parenthe-
2446 sis next to the description in the default descriptions above) to the
2447 desired keystroke.
2448
2449 Examples of all the default key bindings are shown as comments in the
2450 ".twander" example Configuration File supplied in the program distribu-
2451 tion. The easiest way to rebind a particular function is to copy the
2452 relevant line, uncomment the copy, and change the right side of the
2453 assignment to the new key you'd like to use.
2454
2455 It is important to observe several rules when rebinding keys:
2456
2457
2458 o It is best if keyboard navigation commands are all Control or Func-
2459 tion keys. If you assign a navigation or selection function to a
2460 single keystroke, it may conflict with a user-defined command. If
2461 you assign it to a keypad/special key it may conflict with that
2462 key's normal GUI behavior.
2463
2464
2465 o The Tkinter keynames should placed on the right side of the "="
2466 symbol without any quotation marks.
2467
2468 # Incorrect
2469 QUITPROG = '<F3>'
2470
2471 # Correct
2472 QUITPROG = <F3>
2473
2474
2475 o The Program Function Name variables (the left side of the assign-
2476 ment) may not be used as names for your own user-defined variables
2477 elsewhere in the Configuration File. In fact, twander will never
2478 even recognize such an attempt. For example, suppose you try to do
2479 this:
2480
2481 QUITPROG = something-or-other
2482
2483 Because you want to be able to reference [QUITPROG] in a subsequent
2484 Command Definition. twander will actually interpret this as just
2485 another key binding command, in this case binding the program func-
2486 tion QUITPROG to "something-or-other" - probably not what you
2487 intended. Moreover, if you have a Command String somewhere with
2488 [QUITPROG] in it, twander will declare and error and abort because
2489 it has no User-Defined variable of that name in its symbol table.
2490
2491
2492 o When you're done making changes to the Configuration File, be sure
2493 to either restart the program or reload the Configuration File to
2494 assign the new bindings.
2495
2496
2497 o Be aware that twander does no sanity testing on the assignments you
2498 change. If you assign a particular twander function to an illegal
2499 or silly key string, the program will probably blow-up spectacu-
2500 larly. At the very least, that program feature will probably be
2501 unusable, even if twander manages to run.
2502
2503
2504 Directory Shortcut Statements
2505 twander provides a mechanism for directly navigating into one of 12
2506 frequently used directories. 12 keys, KDIRSC1 ... KDIRSC12 (default:
2507 F1 ... F12) have been set aside for this purpose. Directory Shortcut
2508 Statements are entries in the Configuration File which associate one of
2509 these keys with a particular directory path. These statements are in
2510 the form:
2511
2512 DIRSCxx = path
2513
2514 where, xx is a number from 1-12
2515
2516 So, for example, if you want to enter "C:\Documents And Settings" when
2517 you press the F5 key, you would add this to your Configuration File:
2518
2519 DIRSC5 = c:\Documents And Settings
2520
2521 There are several subtleties to Directory Shortcuts you should under-
2522 stand:
2523
2524
2525 o You can end the path with slash or not - twander will understand
2526 the entry either way.
2527
2528
2529 o If there is no path on the righthand side of a Directory Shortcut
2530 Statement, this is the same as having no definition at all for that
2531 key:
2532
2533 # This "undefines" shortcut #5
2534 DIRSC5 =
2535
2536
2537 o twander does absolutely no checking of what you enter to the right
2538 of the equals sign. If you enter something silly for the shortcut
2539 path, you will probably get a warning that the directory cannot be
2540 opened when you try to run that shortcut.
2541
2542
2543 o Keep the Program Function Names (KDIRSC1 ... KDIRSC12) which are
2544 used for Key Binding, distinct in your thinking from the Directory
2545 Shortcut Names (DIRSC1 ... DIRSC12) which are used for defining the
2546 shortcuts.
2547
2548
2549 o If you enter a Directory Shortcut Name that is invalid or out of
2550 range - examples include, DIRSC01 and DIRSC13 - twander treats them
2551 like a User-Defined Variable as described below.
2552
2553
2554 o A Directory Shortcut Statement may make reference to user-defined,
2555 environment, and execution variables.
2556
2557 ~ = [$HOME]
2558
2559 DIRSC1 = [~]/Desktop # User-defined variable
2560 DIRSC3 = [$HOME] # Environment variable
2561 DIRSC5 = [`echo "/tmp"`] # Execution variable (but silly)
2562
2563 If you use one of these forms, it's up to you to make sure that
2564 when when the variables are dereferenced (substituted), the result-
2565 ing string is the name of a directory. Be careful, you may not
2566 spot a definition that is not a directory right away. Variables
2567 are dereferenced at runtime not at the time the Configuration File
2568 is read in. Therefore, Directory Shortcut assignments with vari-
2569 able references in them are shown literally in the Shortcut Menu.
2570 twander cannot know what the value of the variable will be until
2571 you actually press the relevant shortcut key.
2572
2573
2574
2575 Wildcard Statements
2576 As discussed above, twander provides powerful regular expression-based
2577 "wildcard" filtering and selection capabilities via the FILTERWILD
2578 (default: Control-=) and SELWILD (default: Control-\) commands. These
2579 regular expressions can be complex and tedious to enter by hand each
2580 time you need them. You can pre-define frequently needed wildcard
2581 strings in your Configuration File using the following statements:
2582
2583 WILDFILTER = regular-expression-string
2584 WILDSELECT = regular-expression-string
2585
2586 The regular expression will then be pre-loaded into either the Filter
2587 or Select Menus respectively when twander starts. This makes it easy
2588 to use or modify complex wildcards over and over. You may place as
2589 many of these as you like in your Configuration File. (Though the
2590 menus will be limited to displaying MAXMENU number of items - see the
2591 section above on Program Option Statements.)
2592
2593
2594
2595 Variables And Command Definitions
2596 Most programs "ship from the factory" with a pre-defined set of fea-
2597 tures or commands. twander comes with no built-in commands! Instead,
2598 it comes with a mechanism which allows you to specify your own Command
2599 Definitions. By means of a simple and very powerful macro lanuage, you
2600 "program" twander and equip it with commands of your own choosing. For
2601 example, you might define commands to copy, delete, edit, and move the
2602 files or directories you choose. Perhaps you have a specialized shell
2603 script for doing backups. It's a simple matter to write a twander Com-
2604 mand Definition that will pass the names of the files and directories
2605 you've selected to that backup script. You might combine this with
2606 twander's Program Memory feature to keep a running list of the files
2607 and directories you want to backup and then finally issue the backup
2608 command when you're ready. Best of all, commands you define this way
2609 are always a single keystroke. This means that once you've programmed
2610 twander to suit your needs, actually using it is very fast and conve-
2611 nient.
2612
2613 Command Definitions are built out of literal text and may also have any
2614 combination of several variable types: User-Defined Variables, Environ-
2615 ment Variables, Execution Variables, and Built-In Variables.
2616
2617 User-Defined Variables are variables you define in the configuration
2618 file. They can hold any string of text you desire.
2619
2620 Environment Variables are set in the shell you use to invoke twander.
2621 This makes it easy to write a generic command definition that acts
2622 based on something set uniquely for each user in that user's environ-
2623 ment. You can only read, not change, Environment Variables in twander.
2624
2625 Execution Variables are set by running a program - pretty much any pro-
2626 gram will do. (Unix users will be familiar with this if they've ever
2627 used shell "backtick" quoting.) This makes it easy to construct a
2628 twander command that is defined in whole or in part by some external
2629 program.
2630
2631 Built-In Variables are a set of variables defined by twander itself.
2632 There are two general kinds of Built-Ins. The first kind are used to
2633 let your command know (at runtime) which file or files you have cur-
2634 rently selected in the twander interface. The other kind of Built-Ins
2635 are used to prompt you during command execution. There are also a few
2636 other Built-Ins described below.
2637
2638
2639 Just When Does A Variable Get Evaluated?
2640 Before getting into the mechanics of variables and command definitions,
2641 it's important to emphasize one point: Variables get "evaluated"
2642 (read) when a command is actually run. Older versions of twander eval-
2643 uated variables at the time a configuration file was read. However, as
2644 we'll see below, by waiting until the command is actually run to evalu-
2645 ate its variable references, we can do some nifty things.
2646
2647
2648 User-Defined Variables And Environment Variables
2649 User-Defined Variables are defined using the syntax:
2650
2651 Variable Name = Replacement String
2652
2653 Environment Variables are referenced using the syntax:
2654
2655 [$VARIABLE]
2656
2657 Say we have a configuration line like this,
2658
2659 EDITOR = emacs blah blah blah blah
2660
2661 Later on, when defining a command, instead of typing in "emacs blah
2662 blah blah blah", you can just refer to the variable [EDITOR] - the
2663 brackets indicate you are referring to a previously defined variable.
2664
2665 Similarly, suppose you have an environment variable called "EDITOR"
2666 which indicates your preferred editing program. Our definition could
2667 thus become:
2668
2669 EDITOR = [$EDITOR] blah blah blah blah
2670
2671 Why bother with this? Because it makes maintaining complex Configura-
2672 tion Files easier. If you look in the example ".twander" Configuration
2673 File provided in the program distribution, you will see this is mighty
2674 handy when setting up complex "xterm" sessions, for example.
2675
2676 Here are several other subtleties regarding User-Defined Variables:
2677
2678
2679 o twander variable definitions are nothing more than a string substi-
2680 tution mechanism. Suppose you have a variable definition that
2681 refers to another variable:
2682
2683 NewVar = somestring [OldVar]
2684
2685 It is important to realize that this only means: "If you encounter
2686 the string '[NewVar]' in a subsequent Command Definition, replace
2687 it with the string 'somestring [OldVar]'."
2688
2689 In other words, no evaluation of the right side of the expression
2690 takes place when a variable is defined. Evaluation of a variable
2691 only takes place when the variable is referenced (in the Command
2692 String portion of a Command Definition) at the time the command is
2693 run. The Command Definition parser will continue to dereference
2694 variable names until they are all resolved or it has reached the
2695 maximum nesting level (see next bullet).
2696
2697
2698
2699 o User-Defined Variables may be nested up to 32 levels deep (this
2700 default can be changed via the MAXNESTING Program Option). You can
2701 have constructs like:
2702
2703 Var1 = Foo
2704 Var2 = Bar
2705 FB = [Var1][Var2]
2706
2707 Later on (when defining some command) when twander runs into the
2708 variable reference [FB], it will keep substituting variables until
2709 all [...] references have been resolved or it hits the nesting
2710 limit (The default is 32, but you can change it with the MAXNESTING
2711 option). This limit has to be imposed to catch silly things like
2712 this:
2713
2714 Var = a[Var]
2715
2716 This recursive definition is a no-no and will be cause twander to
2717 generate an error while parsing the Configuration File and then
2718 terminate.
2719
2720 Your variable definitions can also nest other kinds of variables
2721 (Environment and Built-Ins). So, constructs like this are per-
2722 fectly OK:
2723
2724 Var1 = [$PAGER]
2725 Var2 = command-arguments
2726 V = [Var1] [Var2] [DSELECTION]
2727
2728
2729 o In the example above, notice that since the right-hand side of
2730 User-Defined Variables is literally replaced, we have to make sure
2731 there is space between the various variable references. If we used
2732 [Var1][Var2][DSELECTION] we would get one long string back instead
2733 of a command with arguments and a list of selected items.
2734
2735
2736
2737 o Variable references are only significant on the right hand side of
2738 an assignment statement:
2739
2740 Var1 = Foo
2741 My[Var1] = bar
2742
2743 This does not create a variable called "MyFoo". It creates a vari-
2744 able called "My[Var1]" and sets its value to "bar". This is both
2745 confusing and useless because you can never dereference this vari-
2746 able, because ...
2747
2748
2749 o Variable references cannot be nested. Using our example above,
2750 suppose we later want to get the value ("bar") of variable
2751 "My[Var1]". That variable reference would look like this:
2752 [My[Var1]] and this is not permitted. A variable reference may
2753 only contain a text string, not references to other variables.
2754
2755
2756 o Variables must be defined before they are referenced (in a Command
2757 Definition). You can, however, include not-yet defined variable
2758 name in another User-Variable Definition so long as all these vari-
2759 able are defined by the time they appear in a Command String. The
2760 following is OK because all variables are defined by the time they
2761 are actually needed:
2762
2763 Var1 = foo
2764 Var2 = [Var3] # This is just a string substitution, not a reference
2765 Var3 = bar
2766 MyVar = [Var1][Var2]
2767
2768 # Now comes the Command Definition
2769 # If we put this before the Variable Definitions above,
2770 # it would be an error.
2771
2772 x mycommand [MyVar]
2773
2774
2775 o Variable Names are case-sensitive - [EDITOR], [Editor], and [edi-
2776 tor] all refer to different variables.
2777
2778
2779 o The "#" character cannot be used in either the variable name or the
2780 replacement string since doing so begins a comment.
2781
2782
2783 o The "=" is what separates the Variable Name from the replacement
2784 string. Therefore, the "=" cannot ever be part of a Variable Name.
2785 A Variable Name cannot begin with "$" (see next bullet). Other
2786 than these minor restrictions, both Variable Names and Replacement
2787 Characters can be any string of characters of any length. Good
2788 judgment would suggest that Variable Names should be somewhat self-
2789 descriptive and of reasonable length - i.e., Much shorter than the
2790 replacement string!
2791
2792
2793 o A Variable Name must never begin with "$". This is because a Com-
2794 mand Definition containing a string in the form [$something] is
2795 understood by twander to be a reference to an Environment Variable,
2796 named "something". If you do this:
2797
2798 $MYVAR = some-string
2799
2800 You will never be able to subsequently reference it because,
2801 [$MYVAR] tells twander to look in the current environment, not its
2802 own symbol table to resolve the reference. However, note that "$"
2803 symbol may appear anywhere else but the first character of a vari-
2804 able name. So, for example, MY$VAR is fine.
2805
2806
2807 o Unlike previous versions of twander, Variable Names may be rede-
2808 fined. This makes it more convenient to exploit the ability for
2809 twander to process the contents of a Configuration File condition-
2810 ally (see the Conditional Processing Statements section below).
2811
2812 For example, you can set a variable to some default value, and then
2813 override it if a condition is satisfied:
2814
2815 # Assume we're running on a Unix-like system
2816
2817 MyEditor = [$EDITOR]
2818
2819 # Override this if we're on Windows
2820
2821 .if [.OS] == nt
2822 MyEditor = write
2823 .endif
2824
2825
2826
2827 Execution Variables
2828 Execution Variables are a special case of User-Defined Variables. How-
2829 ever, instead of setting a variable to some string of text, you tell
2830 twander to run a program and set it's results to the variable:
2831
2832 TODAY = [`date`]
2833
2834 Now, suppose you define a command with [TODAY] in it somewhere. When
2835 you later run that command, [TODAY] will be replaced by the output of
2836 the "date" command. In other words, Execution Variables allow you to
2837 run any external program you like, and have that program's output sub-
2838 stituted into the definition of a command. Several further points are
2839 worth noting here.
2840
2841
2842 o Notice that Execution Variables are delimited by backticks, not
2843 single-quotes.
2844
2845
2846 o If you have something like [`program`] in a Command Definition, it
2847 will be replaced with any text that "program" produces as it runs.
2848 That text will have any trailing newline stripped. Notice that
2849 this is different that most twander variables that are evaluated
2850 once when the Configuration File is first read in.
2851
2852 This is true wherever the execution variable appears - either as
2853 the right-hand-side of a variable statement or explicitly inline
2854 within a command definition. You can confirm this by looking at
2855 the User-Defined Variables and Command Definitions help menus.
2856 Anything referencing an execution variable will show the command to
2857 be executed when the variable is actually referenced at command
2858 invocation time.
2859
2860
2861 o Suppose you want to populate an Execution Variable with a program
2862 that returns multiple lines of text. You'll need to strip all the
2863 newlines out of the output in that case. To do this, you can use a
2864 second form of an Execution Variable: [`-program`]. The leading
2865 minus sign tells twander to strip all newlines when doing the
2866 replacement. For example, let's define a command that lists all
2867 the files in the current directory:
2868
2869 a mycommand echo "[`-ls`]" # We need the double-quotes
2870 # to make echo work right
2871
2872
2873
2874 Command Definitions
2875 The heart of the twander configuration process is creating of one or
2876 more Command Definitions. These definitions are the way user-defined
2877 commands are added to a given instance of twander. A Command Defini-
2878 tion consists of three fields separated by whitespace:
2879
2880 Command-Key Command-Name Command-String
2881
2882 The Command Key is any single character which can be typed on the key-
2883 board. This is the key that will be used to invoke the command from
2884 the keyboard. Command Keys are case-sensitive. If "m" is used as a
2885 Command Key, "M" will not invoke that command. Command Keys must be
2886 unique within a given Configuration File. If twander finds multiple
2887 Command Definitions assigned to the same Command Key, it will associate
2888 the last definition it finds with that Command Key. A Command Key can
2889 never be "#" which is always understood to be the beginning of a com-
2890 ment.
2891
2892 The Command Name is a string of any length containing any characters.
2893 This is the name of the command which is used to invoke the command
2894 from the Command Menu. Command Names are case-sensitive ("command" and
2895 "Command" are different names), but they are not required to be unique
2896 within a given Configuration File. That is, two different Command Def-
2897 initions may have identical Command Names associated with them, though
2898 this is not ordinarily recommended.
2899
2900 The Command String is any arbitrary string which is what twander actu-
2901 ally tries to execute when the command is invoked.
2902
2903
2904 A Simple Command Definition
2905 In its simplest form, a Command Definition looks like this:
2906
2907 # A simple Command Definition
2908 m MyMore more somefile
2909
2910 This command can be invoked pressing the "m" key on the keyboard or
2911 selecting the "MyMore" entry from the Command Menu - either directly
2912 from the menu or from the Command Menu Pop-Up. No matter how it is
2913 invoked, twander will then execute the command, "more somefile".
2914
2915 The problem is that this command as written actually will not give you
2916 the result you'd like (...well, on X-Windows - is does work on Windows
2917 as written). (For more details on why, see the GOTCHAS section below.)
2918 It turns out that starting a non-GUI program like 'more' in a new win-
2919 dow needs some extra work. What we want to do is run 'more' inside a
2920 copy of 'xterm'. Now our command looks like this:
2921
2922 # Our command setup to run as a GUI window
2923 m MyMore xterm -l -e more somefile
2924
2925
2926
2927 Forcing Display Updates In Command Definitions
2928 You are likely to define commands that change the contents of the cur-
2929 rently-viewed directory somehow. For instance, commands that rename,
2930 create, or delete files in the current directory all have this effect.
2931 When such a command is run, it means that the twander display is "out
2932 of sync" with the actual disk contents until the next refresh cycle -
2933 automatic if AUTORFRESH is enabled, manual otherwise.
2934
2935 Placing '+' symbol to the beginning of the Command String tells twander
2936 that, when the command is run, a display refresh should be forced
2937 afterwards. Not immediately afterwards, but AFTERWAIT seconds
2938 (default: 1) later. Why? To give the command in question a chance to
2939 complete before updating the display. For instance,
2940
2941 r removelogs +rm -f *log
2942
2943 This means that when the 'r' key is pressed, the command, "rm -f *.log"
2944 is run, and then, AFTERWAIT seconds later, twander will force a display
2945 update. This happens regardless of the current AUTOREFRESH settings.
2946
2947 This feature is handy, but has some practical limitations. If this
2948 feature updates the display before a command actually completes (i.e.,
2949 the command you've launched takes longer than AFTERWAIT seconds to com-
2950 plete), the final state of the directory will not be displayed. The
2951 idea here is to use this feature for "quicky" updates between more con-
2952 ventional display refreshes, whether via AUTOREFRESH or manually.
2953
2954 By default, anytime you run a command that uses this feature, any
2955 selections in the GUI are cleared. This is because a forced update
2956 presumably is required because the command changes something in the
2957 current directory. In that case, the current selections may no longer
2958 be relevant. If you wish to disable this behavior, set the AFTERCLEAR
2959 program option to False.
2960
2961
2962
2963 User-Defined Variables In A Command String
2964 The last example works quite nicely. But, we're probably going to end
2965 up using the string "xterm -l -e" over and over again for any shell
2966 commands we'd like to see run in a new window. Why not create a User-
2967 Defined Variable for this string so we can simplify its use throughout
2968 the whole Configuration File? Now, our command looks like this:
2969
2970 # Our command enhanced with a User-Defined Variable.
2971 # Remember that the variable has to be defined *before*
2972 # it is referenced.
2973
2974 XTERM = xterm -l -e # This defines the variable
2975 m MyMore [XTERM] more somefile # And the command then uses it
2976
2977
2978 Environment Variables In A Command String
2979 This is all very nice, but we'd really like a command to be generic and
2980 be easily used by a variety of users. Not everyone likes the "more"
2981 program as a pager. In fact, on Unix-like systems there is an environ-
2982 ment variable ($PAGER) set by each user which names the paging program
2983 that user prefers. We can refer to environment variables just like any
2984 other variable as explained previously. Now our command looks like
2985 this:
2986
2987 # Our command using both a User-Defined Variable and
2988 # an Environment Variable to make it more general
2989
2990 XTERM = xterm -l -e
2991 m MyMore [XTERM] [$PAGER] somefile
2992
2993
2994
2995 Execution Variables In A Command String
2996 We can further extend the power of Command Definitions by using an Exe-
2997 cution Variable to define part of the command. Suppose we want a com-
2998 mand that will let us examine all the text files in the current direc-
2999 tory:
3000
3001 # Our command using User-Defined, Environment, and
3002 # Execution Variables
3003
3004 XTERM = xterm -l -e
3005 m MyMore [XTERM] [$PAGER] [`-ls *.txt`]
3006
3007
3008
3009 Built-In Variables In A Command String
3010 It would also be really nice if the command applied to more than just a
3011 single file called "somefile". The whole point of twander is to allow
3012 you to use the GUI to select one or more directories and/or files and
3013 have your Command Definitions make use of those selections. twander
3014 uses a set of Built-In Variables to communicate the current directory
3015 and user selections to the any commands you've defined. Built-In Vari-
3016 ables are referenced just like User-Defined Variables and Environment
3017 Variables and may be inserted any appropriate place in the Command
3018 String. In our example, we probably want the command to pickup what-
3019 ever item the user has selected via the GUI and examine that item with
3020 our paging program. Now our command becomes:
3021
3022
3023 # Our command in its most generic form using
3024 # User-Defined, Environment, and Built-In Variables
3025
3026 XTERM = xterm -l -e
3027 m MyMore [XTERM] [$PAGER] [DSELECTION]
3028
3029 The "DSELECTION" built-in is what communicates the currently selected
3030 item from the GUI to your command when the command actually gets run.
3031
3032
3033 Selection-Related Built-Ins
3034 twander has a rich set of Built-In Variables for use in your Command
3035 Definitions. The first group of these is used to convey your current
3036 directory and items which you've selected to a Command Definition:
3037
3038
3039
3040 o [DIR]
3041
3042 [DIR] is replaced with the current directory twander is viewing.
3043
3044
3045 o [DSELECTION]
3046
3047 [DSELECTION] is replaced with the full path name of the item cur-
3048 rently selected in the GUI. If more than one item is selected,
3049 [DSELECTION] refers to the last item in the group (the bottom-most,
3050 not the most recent item you selected).
3051
3052
3053 o [DSELECTIONS]
3054
3055 [DSELECTIONS] is replaced with the full path name of all items cur-
3056 rently selected in the GUI.
3057
3058
3059 o [SELECTION]
3060
3061 [SELECTION] is replaced with the name of the currently selected
3062 item in the GUI. The path to that file is not included. As with
3063 [DSELECTION], if more than one item is selected in the GUI, the
3064 name of the last item in the group is returned for this variable.
3065
3066
3067 o [SELECTIONS]
3068
3069 [SELECTIONS] is replaced with the names of all items currently
3070 selected in the GUI. The path to those names is not included.
3071
3072
3073 Prompting And Special-Purpose Built-Ins
3074 There are also several special-purpose Built-In Variables which are
3075 used for creating more powerful Command Definitions.
3076
3077 Note: The PROMPT and YESNO Built-Ins use {} as delimiters, not [].
3078
3079
3080 o [HASH]
3081
3082 Because twander always recognizes the "#" as the beginning of a
3083 comment, there is no direct way to include this character in a Com-
3084 mand String. It is conceivable that some commands (such as 'sed')
3085 need to make use of this character. The [HASH] built-in is pro-
3086 vided for this purpose. Anywhere it appears in the Command String,
3087 it will be replaced with the "#" at command execution time. Unlike
3088 all the other Built-In Variables, [HASH] is never quoted when it is
3089 replaced in a Command String (regardless of whether the -t command
3090 argument is used or how the QUOTECHAR Program Option is defined).
3091
3092
3093 o {PROMPT:Prompt-String==>default}
3094
3095 {PROMPT:...} allows you to insert an interactive prompt for the
3096 user anywhere you'd like in a Command String. The user is prompted
3097 with the "Prompt String" and this variable is replaced with their
3098 response. If they respond with nothing, it is interpreted as an
3099 abort, and the command execution is terminated. This makes com-
3100 mands extremely powerful. For instance, say you want to create a
3101 group copy command:
3102
3103 # Copy a group of items to a location set by
3104 # the user at runtime
3105 UnixCopy = cp -R
3106 Win32Copy = copy
3107
3108 # Unix Version
3109 c UnixCP [UnixCopy] [DSELECTIONS] {PROMPT:Enter Destination}
3110
3111 # Win32 Version
3112 C Win32CP [Win32Copy] [DSELECTIONS] {PROMPT:Enter Destination}
3113
3114 You can also provide a default response to the question. The
3115 prompt is separated from the default by the '==>' string. This
3116 default separator string can be changed to anything you like with
3117 the DEFAULTSEP option.
3118
3119 This feature is useful when you want to provide the user the most-
3120 likely response to the prompt:
3121
3122 c UnixCP [UnixCopy] [DSELECTIONS] {PROMPT:Enter Destination==>/my/home/dir}
3123
3124 When the prompt is presented to the user, the default value is pre-
3125 loaded into the response field. The user can either accept or edit
3126 that string.
3127
3128
3129
3130 o {YESNO:Question-String==>Yes|No}
3131
3132 {YESNO:...} allows you to prompt the user with a dialog containing
3133 a Yes/No question and buttons for their response. If the user
3134 presses "Yes", command interpretation/execution continues. If the
3135 user presses "No", the command is aborted. This is handy when you
3136 want to make sure the user really wants to run the command before
3137 continuing. For instance, suppose you define a recursive
3138 file/directory deletion command. Before running it, it's good to
3139 prompt the user to confirm their intentions:
3140
3141 D BigDelete {YESNO:Are You Absolutely Sure About This?} rm -rf [SELECTIONS]
3142
3143 You can also provide a default response to the question. It must
3144 be either "Yes" or "No" (case-insensitive). Anything else will
3145 produce an error. The prompt is separated from the default by the
3146 '==>' string. This default separator string can be changed to any-
3147 thing you like with the DEFAULTSEP option.
3148
3149 This feature is handy because you can pre-select the most likely
3150 response to the dialog:
3151
3152 D BigDelete {YESNO:Are You Absolutely Sure About This?==>No} rm -rf [SELECTIONS]
3153
3154
3155
3156 Using Variable References Within Prompting Built-Ins
3157 You may have guessed that there is something special about the Prompt-
3158 ing Built-In Variables. After all, they use a different delimiter pair
3159 than all other variables in the twander configuration language. That's
3160 because you can include references to other variables within a Prompt-
3161 ing Built-In like this:
3162
3163 PromptYN = Are You Sure You Want To Do This?
3164 DefaultYN = No
3165
3166 a mycommand {YESNO:[PromptYN]==>[DefaultYN]} SomeDangerousCommand
3167
3168
3169 A more sophisticated use of this would be when creating a "rename" com-
3170 mand. You often want to rename a file by changing only a few of its
3171 characters, not the whole file name. Instead of forcing the user to
3172 type the whole name in over again, why not just do this:
3173
3174 Prompt = New File Name?
3175 r rename mv [SELECTION] {PROMPT:[Prompt]==>[SELECTION]}
3176
3177 Now when the user runs the command, the default string will be the name
3178 of the file to be renamed. They can move around inside the dialog box
3179 created by {PROMPT: ...} at runtime to edit the existing file name to
3180 taste.
3181
3182 You can also use Execution Variables inside a prompting Built-In:
3183
3184 d setdate SomeDateCommand {PROMPT:Set Date To: ===>[`date`]}
3185
3186
3187
3188 Program Memory Built-Ins
3189 As described previously, twander implements an advanced notion of a
3190 Clipboard called "Program Memories". There is a corresponding group of
3191 Built-In Variables which allows the contents of these memories to be
3192 used in a Command Definition:
3193
3194
3195 o [MEM1] ... [MEM12]
3196
3197 Return the file/directory names currently stored in the indicated
3198 memory. For example, to move all the files/directories currently
3199 named in the first Program Memory to the current directory we could
3200 define a move command like this:
3201
3202 m move mv [MEM1] ./
3203
3204
3205 Notes On Built-In Variable Use
3206 o Built-In Variables which return a directory name do NOT append a
3207 path separator character ("/" or "\") to the end of the name even
3208 though it is visible in the GUI. This provides maximum flexibility
3209 when defining commands. It is up to the command author to insert
3210 the appropriate path separator character where needed. (NOTE: Ear-
3211 lier releases of twander did include the trailing path separator
3212 and you may have to edit older Configuration Files accordingly.
3213 This change was necessary because certain commands like Unix 'cp'
3214 will not work if given a source directory with the path separator
3215 included.)
3216
3217 For example, another way to express the full path of the currently
3218 selected item is:
3219
3220 # Unix Path Separator
3221 UPSEP = /
3222
3223 #Win32 Path Separator
3224 WPSEP = \
3225
3226 [DIR][UPSEP][SELECTION]
3227
3228 - or -
3229
3230 [DIR][WPSEP][SELECTION]
3231
3232 Be aware that, because of twander quoting rules, such constructs
3233 will result in strings like:
3234
3235 "/mydir"/"myfile"
3236
3237 - or -
3238
3239 "C:\mydir"\"myfile"
3240
3241 This should not generally be a problem with the various Unix
3242 shells, and may work for some Windows commands. However, some Win-
3243 dows programs (noted in 'notepad') reject this kind of filename
3244 when passed on the command line. The workaround (and a generally
3245 easier way to do this sort of thing), is to use the [DSELECTION]
3246 built-in which returns the full path name of an item as a single
3247 quoted string.
3248
3249
3250
3251 o All User-Defined, Environment, and Execution Variables are pro-
3252 cessed each time a command is run. This is especially important
3253 for Execution Variables. The variable will be "executed" each time
3254 the Command Definition in which it is referenced is run.
3255
3256
3257 o Similarly, Built-In Variables are resolved on each command invoca-
3258 tion, i.e - at command runtime. The Built-Ins will always reflect
3259 the current set of files selected in the user interface.
3260
3261
3262 o The results of all built-ins (except HASH) are put inside double-
3263 quotes when they are replaced in the Command String. This default
3264 is recommended so that any built-in substitutions of, say, file-
3265 names with spaces in them, will be properly recognized by your com-
3266 mands. You can suppress the addition of double-quotes by using the
3267 -t command line option when starting twander.
3268
3269
3270 o Any of the variable types may appear multiple times in the same
3271 Command String. For example, suppose you want to define a generic
3272 Unix copy command:
3273
3274 g gencopy cp -R {PROMPT:Enter Source} {PROMPT:Enter Destination}
3275
3276 When the user presses "g" (or clicks on "gencopy" on the Command
3277 Menu), they will be presented with two prompts, one after the
3278 other, and then the command will run.
3279
3280
3281
3282 Associations
3283 Most X-Windows desktops and Microsoft Windows support the idea of
3284 "associations". That is, based on the name of a file, they "associate"
3285 an application that can handle it. So, for example, a filename ending
3286 in ".txt" is handled by a text editor, a filename ending in ".ps" is
3287 handled by a PostScript processing program, and so on. This is handy
3288 inside of visual interfaces because you can double-click on a file and
3289 the interface can infer which program to load to process that file.
3290
3291 The problem is that the various X desktops and Microsoft Windows don't
3292 all handle associations the same way. Some lighter X-Windows desktop
3293 may not even have associations at all. In order for to remain portable
3294 across operating systems, and work more-or-less the same way every-
3295 where, association support has been implemented directly within twander
3296 itself.
3297
3298 All you have to do is tell twander which program to use for a given
3299 file "type". A "type" is defined as a group of files whose names match
3300 a so-called "wildcard" (more on that in a moment). You do this by
3301 adding association statement to the Configuration File:
3302
3303
3304 # Associations are in the form:
3305 # ASSOC file-type-string command-to-handle-this-type-of-file
3306
3307 ASSOC *.txt emacs [SELECTION]
3308
3309 Thereafter, when twander runs, the "emacs" command will be loaded to
3310 process any file whose name ends in ".txt" when the user selects that
3311 file and either double-clicks on it or presses "Enter". On Windows
3312 systems, this check is done in a case-insensitive way, so the associa-
3313 tion above would match files ending in, ".txt", ".TXT", ".Txt", and so
3314 on. On Unix-like systems, the check is case-sensitive and the type
3315 string must match exactly.
3316
3317 Notice that the "handler command" can consist of pretty much anything
3318 that you can use in a command definition (as described in the previous
3319 sections). For instance, you can do things like:
3320
3321
3322 EDITOR = emacs -fn 10x20
3323
3324 ASSOC *.txt {YESNO:Are You Sure You Want To Edit This File?} [EDITOR] [SELECTION]
3325
3326 You can also insert special association command that will be used if no
3327 other explicit association matches. Think of this as a "default" asso-
3328 ciation:
3329
3330 ASSOC *.pdf mypdfreader [SELECTION]
3331 ASSOC *.ps mypostscriptprogram [SELECTION]
3332 ASSOC * myfineeditor [SELECTION] # Default association
3333
3334 In this example, if you double-click or press "Enter" on any file not
3335 ending in either ".pdf" or ".ps", the default association action will
3336 be taken: The file will be opened with myfineeditor.
3337
3338 You can also define a list of file types to be excluded from associa-
3339 tion processing. This is handy if you want to use the default associa-
3340 tion feature for everything except a particular set of file types.
3341 This feature is primarily useful on Windows systems where you want to
3342 define your own default action, but want a few particular types of
3343 files to use the underlying Windows associations.
3344
3345 To do this, put one or more statements in the following form in your
3346 Configuration File:
3347
3348 ASSOC ! space-separated-list-of-file-types
3349
3350
3351 For example:
3352
3353 ASSOC * myfineeditor [SELECTION]
3354 ASSOC ! *.txt *.pyo *.ps
3355
3356 With this configuration, all files would, by default, be handled with
3357 myfineeditor except files whose names end with .txt, .pyo, or .ps.
3358 These excluded file types would be handed to the underlying OS for pro-
3359 cessing when they are selected.
3360
3361 Note that exclusion has higher precedence than any explicit associa-
3362 tion, not just the default association. If you do this:
3363
3364 ASSOC *.pdf mypdfreader [SELECTION]
3365 ASSOC ! .pdf
3366
3367 You are effectively masking the explicit association for .pdf files.
3368
3369 You can also remove a previously defined association by leaving the
3370 right-hand-side of the ASSOC statement blank:
3371
3372 # This example first defines, and then removes an association
3373 # for .pdf files:
3374
3375 ASSOC *.pdf mypdfreader [SELECTION]
3376 ASSOC *.pdf
3377
3378 # This one removes any exclusions you might have previously defined
3379
3380 ASSOC !
3381
3382 # This one removes any default association you might have previously defined
3383
3384 ASSOC *
3385
3386
3387 This feature is primarily useful when you want to define associations
3388 conditionally. That is, you can remove an association if a particular
3389 conditional block is true. A typical use for this might be to get dif-
3390 ferent (or remove) associations based on what OS you're running. (See
3391 the section below entitled: Conditional Processing Statements ).
3392
3393
3394
3395 Association Wildcards
3396 Associations are built around the idea of a file "type". You want
3397 files of the same type handled by the same application program. On
3398 Windows systems, this has traditionally been the set of characters the
3399 follow the period at the end of the filename. But this convention is
3400 not consistently used on Unix-like systems. twander lets you use a
3401 fairly powerful "wildcarding" system to define what is common about the
3402 names of all files of a given type. Unix users will recognize this as
3403 the shell globbing wildcards. Here they are implemented for both Win-
3404 dows and the Unix-like systems in the same way. The only difference is
3405 that, on Windows, the check for a match ("is this file of type ...?")
3406 is done without regard to case, whereas on the Unix-like systems, case
3407 matters.
3408
3409 If you are unfamiliar with Unix-style shell globbing, many references
3410 can easily be found on the web. Here is a summary of the "meta" char-
3411 acters supported:
3412
3413
3414 * Matches everything - strings of any length with any characters
3415
3416 Example: *.text matches all filenames ending in ".text"
3417
3418 ? Matches a single character
3419
3420 Example: foo.??? matches all filenames beginning with "foo."
3421 and ending with any three characters.
3422
3423 [list] Matches any characters in the list
3424
3425 Example: foo*[tT] matches all filenames beginning with "foo",
3426 with any number of characters following, and
3427 ending with either the letters "t" or "T".
3428
3429 [!list] Matches any character NOT in the list
3430
3431 Example: foo*[!tT] matches all filenames beginning with "foo",
3432 with any number of characters following, and NOT
3433 ending with either the letters "t" or "T".
3434
3435 Lists can also be ranges. For example:
3436
3437 [a-z] Matches any lowercase letter
3438 [A-Z] Matches any uppercase letter
3439 [0-9] Matches any numeric digit
3440
3441 So, why bother with this? Because sometimes you want associate an
3442 action with a set of files whose names are similar but vary in some
3443 known way. For instance, suppose you have a database program that pro-
3444 duces files named "data01, data02, data03, ..." and so on. Instead of
3445 having to write a separate association for each different possible
3446 filename, you can just do this:
3447
3448
3449 ASSOC data?? MyFineDatabaseProgram [SELECTION]
3450
3451
3452
3453 Forcing Association Case Insensitivity
3454 Associations on Win32 are case insensitive because the underlying oper-
3455 ating system - while it preserves case - does not observe case distinc-
3456 tions in file and directories. On Unix-like systems, however, the
3457 underlying operating system is case sensitive, so case matters when
3458 defining associations for such systems.
3459
3460 There are circumstances where ignoring case in an association can be
3461 helpful, even in Unix-like systems. For example, if you'd like to as-
3462 sociate an application with text files, it is annoying to have to write
3463 individual associations for "*.txt", "*.Txt", "*.TXT", and so on.
3464 Forcing case insensitivity allows us to write one association rule that
3465 matches each of these file types:
3466
3467
3468 ASSOC ! /*tXt # Exludes files ending in txt, TXT, TxT, TXt, ...
3469 ASSOC /*txT emacs [SELECTION] # Invokes emacs for files ending as above
3470
3471
3472 Prepending the "/" character to the association pattern is what tells
3473 twander to ignore case when doing the matching.
3474
3475 Notice that exclusions have higher precedence than associations. In
3476 the example above, files ending in txt, Txt, and so on would always be
3477 excluded and the association with emacs would never happen.
3478
3479 To cancel a case insensitive association you must use the exact string
3480 originally used to establish the association:
3481
3482
3483 ASSOC /*txT emacs ....
3484 ASSOC *txT # Does NOT undo the previous association
3485 ASSOC *txt # Neither does this
3486 ASSOC /*txT # But this does
3487
3488
3489
3490
3491 A Few Association Subtleties
3492 o The ASSOC keyword itself is case-sensitive - you must enter it
3493 entirely in upper-case. However, the order of ASSOC statements is
3494 unimportant. twander distinguishes ASSOC statements by their
3495 unique file "type" strings. Well ... this is true so long as you
3496 make sure the type strings are unique! Suppose you put this in
3497 your Configuration File:
3498
3499
3500 ASSOC *.text emacs [SELECTION]
3501 ASSOC *xt ci [SELECTION]
3502
3503 A file whose name ends in ".text" will match both of these associa-
3504 tions. So which one does twander use? There is no way to tell -
3505 it's a nonsense condition when a given file type matches more than
3506 one association. The moral of the story here is to make sure each
3507 of your ASSOC statements associates a completely unique file type.
3508 Be really careful about this when using complex wildcards to spec-
3509 ify the file "type". It's easy for wildcards to overlap in their
3510 definition of a filename and you'll end up with more than a sin-
3511 gle, unique association for a given type of file.
3512
3513
3514 o The "default" association - if defined - will only be applied if no
3515 explicit association for a given selection is found and the file in
3516 question is not executable. That way, you can still double-click
3517 (or press "Enter") on executable files to run them without the
3518 default association getting in the way. Of course, if you've
3519 explicitly defined an association for the type of executable file
3520 selected, then that will be applied to the selected file. This can
3521 be handy if, say, you don't want to actually run the executable,
3522 but just edit it when you double-click on it.
3523
3524
3525 o Be careful which Built In Variables you use in an association han-
3526 dler definition. Suppose you do this:
3527
3528 ASSOC *.txt emacs [SELECTIONS]
3529
3530 Note the use of the multiple selection Built In Variable, [SELEC-
3531 TIONS] (as opposed to the single selection [SELECTION] used in the
3532 previous examples). What happens when you double-click or press
3533 "Enter" when multiple files have been selected in the twander
3534 interface? Well, it depends. The program decides which associa-
3535 tion to use based on the last filename you have selected. Suppose,
3536 in order, you select "foo.c", "bar.py", and "baz.txt". Since the
3537 last file selected ends with ".txt", the handler defined above will
3538 match and all the files will be processed using this association.
3539 This may not be what you want.
3540
3541 Even stranger things can happen if the last filename selected is an
3542 executable and you've defined an association for it:
3543
3544 ASSOC *.py python [SELECTIONS]
3545
3546 Say you select "foo.c" and "bar.py". Since "bar.py" is the last
3547 file in the multiple selection, it will match the association
3548 above. This will effectively produce a command that like this:
3549
3550 python foo.c bar.py
3551
3552 Which is, um ... bogus.
3553
3554 As a general matter, multiple selection Built Ins are fine if you
3555 are specifying an association handler that does things like edit-
3556 ing, viewing, printing, and so on. But be wary of them if the han-
3557 dler runs some language processor or other program that expects the
3558 content of its arguments to be in a particular format.
3559
3560
3561
3562 Associations Differences Across Platforms
3563 For the most part, twander associations work pretty much the same way
3564 on all systems . There are, however, some slight differences between
3565 the Unix-like systems and Windows.
3566
3567
3568 o On Unix-like operating systems twander ignores the underlying asso-
3569 ciations (if any) of the system and/or X desktop. It only observes
3570 its own associations. That's because there is no consistent asso-
3571 ciation mechanism across the many OS and desktop variants in use on
3572 those platforms.
3573
3574 But Microsoft Windows is a different matter. All modern variants
3575 of these systems have consistent built-in support for association.
3576 twander was designed to "play nice" with the underlying associa-
3577 tions defined in the Windows registry. It works very simply: An
3578 association defined in twander will take precedence over the native
3579 Windows association. Say you define this:
3580
3581 ASSOC .txt myowneditor [SELECTION}
3582
3583 Then double-clicking "foo.txt" will cause "myowneditor" to be
3584 invoked, even though Windows, by default, associates "notepad" with
3585 text files.
3586
3587 If no matching twander association is found for a particular selec-
3588 tion, then the execution request is handed to Windows, and it's
3589 association for that file type (if any) will be applied.
3590
3591 This is a very handy feature. You may wish to temporarily or per-
3592 manently change which program is associated with a given file type
3593 when you're running twander. Instead of having to fiddle around
3594 with reassociating things in Windows, you can just edit the twander
3595 Configuration File.
3596
3597
3598
3599 o As noted in the previous section, matching the file "type" is case-
3600 sensitive on Unix-like systems and case-insensitive under Windows.
3601 This is because, although Windows observes case in file names, they
3602 are not signficant. Similarly, file types listed in the associa-
3603 tion exclusion list are treated in a case-insensitive way on Win-
3604 dows systems.
3605
3606
3607 o On Unix-like systems, if you attempt double-click or press Enter on
3608 a file that cannot be executed, twander will display an error.
3609 This happens anytime the file is non-executable and you've not
3610 defined an association that matches it.
3611
3612 On Windows, twander does not do this. It simply passes the request
3613 on to Windows. It does this in case there is a native Windows
3614 association that applies for that file. If Windows cannot execute
3615 the file, it will present an error message of its own.
3616
3617
3618 Conditional Processing Statements
3619 Most of twanders power lies in its ability to be customized to each
3620 different user and operating system via its Configuration File. To
3621 make this a bit easier to manage, the twander configuration language
3622 recognizes so-called "Conditional Processing Statements". These state-
3623 ments give you the ability to write a single Configuration File which
3624 automatically tailors itself to run twander properly wherever you are
3625 running.
3626
3627 The general idea is to define a "Condition Block" which begins by doing
3628 a logical test. If that test evaluates to True, all statements in the
3629 block are included in the current configuration. If the test evaluates
3630 to False, all statements to the end of the block are ignored.
3631
3632 A Conditional Block always begins with a "Condition Test Statement" and
3633 ends with the ".endif" statement. Conditional Processing Statements
3634 may be nested without limit. twander keeps track of which '.endif'
3635 matches which Condition Test Statement. Like all Configuration File
3636 entries, whitespace is ignored when processing Conditional Statements
3637 and you are free to indent (or not) as you see fit.
3638
3639 Condition Test Statements are one of three types:
3640
3641 #####
3642 # Existential: True if FOO or $FOO are defined
3643 #####
3644
3645 .if [FOO]
3646 ...
3647 .endif
3648
3649 .if [$FOO]
3650 ...
3651 .endif
3652
3653 #####
3654 # Equality: True if FOO or $FOO are literally
3655 # the same as the test-string
3656 #####
3657
3658 .if [FOO] == test-string
3659 ...
3660 .endif
3661
3662 .if [$FOO] == test-string
3663 ...
3664 .endif
3665
3666 #####
3667 # Inequality: True if FOO or $FOO are literally
3668 # not the same as the test-string
3669 #####
3670
3671 .if [FOO] != test-string
3672 ...
3673 .endif
3674
3675 .if [$FOO] != test-string
3676 ...
3677 .endif
3678
3679 To make it easy to create conditional blocks based on the type of sys-
3680 tem you're running, twander automatically pre-defines two variables
3681 which provide information about your system: .OS (typically: nt, posix)
3682 and .PLATFORM (typically: freebsd4, linux-i386, win32). You should run
3683 twander and examine the "User-Defined Variables" section of the Help
3684 Menu to see how these variables are set on your system.
3685
3686 These predefined variables show up as "User Defined Variables" in the
3687 various twander Help and Debug outputs, but they begin with a period to
3688 remind you of their intended role. They will thus also sort first in
3689 the User-Defined Variables section of the Help Menu.
3690
3691 Several things about Conditional Processing Statements are worth not-
3692 ing:
3693
3694
3695 o Whitespace is mandatory after the ".if" statement - .if[FOO] is
3696 syntactically incorrect. However, you need no whitespace on either
3697 side of a "==" or "!=" test.
3698
3699
3700 o All these tests involve either a User-Defined Variable or an Envi-
3701 ronment Variable, never a Program Option or Built In Variable.
3702
3703
3704 o A Condition Test Statement always involves a variable reference
3705 ("[FOO]", never just "FOO") because we want the contents, not the
3706 name, of the variable for the test.
3707
3708
3709 o The Right Hand Side of an (in)equality test is just a string com-
3710 parsion - no variable expansion is done:
3711
3712 .if [FOO] == string[BAR]
3713
3714 This will not work as you might expect because the contents of
3715 variable FOO are literally compared to the string, "string[BAR]".
3716 Note too that this comparison is case-sensitive.
3717
3718
3719 o The ".endif" statement must appear on the line by itself. Nothing
3720 other than whitespace may precede it, and nothing (other than
3721 whitespace or a comment) may follow it.
3722
3723
3724 See the example ".twander" file provided in the distribution for some
3725 extended examples of using conditionals in your Configuration File.
3726 Also see the GOTCHAS section below for further discussion.
3727
3728
3729 The Include Directive
3730 You may include other files in your Configuration File with the follow-
3731 ing directive:
3732
3733 .include path-to-file
3734
3735 You may place as many of these statements in your Configuration File as
3736 you wish. The only syntactic requirement is that there must be white-
3737 space between the directive and the file path. twander makes no
3738 attempt to validate that path, and you will see an warning message if
3739 the file you specify cannot be opened.
3740
3741 The most common reason to do this is to maintain a "standard" configu-
3742 ration in a separate file which is controlled by the system administra-
3743 tor. This is especially handy on larger systems with multiple users.
3744 The system administrator provides a read-only copy of the standard con-
3745 figuration in a place anyone can read it. Everyone is free to use (but
3746 not modify) that standard configuration. You are then free to add to,
3747 or even override the standard configuration content with statements of
3748 your own following the ".include". Suppose you have the following
3749 "standard" Configuration File available on your system:
3750
3751 # Contents of /usr/local/etc/.twander.global
3752
3753 SHELL = bash -c
3754 XTERM = xterm -fn 9x15 -l
3755 VSHELL = [XTERM] -e [SHELL]
3756
3757 DIRSC1 = /usr/local
3758 DIRSC2 = /usr/sbin
3759
3760 t terminal [XTERM]
3761
3762
3763 Now, you can create your own personal Configuration File which takes
3764 advantage of this standard file, but augments it with additional con-
3765 figuration information of your choosing:
3766
3767 # Contents of $HOME/.twander
3768
3769 .include /usr/local/etc/.twander.global
3770
3771 DIRSC2 = /etc
3772
3773 l ls [VSHELL] 'ls -al | [$PAGER]'
3774
3775
3776 Keep in mind that twander reads the contents of its Configuration File
3777 in order. In this case, it means that all of "/usr/local/etc/.twan-
3778 der.global" is read and then the rest of "$HOME/.twander" is read. If
3779 something is defined more than once, the last definition is what is
3780 used. In this case, DIRSC2 is overriden in the local Configuration
3781 File and is ultimately assigned to "/etc". Similarly, you can override
3782 previous definitions for User-Defined Variables and even Command Defi-
3783 nitions.
3784
3785 The program checks to see if you attempt to do a "circular" include.
3786 For example, say file "A" .includes file "B" and file "B" then
3787 .includes file "A". This wold create a neverending "circle" of
3788 included files. If twander detects this, it will display an error
3789 describing the problem and skip the offending line.
3790
3791
3792
3793 ADVANCED WINDOWS FEATURES
3794 As shipped from the factory, twander runs pretty much identically on
3795 various Unix variants (FreeBSD, Linux) and Windows. However, twander
3796 is written to take advantage of Mark Hammond's 'win32all' Python exten-
3797 sions if they are present on the system. These extensions add many
3798 Windows-specific features to Python and allow twander to provide quite
3799 a bit more Windows-centric information about files, directories, and
3800 drives. You do not have to install 'win32all' for twander to operate
3801 properly on your Windows system. Installing this package just means
3802 you'll get even more twander features on Windows than you would other-
3803 wise. If you've installed 'win32all', you can toggle these features
3804 on- and off with the TOGWIN32ALL key described above.
3805
3806
3807 Getting 'win32all'
3808 You can get the 'win32all' extensions one of two ways. If you've
3809 installed the Active State version of Python for Windows,
3810 (http://www.activestate.com/Products/ActivePython/) 'win32all' is
3811 already installed on your system. If you installed the standard Python
3812 release for Windows (http://www.python.org/download/download_win-
3813 dows.html), you must add 'win32all' to your installation. You'll find
3814 the extensions and painless installation instructions at: http://star-
3815 ship.python.net/crew/mhammond/
3816
3817
3818 New Features Supported With 'win32all'
3819 One important note is in order here: The features enabled by 'win32all'
3820 are only available on "true" Windows systems like Windows 2000 and Win-
3821 dows XP. Earlier versions of Windows like Win98 and WinME emulate por-
3822 tions of the Win32 API and do not implement the advanced security fea-
3823 tures found in the NTFS file system. Therefore, as noted below, some
3824 of these features will not work on any of the older 16-bit Windows
3825 operating systems. twander handles this gracefully without blowing-up
3826 so you can safely have 'win32all' installed on one of these older sys-
3827 tems to take advantage of the features that do work.
3828
3829 Once you have these extensions installed, twander will automatically
3830 enable three new features otherwise unavailable.
3831
3832
3833 o When viewing file/directory detail information, the owner and group
3834 names will be the actual names reported by the operating system
3835 rather than the filler values normally seen in those fields
3836 ('win32owner' and 'win32group'). (Does not work on older Windows
3837 systems like Win98.)
3838
3839
3840 o Instead of showing Unix-style file permissions (which don't mean
3841 much under Windows), systems with 'win32all' installed will show
3842 the so-called "file attributes" maintained by the operating system.
3843 Each detailed entry in the display will have one or more of the
3844 following attributes displayed in what is normally the Unix permis-
3845 sions field:
3846
3847 d - Directory
3848 A - Archive
3849 C - Compressed
3850 H - Hidden
3851 N - Normal
3852 R - Read-Only
3853 S - System
3854
3855
3856 o A top-level "Drive List View" is enabled if 'win32all' is
3857 installed. This shows you a list of all currently available drives
3858 reachable by the system, and information about those drives. For
3859 locally attached drives, the drive label is shown. For network-
3860 attached drives, the share string is shown. The drive type
3861 (CD/DVD, Fixed, Ramdisk, Remote, Removable) is shown as are the
3862 free, and total space statistics. As is the case with other twan-
3863 der displays, these details can be toggled on- and off via the
3864 TOGDETAIL key.
3865
3866 You can enter the Drive List View in a number of ways:
3867
3868 1) Select the ".." from the root directory of any drive.
3869 2) Enter the string "\\" from the CHANGDIR dialog.
3870 3) Press the DRIVELIST key. (default: Control-k)
3871 4) Start twander using "\\" as the starting directory
3872 argument, either on the command line or using the
3873 Configuration File STARTDIR option.
3874
3875 The "Drive List View" is available on all Windows variants, however
3876 the free/total space values will be incorrect on older systems like
3877 Win98.
3878
3879
3880 Notes On Drive List View
3881 The Drive List View is a little different than the usual file/directory
3882 view. Program behavior (semantics) is thus also slightly different
3883 than usual in several ways:
3884
3885
3886 o While in Drive List View, the various Built-In Variables which
3887 return the current selections will return the name or names of the
3888 selected drive(s) (without a trailing slash) just as you would
3889 expect them to in a normal file/directory view. This allows you to
3890 write commands which take drive names (letters) as an argument.
3891 The [DIR] Built-In returns an empty string in this view.
3892
3893
3894 o Normally, as you navigate around a file system, twander sets its
3895 own program context to the current directory. This is why you can
3896 write Command Definitions using only the file/directory name cur-
3897 rently selected - twander knows the current directory. When you
3898 are in Drive List View, the notion of "current directory" has no
3899 real meaning. So, twander treats the directory from which you
3900 entered Drive List View as the "current directory" while in that
3901 view.
3902
3903
3904 o By default, twander automatically rereads the current view about
3905 every 3 seconds. This is fine for a file/directory view but would
3906 be annoyingly slow in the Drive List View since it takes a moment
3907 or two to get the status of any floppy disk drives attached to the
3908 system. Instead of forcing the user to listen to (and wait for)
3909 the floppy drive status to be determined every 3 seconds, twander
3910 only reads the drive information once when it enters Drive List
3911 View. This means if a drive is connected or a floppy is inserted
3912 into the system while in Drive List View, this fact will not be
3913 automatically noted. You can force a manual update of the Drive
3914 List View by pressing the REFRESH key. (default: Control-l)
3915
3916
3917 o The TOGWIN32ALL key (default: Control-w) is disabled in Drive List
3918 View. Drive List View is only available in 'win32all' mode and
3919 toggling that mode off makes no sense here.
3920
3921
3922 o The SELALL (default: Control-comma) and SELINV (default: Control-i)
3923 features work slightly differently in Drive List View than they do
3924 otherwise. Ordinarily, these features never select the first item
3925 of a file/directory display because it is always the ".." entry
3926 pointing to the directory parent. In Drive List View, the first
3927 entry is an entry of interest - usually, but not always, Drive A: -
3928 so these two keys do select it as is appropriate.
3929
3930
3931 Disabling 'win32all' Features
3932 You can toggle these features on-and off using the TOGWIN32ALL key.
3933 (default: Control-w) You can also permanently disable them by setting
3934 the USEWIN32ALL option to False in the Configuration File. This allows
3935 you to leave 'win32all' installed on your system if you need it for
3936 other reasons but don't want these features enabled in twander
3937
3938
3939
3940 GOTCHAS
3941 There are several tricky corners of twander which need further explana-
3942 tion:
3943
3944
3945 Program Starts Very Slowly
3946 twander attempts to determine the name of the host on which it is run-
3947 ning at program startup. This is used in the title bar display. It
3948 first looks to see if the environment variable HOSTNAME is set, and
3949 uses that value if it is. If this variable is not set, twander does a
3950 socket call to see if it can determine the hostname that way.
3951
3952 Either of these methods works fine, but the socket call can be very
3953 slow if the network is misconfigured or malfunctioning. If twander is
3954 starting very slowly, try setting HOSTNAME explicitly in your environ-
3955 ment - this will prevent the socket call from ever taking place. A
3956 simple way to do this with 'ksh' or 'bash' is:
3957
3958 export HOSTNAME=`hostname`
3959
3960 (Note the backticks used to execute the 'hostname' program and assign
3961 its results to HOSTNAME.)
3962
3963 Be aware that 'bash' claims to automatically set this variable when it
3964 starts. However, it does not appear to export it properly on some sys-
3965 tems (noted on FreeBSD 4.7 with 'bash' 2.05b). In this case, you have
3966 to do this manually as just described even when using 'bash'
3967
3968 On Windows, environment variables are set via the System Properties
3969 menu.
3970
3971
3972
3973 Program Loads Slowly
3974 twander is a fairly large Python program and can take a few seconds to
3975 load and initialize, especially on older, slower systems. You can
3976 speed this up a bit by creating an optimized byte-code version of the
3977 program as follows (make sure you have appropriate administrative per-
3978 mission to do this):
3979
3980 1) Go to the directory where the twander.py file is located.
3981 2) Type the following command: python -O
3982 3) Once Python is loaded type: import twander
3983 4) Exit twander.
3984 5) Exit Python by pressing Control-d on Unix or
3985 Control-z on Windows.
3986 6) You will now see a new file in this directory: twander.pyo
3987 This file should be significantly smaller than twander.py.
3988 7) Now you can run the program by entering: python twander.pyo
3989 on Unix/Windows or pythonw twander.pyo on Windows.
3990 8) You have to repeat this procedure each time you install
3991 a new version of twander.py
3992
3993
3994 Cannot Enter Certain Directories On Windows
3995 Windows allows file/directory names to contain non-ASCII characters.
3996 Python, as shipped, defaults to ASCII only and grumbles mightily when
3997 it is asked to deal with a string containing characters with ordinal
3998 values greater than 127 (i.e., 8-Bit "extended" ASCII). The solution
3999 to this problem is to enable Python to handle non-ASCII strings. This
4000 is done by editing a file called "site.py". This file is normally
4001 found in:
4002
4003 C:\Program Files\PythonXX\Lib
4004
4005 Where "XX" is the actual version of Python you're running.
4006
4007 Open this file with an editor and look for the following text:
4008
4009 encoding = "ascii" # Default value set by _PyUnicode_Init()
4010
4011 if 0:
4012 # Enable to support locale aware default string encodings.
4013 import locale
4014
4015 Change the if 0: statement to if 1: and the problem will disappear.
4016
4017
4018
4019 Getting Command Results Displayed In A New Window
4020 When you invoke a command via twander (whether via a command definition
4021 in the Configuration File or the keyboard shortcut), you generally want
4022 it to run in a new window. This turns out to be tricky on Unix-like
4023 systems. If the program you are running is GUI-aware, this should not
4024 be a problem. However, if you are using twander to run a command line
4025 program or script, you have to take extra care in the formulation of
4026 the Command String. In the case of Unix-like systems you have to
4027 invoke the command so that it runs in some GUI context. Say you want
4028 to use a pager like 'less' to view files. You would expect that this
4029 entry might do it:
4030
4031 V view less [DSELECTIONS]
4032
4033 Sadly, this will not work, at least not the way you expect. If you
4034 started twander from a terminal session and use the command above, it
4035 will work, but the results will appear in the invoking terminal window,
4036 not in a new window as you might expect. If you started twander from a
4037 GUI or disconnected it from the initiating terminal with a 'nohup' ...
4038 & invocation, you will get no output. This is not a twander problem,
4039 it is innate to how command line programs run under Unix shell control.
4040
4041 To achieve the desired results, you have to create a new GUI window in
4042 which your command can run and display results. The easiest way to do
4043 this is to run your command in a new 'xterm' window like this:
4044
4045 V view xterm -l -e less [DSELECTIONS]
4046
4047 Some program further require you to provide a shell so they can execute
4048 correctly. For instance, running 'ls' in a command definition requires
4049 something like this:
4050
4051 L lshome xterm -l -e bash -c 'ls / | [$PAGER]'
4052
4053 In fact, this idiom is so common, you will see variables defined in the
4054 example ".twander" file to simplify such definitions (comments
4055 removed):
4056
4057 SHELL = bash -c
4058 VSHELL = [XTERM] [SHELL]
4059 XTERM = xterm -fn 9x15 -l -e
4060
4061 Now you can write the command above like this:
4062
4063 L lshome [VSHELL] 'ls / | [$PAGER]'
4064
4065
4066 This causes your command line program to execute in an 'xterm' context
4067 and under a shell interpreter.
4068
4069 This is not as much an issue on Windows systems where the first form of
4070 the command above works fine. Windows appears to have no problem
4071 invoking a new window whether the command is GUI-aware or not.
4072
4073 However, which terminal window is used for output can be confusing. If
4074 you start twander from a terminal session, all terminal output will be
4075 sent to the terminal session you used to invoke the program. The way
4076 to work around this is to start twander from a Windows shortcut, using
4077 'pythonw.exe' rather than 'python.exe'. Now each time you run a com-
4078 mand that needs a terminal session for output, Windows will automati-
4079 cally create that session for you.
4080
4081
4082
4083 Using Shell Wildcards In Command Definitions
4084 The {PROMPT:...} Built-In Variable is provided to make it possible to
4085 write general-purpose commands which interact with the user. For exam-
4086 ple, you might want to define a directory listing command for Windows
4087 like this:
4088
4089 L DirList dir {PROMPT:Directory Of What?} | more
4090
4091 When the user presses the "L", they are presented with a dialog box
4092 into which they enter their directory name or wildcard pattern such as
4093 "\*.bat" and everything works as expected.
4094
4095 On Unix-like systems, however, this does not work as expected. Suppose
4096 we define the command for these systems to be:
4097
4098 L DirList [VSHELL] 'ls -l {PROMPT:Directory Of What?} | [$PAGER]'
4099
4100 This works fine so long as the user does not enter a wildcard pattern
4101 in response to the prompt. Why? Recall that twander quotes all Built-
4102 In Variable substitutions by default. If the user enters this at the
4103 prompt:
4104
4105 /kern*
4106
4107 The command twander tries to execute is:
4108
4109 VSHELL Stuff ... 'ls -l "/kern*" | ... pager stuff
4110
4111 The argument to 'ls' is double-quoted. The Unix shells understands
4112 this kind of quoting to mean no expansion of wildcard characters is to
4113 be done, which is the exact opposite of what we want.
4114
4115 You might think that the easy way to solve this problem is to turn off
4116 argument quoting with the -t command line flag. However, this is not
4117 really practical. Quoting is on or off globally in the program. Turn-
4118 ing it off means no Built-In Variable substitutions will be quoted.
4119 That's fine so long as no directory/file you select via the user inter-
4120 face has a space in the name. However, you are almost certain to run
4121 into such files sooner or later. (Recall that the only way to deal a
4122 directory/filename with spaces in it as a single argument is to quote
4123 that name.)
4124
4125 So, we need a way to leave quoting on but also properly deal with wild-
4126 card string entries from the user. Fortunately, because of the rich-
4127 ness of Unix shells, there is a simple way to do this: we'll use a
4128 "shell variable" to hold the user's response and the shell's ability to
4129 handle multiple commands on one line separated by semi-colons:
4130
4131 # Note that the line below is split for printing purposes
4132 # In an actual Configuration File, this needs to all be on one line
4133
4134 L DirList [VSHELL] 'UsrResp={PROMPT:Directory Of What?} ;
4135 ls -l $UsrResp | [$PAGER]'
4136
4137
4138 Why does this work? Because the shell interprets (and drops) the dou-
4139 ble-quotes, when the results of the {PROMPT:...} are assigned to Usr-
4140 Resp . The later reference to "$UsrResp" returns just the string the
4141 user entered without the quotes and the command works as expected.
4142
4143 Interestingly, this problem does not occur when entering text via the
4144 RUNCMD dialog. (default: Control-z) Here the text you enter is not
4145 part of a Built-In Variable substitution, so it is not quoted. (The
4146 exception, of course, would be if you entered a {PROMPT:...} reference
4147 in the RUNCMD dialog. In this case, the same problem we've just
4148 described could occur.)
4149
4150
4151 Modal Operation Of New Windows
4152 Notice our example commands above do not end with "&". These should
4153 not be needed on either Unix-like or Windows operating systems. When a
4154 command is executed, twander starts a process which runs concurrently
4155 with twander itself. This means you should be able to continue using
4156 twander while the new command executes.
4157
4158 If you enable the use of threads by setting USETHREADS to True, you may
4159 see twander locked out while the new command runs - so-called "modal"
4160 operation. If this happens, it means your system does not completely
4161 or correctly implement threading and you must use conventional "heavy
4162 weight" processes (the default) rather than threads.
4163
4164
4165 Windows Don't Disappear On Command Completion
4166 It appears that some X Windows implementations (noted on XFree86 /
4167 FreeBSD) do not correctly destroy an 'xterm' window after a command
4168 initiated with -e terminates. This is not a twander problem - it is an
4169 artifact of thread behavior on such systems and only happens if you set
4170 USETHREADS=True. The workaround is to use the default
4171 USETHREADS=False setting.
4172
4173
4174 Program Behavior Incorrect When A Window Is Resized
4175 Certain Unix programs such as 'less' appear to not work correctly when
4176 the window in which they are running is resized. The program seems to
4177 not be properly informed that the window size has changed. This seems
4178 to be an interaction caused by running such programs as threads rather
4179 than processes. Once again, the workaround here is to not change the
4180 USETHREADS=False default setting.
4181
4182
4183 Really Slow Response Times When Changing To A New Directory
4184 You may occasionally see really slow response times when you change to
4185 a new directory. This occurs when you enter a huge directory with
4186 thousands of file or subdirectory entries. twander has to to compute
4187 the detail information for each of these entries and this can take a
4188 lot of time. On a fast machine with modern hard drives and con-
4189 trollers, twander is able to process several thousand entries in just a
4190 second or two. However, a number of factors can significantly slow
4191 down this process:
4192
4193
4194 o The Autorefresh interval is set too low. Processing the directory
4195 takes so long that as soon as one refresh finishes, the next starts
4196 right away. The program will appear to hang. There are two possi-
4197 bilities here. Either disable autorefreshing (via the -r command
4198 line option or the AUTOREFRESH Configuration File option), or set
4199 the REFRESHINT value to some high number so that twander has plenty
4200 of time to process a directory before the next refresh occurs.
4201
4202
4203 o Slow disk drives. You can really watch twander grind if you change
4204 to a large directory on a CDROM, for instance. There is no good
4205 solution here. These drives are inherently slower than hard
4206 drives, and you just have to wait. Make sure you lengthen your
4207 refresh interval as described in the previous bullet.
4208
4209
4210 o By far the worst culprit here, though, is when running Windows with
4211 'win32all' options enabled. It takes a lot more work to get
4212 win32all-style information about each directory entry, than the
4213 default Unix-style information. Simply turning off 'win32all'
4214 features alone can speed up directory processing by a factor as
4215 high as 4X.
4216
4217
4218 When you combine these factors, it is possible to get really long pro-
4219 cessing times. One test situation we observed was reading a directory
4220 with over 4000 entries on a Windows CDROM. With 'win32all' processing
4221 enabled this took over a minute. By disabling these features, the time
4222 came down to under 30 seconds.
4223
4224
4225 o For all these reasons, twander implements an "adaptive refresh"
4226 scheme by default. Whenever a directory is read, the time to do so
4227 is tracked. If that time is less than the current value of
4228 REFRESHINT - i.e., The directory read took less than REFRESHINT
4229 milliseconds to complete - nothing special happens. But, if the
4230 actual directory read time takes longer than REFRESHINT millisec-
4231 onds, twander adjusts the value of REFRESHINT upwards. That way,
4232 you're guaranteed to have time after the read completes to actually
4233 do something.
4234
4235
4236 This dynamic adjustment takes place on every directory read. If you go
4237 to a slow directory and REFRESHINT gets dynamically adjusted to, say,
4238 25 seconds, when you go back to a faster/smaller directory, REFRESHINT
4239 will be reset to its default value. The changing value of REFRESHINT
4240 is not shown in the program options help menu. The value there is the
4241 one set by default or set in the Configuration File. Think of this as
4242 the "base" value for REFRESHINT.
4243
4244
4245 If you don't like this adaptive refresh interval business, set the
4246 ADAPTREFRESH program option to False. In that case, REFRESHINT will be
4247 strictly observed.
4248
4249
4250
4251 Your Configuration File Does Not Produce The Desired Results
4252 It's easy to fall into the trap of treating the twander configuration
4253 capabilities as a real "programming language". It is not, it is a
4254 fairly simple macro language that does very little more than string
4255 substitutions. Keep the following rules in mind as you edit your con-
4256 figuration:
4257
4258
4259
4260 o Except for conditional tests, Environment Variables and User-
4261 Defined Variables are never resolved until they appear in a Command
4262 Definition.
4263
4264
4265 o The Right Hand Side of Option Statements, Key Binding Statements,
4266 Directory Shortcut Statements, Wildcard Statements, and Condition
4267 Test Statements are treated literally - No variable substitution is
4268 ever done there.
4269
4270
4271 o A Condition Test Statement always involves a variable reference,
4272 never just a variable name.
4273
4274
4275 o For a Condition Test Statement to be true, the referenced variable
4276 must be defined and any equality test must be satisfied.
4277
4278
4279 o When testing for the existence of a User-Defined or Environment
4280 Variable, twander does not care what value the variable contains.
4281 It is perfectly permissible to have either type of variable set to
4282 an empty string. The fact that the variable exists at all is what
4283 makes the following construct true:
4284
4285 CondVar =
4286 .if [CondVar]
4287 ....
4288 .endif
4289
4290
4291 o You have to be careful when overriding variable or command defini-
4292 tions. User-Defined Variables referenced in a Command Definition
4293 are de-referenced at the time the Command Definition is encountered
4294 in the Configuration File. This means that if you change a User-
4295 Defined Variable after it has already been used in a Command Defi-
4296 nition, only future references to that variable will reflect the
4297 change:
4298
4299 FOO = bar
4300
4301 x cmd1 command [FOO]
4302
4303 FOO = baz
4304
4305 y cmd2 command [FOO]
4306
4307 In this example, the first command will be defined as "command
4308 bar", but the second will be defined as "command baz".
4309
4310 Watch for this, especially, when using the ".include" directive
4311 and then overriding a variable defined in that file.
4312
4313
4314 Common mistakes include:
4315
4316 #####
4317 # Trying to embed a variable where it will never be resolved
4318 #####
4319
4320 DIRSC03 = [$SystemDrive]\Program Files
4321 MYCOLOR = blue
4322 FCOLOR = [MYCOLOR]
4323
4324 #####
4325 # Expecting a conditional variable to be resolved before the test
4326 # Suppose $EDITOR is set to "/usr/local/bin/emacs" ...
4327 #
4328 # The following will be False because [EDT] equals
4329 # the string "[$EDITOR]". It is not replaced
4330 # with "/usr/local/bin/emacs" until [EDT] appears
4331 # in a Command Definition
4332 #####
4333
4334 EDT = [$EDITOR]
4335
4336 .if [EDT] == /usr/local/bin/emacs
4337 ...
4338 .endif
4339
4340
4341 # Note, however, that *this* would work because
4342 # Environment Variables are permitted in conditionals ...
4343
4344 .if [$EDITOR] == /usr/local/bin/emacs
4345 ...
4346 .endif
4347
4348 #####
4349 # A badly formed condition is ignored (after a warning)
4350 # which means *all the lines following will be processed*
4351 # (until a valid condition statement which is False is
4352 # encountered).
4353 #####
4354
4355 PROCESS = no
4356 SUBPART = no
4357
4358 # We meant not to process the following but all the
4359 # lines up to the next .if statement *are* processed
4360 # because the bad syntax on the next line means it's ignored
4361
4362 .if PROCESS != no
4363 ... # Processed!
4364
4365 .if [SUBPART] == yes # *Now* we'll stop
4366 ...
4367 .endif
4368
4369 .endif
4370
4371
4372
4373 OTHER
4374 File/Directory name sorting is done without-case sensitivity on Windows
4375 systems because the underlying operating system does not observe case.
4376
4377 Because this program has not been tested on anything other than Unix-
4378 like and Windows systems, command execution by double-click or pressing
4379 Enter is inhibited on all other operating systems by default.
4380
4381 You must have Python 2.2 or later installed as well as Tkinter support
4382 installed for that release. In the case of Windows, Tkinter is bundled
4383 with the standard Windows Python distribution. In the case of Unix-
4384 like systems, you may have to first install Python and then the appro-
4385 priate release of Tkinter. This is the case, for example, with
4386 FreeBSD.
4387
4388 You must install the 'win32all' extensions if you want to use the
4389 advanced Windows features.
4390
4391 You'll find the latest version and, occasionally, Release Candidates of
4392 the next version of twander at:
4393
4394 http://www.tundraware.com/Software/twander
4395
4396 You should check this site regularly for updates and bug-fixes. The
4397 'WHATSNEW.txt' file describes changes since the last public release of
4398 the program.
4399
4400
4401
4402 BUGS AND MISFEATURES
4403 As of this release, a number of problems relating to twander use have
4404 been noted:
4405
4406
4407 o The Configuration File parser does no validation to check the san-
4408 ity of its various entries for Program Options, Key Bindings,
4409 Directory Shortcuts, Variable Definitions, and Command Definitions.
4410 It is entirely possible to edit something into this file that makes
4411 no sense at all and causes twander to misbehave.
4412
4413
4414 o There appears to be a Tkinter/Tk bug on Unix which sometimes
4415 inhibits the correct title display when you tear-off a menu. This
4416 is a cosmetic defect and may disappear in future releases of Tkin-
4417 ter/Tk/X-Windows.
4418
4419
4420 o Some 'win32all' features do not work correctly or at all on older
4421 Windows OSs. For example, the free/total space available in the
4422 Drive List View has been noted to display incorrect values on
4423 Win98. Similarly, the owner and group names are displayed as
4424 "Unavailable" on pre-NTFS file systems. These are OS limitations
4425 which twander handles gracefully.
4426
4427
4428 o If you are using 'bash' as your Unix shell, be aware that, although
4429 it sets HOSTNAME automatically, this environment variable appears
4430 to not be exported consistently on all systems.
4431
4432
4433 o If you are running Windows and have file or directory names with
4434 non-ASCII characters in them, you must configure Python to properly
4435 deal with such characters. This is described above in the section
4436 entitled, GOTCHAS.
4437
4438
4439 o This program has not been tested on MacOS. It has been reported
4440 that Python on MacOS X returns 'posix' as its OS name. If true,
4441 twander should work as written, though we've not verified this.
4442 Please let us know how/if it works there and any issues you dis-
4443 cover.
4444
4445
4446
4447 INSTALLING twander
4448 Installation of twander is fairly simple and takes only a few moments.
4449 The most important thing before installing the program is to make sure
4450 you have Python 2.2 (or later) with Tkinter support installed on your
4451 system.
4452
4453 One other note: However you install the program, it is probably easiest
4454 to get started by editing the example ".twander" file to taste. Be
4455 aware that this file is shipped with everything commented out. You
4456 have to uncomment/edit the section relevant to your operating system:
4457 Unix-like or Windows.
4458
4459
4460 Installing Using The FreeBSD Port
4461 If you've installed twander using the FreeBSD port, all you have to do
4462 is copy the example Configuration File, ".twander" found in
4463 /usr/local/share/doc/twander to your home directory and edit it to
4464 taste. (You'll also find documentation for twander in various formats
4465 in this directory as well.)
4466
4467 Make sure that /usr/local/bin is in your path. To start the program,
4468 just type "twander.py" from the shell prompt.
4469
4470
4471 Installing Manually On A Unix-like System
4472 Copy the "twander.py" file to a directory somewhere on your path.
4473 (/usr/local/bin is a good candidate). Make sure this file has permis-
4474 sions 755 and owner/group appropriate for your system (root/wheel,
4475 root/root, or bin/bin). Copy the ".twander" file to your home direc-
4476 tory and edit to taste.
4477
4478 To run the program, just type "twander.py" from a shell prompt.
4479
4480 Red Hat Linux Users Please Note: RH Linux (and possibly other Linux
4481 systems) installs two versions of Python. Version 1.52 is called
4482 'python', and Version 2.2 is called 'python2'. twander requires the
4483 latter and will not run on the former. As shipped, twander invokes
4484 Python with the Unix shell "#!" mechanism using the name 'python' -
4485 which in this case is the wrong version. You can work around this
4486 problem one of several ways:
4487
4488
4489 o Rename 'python' to 'python1' and then rename 'python2' to 'python'.
4490 (Not Recommended - could break other programs.)
4491
4492
4493 o Write an alias or shell script which explicity starts twander with
4494 the correct version of Python:
4495
4496 #!/bin/sh
4497 python2 twander.py $*
4498
4499
4500 o Change the first line of the twander code to refer to 'python2'
4501 instead of 'python'.
4502
4503
4504 Red Hat users who have upgraded from earlier Linux versions should also
4505 note that you may have files in your home directories owned by owners
4506 and groups which are no longer defined in the system! twander shows
4507 the owner and group fields for such files as numbers rather than names.
4508 As best as we can determine, this is caused when an RH installation is
4509 updated from an older version.
4510
4511
4512 Installing Manually On A Windows System
4513 Copy the "twander.py" file to a directory somewhere on your path, or
4514 create a new directory to hold this file and add that directory path to
4515 the PATH environment variable.
4516
4517 IMPORTANT NOTE TO WINDOWS USERS: Windows has the old MS-DOS legacy of
4518 assuming that a "." begins a file "extension". Although you can create
4519 and read files in the form ".something", it is not recommended because
4520 many Windows programs get confused when they see this. It is also dif-
4521 ficult to remove files named this way with the standard Windows pro-
4522 grams and utilities. This is especially the case for older Windows
4523 operating systems like Win98. For this reason, it is recommended that
4524 you rename the ".twander" default Configuration File provided in the
4525 program distribution to something else like "twander.conf" and use the
4526 twander -c command line option to point to this Configuration File.
4527
4528
4529 On Windows, where to put the Configuration File raises an interesting
4530 question. Microsoft operating systems normally do not set the "HOME"
4531 environment variable, because they have no notion of a "home" directory
4532 - Well, they do, but it is called "USERPROFILE" not "HOME". So, you
4533 can either create a new user-specific environment variable called HOME
4534 yourself (which points to your desired home directory) or you can
4535 invoke twander with the -c argument to explictly declare where it can
4536 find its Configuration File.
4537
4538 You can run the program several ways on Windows systems:
4539
4540
4541 o Create a Windows shortcut which points to the "twander.py" file
4542 using the "pythonw" command to invoke it. Normally, starting a
4543 Python program from the Windows GUI creates a parent window which
4544 persists as long as the program runs. Using "pythonw" instead of
4545 "python" to run your program suppresses the creation of this blank
4546 parent window. For example, you might have something like this in
4547 the "Target:" field of your shortcut:
4548
4549 "C:\Program Files\Python22\pythonw.exe" C:\twander.py \
4550
4551 This runs the program starting at the root directory of the current
4552 drive (assuming "twander.py" is located in C:\.
4553
4554
4555 o Start a command line window and issue a command like the one above
4556 directly from the command line.
4557
4558
4559 o Use Windows Explorer (or better still, an already running instance
4560 of twander!) to navigate to the directory where "twander.py" is
4561 located. Double-click on the file. If Python is properly
4562 installed, there should be an association for ".py" file types and
4563 twander should start automatically.
4564
4565
4566
4567 GETTING HELP: THE twander MAILING LIST
4568 TundraWare Inc. maintains an email list for twander users to get help
4569 and exchange ideas. To subscribe, send mail to:
4570
4571 majordomo@tundraware.com
4572
4573 In the body (not the subject line) of the email, enter the following
4574 text, substituting your own email address as indicated:
4575
4576 subscribe twander-users your-email-address
4577
4578
4579
4580 DESIGN PHILOSOPHY
4581 Graphical User Interfaces (GUIs) are a blessing and a curse. On the one
4582 hand, they make it easy to learn and use a computer system. On the
4583 other, they are a real inconvenience to experienced users who are touch
4584 typists. Taking hands off the keyboard to use the mouse can really
4585 slow down a good typist.
4586
4587 Nowhere is this more apparent than in filesystem browsers. In one cor-
4588 ner we have the GUI variants like 'Konqueror' and 'Microsoft Windows
4589 Explorer'. These are very easy to use but you pretty much need the
4590 mouse in your hand to do anything useful. In the other corner are the
4591 text-based file browsers like 'List', 'Norton Commander', and 'Midnight
4592 Commander'. These are really efficient to use, but have limited func-
4593 tionality and generally do not operate very well on groups of things.
4594
4595 Both of these approaches also suffer from the well-known interface
4596 problem of "What You See Is All You Get" - Each program has a prede-
4597 fined set of commands and the user cannot easily extend these with
4598 their own, new commands.
4599
4600 twander is another approach to the filesystem navigation problem which
4601 embraces the best of both the GUI-based approach and the text-based
4602 approach. It also provides a rich mechanism whereby each user can eas-
4603 ily define their own command set and thereby customize the program as
4604 they see fit. This is done with a number of key features:
4605
4606
4607
4608 1) The Navigation of the filesystem is graphical - you can use the
4609 mouse to select files, directories, or to change directories.
4610 However, each major filesystem navigational feature is also dou-
4611 bled on the keyboard (using Control keys) so you can move around
4612 and select things without ever touching the mouse.
4613
4614
4615 2) twander also supports a number of navigation shortcuts. It pro-
4616 vides single control-key access to changing directories, moving
4617 to the previous directory, moving up one directory level, moving
4618 to any previously visited directory, (de)selecting any or all
4619 files/directories in the current view, and escaping to the oper-
4620 ating system to run a command. Some (but not all) of these fea-
4621 tures are also doubled via GUI/mouse operations.
4622
4623
4624 3) There are no built-in file or directory commands. All commands
4625 which manipulate the files or directories selected during navi-
4626 gation are user-defined. This Command Definition is done in an
4627 external Configuration File using a simple but powerful command
4628 macro language. This means that that the command set of the
4629 program can easily be changed or expanded without having to
4630 release a new version of twander every time. Better still,
4631 every different user can have their own command set defined in a
4632 way that suits their style of working. Best of all, commands
4633 can be invoked either graphically (with a mouse click) or via a
4634 single keypress to minimize moving your hands off the keyboard.
4635
4636
4637 4) Because twander is written in Python using Tkinter, the same
4638 program runs essentially identically on many Unix-like and Win-
4639 dows systems. The only thing that may need to be changed across
4640 these various platforms are the Command Definitions in the con-
4641 figuration file. You only need to learn one interface (and the
4642 commands you've defined) across all the different systems you
4643 use.
4644
4645
4646 The consequence of all this is that twander is an extremely powerful
4647 and highly customizable filesystem navigator. Once learned, both navi-
4648 gation and command execution are lightning-fast (or at least, as fast
4649 as your machine can go ;) while minimizing dependency on the mouse.
4650
4651
4652
4653 COPYRIGHT AND LICENSING
4654 twander is Copyright(c) 2002-2009 TundraWare Inc. For terms of use,
4655 see the twander-license.txt file in the program distribution. If you
4656 install twander on a FreeBSD system using the 'ports' mechanism, you
4657 will also find this file in /usr/local/share/doc/twander.
4658
4659
4660
4661 AUTHOR
4662 Tim Daneliuk
4663 twander@tundraware.com
4664
4665
4666 DOCUMENT REVISION INFORMATION
4667 $Id: twander.1,v 1.155 2009/07/01 20:16:33 tundra Exp $
4668
4669
4670
4671 TundraWare Inc. twander(1)