"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)
    5 NAME
    6        twander - File Browser
   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.
   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.
   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.
   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.
   35        You  can  get  the latest version of the program and documentation from
   36        the twander homepage:
   38            http://www.tundraware.com/Software/twander/
   41        You should check this site periodically for program updates, bug fixes,
   42        and enhancements.
   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.
   53        twander [-cdhqrtv] [startdir]
   58        startdir
   59               Directory  in  which to begin. (default: directory in which pro-
   60               gram was started)
   62               If this directory does not exist or cannot  be  opened,  twander
   63               will display an error message and abort.
   66        -c path/name of Configuration File
   67               Specify  the  location  and  name  of  the  configuration  file.
   68               (default is ~/.twander)
   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).
   78        -d debuglevel
   79               Start  in  debug  mode  dumping the items specified in the debu-
   80               glevel.  (default: debuglevel=0/debug off)
   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:
   89                   Bit  Hex Value   Meaning
   90                   ---  ---------   -------
   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
  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.
  112        -h     Print help information on stdout.
  115        -q     Quiet mode - suppresses warnings. (default: warnings on)
  118        -r     Turn  off  automatic  refreshing of directory display. (default:
  119               refresh on)
  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).
  132        -t     Turn off quoting when substituting built-in variables. (default:
  133               quoting on)
  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.
  145        -v     Print detailed version information.
  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:
  156            export TWANDER=-qt
  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.
  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.
  166        twander evaluates options in the following order (from first to last):
  169        o   Internally set default value of options
  172        o   Options set in the Configuration File
  175        o   Options set in the TWANDER environment variable
  178        o   Options set on the command line
  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.
  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.
  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.
  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:
  209        o   Program name and version number.
  212        o   Login name and machine/domain of current user.
  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.
  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.
  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.
  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.
  236        o   An indication of whether or not "dotfiles" are currently hidden.
  239        o   The total number of files in this directory.  The ".." entry is not
  240            included in this count.
  243        o   The total size of all the files in this directory.  The size of the
  244            ".."  directory is not included in this total.
  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.
  252        o   An  indication of whether or not directories and ordinary files are
  253            being separated in the display.
  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.
  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.
  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.
  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.
  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).
  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.
  305        Here,  ordered by category, are the default keyboard and mouse bindings
  306        for twander.  The general format is:
  309        Description (Program Function Name)
  310               Default Key Assignment
  312               Default Mouse Assignment (if any)
  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.
  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.
  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.
  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.
  337    General Program Commands
  338        This family of commands controls the operation of twander itself.
  341        Clear History (CLRHIST)
  342               Control-y
  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.
  351        Decrement Font Size (FONTDECR)
  352               Control-[
  354               Decrease font size.
  357        Increment Font Size (FONTINCR)
  358               Control-]
  360               Increase font size.
  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.
  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.
  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.
  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.
  405        Display Command Menu (MOUSECTX)
  406               Right-Mouse-Button
  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.
  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.
  422        Display Directory Menu (MOUSEDIR)
  423               Shift-Right-Mouse-Button
  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.
  432        Display History Menu (MOUSEHIST)
  433               Control-Shift-Right-Mouse-Button
  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.)
  444        Display Shortcut Menu (MOUSESC)
  445               Alt-Control-Left-Mouse-Button
  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.
  455        Display Sorting Menu (MOUSESORT)
  456               Alt-Shift-Right-Mouse-Button
  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.)
  462               Displays a list of all the sorting options in a pop-up menu near
  463               the mouse.
  466        Quit Program (QUITPROG)
  467               Control-q
  469               Exit the program.
  472        Re-Read Configuration File (READCONF)
  473               Control-r
  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.
  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.
  491        Refresh Display (REFRESH)
  492               Control-l
  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.
  500        Toggle Autorefreshing (TOGAUTO)
  501               Control-o
  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.
  513               The  state  of  the Autorefresh feature is displayed on the main
  514               window title bar.
  517        Toggle Details (TOGDETAIL)
  518               Control-t
  520               Toggle between detailed and filename-only views  of  the  direc-
  521               tory.
  524        Toggle Between Normalized And Actual File Length Display (TOGLENGTH)
  525               Control-0
  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.
  538        Toggle Sorting Of Symbolic Link Directories (TOGSYMDIR)
  539               Control-~
  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.
  549        Toggle The Display Of Symbolic Link Targets (TOGSYMEXPAND)
  550               Control-!
  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.
  558        Toggle The Display Of Absolute Symbolic Link Targets(TOGSYMRESOLV)
  559               Control-@
  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.
  570        Toggle 'win32all' Features (TOGWIN32ALL)
  571               Control-w
  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.
  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.
  593        Change Directory (CHANGEDIR)
  594               Control-x
  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.
  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.
  609        Go To Home Directory (DIRHOME)
  610               Control-h
  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.
  618        Go Back One Directory (DIRBACK and MOUSEBACK)
  619               Control-b
  621               Control-DoubleClick-Left-Mouse-Button
  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.
  633        Go To Root Directory (DIRROOT)
  634               Control-j
  636               Go to the root directory.
  639        Go To Starting Directory (DIRSTART)
  640               Control-s
  642               Go back to the original directory in which twander was  started.
  645        Go Up To Parent Directory (DIRUP and MOUSEUP)
  646               Control-u
  648               Control-DoubleClick-Right-Mouse-Button
  650               Move to the parent of the current directory ("..").
  653        Display Drive List View (DRIVELIST)
  654               Control-k
  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.
  667    Selection Keys
  668        This  family  of commands controls the selection of one or more (or no)
  669        items in the current directory.
  672        Select All Items (SELALL)
  673               Control-Comma
  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.)
  683        Invert Current Selection (SELINV)
  684               Control-i
  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.
  692        Unselect All Items (SELNONE)
  693               Control-Period
  695               Unselect everything in the current directory.
  698        Select Next Item (SELNEXT)
  699               Control-n
  701               Select next item down in the directory.
  704        Select Previous Item (SELPREV)
  705               Control-p
  707               Select previous item up in the directory.
  710        Select Last Item (SELEND)
  711               Control-e
  713               Select last item in the directory.
  716        Select First Item (SELTOP)
  717               Control-a
  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.
  724        Mouse-Based Selections
  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.
  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:
  744        Scroll Page Down (PGDN)
  745               Control-v
  747               Scroll down one page in the directory listing.
  750        Scroll Page Up (PGUP)
  751               Control-c
  753               Scroll up one page in the directory listing.
  756        Scroll Page Right (PGRT)
  757               Control-g
  759               Scroll to the right one page width.
  762        Scroll Page Left (PGLFT)
  763               Control-f
  765               Scroll to the left one page width.
  768    Command Execution Options
  769        This  family  of commands causes twander to actually attempt to execute
  770        some command you've chosen:
  773        Run Arbitrary Command (RUNCMD)
  774               Control-z
  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.
  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):
  790                   cp [SELECTIONS] newdir
  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:
  802                   [$EDITOR] [SELECTIONS]
  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:
  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]
  827               Of course, the full form is also fine as well.
  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.
  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.
  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.
  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,
  855                   +mycommand
  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.
  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.
  869        Run Selected File / Move To Selected Directory (SELKEY and MOUSESEL)
  870               Return (Enter Key)
  872               DoubleClick-Left-Mouse-Button
  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.
  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.
  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).
  891               If twander determines that it is running on neither a  Unix-like
  892               or Windows system, double-clicking on a file does nothing.
  895        Run User-Defined Command
  896               User-Defined (Single Letter) Key
  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.
  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:
  911        Navigate Directly To A Directory (KDIRSC1 ... KDIRSC12)
  912               F1 ... F12
  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
  920        Assign Current Directory To One Of The Shortcut Keys (KDIRSCSET)
  921               Control-8
  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.
  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.
  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).
  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.
  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).
  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:
  974        Clear Selected Program Memory (MEMCLR1 - MEMCLR12)
  975               Control-F1 ... Control-F12
  977               Clear (empty) the selected Program Memory.
  980        Clear All Program Memories (MEMCLRALL)
  981               Control-m
  983               Clear (empty) all 12 Program Memories at once.
  986        Set Selected Program Memory (MEMSET1 - MEMSET12)
  987               Alt-F1 ... Alt-F12
  989               Append  the  the full path names of the currently selected files
  990               and directories to the Program Memory desired.
  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
 1001                         Program
 1002                         Function      Sort Order In    Sort Order In
 1003            Key          Name          Normal View      Drive List View
 1004            ---          --------      ------------     ---------------
 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
 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.
 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.
 1027        SORTREV reverses the order of the sort.
 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.
 1036        You'll find the currently selected sorting  options  displayed  in  the
 1037        program title bar.
 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".
 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.
 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.
 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:
 1070            drwx------
 1072        twander  would  display  only  the entries that are directories with no
 1073        permissions enabled for group or world users.
 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":
 1087            Ju. 0
 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".
 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.
 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.
 1104        For an excellent tutorial on Python-compliant regular expressions, see:
 1106            http://www.amk.ca/python/howto/regex/
 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.)
 1121        Suppose  we  changed  our  example above slightly and used this regular
 1122        expression:
 1124            "^drwx------
 1126        Now twander would select only the directories  without  any  group  and
 1127        world access because:
 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.
 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.
 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.
 1149        A few points to keep in mind when using wildcard features:
 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.
 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.
 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.
 1182        Display Files Matching A Regular Expression (FILTERWILD)
 1183               Control-equal
 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.
 1192        Toggle Active Filter (TOGFILT)
 1193               Control-minus
 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.
 1204        Select Files Matching A Regular Expression 'Wildcards' (SELWILD)
 1205               Control-\
 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.
 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.
 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 "+".
 1222        Display Selection Wildcard Menu (MOUSEFILTERSEL)
 1223               Alt-Control-Middle-Mouse-Button
 1225        Display Selection Wildcard Menu (MOUSEWILDSEL)
 1226               Alt-Control-Right-Mouse-Button
 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.)
 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.
 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.
 1248        By default, dotfiles are not hidden, but this can be changed  with  the
 1249        HIDEDOTFILES configuration option.
 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.
 1256        Toggle Dotfile Hiding (TOGHIDEDOT)
 1257               Control-9
 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.
 1265        Unlike Wildcard Filters (which test the entire displayed line), dotfile
 1266        hiding is triggered only by the name of the file or directory.
 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.
 1273        The current state of dotfile hiding is displayed in  the  window  title
 1274        bar, immediately after the Filter information.
 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:
 1280             c cleandot rm .*~
 1283        This  command  will remove any backup (~) files, whether or not you can
 1284        see them in the interface.
 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.
 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.
 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.
 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.
 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.
 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.
 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.
 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.
 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).
 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.
 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.
 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.)
 1393        The History Menu is emptied and grayed out when you press  the  CLRHIST
 1394        key. (default: Control-y)
 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.
 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.
 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.
 1417        The Directory Menu is emptied and grayed out when you press the CLRHIST
 1418        key. (default: Control-y)
 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.
 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.)
 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.
 1442        Selecting something from this menu brings up a dialog box which  allows
 1443        you to edit the selected wildcard before using it.
 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.
 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.
 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.)
 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.
 1467        Selecting  something from this menu brings up a dialog box which allows
 1468        you to edit the selected wildcard before using it.
 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.
 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.
 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.)
 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).
 1491        You'll  find  the  currently  selected sorting options displayed in the
 1492        program title bar.
 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.
 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.
 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.
 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 )
 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):
 1533        o   If the -c argument was given on the command line, use this argument
 1534            for a Configuration File.
 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.
 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.
 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.
 1553        There are several possible legal lines in a twander Configuration File:
 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
 1565        (See  the  ".twander"  file  provided with the program distribution for
 1566        examples of valid configuration statements.)
 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.
 1578        The following sections describe each of the  valid  Configuration  File
 1579        entires in more detail.
 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.
 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.
 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:
 1606            Option Name = Option Value
 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.
 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.
 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.
 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.
 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).
 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.
 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:
 1640            # This effectively sets BCOLOR to its default value when
 1641            # the Configuration File is reloaded
 1642            BCOLOR =
 1644            # But this means the value of BCOLOR is set to red
 1646            BCOLOR = red
 1647            BCOLOR =
 1649        In other words, you should think of Program Option  Statements  with  a
 1650        blank Right Hand Side as comments - present but ignored.
 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:
 1659            # A Nice Way To Clobber twander
 1660            BCOLOR = goo
 1662        The following sections document each  available  Program  Option  using
 1663        this general format:
 1665            Option-Name [Type] (Default Value)
 1668        ACTUALLENGTH [Boolean] (False)
 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).
 1681        ADAPTREFRESH [Boolean] (True)
 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.
 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.
 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.
 1707        AFTERCLEAR [Boolean] (True)
 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.
 1717               Setting  AFTERCLEAR  to False, will leave the current selections
 1718               alone after doing a command with a forced update.
 1722        AFTERWAIT [Numeric] (1)
 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.
 1734        AUTOREFRESH [Boolean] (True)
 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)
 1745        BCOLOR [String] (Black)
 1747               Selects the main display Background Color.
 1750        CMDMENUSORT [Boolean] (False)
 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.
 1760               Note  that the Command Definitions help menu ignores CMDMENUSORT
 1761               and is always presented in sorted order.
 1765        CMDSHELL [String] ()
 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:
 1776                   x MyCommand   xterm -l -e bash -c 'stuff-for-my-command'
 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):
 1783                   SHELL       = bash -c
 1784                   VSHELL      = [XTERM] [SHELL]
 1785                   XTERM       = xterm -fn 9x15 -l -e
 1787               Now the Command Definition above becomes:
 1789                   x MyCommand [VSHELL] 'stuff-for-my-command'
 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).
 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:
 1802                   CMDSHELL = xterm -l -e bash -c
 1804                               - or -
 1806                   CMDSHELL = [VSHELL]  # Assuming VSHELL is defined previously
 1808               Now every time you enter a command, this will be placed in front
 1809               of your text before command execution commences.
 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:
 1816                   CMDSHELL =
 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.
 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.
 1834        DEBUGLEVEL [Numeric] (0)
 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:
 1843                   DEBUGLEVEL = 0x004
 1847        DEFAULTSEP [String] (==>)
 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.
 1860        DOTFILE [String] (.)
 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.
 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.
 1880        FCOLOR [String] (green)
 1882               Selects the main display Foreground (Text) Color.
 1885        FNAME [String] (Courier)
 1887               Selects the main display Font Name.
 1890        FSZ [Numeric] (12)
 1892               Selects the main display Font Size.
 1895        FWT [String] (bold)
 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.
 1902        FORCEUNIXPATH [Boolean] (False)
 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).
 1911               If  you  set  FORCEUNIXPATH to True, twander will always use the
 1912               Unix path separator character("/") in these substitutions.
 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.
 1918               This option is only relevant on Windows systems.  It is  ignored
 1919               on other operating systems.
 1923        HBCOLOR [String] (lightgreen)
 1925               Selects the help menu Background Color.
 1928        HEIGHT [Numeric] (600)
 1930               Initial vertical size of the twander window in pixels.
 1933        HFCOLOR [String] (black)
 1935               Selects the help menu Foreground (Text) Color.
 1938        HFNAME [String] (Courier)
 1940               Selects the help menu Font Name.
 1943        HFSZ [Numeric] (10)
 1945               Selects the help menu Font Size.
 1948        HFWT [String] (italic)
 1950               This selects the help menu Font Weight.
 1954        HIDEDOTFILES [Boolean] (False)
 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.
 1962        INVERTFILTER [Boolean] (False)
 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.
 1971        ISODATE [Boolean] (False)
 1973               Set this to True to display file/directory date and time in  ISO
 1974               8601 format instead of the default US localized format.
 1977        MAXMENU [Numeric] (32)
 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).
 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.
 1992        MAXNESTING [Numeric] (32)
 1994               Number of times a Command Definition is processed to dereference
 1995               all variables.  For example, suppose you have this:
 1997                   FOO = bax
 1998                   BAM = x[FOO]
 2000                   x mycmd [BAM] [SELECTION]
 2002               When you press the x key, the twander command interpreter has to
 2003               process the line repeatedly until all variables are resolved:
 2005                   [BAM] [SELECTION]   -> x[FOO] [SELECTION]
 2006                   x[FOO] [SELECTION]  -> xbax [SELECTION]
 2007                   xbax [SELECTION]    -> xbax selected-item
 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:
 2013                   FOO = x[FOO]
 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.
 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.
 2025        MBARCOL [String] (beige)
 2027               Selects the Menu Bar color.
 2030        MBCOLOR [String] (beige)
 2032               Selects the menu Background Color.
 2035        MFCOLOR [String] (black)
 2037               Selects the menu  Foreground (text) Color.
 2040        MFNAME [String] (Courier)
 2042               Selects the menu Font Name.
 2045        MFSZ [Numeric] (12)
 2047               Selects the menu Font Size.
 2050        MFWT [String] (bold)
 2052               Selects the menu Font Weight.
 2055        NODETAILS [Boolean] (False)
 2057               Prevents details from ever being displayed.
 2060        NONAVIGATE [Boolean] (False)
 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.
 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.
 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.
 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.
 2090        QUOTECHAR [String] (double-quote symbol)
 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.
 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.
 2111        REFRESHINT [Numeric] (5000)
 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.
 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.
 2131        SCALEPRECISION [Numeric] (1)
 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.
 2142        SORTBYFIELD [String] (Name)
 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.
 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
 2165        SORTREVERSE [Boolean] (False)
 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.
 2172        SORTSEPARATE [Boolean] (True)
 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.
 2179               This option is ignored in Drive List View.
 2182        STARTDIR [String] (Directory In Which Program Started)
 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.
 2192        STARTX [Numeric] (0)
 2194               Initial horizontal offset of the twander window in pixels.
 2197        STARTY [Numeric] (0)
 2199               Initial vertical offset of the twander window in pixels.
 2202        SYMDIR [Boolean] (True)
 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.
 2217        SYMEXPAND [Boolean] (True)
 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.
 2230        SYMRESOLV [Boolean] (False)
 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.
 2249        USETHREADS [Boolean] (False)
 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.
 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..
 2265        USEWIN32ALL [Boolean] (True)
 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).
 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.
 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.
 2286        WARN [Boolean] (True)
 2288               Determines  whether  interactive warnings should be displayed as
 2289               twander encounters them (while parsing a Configuration  File  or
 2290               just in normal execution).
 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.
 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.
 2307        WIDTH [Numeric] (800)
 2309               Initial horizontal size of the twander window in pixels.
 2312        WILDNOCASE [Boolean] (True On Win32 / False Elsewhere)
 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.
 2320        A few general notes about Program Options are worth mentioning here:
 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...
 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.
 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.
 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.
 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.
 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).
 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).
 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.
 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:
 2391                x mycmd MyPythonScript [DSELECTIONS] other stuff
 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.
 2397            You probably won't need this often, but its nice to have.
 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.
 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.
 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.
 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:
 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/
 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.)
 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:
 2442            Program Function Name = Tkinter Keystroke Name
 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.
 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.
 2455        It is important to observe several rules when rebinding keys:
 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.
 2465        o   The  Tkinter  keynames  should  placed on the right side of the "="
 2466            symbol without any quotation marks.
 2468                # Incorrect
 2469                QUITPROG = '<F3>'
 2471                # Correct
 2472                QUITPROG = <F3>
 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:
 2481                QUITPROG = something-or-other
 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.
 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.
 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.
 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:
 2512            DIRSCxx = path
 2514               where, xx is a number from 1-12
 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:
 2519            DIRSC5 = c:\Documents And Settings
 2521        There are several subtleties to Directory Shortcuts you  should  under-
 2522        stand:
 2525        o   You  can  end  the path with slash or not - twander will understand
 2526            the entry either way.
 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:
 2533                # This "undefines" shortcut #5
 2534                DIRSC5 =
 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.
 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.
 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.
 2554        o   A Directory Shortcut Statement may make reference to  user-defined,
 2555            environment, and execution variables.
 2557                ~ = [$HOME]
 2559                DIRSC1 = [~]/Desktop       # User-defined variable
 2560                DIRSC3 = [$HOME]           # Environment variable
 2561                DIRSC5 = [`echo "/tmp"`]   # Execution variable (but silly)
 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.
 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:
 2583            WILDFILTER = regular-expression-string
 2584            WILDSELECT = regular-expression-string
 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.)
 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.
 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.
 2617        User-Defined Variables are variables you define  in  the  configuration
 2618        file.  They can hold any string of text you desire.
 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.
 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.
 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.
 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.
 2648    User-Defined Variables And Environment Variables
 2649        User-Defined Variables are defined using the syntax:
 2651            Variable Name = Replacement String
 2653        Environment Variables are referenced using the syntax:
 2655            [$VARIABLE]
 2657        Say we have a configuration line like this,
 2659            EDITOR = emacs blah blah blah blah
 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.
 2665        Similarly,  suppose  you  have  an environment variable called "EDITOR"
 2666        which indicates your preferred editing program.  Our  definition  could
 2667        thus become:
 2669            EDITOR = [$EDITOR] blah blah blah blah
 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.
 2676        Here are several other subtleties regarding User-Defined Variables:
 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:
 2683                NewVar = somestring [OldVar]
 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]'."
 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).
 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:
 2703                Var1 = Foo
 2704                Var2 = Bar
 2705                FB = [Var1][Var2]
 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:
 2714                Var = a[Var]
 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.
 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:
 2724                Var1 = [$PAGER]
 2725                Var2 = command-arguments
 2726                V    = [Var1]  [Var2]  [DSELECTION]
 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.
 2737        o   Variable  references are only significant on the right hand side of
 2738            an assignment statement:
 2740                Var1     = Foo
 2741                My[Var1] = bar
 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 ...
 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.
 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:
 2763                Var1 = foo
 2764                Var2 = [Var3]    # This is just a string substitution, not a reference
 2765                Var3 = bar
 2766                MyVar = [Var1][Var2]
 2768                # Now comes the Command Definition
 2769                # If we put this before the Variable Definitions above,
 2770                # it would be an error.
 2772                x mycommand [MyVar]
 2775        o   Variable Names are case-sensitive - [EDITOR], [Editor],  and  [edi-
 2776            tor] all refer to different variables.
 2779        o   The "#" character cannot be used in either the variable name or the
 2780            replacement string since doing so begins a comment.
 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!
 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:
 2798                $MYVAR = some-string
 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.
 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).
 2812            For example, you can set a variable to some default value, and then
 2813            override it if a condition is satisfied:
 2815                # Assume we're running on a Unix-like system
 2817                MyEditor = [$EDITOR]
 2819                # Override this if we're on Windows
 2821                .if [.OS] == nt
 2822                        MyEditor = write
 2823                .endif
 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:
 2832            TODAY = [`date`]
 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.
 2842        o   Notice  that  Execution  Variables  are delimited by backticks, not
 2843            single-quotes.
 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.
 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.
 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:
 2869                a mycommand echo "[`-ls`]"  # We need the double-quotes
 2870                                              # to make echo work right
 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:
 2880            Command-Key  Command-Name  Command-String
 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.
 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.
 2900        The  Command String is any arbitrary string which is what twander actu-
 2901        ally tries to execute when the command is invoked.
 2904    A Simple Command Definition
 2905        In its simplest form, a Command Definition looks like this:
 2907            # A simple Command Definition
 2908            m  MyMore  more somefile
 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".
 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:
 2922            # Our command setup to run as a GUI window
 2923            m MyMore xterm -l -e more somefile
 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.
 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,
 2941            r removelogs +rm -f *log
 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.
 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.
 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.
 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:
 2970            # Our command enhanced with a User-Defined Variable.
 2971            # Remember that the variable has to be defined *before*
 2972            # it is referenced.
 2974            XTERM = xterm -l -e                 # This defines the variable
 2975            m MyMore [XTERM] more somefile      # And the command then uses it
 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:
 2987            # Our command using both a User-Defined Variable and
 2988            # an Environment Variable to make it more general
 2990            XTERM = xterm -l -e
 2991            m MyMore [XTERM] [$PAGER] somefile
 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:
 3001            # Our command using User-Defined, Environment, and
 3002            # Execution Variables
 3004            XTERM = xterm -l -e
 3005            m MyMore [XTERM]  [$PAGER]  [`-ls *.txt`]
 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:
 3023            # Our command in its most generic form using
 3024            # User-Defined, Environment, and Built-In Variables
 3026            XTERM = xterm -l -e
 3027            m MyMore [XTERM]  [$PAGER]  [DSELECTION]
 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.
 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:
 3040        o   [DIR]
 3042            [DIR] is replaced with the current directory twander is viewing.
 3045        o   [DSELECTION]
 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).
 3053        o   [DSELECTIONS]
 3055            [DSELECTIONS] is replaced with the full path name of all items cur-
 3056            rently selected in the GUI.
 3059        o   [SELECTION]
 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.
 3067        o   [SELECTIONS]
 3069            [SELECTIONS] is replaced with the  names  of  all  items  currently
 3070            selected in the GUI.  The path to those names is not included.
 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.
 3077        Note: The PROMPT and YESNO Built-Ins use {} as delimiters, not [].
 3080        o   [HASH]
 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).
 3093        o   {PROMPT:Prompt-String==>default}
 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:
 3103                # Copy a group of items to a location set by
 3104                # the user at runtime
 3105                UnixCopy  = cp -R
 3106                Win32Copy = copy
 3108                # Unix Version
 3109                c UnixCP [UnixCopy]  [DSELECTIONS]  {PROMPT:Enter Destination}
 3111                # Win32 Version
 3112                C Win32CP [Win32Copy]   [DSELECTIONS]  {PROMPT:Enter Destination}
 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.
 3119            This  feature is useful when you want to provide the user the most-
 3120            likely response to the prompt:
 3122                c UnixCP [UnixCopy]  [DSELECTIONS]  {PROMPT:Enter Destination==>/my/home/dir}
 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.
 3130        o   {YESNO:Question-String==>Yes|No}
 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:
 3141                D BigDelete {YESNO:Are You Absolutely Sure About This?} rm -rf [SELECTIONS]
 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.
 3149            This  feature  is  handy because you can pre-select the most likely
 3150            response to the dialog:
 3152                D BigDelete {YESNO:Are You Absolutely Sure About This?==>No} rm -rf [SELECTIONS]
 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:
 3163            PromptYN  = Are You Sure You Want To Do This?
 3164            DefaultYN = No
 3166            a mycommand  {YESNO:[PromptYN]==>[DefaultYN]} SomeDangerousCommand
 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:
 3174            Prompt = New File Name?
 3175            r rename mv [SELECTION] {PROMPT:[Prompt]==>[SELECTION]}
 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.
 3182        You can also use Execution Variables inside a prompting Built-In:
 3184            d setdate SomeDateCommand {PROMPT:Set Date To: ===>[`date`]}
 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:
 3195        o   [MEM1] ... [MEM12]
 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:
 3202                m move mv [MEM1] ./
 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.)
 3217             For example, another way to express the full path of the currently
 3218            selected item is:
 3220                # Unix Path Separator
 3221                UPSEP = /
 3223                #Win32 Path Separator
 3224                WPSEP = \
 3226                [DIR][UPSEP][SELECTION]
 3228                          - or -
 3230                [DIR][WPSEP][SELECTION]
 3232            Be aware that, because of twander quoting  rules,  such  constructs
 3233            will result in strings like:
 3235                "/mydir"/"myfile"
 3237                          - or -
 3239                "C:\mydir"\"myfile"
 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.
 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.
 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.
 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.
 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:
 3274                g gencopy cp -R  {PROMPT:Enter Source}  {PROMPT:Enter Destination}
 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.
 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.
 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.
 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:
 3304           # Associations are in the form:
 3305           #     ASSOC file-type-string command-to-handle-this-type-of-file
 3307           ASSOC *.txt emacs [SELECTION]
 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.
 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:
 3322           EDITOR = emacs -fn 10x20
 3324           ASSOC *.txt {YESNO:Are You Sure You Want To Edit This File?} [EDITOR] [SELECTION]
 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:
 3330           ASSOC *.pdf   mypdfreader          [SELECTION]
 3331           ASSOC *.ps    mypostscriptprogram  [SELECTION]
 3332           ASSOC  *      myfineeditor         [SELECTION]   # Default association
 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.
 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.
 3345        To do this, put one or more statements in the following  form  in  your
 3346        Configuration File:
 3348           ASSOC ! space-separated-list-of-file-types
 3351        For example:
 3353           ASSOC  *     myfineeditor [SELECTION]
 3354           ASSOC  !     *.txt *.pyo *.ps
 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.
 3361        Note that exclusion has higher precedence than  any  explicit  associa-
 3362        tion, not just the default association.  If you do this:
 3364           ASSOC *.pdf   mypdfreader [SELECTION]
 3365           ASSOC !      .pdf
 3367        You are effectively masking the explicit association for .pdf files.
 3369        You  can  also  remove  a previously defined association by leaving the
 3370        right-hand-side of the ASSOC statement blank:
 3372           # This example first defines, and then removes an association
 3373           # for .pdf files:
 3375           ASSOC *.pdf   mypdfreader [SELECTION]
 3376           ASSOC *.pdf
 3378           # This one removes any exclusions you might have previously defined
 3380           ASSOC !
 3382           # This one removes any default association you might have previously defined
 3384           ASSOC *
 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 ).
 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.
 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:
 3414            *        Matches everything - strings of any length with any characters
 3416                        Example:  *.text matches all filenames ending in ".text"
 3418            ?        Matches a single character
 3420                        Example:  foo.??? matches all filenames beginning with "foo."
 3421                                  and ending with any three characters.
 3423            [list]   Matches any characters in the list
 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".
 3429            [!list]  Matches any character NOT in the list
 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".
 3435            Lists can also be ranges.  For example:
 3437                         [a-z]        Matches any lowercase letter
 3438                         [A-Z]        Matches any uppercase letter
 3439                         [0-9]        Matches any numeric digit
 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:
 3449           ASSOC   data??  MyFineDatabaseProgram [SELECTION]
 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.
 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:
 3468            ASSOC ! /*tXt  # Exludes files ending in txt, TXT, TxT, TXt, ...
 3469            ASSOC   /*txT emacs [SELECTION] # Invokes emacs for files ending as above
 3472        Prepending  the  "/" character to the association pattern is what tells
 3473        twander to ignore case when doing the matching.
 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.
 3479        To cancel a case insensitive association you must use the exact  string
 3480        originally used to establish the association:
 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
 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:
 3500               ASSOC *.text emacs [SELECTION]
 3501               ASSOC   *xt  ci [SELECTION]
 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.
 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.
 3525        o   Be careful which Built In Variables you use in an association  han-
 3526            dler definition.  Suppose you do this:
 3528               ASSOC *.txt emacs [SELECTIONS]
 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.
 3541            Even stranger things can happen if the last filename selected is an
 3542            executable and you've defined an association for it:
 3544               ASSOC *.py python [SELECTIONS]
 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:
 3550               python foo.c bar.py
 3552            Which is, um ... bogus.
 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.
 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.
 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.
 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:
 3581              ASSOC .txt myowneditor [SELECTION}
 3583            Then double-clicking  "foo.txt"  will  cause  "myowneditor"  to  be
 3584            invoked, even though Windows, by default, associates "notepad" with
 3585            text files.
 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.
 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.
 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.
 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.
 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.
 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.
 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.
 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.
 3639        Condition Test Statements are one of three types:
 3641            #####
 3642            # Existential: True if FOO or $FOO are defined
 3643            #####
 3645             .if [FOO]
 3646               ...
 3647            .endif
 3649             .if [$FOO]
 3650               ...
 3651            .endif
 3653            #####
 3654            # Equality: True if FOO or $FOO are literally
 3655            # the same as the test-string
 3656            #####
 3658            .if [FOO] == test-string
 3659                    ...
 3660            .endif
 3662            .if [$FOO] == test-string
 3663                    ...
 3664            .endif
 3666            #####
 3667            # Inequality: True if FOO or $FOO are literally
 3668            # not the same as the test-string
 3669            #####
 3671            .if [FOO] != test-string
 3672                    ...
 3673            .endif
 3675            .if [$FOO] != test-string
 3676                    ...
 3677            .endif
 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.
 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.
 3691        Several  things  about Conditional Processing Statements are worth not-
 3692        ing:
 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.
 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.
 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.
 3709        o   The  Right  Hand Side of an (in)equality test is just a string com-
 3710            parsion - no variable expansion is done:
 3712                .if [FOO] == string[BAR]
 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.
 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.
 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.
 3729    The Include Directive
 3730        You may include other files in your Configuration File with the follow-
 3731        ing directive:
 3733            .include path-to-file
 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.
 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:
 3751            # Contents of /usr/local/etc/.twander.global
 3753            SHELL   = bash -c
 3754            XTERM   = xterm -fn 9x15 -l
 3755            VSHELL  = [XTERM] -e [SHELL]
 3757            DIRSC1  = /usr/local
 3758            DIRSC2  = /usr/sbin
 3760            t terminal   [XTERM]
 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:
 3767            # Contents of $HOME/.twander
 3769            .include /usr/local/etc/.twander.global
 3771            DIRSC2  = /etc
 3773            l ls       [VSHELL] 'ls -al | [$PAGER]'
 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.
 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.
 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.
 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/
 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.
 3829        Once  you  have  these extensions installed, twander will automatically
 3830        enable three new features otherwise unavailable.
 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.)
 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:
 3847                d - Directory
 3848                A - Archive
 3849                C - Compressed
 3850                H - Hidden
 3851                N - Normal
 3852                R - Read-Only
 3853                S - System
 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.
 3866            You can enter the Drive List View in a number of ways:
 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.
 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.
 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:
 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.
 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.
 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)
 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.
 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.
 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
 3941        There are several tricky corners of twander which need further explana-
 3942        tion:
 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.
 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:
 3958            export HOSTNAME=`hostname`
 3960        (Note the backticks used to execute the 'hostname' program  and  assign
 3961        its results to HOSTNAME.)
 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'
 3968        On Windows, environment variables are set  via  the  System  Properties
 3969        menu.
 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):
 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
 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:
 4003            C:\Program Files\PythonXX\Lib
 4005        Where "XX" is the actual version of Python you're running.
 4007        Open this file with an editor and look for the following text:
 4009            encoding = "ascii" # Default value set by _PyUnicode_Init()
 4011            if 0:
 4012                # Enable to support locale aware default string encodings.
 4013                import locale
 4015        Change the if 0: statement to if 1: and the problem will disappear.
 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:
 4031            V   view    less    [DSELECTIONS]
 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.
 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:
 4045            V   view         xterm -l -e less [DSELECTIONS]
 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:
 4051            L lshome         xterm -l -e bash -c 'ls / | [$PAGER]'
 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):
 4057            SHELL       = bash -c
 4058            VSHELL      = [XTERM] [SHELL]
 4059            XTERM       = xterm -fn 9x15 -l -e
 4061        Now you can write the command above like this:
 4063            L lshome          [VSHELL] 'ls / | [$PAGER]'
 4066        This  causes your command line program to execute in an 'xterm' context
 4067        and under a shell interpreter.
 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.
 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.
 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:
 4089            L DirList dir {PROMPT:Directory Of What?} | more
 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.
 4095        On Unix-like systems, however, this does not work as expected.  Suppose
 4096        we define the command for these systems to be:
 4098            L DirList [VSHELL] 'ls -l {PROMPT:Directory Of What?} | [$PAGER]'
 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:
 4105            /kern*
 4107        The command twander tries to execute is:
 4109            VSHELL Stuff ... 'ls -l "/kern*" | ... pager stuff
 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.
 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.)
 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:
 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
 4134            L DirList [VSHELL] 'UsrResp={PROMPT:Directory Of What?} ;
 4135                                         ls -l $UsrResp | [$PAGER]'
 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.
 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.)
 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.
 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.
 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.
 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.
 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:
 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.
 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.
 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.
 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.
 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.
 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.
 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.
 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:
 4260        o   Except  for  conditional  tests,  Environment  Variables  and User-
 4261            Defined Variables are never resolved until they appear in a Command
 4262            Definition.
 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.
 4271        o   A Condition Test Statement always involves  a  variable  reference,
 4272            never just a variable name.
 4275        o   For  a Condition Test Statement to be true, the referenced variable
 4276            must be defined and any equality test must be satisfied.
 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:
 4285                CondVar =
 4286                .if [CondVar]
 4287                  ....
 4288                .endif
 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:
 4299                FOO = bar
 4301                x cmd1 command [FOO]
 4303                FOO = baz
 4305                y cmd2 command [FOO]
 4307            In this example, the first command  will  be  defined  as  "command
 4308            bar", but the second will be defined as "command baz".
 4310            Watch  for  this,  especially,  when using the ".include" directive
 4311            and then overriding a variable defined in that file.
 4314        Common mistakes include:
 4316            #####
 4317            # Trying to embed a variable where it will never be resolved
 4318            #####
 4320            DIRSC03 = [$SystemDrive]\Program Files
 4321            MYCOLOR = blue
 4322            FCOLOR  = [MYCOLOR]
 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            #####
 4334            EDT = [$EDITOR]
 4336            .if [EDT] == /usr/local/bin/emacs
 4337                      ...
 4338            .endif
 4341            # Note, however, that *this* would work because
 4342            # Environment Variables are permitted in conditionals ...
 4344            .if [$EDITOR] == /usr/local/bin/emacs
 4345                      ...
 4346            .endif
 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            #####
 4355            PROCESS = no
 4356            SUBPART = no
 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
 4362            .if PROCESS != no
 4363                ...           # Processed!
 4365                .if [SUBPART] == yes   # *Now* we'll stop
 4366                    ...
 4367                .endif
 4369            .endif
 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.
 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.
 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.
 4388        You  must  install  the  'win32all'  extensions  if you want to use the
 4389        advanced Windows features.
 4391        You'll find the latest version and, occasionally, Release Candidates of
 4392        the next version of twander at:
 4394            http://www.tundraware.com/Software/twander
 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.
 4403        As  of  this release, a number of problems relating to twander use have
 4404        been noted:
 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.
 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.
 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.
 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.
 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.
 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.
 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.
 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.
 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.)
 4467        Make sure that /usr/local/bin is in your path.  To start  the  program,
 4468        just type "twander.py" from the shell prompt.
 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.
 4478        To run the program, just type "twander.py" from a shell prompt.
 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:
 4489        o   Rename 'python' to 'python1' and then rename 'python2' to 'python'.
 4490            (Not Recommended - could break other programs.)
 4493        o   Write an alias or shell script which explicity starts twander  with
 4494            the correct version of Python:
 4496                #!/bin/sh
 4497                python2 twander.py $*
 4500        o   Change  the  first  line  of the twander code to refer to 'python2'
 4501            instead of 'python'.
 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.
 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.
 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.
 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.
 4538        You can run the program several ways on Windows systems:
 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:
 4549                "C:\Program Files\Python22\pythonw.exe" C:\twander.py \
 4551            This runs the program starting at the root directory of the current
 4552            drive (assuming "twander.py" is located in C:\.
 4555        o   Start a command line window and issue a command like the one  above
 4556            directly from the command line.
 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.
 4568        TundraWare  Inc.  maintains an email list for twander users to get help
 4569        and exchange ideas.  To subscribe, send mail to:
 4571            majordomo@tundraware.com
 4573        In the body (not the subject line) of the email,  enter  the  following
 4574        text, substituting your own email address as indicated:
 4576            subscribe twander-users your-email-address
 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.
 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.
 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.
 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:
 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.
 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.
 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.
 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.
 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.
 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.
 4661 AUTHOR
 4662            Tim Daneliuk
 4663            twander@tundraware.com
 4667        $Id: twander.1,v 1.155 2009/07/01 20:16:33 tundra Exp $
 4671                                 TundraWare Inc.                     twander(1)