Kind of Documentation for "tkdir"
---------------------------------

What is "tkdir" NOT ?
   it is NOT the "Norton Commander" nor is it modelled after the "Norton
   Commander" or tries to be something similar to it. Please don't compare it to
   the "Norton Commander" !
   Now, that I have mentioned it 3 times, I hope that this ugly old disease will
   never be mentioned again and especially not in conjuction with "tkdir".
   But if you REALLY want to know, where I have got the basic Ideas behind
   "tkdir": The Tools which have been "models" for "tkdir" are: CLIMate,
   DirUtil, DirectoryWorks and DirectoryOpus (And 100 Points if you guess from
   which little toy)
   
What is the Idea behind "tkdir" ?
   At first, it is true, that with respect to the pure "directory utility"
   functionality of "tkdir" there are lots of other tools which may be even
   better than "tkdir", but I hope, that "tkdir" will improve over the time.
   (If you know DirectoryOpus and DirectoryWorks, you probably know what I mean)
   But what is REALLY missing with UNIX is a tool for easy maintaining of 
   files in a Workstation Cluster !
   (Of course there are many tools like "supper" or "rdist" and even advanced
   tools for complex Cluster Management up to complete site administration, but
   this was NOT the point I wanted to adress.)
   To give you an Idea of what I mean:
      In our RS6000 Cluster we have 4 Machines with the  normal Power Processor
      and 10 nodes of an SP2 with a Power2 Processor.
      It is expected that we will have some PowerPC Workstations in the nearest
      future too.
      Now we have to maintain a large set of library routines and scientiffic
      analysis programs which are running on all machines.
      The time critical libraries should be compiled with special options for
      each processor to gain the maximum available speed, but we don't want to
      do this for all programs.
      So we are working with several directories and links between the
      directories for files which do not need to be compiled in the fastest
      way.
      We know exactly which files need to be linked, but typing all this stuff
      by hand is stupid and exactly this kind of work for which a computer
      could be used.
      So probably you would write a small script which does this for you. This
      will probably take you more time than doing it with hand, but the Work is
      less stupid. But I decided to spend even MORE Work and wrote this tool,
      which also should assist with other Problems:
      - Distributing files from one node to a cluster
      - Copying files (from /etc or /var/adm) between different Workstations
      - easy maintaining of files in a Cluster (Comparing, Deleting,...)
      It is also intended to add routines which should assist in maintaining
      the AFS. I hope, that future releases of "tkdir" will be more open and
      configurable than the current one, which is released to start the whole
      thing and get my above mentioned "links".
      
Modes of operation and how it works:
   The main difference between a conventional "Directory Utility" and "tkdir"
   is that you do not operate on "local" files alone. 
   Instead of this you may have the following modes:
   - working on LOCAL FILES ONLY (similar to the conventional tools)
   - working on the LOCAL SOURCE for ONE REMOTE DESTINATION
   - working on ONE REMOTE SOURCE and the LOCAL DESTINATION
   - working on ONE REMOTE SOURCE and ONE REMOTE DESTINATION
   - working on the LOCAL SOURCE and a CLUSTER DESTINATION
   - working on ONE REMOTE SOURCE and a CLUSTER DESTINATION
   How is this done ?
   Simply by working with "rsh" and "rcp" !

Mouse Buttons:
   The left button selects files and directories. Dragging selects a Range
   The Right Buttons (2 AND 3) unselect files and directories
   Double Clicking on a directory changes to this directory
   Double Clicking on a File views this file with "tke"
      NOTE: "tke" is not part of this package. It is part of the "tkedit"
            distribution (available at alcatel mirrors or at
            ftp.ifh.de:/pub/unix/edit/tkedit-l.m.n.tar.Z)
   If "tkdir" was started with the "-fs" option double clicking returns
   the name of the file (and if not on the actual host also the hostname)
   
   In the Directory hotlist the left button sets the left file box, whereas the
   middle and right button are setting the right filebox.

Entry Widget setup:
   All entry widgets have the following behaviour:
   <Return>    starts all actions (eg. reading directory or return input)
               Note: THERE IS NO OTHER WAY to start the actions then 
                      typing RETURN !!!
   <Button-2>  inserts X-Select
   <Control-k> kills line
   <Cursor keys> move forward and backward

The left and right Main widgets:
   The left File selection widget is referred to as "the source" and the right
   as "the destination" but in some cases operations are executed on BOTH.
   You may add or remove special information widgets from the "View Left" and
   "View Right" Menu items.
   Directories, Links and normal files are displayed in different colours.
   Set UID files are listed in black with red background !
   Double Clicking on a directory goes into this directory,
   Double clicking on a link tries to follow this link
   Double clicking on a file starts a viewer for this file

The Cluster widget:
   If you are Working on a Cluster a special "Cluster information" box is
   added to the right side
   You can select nodes from this widget in a similar way as with files.
   Selecting "All" and "None" is provided in the menu.
   Prior to ANY operation you MUST have selected some nodes to work on !
   Double clicking on any node displays the directory on this node (only the
   right side is read)
   
The "Buttons" and "Entries" from the first row
   The Top left Button lablled "Q" is of course the "Quit Button"
   Then follows the Information label with the number of files and the sum in
   bytes.
   The "Root" button goes to "/", the "Home" Button to "$HOME" and the "Parent"
   Button to ".."

   The Entry window selects the subset of files to be displayed. You simply
   click with the mouse inside of this window, make your modifications and
   TYPE RETURN ! After this the window will be uypdated. Note: The directory is
   neither READ again nor fully Sorted again ! (so it will be faster than
   reading the whole directory and sorting it again) 
   
   The right hand side is similar.
   
The row below the "file information widgets"
   The Buttons labeled "^" and "v" are serving as "stack" for the following
   entries:
   - The Entry for the hostname you want to work on (If this happens to be the
     same name as the node you are on, operations are local)
   - The Entry for the directory you are in.
   The Button labled ">" copies the information to the right window
   The Button labeled "<>" excanges source and destination sides 
   The Button labeled "<" copies the information from the right side to the
   left side.
   The entry widgets for the destination are similar to those for the source.
   
The last row
   This row contains two Entry widgets and one Button.
   The first Entry widget shows you specific informations.
   The second Entry widget is for your input in cases were it is needed.
   The Button calls a second "tkdir" as replacement for a "FileSelector" box
      this enables you to choose file names from a menu rather than typing them
      in (future releases will make this a configuration option)
      
The operation Buttons
   <All>       L  Selects all entries on the LEFT side as source
   <None>      B  Deselect all entries from BOTH sides
   <Intersect> L  Selects all entries (in LEFT) which are in both windows
   <NOT in TO> L  Selects all entries which are NOT in the right window
   <Diff Len>  L  Selects all entries with equal names and different sizes
   <pattern>   L  Asks for a pattern (glob style) for selection
   <Reselect>  B  Normally "tkdir" resets all selections after any operation
                  With this button you may restore the selection
   <Force Read> B Normally a directory which has allready been read will never
                  be read again. With this button you can enforce a reread.
   
   <Copy>      BC Copies ALL SELECTED files and directories.
                  If destination is a cluster it copies all entries from the
                  left window to all destination machines but only the files
                  from the machine denoted in the "hostname" widget are copied
                  in the reverse direction (any other behaviour would be
                  senseless)
                  NOTE: If files are selected in the destination widget, they
                  are also copied to the source !
                  NOTE: Please refer to the "rcp" man pages to see if any
                  of these actions are not supported by your "rcp"
   <Delete>    BC Entries are deleted on the side were they are selected.
                  NOTE: If a directory is selected it will also be deleted !
                  This way you may delete a whole tree in the Cluster !
   <Move>      B  This will move files from one side to the other
                  NOTE: since I am not shure if it makes sense to move files
                  between Workstations, I have not enabled this feature yet.
   <Rename>    BC Asks for a new name. If multiple files are selected
                  you are asked several times !
   <Link>     -BB This Operation works ONLY LOCALLY (if you know how to make it
                  a cluster wide feature, let me know)
                  It works exactly like <Copy> from both sides simultaneously
                  except, that the file is linked instead of copied
   <Compare>   B  Starts "tkdiff" on ALL Selected files.
                  NOTE: Up to now this  feature works only locally
                  NOTE: This requires "tkdiff" to be installed. "tkdiff" is a
                  separate package, available from any tcl-site
   <MakeDir>   R  Creates a directory on the DESTINATION side (where you later
                  on may want to copy files to)
   <Chmod>     BC Changes file permissions. Asks for the permissions as used by
                  "chmod" itself.
                  NOTE: If you want to make it recursively, add a "-R" before
                  the pattern
   <Chgrp>     BC Works similar to <Chmod>. Asks for the parameter of "chgrp"
   <Chown>     BC Works similar to <Chgrp>. Asks for the parameter of "chown"
   <Edit>     -B  Starts "tkedit" on a file. Works on either side 
                  Multiple files are edited in one editor window.
                  NOTE: "tkedit" is an editor written in TCL-TK and not part of
                  this distribution. Source: alcatel archive or:
                  ftp.ifh.de:/pub/unix/edit/tkedit-k.l.m.tar.Z
   <View>     -B  Starts "tke" on the output of a "cat" pipe. Works Remotely
                  but not for a whole cluster.
                  NOTE: Each file will be viewed in a separate window !
                  NOTE: "tke" is part of the "tkedit" package and not included
                  in this distribution
   <tar extr.> BC Extracts an archive (even if compressed)
                  NOTE: gtar (gnutar) is needed
   <tar crea.> B  Asks for a file name and generates an archive of all selected
                  files.
                  NOTE: gtar (gnutar) is needed
   <tar list>  B  Shows contents of an archive. (even if compressed)
                  NOTE: gtar (gnutar) is needed
   <configure> R  starts configure script in destination directory
   <xmkmf>     R  starts Imake in the destination directory
   <make>      R  starts make in the destination directory
   <Command>   RC executes a command on the remote machine or the whole cluster.
                  The Working directory is set according to the Directory entry.
                  A Percent sign (%) will be expanded to all selected files !
                  All Commands are executed in Serial up to now
                  Output goes to a text scroll window.
                  
In FileSelect Mode there are two extra buttons:
   <OK>           returns all selected files and exits
   <EDIT & OK>    lets you edit the name and exits
   There is no extra Cancel button. Use <Q> !

Startup files:
   Preferences are saved in ~/.tkdir
   You may add additional functions in a scriptfile ~/.tkdirrc which will
   be sourced after all procedures have been set up and before the command line
   arguments are passed.
   System administrators can set default values for specific machines in the
   file /etc/tkdir.cfg (look at default file supplied with tkdir)
   
Command line arguments:
   -patt[1|2]  Preselects a matching pattern
   -dir[1|2]   Sets a directory
   -fs         Starts in "FileSelect" mode
   
Using Internals:
   1. Variables used so far:
      Please have a look at the beginning of "tkdir" to see if you need to
      change some constants. BUT PLEASE DO THIS IN YOUR .tkdirrc !
      Other Variables:
      WorkStation1 , WorkStation2 , DirName1 , DirName2 refer to the file names
      "Comment" and "Input" are the Bottom widget string variables
   2. Usefull procs:
      AskUser comment preset
            makes the user query
      GetCluster
            returns all nodes of the cluster
      GetSelect win flg
            win = 1,2
            flg = -1 , 0 , 1 (files, dir/file , ws:dir/file)
            returns all selected files.
      OperationMode
            returns LL LR LC RL RR RC for "Local", "Remote" and "Cluster"
   
   3. Adding buttons
      The most interesting part is of course is to add custom buttons.
      Add your frames inside the .public frame
      Template:

      frame .myframe
      pack .myframe -in .public -side top -expand 0 -fill both
      button .myfun -text "hello" -width 10 -command {puts stdout "hello"}
      pack .myfun -in .myframe -side left
      
      BUT PLEASE DO THIS IN YOUR .tkdirrc !
      
Update Notes:
Changes in Version 1.0.1:
   -  Made Cluster window a "text" widget rather than a "listbox" to enable
      selection of single nodes
   - Added "Command" button

Changes in Version 1.0.2:
   - Fixed Bug with "Taggedx - no such variable" during Cluster operations
   
Changes in Version 1.0.3:
   - improved reading of files
   - does not allways spawn a tkedit
   - imroved following links
   - Added "%" replacement for selection in <Command> button
   
Changes in Version 1.0.4:
   - Fixed Bug with "rsh 2>/dev/null" not found in cluster mode
   - Fixed Bug that "~" files could not be viewed
   - Added some more viewers (double click on file)
   
Changes in Version 1.0.5:
   - Added Automagic switching of ls command between "ls -la" and "ls -lag"
   
Changes in Version 1.0.6:
   - Fixed Bug with wish4.0: scroll command did not work
     (same problem as with tkedit)
   - Fixed bug with "for each"
   - Improved text viewing widget

Changes in Version 1.0.7:
   - Added Saving of Cluster with preferences
   - Added automatic command mode
   
Changes in Version 1.0.8:
   - Improved Stack
   - Added Directory Hotlist
   - Added Reading of cluster from Netgroups
   
Changes in Version 1.0.9:
   - Added automatic detection of "remsh" command (instead of rsh)
   
Changes in Version 1.1.0:
   - Added Preferences for BW-Terminals
   - fixed Bug with "Rename" on remote machines
   - Now reading error output from commands also

Changes in Version 1.1.1:
   - Fixed Bug in "configure" button (Thanks to Marie Roch)
   - Fixed bug with preferences: commands were not handled correctly !
     (Why did no one send me a mail about THIS bug ?)
   - Added preferences "ls" configuration
   - Added /etc/tkdir.cfg
   - Fixed Bug with wish4.0: Middle button does not insert text anymore (Thanks
     to Marie Roch)
   - Added Color Options for the View-window, the directory entry and the
     buttons (Thanks to Monty Scroggins)
     
Changes in Version 1.1.2:
   - Added changing of button and entry colors for BW-Terminals 

Changes in Version 1.1.3:
   - Fixed Bug which prevented preferences "ls" configuration to work properly
     (introduced with configuring the "ln" command also)
   - Corrected some color and font adjustments
   - Added scrollbar for directory names
   
Changes in Version 1.1.4:
   - I am in the process of rewriting a large amount of code.
     This is an intermediate Version which has only been released to fix a
     problem with wish4.0 (the entry button scroll "view" -> "xview" command)
     
Changes in Version 1.1.5:
   - Another fix for tk4.x: Now the scrollbars do behave normally

Bugs:
   - Clusteroperations are often done as background processes and may not 
     have finihed after the reread is started. Start a second "Force Read"
     in this case to see if everything went OK
   - rsh may return "no remote authentication" on AFS machines
   - rcp may not work remote to remote
   - Cluster directories may not be updated after changing the destinations.
     Use separate "Force Read"
     
Nasty Bugs:
   - catch {exec rsh ... } var
      works fine most of the time. But sometimes (10% of the time !) it does
      not set "var" correct. This is also true for wish4.0 !
      So there was no way for executing remote commands to give an error return
      other than to let it writeout to a file

Thanks for Help to:
   Marie Roch        (mroch@research.att.com)
   Monty Scroggins   (Monty.Scroggins@rsd.dl.nec.com)
   to be continued...
   
------------------------------------------------------------------------------
Rainer Kowallik         postdoc at           DESY-Ifh Zeuthen
Kowallik@ifh.de                              Platanenallee 6, D-15738 Zeuthen



