twander-3.231.tar.gz: twander-3.231/twander.txt

"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)