FileRunner
----------

(C) 1996-1998 Henrik Harmsen


Table of contents
-----------------------------------------------------------------------------
1       Concepts And Basic Usage

2       The Main FileRunner Window - A Quick Tour

3       Reference
3.1     The Main Menu
3.2     The Status Line
3.3     The Directory Panels
3.3.1   The Directory Panel Menus
3.3.2   The Directory Panel Buttons
3.3.3   The Directory Entry
3.3.4   The File List
3.3.4.1 Mouse Buttons In The File List
3.3.4.2 Keyboard Support In The File List
3.4     The Command Button List
3.4.1   Synchronous vs. Asynchronous Command Execution
3.5     Command Line Arguments

4       The Classing Engine

5       The Internal Text Viewer And Editor
5.1     The Internal Text Viewer Menu
5.2     The Internal Text Editor Menu

6       Configuration

7       Home-made Buttons

8       FTP (File Transfer Protocol)
8.1     Anonymous FTP
8.2     FTP Through Proxy
8.3     Synchronous Or Asynchronous FTP Transfers
8.4     FTP Timeout
8.5     Closing FTP Connections
8.6     FTP Transfer Status
8.7     Temporary Storage For FTP Files
8.8     Using The Rule-based Configuration For FTP Logins
8.9     Batch FTP
8.10    FTP Transfer Speed (dropped characters with a buffered serial port??)

9       The Internal Shell Windows

10      Miscellaneous
10.1    Exported Selections
10.2    Files Used and Created By FileRunner
10.3    Choosing cursor color
10.4    HTTP download

11      Copying/Copyrights/Legal Stuff

12      Bug Reports/Questions

13      Contacting The Author / The Announcement Mailing List



1. Concepts And Basic Usage
=============================================================================

In the FileRunner window there are two file listing panels, side by
side. They are equivalent in function, but one will act as "source"
panel and the other "destination". To make one panel "source" panel,
you just select files in a panel and that panel becomes "source". The
opposite panel becomes "destination". The source and destination
panels are then used in the commands. To copy a few files or
directories, just select the files and directories in the left or the
right panel and press the Copy button, the files/directories will then
be copied into the opposite panel.

Selecting files/directories is done by holding the left mouse button
down on a file and drag the mouse to select a range of files. You can
do an extended select by using the Ctrl-button + left mouse
button. This will let you select more than just a range of consecutive
files. Try it and you will see how it works.

So, the left mouse button is a select-button and will also activate
buttons and menus. The right mouse button is a "view" button. Press it
over a directory and you will enter that directory. Press it over a
text file and a text viewer will pop up. Press it over any file and
FileRunner will try to guess what kind of file it is and view it some
way or another. Double-clicking the left mouse-button will do the same
thing as using the right mouse button.


2. The Main FileRunner Window - A Quick Tour
=============================================================================

At the top, there is a menu (File, Configuration, Utilities and Help) that
holds the main FileRunner menu. 'nuff said.

Below the top menu, there is a status line that will show messages
generated by the program. Most of these messages go into a log that
can be viewed and saved later (File->View Log).

Below the status line to the left and right are the directory panels,
and in the middle are the command buttons. The directory panels
contain buttons and menus that act on the directory list shown in that
panel. More about this in the reference chapter below.

3. Reference
=============================================================================

Here is the full reference to all commands and buttons and tricks you
can do in FileRunner. 

3.1 The Main Menu
=============================================================================

  File->About

About FileRunner.

  File->View Log

View the log that FileRunner keeps of everything that has been
done. Most (important) messages to the status line end up in the log
also. The log can be saved if you press the right mouse button in the
viewer and select "Save As...".

  File->Quit

Quit (will save the history to disk first).

  Configuration->Save Configuration

Your configuration and preferences are saved in a file called
"$HOME/.fr/config" (The .fr directory is created at first start
automatically). This file is read every time FileRunner starts up. The
config file is auto-generated when saved like this, so this operation
will erase any edits you have done to the file. This is an operation
you will want to do when you add stuff to the hotlist so it will be
saved for next time, and also in the other cases when changes in the
FileRunner menus affect the configuration file. Warning: If you have
more than one FileRunner running and use both to save configuration
they will overwrite each others configuration. Also note that per
default, FileRunner will save its configuration upon exit (unless you
set the configuration option config(save_conf_at_exit) to
zero). Another good time to save your configuration like this is when
you get a new version of FileRunner, so the config file will show the
correct setting variables available for that version.

  Configuration->Edit Configuration

This will launch a configuration browser. Click on the options in the
left list to quickly jump to an option and edit the option in the text
field to the right. When done, press OK.

  Configuration->Reread Configuration

The config file ($HOME/.fr/config) is re-read. This can be used if you
edit the config file with an external editor and you want the
configuration to be read back into FileRunner.

  Configuration->Show All Files

Determines whether files beginning with a dot (.) should be shown or
not in the file lists.

  Configuration->Create Relative Links

If set, the S-Link and S-LnAs buttons will create relative soft
links. Otherwise, they create absolute soft links.

  Configuration->Run Pwd After CD

If set, FileRunner will run "pwd" after cd'ing to a new directory to
check where it ended up. Otherwise, it will not do this, but instead
infer the new path from the old path. This makes a difference when
cd'ing to a link that points to a directory.

  Configuration->Run Pwd After CD (FTP)

Same as previous setting above, only that it affects FTP
listings. Setting this to off will also yield slightly faster
directory traversing in FTP.

  Configuration->Anonymous FTP

Determines whether FTP connections should be done anonymously, i.e
using "anonymous" as user login and your email address as password. If
you turn this off, you will be asked for username and password
whenever a new FTP link is set up.

  Configuration->Use FTP Proxy

Determines whether the FTP proxy should be used when doing FTP. See
more in the FTP chapter about this.

  Configuration->Sort *****

Determines which way the file lists will be sorted. Try it out and you
will see how it works.

  Configuration->Edit xxx color

Change various GUI colors. You have to save your configuration if you want
them to survive to the next time you run FileRunner. These configuration
(with their documentation) are in the configuration file also.

  Configuration->Edit xxx font

Change various GUI fonts. You have to save your configuration if you want
them to survive to the next time you run FileRunner. These configuration
(with their documentation) are in the configuration file also.

  Configuration->Set Left Start Dir
  Configuration->Set Right Start Dir

When you issue one of these commands for the left and right file list
panels, respectively, you change the config(startpwd,[left,right])
variables so that the next time you start FileRunner it will start at
that directory position.  You have to save your configuration to store it
to the config file.

Another way of doing this is to edit the configuration file with
Configuration->Edit Configuration and change those two variables.

  Configuration->Set Window Pos/Size

When you issue this command, you change the config(geometry,main)
variable so that the next time you start FileRunner it will start with
the current size. You have to save your configuration to store it to the
config file.

Another way of doing this is to edit the configuration file with
Configuration->Edit Configuration and change the config(geometry,main) variable.

  Utilities->Swap Windows

Swap the current directories between the two file list panels.

  Utilities->View As Text

View selected files as text files. This comes in handy when the file
classification rules don't work. Like for example when you have a text
file called foo.gif, FileRunner will think this is an image and launch
the image viewer if you just right-mouse-button click on it.

  Utilities->What Is?...

Select a file and choose this command to use the Unix "file" utility
to try to figure out what kind of file it is.

  Utilities->Select On Contents...

Lets say you have selected all the .h files with the Select command
above and you want to narrow the selection to only the files that
contain the string "MAXBUF". Choose this command and edit the grep
command to "grep MAXBUF" and press return. The selection will now show
only files containing the MAXBUF string.

  Utilities->Run Command...

Select a few entries and choose this command and you will then get a
popup asking you to enter a command that is to be run with the
selected files as argument. The output of the command, if any, will
show up in a text viewer. You can also use this to start
programs. Just select the executable, press RunCmd, edit the command
and press enter (add a "&" if you like to run it in the background).

  Utilities->Check Size Of Selected...

This command counts the size of selected files and directories and
shows the result in kilobytes. Note that this uses the du command
and you might have to add the -k flag here to get the answer in
kilobytes on some platforms (like Solaris 2.x). Do that in the
Configuration->Edit Configuration command [config(cmd,du)].

  Utilities->FTP Copy With Resume

Use this menu choice instead of the Copy button if you want to copy
files with FTP in "resume" mode. This means that if you have
previously dropped an FTP transfer you can continue to download where
you left off.

  The Stop button

This tries to abort the current command. For normal file access
commands (copy, move etc) it can only abort between two files, not in
the middle of operating on a file (ex:in the middle of copying a
file). For FTP, you can abort in the middle of a transfer. The FTP
link will be closed when you do this, but reopened the next time you
access an FTP file. You can

  The Clone button

Start another instance of FileRunner at the same directory positions
as the current one. In addition to the Stop button above, these two
buttons are the only ones that can be pressed during execution of a
long command (usually, not all commands accept this). This button is
especially good if you start a long FTP transfer and you want to
continue to browse during the transfer in another window.

  Username@Machine

This is an indicator showing you the user FileRunner was started by
and which machine it is executing on.

  The Clock

You can get two different formats for this. Check the configuration
file for config(dateformat).

  Help->****

Online help texts.


3.2 The Status Line
=============================================================================

Various status messages will show up here. Important ones will also be
logged to the internal message log that can be viewed and saved with
"File->View Log".

3.3 The Directory Panels
=============================================================================

At the top of each directory panel is a status line that tells the
number of selected files out of the total number of files, the number
of bytes in those selected files and also how much free space is left
on the disk.

3.3.1 The Directory Panel Menus
=============================================================================

  [Tree image]->*****

This is a very cool feature of FileRunner. Under this menu, you have
your entire file system mapped in a cascaded hierarchical menu. Just
go down into the menu and select a directory and you will swoosh over
there. Don't worry, FileRunner does not map your entire file system at
startup, it builds the menus as you traverse them (this is why it
sometimes takes a while if you go into slow file systems).

  Hotlist->Add to hotlist

Adds the currently shown directory to the hotlist.

  Hotlist->[directories]

Choose a directory to go there.

  History->******

As you travel through the file system visiting various directories,
there is a history to keep track of where you have been. Just select
this menu to go back in time. Note that the history list is limited to
20 entries, to keep it from growing outside your screen.

  Etc->Find File...

Let's you type in a fragment of a file name and search for this in the
current directory. A panel with the search results will pop up and you
can click on the file names to locate the file in the file list panel.

  Etc->Create Empty File...

You'll figure it out...

  Etc->Add To Batch List...

Add all selected files to the FTP batch list

  Etc->View Batch List...

View the FTP batch list

  Etc->Clear Batch List

Clear the FTP batch list.

  Etc->FTP Batch Receive...

Download all files in the FTP batch list to the current directory.


3.3.2 The Directory Panel Buttons
=============================================================================

  [Left-Arrow]

Use this to go back to previously visited directories. Works just like
the back button in Netscape. This button is a little different than
the history menu, since the history meny holds the history of the left
and right visited directories merged together, while the back button
is a "true" back button that really let's you travel backwards in each
file list panels individually.

  [Two arrows in a circle]

Press this to update the file list, in case you think it needs
to. FileRunner will notice certain events by itself and will usually
keep the list up-to-date automatically.

  [Up-Arrow]

Press this to go upwards (cd ..) in the directory tree.

  [Image of the built-in shell window]

Starts the built-in shell for the left or right panel. See chapter 10
for more info on this.

  [Image of a terminal window]

Press this to start a terminal window at the current directory
location.

3.3.3 The Directory Entry
=============================================================================

This entry shows what directory is listed in the file list below. Edit
this to go somewhere else. Sometimes it is also used as an input to
commands. For example the MakeDir button will want the name of the new
directory here before you press the button.

To quickly clear the entry: Press Ctrl-A (to go to the start of the
entry) and Ctrl-K to clear it.

You can also press the right mouse button in the directory entry to
pop up a requester where you can type in the new path.

If you type in a directory that doesn't exist a requester pops up to
ask you to correct your input. Here you can also press a Create button
that creates the new directory and changes directory to it. This is a
good way of creating new directories. When the new directory is
created, all it's parent directories are created also if they don't
already exist.

3.3.4 The File List
=============================================================================

This panel shows the contents of the directory. You can scroll around
using the scrollbars, or the middle mouse button. To the left are the
file names. Files shown with a / appended to them are directories.
Files with a @ appended are links. You can see where the link points
to if you scroll the list to the far right. Next comes the size of the
files, followed by the date of their last modification. The date
format can be changed, do a "Configuration->Edit Configuration" and
look for the config(dateformat) variable. After the date comes the
standard Unix file mode flags. After this the owner (user/group) is
shown. Last on the line comes an indication of where a soft link
points to, if the file is a soft link, that is.

If you activate a panel (by selecting a file in it) and press a key,
the file list will adjust to show files starting with that
character. This is handy to quickly search for a file you know starts
with a certain character.

At the bottom right of the file list panel, where the scrollbars meet,
there is a button with the letter S in it. This is a select-all /
select-none toggle button to quickly select all files or no file.

3.3.4.1 Mouse Buttons In The File List
=============================================================================

This area is a little bit messy, so I'll try to clear it up with a
simple table of available mouse operations.

LMB = left mouse button
MMB = middle mouse button
RMB = right mouse button

LMB         - select/unselect (clears selection first)
MMB         - select/unselect (does not clear selection first)
Ctrl-LMB    - select/unselect (does not clear selection first)
RMB         - view things/cd to directory
Double-LMB  - view things/cd to directory
Ctrl-RMB    - View directories in opposite panel

As you can see, some functions are on more than one button. This is as
it should be. Which you use is a matter of convenience. When it says
Ctrl-RMB that means you have to press Ctrl on the keyboard and hold it
and then press RMB. Double-LMB is a normal doubleclick.

As can be seen from the table, viewing stuff is done by pressing RMB
on a file. Press it on a text file, you will view the text file. Press
it on an image file, you will view the image. Press it on an archive
and you will get a list of the contents of the archive. Etc..

You also change directory to a new directory by pressing RMB on the
directory.

If you press Ctrl with RMB on a directory, the directory will show up
on the opposite panel, letting you easily browse a list of
directories. Very handy!


3.3.4.2 Keyboard Support In The File List
============================================================================

If you set the config variable config(keyb_support) to 1, FileRunner
activates keyboard support mode. Currently, this is not very
extensive. This is what happens:

The file list panels take focus when clicked and the selection can be
adjusted with the up/down arrows.

When the one of the file list panels are in focus:

  * Pressing tab changes focus to the opposite window
  * Up/Down arrows adjust select
  * PgUp/PgDown scrolls a whole page up and down
  * Left arrow goes one directory up (cd ..)
  * Right arrow views things (including directories)
  * The underlined characters in the middle command buttons can be
    pressed to start a command. (c : Copy, d : Delete etc.)

I'm sorry FileRunner does not yet have better keyboard support, but it
really was designed as a mouse-operated application from the ground
up.


3.4 The Command Button List
=============================================================================

At the top of the command button list there are two buttons with an up
and a down arrow on them (ignore the sideways arrow for now). If you
press these you will scroll through the whole list of command
buttons. This is handy when the number of buttons grow beyond the size
of the window. (You can add more buttons here yourself, see below).

Below these two buttons comes the main command button list. Most of
these buttons will do nothing if you do not first select something. If
the command button supports asynchronous mode, this will be noted
below. Also see chapter 3.4.1 below about asynchronous vs. synchronous
command execution.


  [left-arrow] and [right-arrow] buttons

Press these to "copy" the current directory from one panel to the
other.


  Copy

Copy files and directories. If you copy a link to a file, the file is
copied (not the link). If you copy a link to a directory, the
directory is copied (not the link). The only time links are copied is
if they reside in a directory that is copied.

Async operation support: Only for directories.


  Copy As

Same as Copy, but this will let you choose a new name for the copy.

Async operation support: Only for directories.


  Delete

Deletes files and directories.

Async operation support: Only for directories.


  Move 

Moving files around. This function is limited by the standard mv
command in that it can usually not move directories across file
systems. (You will get an error if you try)

Async operation support: No


  Rename

Rename stuff.

Async operation support: No


  MakeDir

Create new directories. You have to enter the name of the new
directory in one of the directory entries and then press the MakeDir
button to create a new directory. When the new directory is created,
all it's parent directories are created also if they don't already
exist.

Async operation support: No


  S-Link (Soft-Link)

Works the same way as Copy, but will not actually copy stuff, only
create a soft link to pointing back to the original.

Async operation support: No


  S-LnAs (Soft-Link with rename)

Works the same way as S-Link, but will not actually copy stuff, only
create a soft link to pointing back to the original. This version lets
you rename the link before it's created.

Async operation support: No


  Chmod (Change Mode == Change permissions)

Lets you change permission flags on a file. You can set permissions,
meaning you select exactly which permissions a file should have, you
can also add or delete permissions, meaning you only add a few
permission bits or delete a few bits and leave the rest unchanged. You
can also set permissions recursively. A tip: Usually you only use the
recurse mode with the add/delete actions and not the set action. For
example if you want to add group read and write permissions to a whole
tree of files, you chould use the add action and the recurse
option. See the chmod man page for more info on Unix file permissions.

Async operation support: Yes


  View

Same as pressing the right mouse button on a file to view it with the
exception when you view multiple files: When you do this, the viewer
command will not be started once for every file you have selected, but
instead it will be passed all your selected files as argument to the
viewer, starting it only once. The first file selected will determine
what kind of viewer will be opened for ALL the files. You can't select
one text file and one image and press the view button. See the config
file on how you can set up your own bindings so for example you start
xv when you view .jpg files.

Async operation support: Always async


  Edit

Will start the editor of your choice (see configuration below) with
the argument of all your selected files.

Async operation support: Always async


  Q-Edit  (Quick-Edit, the builtin editor)

Select a few files and press Q-Edit to launch the editor. See below
for a reference on the internal text editor.

Async operation support: Always async


  Arc  (Archive)

If you select a directory, the Arc button will create an archive file
that contains the contents of the directory tree. It will use the
archiver you have configured. The archived file will be named the same
name as the directory with an extension added to it. If you press it
on a regular file, it will pack the file with the packer you have
configured. The archived or packed files will be created in the same
directory as the original sources.

Async operation support: Yes


  UnArc  (Unarchive)

If you select an archive, FileRunner will try to guess what type of
archive it is and then unarchive it into the OPPOSITE directory
panel. If you want the archive unarchived into the same directory, you
have to set the same directory in the left and right panels
first. (This may sound weird, but it is actually quite handy since you
often don't want to unarchive stuff in the same place as the archived
file resides).

Async operation support: Yes


  UnPack

If you select a packed file, FileRunner will try to guess what type of
packed file it is and unpack it in the same directory as the packed
file.

Async operation support: Yes


  Print

Select a file and press print. FileRunner will invoke the print
command you have configured.

Async operation support: Always async


  Select

This command is used to easily select, for instance, all
.h-files. First you enter a select-pattern in one of the directory
entries and then you press select. For example: Let's say your left
directory panel shows /usr/src/foobar and you want to select all
.h-files. Just edit the directory to /usr/src/foobar/*.h and press
select.


  Diff

Select two files or directories and press diff to see what the
difference is between them. You can also select files in different
panels just by clicking on one file in one panel and then selecting
another in the other panel. You can configure what diff command to
use.

Async operation support: No


3.4.1 Synchronous vs. Asynchronous Command Execution
=============================================================================

If you press the left mouse button on one of the command buttons, the
file operation is executed synchronously, i.e FileRunner will wait for
the command to finish before accepting another command to run. If you
press the right mouse button the command will be executed
asynchronously (in the background) letting FileRunner take more
commands immediately while the first one is still running in the
background. For some buttons, this is not implemented (where the
operation is very fast anyway, like doing soft links). This IS
implemented for FTP, which means you can mark 25 files and press the
right mouse button over the Copy button and have 25 parallell
transfers going to the same server simultaneously... Be careful with
this, since it will load the ftp server and net connection badly!
(Which is a naughty thing to do if you are a nice netizen :-)

The drawback with asynchronous operations is that it won't tell you if
things go wrong during a copy, etc (for some operations, though it
will print this to the standard error output for FileRunner).  It will
also increase the risk that the file panels aren't showing correct
information (you'll have to use the Update (two arrows in a circle)
button). For ftp transfers, it will usually take longer since it has
to start another ftp session for every file it copies (in parallell).


3.5 Command Line Arguments
=============================================================================

Syntax:

  fr [-iconified] [left-start-dir] [right-start-dir]

  -iconfied         Start up iconified
  left-start-dir    Start by showing this directory in the left panel.
  right-start-dir   Start by showing this directory in the right panel.


4. The Classing Engine.
=============================================================================

[Chapter deleted, obsoleted by the unpacker/viewer config parameters]



5. The Internal Text Viewer And Editor
=============================================================================

The internal text viewer pops up when you view text files and the
internal text editor is used when you press the Q-Edit button. When
you enter these programs, you just get a text view and a scrollbar. To
activate any command you press the right mouse button in the text and
use the pop-up menu. Note that this popup menu can be "torn off" by
selecting the dashed line at the top. This will make the menu stay up
after use, and is very handy if you want to press "Search Again" many
times.

The text viewer and editor are normal Tk text widgets and have the
standard text widget bindings. Some interesting bindings are:

* Position the cursor with the left mouse button.
* Double click or triple click to select a whole word or line,
  respectively. 
* Drag with mouse button 1 to make a selection of text.
* Click the middle mouse button to insert text from the selection.
* Drag the middle mouse button to scroll the text (fast panning, very cool).
* Ctrl-A and Ctrl-E moves the cursor the beginning and end of the
  line, respectively.
* Ctrl-Home and Ctrl-End moves the cursor the start and end of the
  text, respectively. 
* Copy, Cut and Paste (F16, F20 and F18 or Meta-w, Ctrl-w and Ctrl-y)
  work as they are intended (Cutting, copying or pasting the selection).
* Ctrl-k deletes a line.


Take a look at the Tk "text" manual for more info on this.

To quit the text editor and viewer you have no less than four choices: 

- The standard X11 "delete-window" command (accessed from your window
  manager, not FileRunner).
- Press the little cross at the top right of the window.
- Select the menu in the window with the right mouse button and 
  choose quit. 
- Press the Escape button in the window.

The text editor will check if it loses any characters when the file is
converted to text. If this happens, you will get a warning. You cannot
edit binary files. When reading MS-DOS text files on a Unix machine,
any CR/LF tuples will be converted into LF's, but you will get a
warning if this happens.

5.1 The Internal Text Viewer Menu
=============================================================================

  "------"

"Tear off" the menu. Try it to see what happens.

  Search...

Pops up a requester asking you to type in a string to search for in
the text.

  Search Again

Search for the same string again.

  Save As...

Lets you save the contents of the text view to a file. If you have
edited the text, the edits will be saved. (Yes, you can _edit_
in the text _viewer_ ....:-)

  Quit

Quit the viewer.


5.2 The Internal Text Editor Menu
=============================================================================

Same as the text viewer menu (above) except that it also has a command
called "Save & Quit" which will immediately save the file that is
edited and then quit. Also, the text editor has a "Save" command that
just saves the current file to disk and does nothing more.



6. Configuration
=============================================================================

The configuration is saved in a file called "config" which is located
in a sub-directory called ".fr". This directory is created in your
home directory the first time you start up. This is where all the
configuration options are stored. Some options can only be changed in
the config file but many options can also be changed in the
Configuration menu. If you change anything, the changes are saved when
you exit (unless you set the configuration option
config(save_conf_at_exit) to zero). You can also manually save the
change by doing a "Configuration->Save Configuration" in the menu.

There is also a system-wide config file that you can edit to reflect
some of the local configuration options at your site, so everyone will
not have to edit these parameters themselves. Typically you enter
stuff like the name of the ftp proxy server etc. The file should be
called "config" and put in the FileRunner distribution directory
(where all the .tcl files and the fr main script is located.) This
file does not get auto-generated. Just enter the config parameters you
want in this file, and they will override the default FileRunner
configuration (but they won't override the individual user
configuration).

When you edit the configuration with "Configuration->Edit
Configuration" and save the file, it is read back in by FileRunner to
reflect the new configuration.

When you save configuration with "Configuration->Save Configuration",
the .fr/config file is auto-generated, so don't add anything to the
configuration file you want to save...

You can re-read the configuration file any time with the
"Configuration->Reread Configuration" command. This is good if you
edit the configuration with another editor other than the default
"Configuration->Edit Configuration".

Here comes an example of a config file with some added comments. Note
that all the config options already have some documentation, so it
will be easy to edit. Not all configuration options are listed in the
example config file below, only the ones that need a more explicit
explanation than what is already in the config file. To see a complete
list of options, choose "Configuration->Save Configuration" and then
"Configuration->Edit Configuration...".

---------------- Example config file -----------------------------------

# This is the configuration file for FileRunner. It will be read
# everytime FileRunner starts up and also when you do a Save&Quit after
# editing this file. Only edit values for variables that are listed. Do
# not add or delete anything, since this file will be automatically
# re-generated when you do a Save Configuration and those changes will be
# lost.

#-----------------------------------------------------------------------
# This list is what will show up in your HotList menu. (Like "bookmarks"
# in Netscape). Feel free to edit this list.

set config(hotlist) {
    /home/harmsen
    /usr/src/linux
  }

The above hotlist is in its most simple format. If you want to have
more informative entries in the hotlist you can make aliases for the
entries like this:

set config(hotlist) {
    {{My Home}        /home/harmsen}
    {{Home of Linux}  /usr/src/linux}
  }

This will make "My Home" show up in the hotlist entry, but you will
still be going to /home/harmsen when you select it. Note the added
braces.

You can also have submenus like this:

set config(hotlist) {
    { {-Cool homes}
      {{My Home}        /home/harmsen}
      {{Home of Linux}  /usr/src/linux}
    }
    {{Linux kernels} ftp://ftp.funet.fi/pub/Linux/PEOPLE/Linus}
  }

This will make a submenu in the hotlist called "Cool homes" and under
it will be "My Home" and "Home of Linux". Note the added "-" before
"Cool Homes" (this is to identify this entry as the head of a submenu)
and the extra braces. Currently, you can only have one nesting level
here. At the end of this hotlist is an FTP-URL, they are treated as
any path in the hotlist.

Someday, I'll create a cool bookmarks-editor that can do this for
you... 

#-----------------------------------------------------------------------
# The print command you want to use to print files.

set config(cmd,print) "lpr {%s}"

If you, like me, are using the cool atp program, you can edit this to:

set config(cmd,print) "atp {%s} | lpr -Phplj5"

The | character is a normal shell-pipe symbol, so you can have those in
here too. The print command will be launched in the background.

#-----------------------------------------------------------------------
# Sets how often FileRunner checks to see if it needs to update its windows.
# Set this to 0 to disable. Value is in seconds.

set config(autoupdate) "5"

The updating is currently done by checking the modification time of
the directories that are shown in the left and right panel. This will
detect added or deleted files, but not modified files.


---------------- End of Example .fr file -------------------------------

(As mentioned above, do a Configuration->Edit Configuration to see all
parameters)

See also the FTP chapter 8.8 where the config(ftp,login) parameter is
further explained.


7. Home-made Buttons
=============================================================================

You can define your own buttons and your own commands to use with
these. These are read at startup from a file called $HOME/.fr/cmds.

These buttons now have a new interface in v2.0 compared to v1.2. Now
they get the whole list of selected files at once and they can also
get called with an empty list when there is no selection.

New for v2.4: The commands will now receive an extra argument
"mbutton" that says which mouse button was pressed.

This is an example of how it should look:

---------------- Example .fr/cmds file -------------------------------
# This is an example of user-defined commands. This file should be named
# $HOME/.fr/cmds. It will be read by FileRunner at startup.

# This list should contain all user-defined commands formatted as: { { <button-title> <procedure-name> } {..} {..} }
set config(usercommands) { 
  { MyBut MyButton }
  { FindFile FindFile }
}


# This is an example of a command button that runs the "file" command on the selected files.
# Arguments:
#   filelist - list of selected files under $srcdir, can be empty
#   srcdir   - source directory
#   destdir  - destination directory
#   mbutton  - which mouse button was pressed (Values: 1:Left 2:Right 3:Middle)
proc MyButton { filelist srcdir destdir mbutton } {
  cd $srcdir
  set l {}
  foreach f $filelist {
    set l "$l\n$f [exec file $f]"
  }
  ViewString "MyButton Output" l ""
}


# An example of using the find command in FileRunner
# Note that you need to mark something in one of the directory panels
# to set the srcdir directory, even if nothing from $filelist
# is used.
# Arguments:
#   filelist - list of selected files under $srcdir, can be empty
#   srcdir   - source directory
#   destdir  - destination directory
#   mbutton  - which mouse button was pressed (1:Left 2:Right 3:Middle)
proc FindFile { filelist srcdir destdir mbutton } { 
  set findname [EntryDialog "Find..." "Please enter substring of filename to search for" ""]
  if {$findname == ""} return
  cd $srcdir
  set out [exec find . -name "*${findname}*" -print]
  ViewString "Output" out ""
}

---------------- End of Example .fr/cmds file ---------------------------

The prototype for the command is:

proc MyButton { filelist srcdir destdir mbutton } {

   filelist - list of selected files under $srcdir, can be empty
   srcdir   - source directory
   destdir  - destination directory
   mbutton  - which mouse button was pressed (Values: 1:Left 2:Right 3:Middle)

You are welcome to use the following internal commands of FileRunner
in your own buttons:

Command       Arguments                           Comment
-------------------------------------------------------------------------
ViewText      filename
ViewString    title string-variable filename      (set filename to "")
ViewImage     filename
EditText      filename script-to-run-when-saved   (set the last arg to "")
EntryDialog   title info-text start-entry         (returns the entry-text or "" if aborted)
PopInfo       info-text
PopWarn       warn-text
PopError      error-text
Log           log-text

And all normal Tcl/Tk stuff of course.


8. FTP (File Transfer Protocol)
=============================================================================

You can also do FTP sessions with FileRunner. You can browse FTP sites
just as if they were on your local file system.

Just enter an FTP URL in the directory entry and you will be browsing
an FTP site. For example: "ftp://ftp.funet.fi/pub". You can do most of
the same things with an FTP listing as you can with a "normal"
directory, like copying, deleting, renaming and viewing stuff etc.

There are some things you cannot do on an FTP file/directory:
- You can't make soft links to an FTP file. Wouldn't be useful...
- You can't move things from or to FTP. Use copy and delete.
- For the source/directory operations (copy, move, etc) you cannot
  have FTP on both sides at the same time.
There are other things you can't do but FileRunner will tell you so if
you try, so don't be afraid of trying.

The hotlist can hold FTP sites as well as normal directories. Just do
"HotList->Add to hotlist" and then probably you want to do a
"Configuration->Save Configuration" to save it for later.

If you want to FTP to an FTP site which is not at port 21 (the normal
FTP port), you can add a port suffix to the FTP URL:
  ftp://<site>:<port>/<path>
example:
  ftp://ftp.foo.com:8080/pub/bar

8.1 Anonymous FTP
=============================================================================

Under the configuration menu, you can turn on or off anonymous FTP. If you
turn it off, you will be prompted for username and password when you
go to a new FTP site.

8.2 FTP Through Proxy
=============================================================================

You can also do FTP through an FTP proxy site. Ask your administrator
if you have an FTP proxy and what the name of it is and enter it into
the config file in the config(ftp,proxy) variable. Currently, the FTP
proxy functionality has only been tested in one of the proxy types
where you have this kind of log-on sequence:

~> ftp proxy-host
Connected to proxy-host.
220 You're now at the FTP gateway.
Name (proxy-host:username): anonymous@ftp.funet.fi
331-(----GATEWAY CONNECTED TO ftp.funet.fi----)
[more stuff]
Password: [here I enter my password which is my email address, since
           this is an anonymous connection]
230-       Finnish University and Research network FUNET
[more stuff]
ftp> 

As you can see, you enter the username and ftp site in the Name:
prompt, and then your password as normal. Is there other kinds of
proxys out there? Let me know!

8.3 Synchronous Or Asynchronous FTP Transfers
=============================================================================

When you receive files from FTP, this is normally done synchronously,
meaning FileRunner can not be used for other stuff during the
transfer. If you want to continue to use the FTP session and have a
long transfer run in the background, just use the right mouse button
over when you click the Copy button. The transfer of will then take
place in a separate window and will let you continue working. If you
forgot to do this and still want to continue browsing the FTP site,
press the clone button to fire up another copy of FileRunner to
continue browsing there.

8.4 FTP Timeout
=============================================================================

Usually, FTP connections time out after a while (900 seconds or
so). When this happens, FileRunner will give you an error message the
next time you access the FTP site. Just click OK on this popup and try
the command again, and the FTP connection will automatically be
reopened.

8.5 Closing FTP Connections
=============================================================================

You don't have to close FTP connections explicitly. They are closed
automatically when you go to another FTP site or to another Unix
directory. The FTP connection will of course not close if it is still
used in the opposite panel.

8.6 FTP Transfer Status
=============================================================================

When you receive files through FTP you get status indication in the
status line telling you how many bytes are left, how fast the transfer
currently is and estimated time of arrival (ETA). The speed
calculation and ETA calculation use speed measurements over the last
60 seconds averaged to calculate the current speed. Just using the
current speed sample (measuring the time for one 4kB block) would give
inaccurate results due to kernel buffering and various TCP tricks. At
the end of the transfer you will be told how fast the download was in
total (total number of bytes divided by the total time for the
download). Note that the ETA is showed both in relative time (MM:SS)
and absolute time (HH:MM).

8.7 Temporary Storage For FTP Files
=============================================================================

When you view stuff with the view button or right button mouse the
file is temporarily placed under ~/.fr/tmp. This directory is cleaned
up when you exit FileRunner.

8.8 Using The Rule-based Configuration For FTP Logins
=============================================================================

FileRunner contains a rule based configuration for FTP logins. For
example: you can tell it to always log in with username X and password
Y to sites matching *.Z.com etc. This is very convenient as you don't
have to toggle back and forth in the Configuration menu for the
anonymous and proxy configuration when jumping between FTP
sites. Instead you decide once and for all what information to use
when connecting to specific sites.

Let's have a look at an example of the config(ftp,login) parameter.
To change it you do a "Configuration->Edit Configuration" and edit the
config(ftp,login) parameter in the FTP section.

set config(ftp,login) {
  { *.foo.com { myusername mypassword } }
  { machine.bar.com { myotherusername XXX } proxy1.local.edu }
  { * { anonymous joe@mailbox.edu } proxy2.local.com }
}

The rule is a list of configurations. When you connect to a new site
the list is scanned from beginning to end, to see if there is a
match. If there is, the information in the list is used and the
current settings under the Configuration menu are disregarderd (the
anonymous and proxy configuration). The rules look like this:

  { ftp-site-pattern { username password } optional-proxy }

First there is a pattern that is matched to the FTP site you want to
connect to. You can use wildcards in this pattern. Next comes a list
with username and password that is to be used when connecting to the
FTP site. Last is the name of the proxy ftp site, if you need
one. Leave this empty if you don't connect through a proxy. Taking the
elements one by one from the example:

  { *.foo.com { myusername mypassword } }

This line matches all FTP sites that match the pattern *.foo.com. It
tells FileRunner to always use the username "myusername" and the
password "mypassword" when connecting to these sites. This rule does
not use a proxy.

  { machine.bar.com { myotherusername XXX } proxy1.local.edu }

This line is used for doing FTP to a single machine only;
"machine.bar.com". It says to use username "myotherusername". The
password says "XXX", which means that FileRunner should prompt for the
password when you connect to the site. This connection goes through an
FTP proxy: "proxy1.local.edu".

  { * { anonymous joe@mailbox.edu } proxy2.local.com }

This line matches all other sites and says you want to do anonymous
FTP to these sites.  As password you should insert your email address.
For these connections the example says to use the FTP proxy
"proxy2.local.com". Since these three rules will match anything (the
rules are scanned from beginning to end and the "*" will match any
site), you never have to bother with the Anonymous and Proxy
settings under the Configuration menu.

A note about security:

As you can see above, it is possible to store passwords in this
parameter but you can also insert XXX to have FileRunner prompt you
for your password when you connect to a new site. As you've probably
figured out, it is not very safe to have your passwords stored in your
config file, accessible to anyone... Well if you are running a local
machine (at home perhaps) and you deny everyone on the Internet access
to the local machine (by not starting inetd, for example), you should
be able to safely store your passwords in the config file since only
you have access to your local machine anyway (as was assumed). On the
other hand, if you are for example on a University network, you should
be aware that even if you change permission on the config file to
-rw-------, it's not really safe anyway since System Administrators
and other scruffy people can read your file anyway, either through
running as root or by using yet another Unix security bug. In general
it is a Bad Thing (tm) to store your passwords in any file in a
networked environment...  Some will do it anyway, but PLEASE at least
change the read permissions on the config file first!

This is how you do this:
> chmod go-rw ~/.fr/config

You Have Been Warned...

8.9 Batch FTP
=============================================================================

Batch FTP download is useful when you want to select a number of files
for downloading when the files are not in the same directory or even
on the same site. You can browse any FTP site, add the selected files
to the batch list, then later start the batch download and go do
something else while the files download. 

This is all done by using an FTP batch list. You can add, view and
clear the batch list (Etc menu). When the batch list holds the files
you want, select "Etc->FTP Batch Receive..." to download the files to
the current directory. See the Etc menu.

8.10 FTP Transfer Speed (dropped characters with a buffered serial port??)
=============================================================================

This chapter has nothing to do whatsoever with FileRunner, but I'd
like to share this information anyway since it has a lot to do with
FTP transfers.

I have a Sportster 28800 modem and I've never (until recently) been
able to achieve better than ca 2.2 kb/s on FTP transfers. This is on a
486/66 w 20MB RAM and a couple of IDE disks and a 165550A buffered
serial port. The problem showed itself when I ran the program
ifconfig, I always got several dropped packes which hurt performance a
lot. It turned out the problem was the high latency of the IDE disk
driver in the Linux kernel. The latency was so high the serial port
dropped characters even though it is buffered. The solution to this
was to 1: Switch to Linux kernel 2.0.22 and 2: run the hdparm v2.9
program in my rc.local file like this:

hdparm -u 1 /dev/hda

(actually my command looks like this "hdparm -q -u 1 -q -m 8 -q 
-W 1 /dev/hda", but it is the -u switch that counts here).

This let's the IDE driver be interrupted by the serial IO driver and
voila: No more dropped packets. FTP transfer went up to a steady 
3.3kb/s with peaks of 8kb/s on text files!! Not a single dropped
packet!

In the hdparm manual it says the -u switch is dangerous, but as far as
I can tell from the manpage it's not dangerous if you run kernel
2.0.22 or later. I have not had any problems with it anyway.

You can get hdparm from:

ftp://sunsite.unc.edu/pub/Linux/kernel/patches/diskdrives

It's a great program. It also lets you turn on the IDE multi-block
transfer mode (-m 8 above) and write caching (-W 1 above). Just make
sure to read the manual first...

Recent note: Some video card drivers will also generate dropped
packets. Sometimes the driver is written to ignore checking the status
of the graphics card and just continue to shuffle commands to the card
even though it is working. This will usually result in the CPU hanging
on the bus waiting for the graphics card and you will get lots of
interrupts from the serial port that the CPU will miss. Better drivers
will solve this.


9. The Internal Shell Windows
=============================================================================

FileRunner has built-in shell windows that pop up when you press the
little rectangular button to the right of the up-dir arrow button at
the top of the file list panels. These windows behave much like an
xterm window with a shell running in it, although the shell windows
cannot handle interactive programs, they only allow output from the
commands you run in them. Having a shell inside FileRunner gives you
the flexibility to run simple commands without having to switch to a
terminal window.

These windows have a text area where the output of the command is
sent. They have a scrollbar so you can see output from previous
commands. There is also a small text string at the left side that
shows the current directory for the shell, and a command entry where
you type your commands. At the right of the command entry there is an
"R". This turns red when commands execute so you know if they are
finished or not. To the right of this, there are three "size" buttons
(smaller, larger, maximum) that you can press to change the size of
the window.

There is one shell window for each of the left and right file panels,
and they always show the same current directory as their respective
file panels. If you travel around in the directory tree in the file
list panels, the shell current directory will follow, and if you
change directory in the shell, the file list panel will follow and
update itself. Since directory traversing can be done very fast within
FileRunner, this is a big time-saver (and the main reason there are
built in shell windows in FileRunner in the first place).

For the shell connected to the left file list panel, the scrollbar is
on the left side of the command output area. For the right file list
panel shell, the scrollbar is placed to the right. This is how you
tell them apart.


Running commands:

To run a command, just type the command into the text entry and press
enter. The command will be run in the background and you can
immediately run more commands if you wish. A small "R" to the right of
the command line will turn red as long as one or more commands are
executing. If multiple commands produce output at the same time they
might become intermixed.


History:

To retreive previous commands, you can press the up and down arrow
keys to flip through the history. Type the command "history" and you
will see all previously executed commands.


Filename completion:

The shell has built-in file name completion activated with the Tab
button. If you type parts of a command verb or file name, FileRunner
will search the directory and replace it with a full filename. For
example, if you have a file called foo.bar and you type "rm fo"+tab,
FileRunner will fill in "o.bar" and complete the filename. If there is
more than one file matching (for example you type x+Tab and you have
files called x1 x2 x3...), it will put in the first of these matched
files (x1 in this example). If you then press Tab again it will cycle
through all possible matches (x2, x3 etc). If you press Control-D, the
shell will show you all possible matches to the completion request.


Internal commands:

cd [dir]      - Change directory. Synchronized with the file panel.
view [file]   - Start the internal text viewer on the file specified.
history       - Show previously executed commands.


Aliases:

You can define aliases within the shell window. See the config file on
how to do this.


Tcl commands:

You can also execute Tcl commands in the internal FileRunner
context. Just prefix the command with a % and type in a normal Tcl
command. This is of limited use to others than the author...


See also the configuration file for more configuration on the shell,
like command color and shell window sizes.


10. Miscellaneous
=============================================================================

10.1 Exported Selections
=============================================================================

When you select files and directories in the file list panels and then
"paste" this selection into an xterm, for example, by clicking the
middle mouse button inside the xterm, you now get the list of files
you have selected, fully qualified with paths. This is very handy when
you are working inside FileRunner and you need to do something with a
file in an external window. Can of course also be used inside the
internal shell window.

10.2 Files Used and Created By FileRunner
=============================================================================

~/.fr               Configuration directory
~/.fr/config        Config file
~/.fr/cmds          Your own button commands
~/.fr/ver           Latest version of FileRunner run.
~/.fr/history       Directory history saved to disk
~/.fr/tmp/*         Temporary files (created when viewing FTP files)


10.3 Choosing cursor color
=============================================================================

You can actually change the shape and colors of the cursor if you for
example choose a dark background with bright text and you have a hard
time seeing the cursor. Put the following command in the
~/fr/cmds-file:

. config -cursor {left_ptr Blue Red}

This will give you a small blue and red arrow. You can see what other
cursors are available from looking at the
/usr/X11/include/X11/cursorfont.h file. Just strip the XC_ prefix and
use one of the cursors defined. The colors defined are standard
X11-colors.

10.4 HTTP Download
=============================================================================

You can also use FileRunner to download HTTP files (HTML, binaries,
whatever). The reason I've added this is that the download function in
Netscape is so incredibly crappy: Nine times out of ten, it will stop
downloading somewhere near the end of the file and not say a peep
about the fact that the file you got was truncated and utterly
useless... Anyway, this one works lots better of course :-) It warns
you (if it can) if the file received was too short and it also uses a
longer timeout than Netscape so you will (hopefully) get fewer aborted
downloads.

Use: Just choose "Etc->HTTP Download" and enter an URL to
download. You don't have to bother with adding "http://" if you don't
want to. Then choose a filename to save the download to.

11. Copying/Copyrights/Legal Stuff
=============================================================================

The program and all associated files are Copyright (C) 1996-1999 by
Henrik Harmsen.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
USA

12. Bug Reports/Questions
=============================================================================

Before sending me bug reports or questions, please have a look at the
FAQ file and the README file to see if your problem is already
answered there.

Sometimes FileRunner will pop up a window saying you've found a
bug. That means something really serious just happened and FileRunner
will not continue executing. You then have the option of preparing a
bug report you can send to me. Please do. But please check the FAQ to
see if this bug is described there already (it'll save both you and me
time).


13. Contacting The Author / The Announcement Mailing List
=============================================================================

You are very welcome to mail me suggestions for improvement or bug
reports or questions or whatever. I might not have time to answer them
all, though.

Email:      hch@cd.chalmers.se (preferred)
        or  Henrik.Harmsen@erv.ericsson.se

If you have trouble contacting me, try search the web for "FiLeRuNnEr"
(this exact string) and you should be able to find my new address.
Currently you will find the webpage at 
http://www.cd.chalmers.se/~hch/filerunner.html

There is a mailing list with announcements for FileRunner. Mail me and
tell me if you're interested to be on it.