
FileRunner
----------

(C) 1996, 1997 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 Menu
3.3.2   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
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     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
11.     Copying/Copyrights/Legal Stuff
12.     Registration Fees
13.     Bug Reports/Questions
14.     Contacting The Author / The Announcement Mailing List



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

Starting: Just type "fr" followed with two optional arguments for the
starting directories for the left and right panels.

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 the left or right 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 diectories 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 pressing the Ctrl-button and use the 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, Settings, 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 tne middle are the command buttons.

The directory panels contain, at the top, a status line that tells you
the number of selected files out of total number of files, number of
bytes in selected files and also how much free space there is left on
the disk. Below this comes a toolbar, of sorts. From left to right on
this: The "back" (left arrow) button, the "Dir", "Hotlist", "History"
menus that will help you travel quickly between directories, the
"update" (two arrows in a circle) button, the "parent dir" (up arrow)
button, the built-in shell button (square with text in it, divided)
and the terminal button (square with text in it). More on these
later. Below this is the directory entry. It always shows what
directory the list is showing. Below this comes the actual file list
showing the contents of the directory.

At the very top of the middle row of buttons there are two buttons
with an up and a down arrow. These are used when all the command
buttons can't be showed at once to scroll the command buttons up and
down. Below these buttons are the command buttons that will be used to
do the actual work.



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

Here is the full reference to all commands and buttons and tricks you
can do in FileRunner. Sometimes there is no explanation for things,
they are supposed to be obvious... :-)

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

  File->About

  File->View Log    

View the log that FileRunner keeps of evertyhing 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

  Settings->Save Settings

Your settings and preferences are saved in your home directory in a
file called ".fr". This file is read every time FileRunner starts
up. The .fr file is auto-generated when saved like this, so this
operation will erase any edits you have done to the .fr file other
than normal changes to settings. 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 (very few) cases when changes in the
FileRunner menus affect the settings file. Warning: If you have more
than one FileRunner running and use both to save settings they will
overwrite each others settings. Another good time to save your
settings like this is when you get a new version of FileRunner, so the
.fr file will show the correct setting variables available for that
version.

  Settings->Edit Settings

This will launch the internal editor and start editing the .fr
settings file. I could have made a fancy preferences panel with a
gazillion check buttons and entries instead of a plain text file, but
this way FileRunner is kept smaller and simpler. Also, with the text
file you get the documentation for every setting in-line in the
file. When you are done editing, press the right mouse button in the
file and choose "Save&Quit". When the settings are saved, they are
reread from the file to reconfigure FileRunner. This works for most
settings, but not the ones that determine fonts and colors, you have
to restart FileRunner to activate those. If you do not have a .fr file
before you issue this command, the "Settings->Save Settings" command
is run before, so you have something to edit.

  Settings->Reread Settings

The .fr file is re-read to get settings from this file. This can be
used if you edit the .fr file some other way than choosing "Settings->
Edit Settings" and you want the settings to be read back into
FileRunner.

  Settings->Show All Files

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

  Settings->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.

  Settings->Use FTP Proxy

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

  Settings->Sort *****

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

  Settings->Edit xxx color

Change various GUI colors on the fly. You have to save your settings
to store it to the .fr file. These settings (with their documentation)
are in the settings file also.

  Settings->Edit xxx font

Change various GUI fonts on the fly. You have to save your settings to
store it to the .fr file. These settings (with their documentation)
are in the settings file also.

  Settings->Set Left Start Dir
  Settings->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 settings to store it
to the .fr file.

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

  Settings->Set Window Pos/Size

When you issue this commands for, 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 settings to store it to the
.fr file.

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

  Utilities->Swap Windows

Exchanges 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 -s 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
Settings->Edit Settings 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 settings file
for config(dateformat).

  Help->****



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 Menu
=============================================================================

  Directory->*****

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. Make sure to do a
"Settings->Save Settings" afterwards to save the new hotlist.

  Hotlist->[directories]

Choose a directory to go there. See more about this in the
configuration chapter below.

  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...


3.3.2 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 enter a directory that doesn't exist a requester pops up to ask
you to enter a new directory. 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 "Settings->Edit Settings" 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 an
alphanumeric 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. 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. Directory copying is done by using tar, so
it will preserve soft-links. Copying directories is not implemented
for FTP browsing. When copying FTP files you will get a progress meter
in the status line that tells you how much is left of the file to get
and how much time is estimated before its arrival (the ETA
timer). There is also a measurement of how fast the download currently
is, in kilobytes per second. This measurement is the average speed of
the 12 last samples.

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.

See also the explanation for Utilities->FTP Copy With Resume.

Async operation support: Yes


  Copy As

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

Async operation support: Yes


  Delete

Deletes files and directories.

Async operation support: Only for deleting 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: Yes


  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 (see
3.3.4.1 above) with the exception in the case of when you view
multiple images. When you do this, the image viewer 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. When you view text files, the internal text viewer will be
started. See below for a reference on the internal text viewer. 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.


  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.


  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 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 on one of the command buttons 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).



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 or do a
"Settings->Save Settings". 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.

Note that if you are editing config settings you must NOT do this: (if
you want to save the config) choose Save and then Quit in the
menu. You must choose Save&Quit in the menu instead.

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
=============================================================================

  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


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. Don't use
"save", then "quit" when editing config settings, use "save&quit"
instead... (Or the config won't be read back in)




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

The configuration settings are saved in your home directory in a file
called ".fr". This is where all the configuration options are
stored. All configuration options affect the behaviour of FileRunner
and a some settings in FileRunner affect the config file (like color
settings and fonts etc.). If you change these, you need to do a
"Settings->Save Settings" for them to have effect next time you start
up.

There is a system wide .fr file that you (when you install the
package) 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 can here enter stuff like the name of the
ftp proxy server etc.  This .fr file should be put in the installation
directory where the rest of the FileRunner stuff resides. It does not
get auto-genereated. Just enter the config parameters you want to
override the default FileRunner settings in the system-wide .fr file.

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

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

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

Here comes an example of a .fr 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 .fr file below, only the ones that need a more explicit
explanation than what is already in the .fr file. To see a complete
list of options, choose "Settings->Save Settings" and then
"Settings->Edit Settings...".

---------------- Example .fr 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 Settings 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 -Phplj_post"

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


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 that should be called
.fr_cmds and be placed in you home directory. 

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.

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
# .fr_cmds and placed in your home directory. It will then 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
proc MyButton { filelist srcdir destdir } {
  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
proc FindFile { filelist srcdir destdir } { 
  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 ---------------------------

When you select files/directories and press one of your home-made
buttons, your command will run once for every selected file.

The prototype for the command is:
proc MyButton { entry srcdir destdir type } {

filelist  : list of selected files under $srcdir, can be empty
srcdir    : The directory where the $entry file/directory is located (selected)
destdir   : The directory shown in the opposite directory panel.

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
"Settings->Save Settings" 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 settings 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 the 12 last speed samples 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).

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 /tmp/<username>_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 Settings menu for the anonymous
and proxy settings 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 "Settings->Edit Settings" 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 Settings menu are disregarderd (the
anonymous and proxy settings). 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 Settings 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
.fr 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 .fr 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 .fr 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 .fr file first!

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

You Have Been Warned...

8.9 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...

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 settings 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               Settings file
~/.fr_cmds          Your own button commands
~/.fr_ver           Latest version of FileRunner run.
~/.fr_history       Directory history saved to disk
/tmp/$USER_fr_tmp/* Temporary files (created when viewing FTP files)

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

The program and all associated files are Copyright (C) 1996, 1997
Henrik Harmsen.

Definitions:

"Personal use"   - Using the program for non-profit use.
"Commercial use" - Using the program to make/save money/time 
                   in businesses/institutions/corporations.

The following terms apply to all files associated with the software
unless explicitly disclaimed in individual files.


Personal use:

Permission to use, copy and distribute this program and its
documentation is hereby granted without fee, provided that this
copyright notice appear verbatim in all copies. You are also free to
modify this program, but not re-distribute modified programs without
the permission of the author.

Commercial use:

Permission to copy and distribute this program and its documentation
is hereby granted without fee, provided that this copyright notice
appear verbatim in all copies. You are also free to modify this
program, but not re-distribute modified programs without the
permission of the author. Commercial users are expected to pay a small
registration fee for every user (of the program) after an evaluation
period of no more than 30 days (see next chapter). Note that
"commercial use", as already stated above, means using the program in
regular business work as a means of making/saving money/time. Anything
else falls under the category of personal use, even it the program is
used at the workplace (while not doing business-related work).


The following holds for both personal and commercial use:

If you re-distribute or copy this program, the copyright notice and
all legal terms as stated in this chapter must be included verbatim in
all copies.


IN NO EVENT SHALL THE AUTHOR OR DISTRIBUTORS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
DERIVATIVES THEREOF, EVEN IF THE AUTHOR HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

THE AUTHOR AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-
INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE
AUTHOR AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE,
SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

----------- Legal mode off -----------


Clarifications:

Here comes a few notes on things I want to make clear with the
copyright above:

1. It is OK to sell the media for this program (the archive containing
FileRunner), and/or include it in distributions of one kind or
another, provided you include the copyright notice and all legal terms
verbatim in all copies (as stated above). You must also make sure the
buyer of the media does not get the impression he is paying
registration fees when he is buying the media. If you do want to
include it in distributions and/or sell it, please leave me a note,
just so I know what's happening.

2. The registration for commercial users is tied to how many users
there are. If one user uses FileRunner on 10 different machines, it is
still only one fee of US$20.

If anything else is unclear, just get in contact with me, the author.


12. Registration Fees
=============================================================================

Registration is required for commercial use of FileRunner. The
registration fee is US$20 per user of FileRunner. 

Registration is welcome, but not required, for personal use. The
registration fee is US$20. If you don't register for personal use,
please send me a cool postcard from the area where you live! 
(Email doesn't count :-).

Updates are free if not stated otherwise in later releases. Beta
versions of FileRunner (indicated by the version number having a "b"
in it e.g 1.0b5) should not be registered, please wait for a non-beta
version and register that instead.

The registration fee should be sent to the author by check or cash
(preferrably bank-notes). See address below. Make sure you include (at
least) your email address in the registration so I can get in contact
with you.


13. 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).


14. 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 
        or  Henrik.Harmsen@erv.ericsson.se

Snail-mail: Henrik Harmsen
            Kunglvsgatan 5A
            S-416 69 Gteborg
            SWEDEN

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.



