
FileRunner
----------
(C) 2010-2020 Tom Turkey
(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 Directory list header
3.3.5   The File List
3.3.5.1 Mouse Buttons In The File List
3.3.5.2 Keyboard Support In The File List
3.3.5.3 Keys in the File List without Keyboard Support
3.4     The Command Button List
3.4.1   Synchronous vs. Asynchronous Command Execution
3.5     Command Line Arguments

4       MSW and WSL and such.

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

6       Configuration
6.1     Enviroment variables
6.2     The Configuration button

7       Home-made Buttons & User configuration file
7.1     Spelling filters, supplied and home-made.

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??)
8.11    Other FTP modes (sftp and aftp)

9       The Internal Shell Windows
9.1     Running commands
9.2     History
9.3     Filename completion
9.4     Internal commands
9.5     Aliases
9.6     Tcl commands

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 the "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 draging 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.  Also Shift + left mouse will select all files beteen the current position and the last selected.

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 send the file to the editor (same as the edit button).

* Mouse buttons are configurable.  The above "view" actions is the result of binding the function "ViewOne" to the given mouse button (right).  The "Double-clicking the left mouse-button" is the result of binding "Edit" to that button.

You can also select using a pattern, try the "select" 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

The configure file is locate in one of two places:

$HOME/.fr/         for older systems and their decendants
$HOME/.config/.fr  for new systems

(This is different for MS windows systems i.e.:
 %APPDATA%
 %LOCALAPPDATA%
 %USERPROFILE% )


Within this directory the configure file is named "config-date" where "date" is the release date of fr (format yymmdd). When you update filerunner a new config file will be automatically created from the prior one and given a new name. The old file remains.  If you have two filerunners of differing revision on your system they will use the config file that matches their revision (this makes it easy to work on
filerunner without destroying the configuration of the more reliable older version).

Your configuration and preferences are saved in the config-xxxxx file. This file is read every time FileRunner starts up. The config file is auto-generated when saved  so the save (stopping of filerunner) will erase any edits you have done to the file. You will want to save the configuration 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) false (zero).

  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 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.  You can also use this to reset the directory list window configuration (width of subpannels and order) if you change them.

  Configuration->Expand Error Messages

If this is set, error messages will be expanded to include tcl/tk error information from the tcl variable "errorInfo".  It also turns on a LOT of internal messages that, mostly, help me figure out how to fix problems I have inserted to test my debugging skills.

  Configuration->Balloon Help

Determines if "Balloon Help" (or "Tips" if you prefer) is on or not. The things covered by Balloon Help is expanding...

  Configuration->Position to directories

If set, selecting any file in a directory list pannel and typing an alphanumeric character will scroll the window to center directories that start with that character in the pannel.  If not set, positioning is done for files (not directories). This may also be done by holding the Control key dowm while typing an alphanumeric character.

  Configuration->Show All Files

Determines whether files beginning with a dot (.) (or hidden in Windows) 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 VFS listings. Setting this to off will also yield slightly faster directory traversing in VFS.

  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->Color Edit menu

Brings up a submenu to enter the various color edit options.  This is a tearoff menu so by clicking on the dashed line at the top the menu will appear in its own window.

Change various GUI colors. You have to save your configuration if you want them to survive to the next time you run FileRunner. These configurations (with their documentation) are in the configuration file also.  Each of these pops up a window that configures the given color.  Any number of the colors may be configured at the same time, and it is all live. To help keep track of elevated MSW running or of a root fr, a second set of colors is available for elevated or root. Just change the colors while elevated or running as root and they will be recalled when ever fr is run in elevated mode or as root. You can also use different colors for a fr that you run with a remote login, so you can give a unique color to fr running in several environments.

  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.  These options all pop up the same font selection window which has options to select and change any of the configurable fonts.  When ready, you can make the selection live and then, if you don't like it, back it out. As with colors, there is a second set of fonts used when fr is run in elevated or root mode.

  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.  This setting can be overridden by starting fr with parameters.

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

  
  Configuration->Set Column Scroll **

Each directory panel has several columns that may not be wide enough to see all at once.  Here you can change the position of the scroll bars used for each column, or turn it off completly.  You can also scroll the columns by draging an entry with the mouse.
 
  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. For MSW fr uses a Tcl routine to do this.

  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 (one or more), choose this command and you will get a popup asking you to select a program to run or "Enter a program name".  If you choose to "Enter a program name" a dialog window will appear that will allow you to enter details on what program to run and exactly what the runs string should look like.  You will also have the option of saveing this information in the "runlist" so the next time you use this command you can just click on the "nice" name you give the program and its detailed instructions at this time.  If you "Edit the configuration" you will find an example of how to setup a run of the "thunderbird" mailer to pop up a compose window with the selected files as attachments, all with the display name of "mail-to". This command is also a possible middle button.

  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.

  Utilities->Show Console

This command is mostly for debugging. It pops up a console that has direct contact with the underlying 'wish' program that is running fr.  When poped up it also redirects stdout to itself.  This is useful for me (the author) as a lot of error messages go to stdout, especially if Configuration->Expand Error Messages is true. This command requires the tcl/tk package 'tkcon' be available so filerunner is shipped with this package. 

  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 "Utilities->FTP Copy With Resume".

  Utilities->Clone

Start another instance of FileRunner at the same directory positions as the current one. In addition to the Stop button above, this command can used 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". This window is also used as a progress bar for some functions (finding remote shares on MSW, for example).

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).  The Windows version of tcl/tk does not support the tk scripts required to do this so this will not work on Windows systems (and the button to do it is not displayed).

  Hotlist->Add to hotlist

Adds the currently shown directory to the hotlist.  Check out the configuration editer (Configure->Edit Configuration) entry on the Hotlist to see how to make cascading entries.

  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 and below. 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 menu 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. An attempt is made to position the pannel in the same place it was when you left it.

  [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.  Again, an attempt is made to position the list to the same location as when left. Note that this is not always the same as the history button (<-) as it works by doing "cd .." which will differ if you got here via a link.

  [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 move to the '<volume>' panel. If you try the 'Up-Arrow" here fr will pop up a requester where you can select new path.  This is the best way to move to a remote directory in the MS Windows system.

If you type in a directory that doesn't exist a requester pops up to ask you to correct your input. Here if you press OK or Return filerunner will attempt to create the new directory and change 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.

A right mouse while holding down an ALT key (this is configurable) will pop-up a window with the full directory name with any 'display names' resolved.

A 'Double' left-mouse on any directory in this window will change the pane to that window, for example if the window contains "/home/tom/.config/.fr/tmp" a double left click on '.config' will change the panel to display the contents of "/home/tom/.config".

A summery:
<1>         puts insert cursor on the character just before the mouse. 
            Clears selection and brings window into focus.            
<Control-1> puts insert cursor on the character just before the mouse. 
            Does not clear the selection and brings window into focus.
<Double-1>  changes the displayed directory to the directory under the mouse.
<Key-char>  with focus, insets the character at the insert cursor. Ignored without focus.
<2>         current selection replaces contents and an attempt is made to display that directory.
            If the new entry ends in a file name, that files directory  is displayed and the
            file is selected.
<Key-Left>  with focus, moves insert cursor to the left.
<Key-Right> with focus, moves insert cursor to the right.
<Key-Home>  with focus, moves insert cursor to the beginning of the entry.
<Key-End>   with focus, moves insert cursor to the end of the entry.


3.3.4 The Directory list header
=============================================================================

Each directory column has a heading in a window with a 'handle' at the end. (The handle is in a different color which may be configured by the color editor.)  You may change the size of a column by using your mouse to move this 'handle' from left to right.  There is a mininum width of 2 characters or more depending on the width needed for the column scroll bar.

You may also rearrange the columns by clicking on the column heading (where the text is) and moving the mouse left or right.  You must release the mouse on a loction beyond the adjacent column to make this happen.  The mouse release need not be in the window itself.

Just below the left and right block arrows in the column between the directory panels is a short entry with line arrows and an a lock image between them.  If "locked" any change you make on one panel causes the other panel to be so changed.  If you click on the lock image it will change (lock to unlock) which allows you to change one panel with out the other changing.  If the panels are not the same (column order and width wise) the image will be colored (red as shipped_) and disabled (i.e. it will do nothing).  When the columns are not the same, the line arrows may be used to copy the configuration from one panel to the other.  Once the panels are the same, the lock image will be normal, allowing you to push it bring back the "locked" image  and locking the panel configurations.  

You must save the configuration to keep this configuration for the next run of filerunner.  The columns are also configurable by editing the configuration file where you can also add or delete columns.  See the instructions there on how to do this.

3.3.5 The File List
=============================================================================

This description depends on a particular order of the columns, which as indicated above, is not fixed.

This panel shows the contents of the directory. You can scroll around using the scrollbars, or the left 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. Files with ?? appended are files that exist but for which no information is available. For these files the reason no information is available is in the "link to" field. (At this time I am only aware that this happens with VFSadb where the adb log in is not as super user.) 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 put the mouse pointer in a panel 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. If you hold down the control key and press a key the file list will adjust to show directories starting with that character. If the "Position to directories" option (see the Configuration menu) is selected these options are reversed, i.e. simple characters position to directroies and control key characters position to files. In both cases the positioning is case sensitive unless the sort option "Ignore case on sort" is selected.

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-inversion button.  If no files are selected it will select all files.  If any files are selected it will deselect those and select all the others.

"Selected files are exported with full path names to the clip board.

3.3.5.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.  Most of these buttons are configurable.  First I will list the fixed ones and then (most of) the configurable ones.  I will use the notation for the button that you should use in the "bind" configuration.  See below for an example.  You will find the "bind" configure stuff in the "Edit configuration" window near the top and labeled "bind".

<1> or <Button-1> usually left mouse button
<2> or <Button-2> usually middle mouse button
<3> or <Button-3> usually right mouse button

<1>         - select/unselect (clears selection first)
<TAB>       - (a key) moves the focus to the next window (not very useful)
<4> & <5>   - these control the mouse wheel, you, likely, will not want to mess with them

Most useful for binding:

<Control-1>
<Double-1>
<Button-2>
<Button-3>
<Control-3>

To use one of these in a bind configuration you might enter:

  set config(bind,Control-3) ViewDirOpposite

Here we have set up Control-3 (usually the right button) to execute the command "ViewDirOpposite" which, if the mouse is over a directory will open that directory in the opposite pannel.

It is also possible to bind mouse buttons to menus which you create.  See the "Edit Configuration" under "menu" (which follows "bind").

A menu configure line looks like this:

  set config(bind,Button-3) {DoMenu,sample}

where sample is the name of a menu which might look like:

  set config(menu,sample) {
	{{View this} {ViewOne}}
        {Edit}
	{}
	{ViewDirOpposite}
   }

In this menu, the first entry has a "nice" label of "View this" and if pressed, calls "ViewOne".  The second entry uses the simple name "Edit" and calls the "Edit" command (same as the "Edit" button).  The "{}" entry will put a seperator in the menu.

The configure file has a list of available commands that can be put in menus or directly bound to a mouse button.  A more expanded list of bind options can be found in the "tk bind" man page which is best found and viewed via google (the man page formatting is a bit rough in the local man page).


3.3.5.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 key positoning described in section 3.3.5 is disabled, however the Alt-key still works in this mode.

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

FileRunner could have better keyboard support, but it really was designed as a mouse-operated application from the ground up.


3.3.5.3 Keys in the File List without Keyboard Support
============================================================================

If you did not set the config variable config(keyb_support) to 1, a key press in a file list pane will position the file list to center on the range of enties that start with that character. This depends on the sort order and you will be asked to fix it if it is wrong (not by name only).  If you use control with the key or if Configuration->Position to directories is set the file list will position to directories that start with the given character (with control this will be lower case). See 3.5 above for the full details.

3.3.5.3 Key board command dispatch.
=============================================================================

Alt-Key in either directory pane will dispatch the center button command with 'Key' underlined. If 'Keyboard Support' is on this also works with just 'Key'.

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). You can also scroll through the button list using the mouse wheel. Just put the mouse on the button list and turn the wheel.

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.

  [left-arrow] <padlock> [right-arrow] buttons  covered in section 3.3.4

The order of the buttons is configureable.  This may not be the order you see.

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


  Move 

Moving files around. This function is NOT limited by the standard mv command in that it can move directories across file systems. Move and MoveAs can move from/to local as well as from/to VFS mounted files, including moving from one VFS to another.

Async operation support: Yes.


  Rename

Rename stuff. Rename is really the same as MoveAs and will rename a file from one system to another, the same as MoveAs.

Async operation support: Yes.


  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. Soft-Links must refer to files on the same system. MSW supports S-link and S-lnAs only for directories. For files try 'Short Cut' and 'Short CutAS'.

Async operation support: No


  S-LnAs (Soft-Link with rename)

Works the same way as S-Link, 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. For MSW see the 'Properties' button.

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 (using the config file (see Edit Configuration)) 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  (using the config file (see Edit Configuration)) 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. Diff always uses the last two selections regardless of which panel or even if the same panel.  The last selection is highlighted so you know which it is.

Async operation support: No

  Open

This is very much like the 'View' command.  It has its own 'completion list'.  It also calls a system program if the 'completion list' search fails.  The intent is that the program called will run the 'correct' thing to 'open' the passed file(s).  In windows this is done by 'cmd -c'.  In linux there are a number of possible choices.  See the configuration file 'Cmd Open'. for details.

Async always

  Run

This is just another way to access the Utilities menu Run command.


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

There are two ways of doing asynchronous operations. One way is to launch an action program in the background. This, e.g., is what is done if you attempt an asynchronous copy and "cmd cp" is set to an external program such as cp.  The other way is for filerunner to launch an asynchronous command (in tcl this is done by using the tcl "after" command (i.e. "after 0 script"). This may not work as well as one would like due to the commands blocking in such a way that all of filerunner is blocked. The "Find file" and "Rsync copy" commands work this way with rather good results as do most "ftp" transfers.

For internal async commands there is an 'Async 0' on the menu bar that turns red when an async command is executing. The '0' also changes to indicate the number of async commands currently executing. These commands will also produce error messages if they fail in some way.

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

Syntax:

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

  -iconfied         Start up iconified
  -db               Run in debug mode, LOTS of messages
  tkcon             Start tkcon
  early             This causes fr to look at and set up the tkcon and
                    db options early in the load process.
  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. MSW and WSL and such.
=============================================================================

Filerunner was originally written for *nix (linux, unix) systems. On the other hand Tcl/Tk runs on MSW as well. For some time I have been adding code to make fr work as well on MSW as it does on *nix.  Here is an update on where I think I am with this, whats good, ok and bad.

Whats good.

We have good directory listings, and are getting a lot better with some of the support programs. With this release, for example, we have eliminated the need for the *nix 'file' program. Over time we have enhanced the command handeling code to call MSW programs AND *nix programs that have been recompiled to run on MSW systems. If you want/need something closer to *nix look into downloading the GNU core binaries for MSW. Or, if you are and "emacs" fan (as I am) the emacs download for MSW (with support files) contains a large selection of converted *nix files. We have made it easy to use these and treat references to scripts in a way that eliminates the need for the script handling code to be located in any particular directory. All that is required is that the 'PATH' environment variable point at them. I recommend 'Rapid Environment Editor' to set these up for you. Internally fr reorganizes the 'PATH' to put the user entries first. The Tcl 'auto_execok' routine has been rewritten for MSW to find the scripts and the programs that run them and give them full path names. When we first tried to work with MSW we ran into something of a nightmare trying to put 'exec' calls together. To add to the problem MSW uses (and somtimes requires) native file names (i.e. with backslashes) and of course the spaces in file names. We have two routines to deal with the problems these present, the fr Exec Call Function (frECF) and the 'fixMSWcommand' functions.

In addition we have tried to come up with more reasonable handling of 'cifs' shares. These are the connections that allow interconnectivty with other systems (MSW and *nix).

WSL

Windows Subsystem Linux (WSL) is relatively new. It allows you to set up a linux area on the hard drive  which will contain a relatively complete linux system. Actually you can set up several such areas, one for each flavor of linux you would like. 

Installing a WSL distro is relatively easy. The MSW store has several distros available for free and while they charge for the Fedora distro, it is available for free from the git hub.

To run fr in one of these areas you need to:

1.) Down load and install a X server in the MSW side of the house. I am using Xming, but there are others.
2.} Start the X server and then WSL.
3.) At this point you will be in 'bash'. Modify (if needed) .bashrc to export DISPLAY=:0
4.) Download one of the 3 fr install scripts (*.rpm, *.deb or *.tar.gz)
5.) If the linux distro supports 'rpm's:
    sudo dnf install /mnt/c/Users/<your home>/Downloads/filerunner*.rpm

dnf will download and install the tcl support code and install the filerunner code. When done you should be able to type 'fr &' and it will come up.  If you get an error message about the DISPLAY you haven't exported it yet. The easy fix is to exit and restart the WSL (you don't need to restart MSW at this point, just the WSL) and then start fr.

If your chosen linux distro supports *.deb files you should be able to do the install much as above, however, the DEB distro management system seems not to support loading of the dependencies fr needs. These are: tcl, tcllib, tk and tklib. 
If you are installing from the *.tar.gz file you need to make sure that you also have the tcl dependencies installed (these are: tcl, tcllib, tk and tklib).

Interoperability

This is the neat stuff. From the linux side of the house you can see and modify all or the local MSW system files. Files on C:/ on the windows side are at /mnt/c/ on the linux side (this can be changed to mount the MSW volumes at other points in the linux file system (see /etc/wsl.conf and search for more info on it). From the windows side, files at /<any path> are available at //wsl$/<distro>/<any path>. For your reading enjoyment the windows version of filerunner looks up the WSL distros on your system and puts the result in the <volume> directory.
On the other side, if the linux side tries to execute a MSW binary who's name ends in .exe, it works. It will see files with MSW side paths.  So fr allows this and converts file path names from /mnt/?/.. to ?:/... MSW, for its part, if the file is not in one of the /mnt/ dirs, converts its name to //wsl$/<distro>/. (As mention above, the mount point can be changed. Fr follows this change and adapts to it so that, e.g. in the above calls will work.)

For example, I have 'emacs' (MSW version) running on the windows side. Using fr I can edit files from either side just by selecting and pushing the edit button.

Remote shares

Remote shares are not auto mounted as the local files are, unless you put the mount instructions in the /etc/fstab file AND put the correction notation of this in the /etc/wsl.conf file.  Each line of /etc/fstab will look like:

<letter>: /mnt/<letter> drvfs defaults 0 0
or e.g.
z: /mnt/z drvfs defaults 0 0

To complete this on the linux side, it would be nice if 'auto_execok' would return windows side files.  Working on this, however, I have not found it easy (or even possible?) to run wsl linux programs or scripts from the windows side.

It is possible, and the wsl install script will set up linux soft-links to files located in either area (MSW or linux). For example, I created a directory '.config' on the MSW side and soft-link to it from my 'HOME' directory in the linux system. If you do this before you run fr in the linux wsl, it will put the '.fr' configuration files there. If you want to do it after running fr on the linux side, using the linux side fr to rename the local .config (to get it out of the way) then create and soft-link to your MSW version of .config. You can then copy the stuff in the renamed .config to the new .config.

Challenges we faced and possibly overcome...

The wsl system does a good job (for the most part) of replicating the linux file system, however, if looking at it from the MSW side soft-links are not readable using the tcl file system interface. This was solved.

The links also needed special interpretation if they pointed to MSW files. This is done automatically.

If you want to automatically call MSW '.exe' routines from linux, it helps to be able to find them using the PATH. The default /etc/wsl.conf set up adds the MSW path elements to the wsl linux PATH. Fr's auto_execok first searches the linux side for the program and then searches for the same program with '.exe' appended to it on the MSW side.



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.
* Ctrl-z undoes the last edit (Also an option in the popup window)
* Ctrl-Z redoes the last undo (Also an option in the popup window)

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 five 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. 
- Select the menu in the window with the right mouse button and 
  choose Save&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...

Inserts a sub window at the top asking you to type in a string to search for in the text.  You will also find check boxes to select where to start the search from, which direction to search, whether to case fold  and if the search is to use regular expression searching.  Search will stop at the end of the text with a pop up message.  You can either click this message to dismiss it or just redo the search in some way. The "<" and ">" buttons here search backward and search forward. The string entry window has a drop down which allows you to choose previous searches.

  Search Again Forward
  Search Again Backward

Search for the same string again.

  Undo
  Redo

In case you are editing and need to Undo (or Redo) an edit.	

  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_ ....:-)

  Save&Quit

Saves the file in the orgional location and quits.

  Quit

Quit the viewer.


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

Same as the text viewer menu (above) except that it does not have the follow entry.

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

The configuration is saved in a file called "config-<rev>" which is located in a sub-directory called ".fr". This directory is created in your home directory the first time you start up. (Its exact location may very and differs on MSW and *nix systems. See section 3.1 above for more on this.) 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 changes 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).

6.1 Environment variables
=============================================================================

Environment variables can be set in the 'config' file with the following sequence:

global env
set env(ENVIRONMENTVAR) value
for example to set the manpage width enviroment variable to 80:
set env(MANWIDTH) 80

6.2 The Configuration button
=============================================================================

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

# Generated by FileRunner <20220314.1259.18> on Tue Aug 03 10:36:53 MDT 2010

# This is the configuration file for FileRunner. It is read every time
# FileRunner starts up. It is saved in your home directory as
# "~/.fr/config" (~ is short for the path to your home directory). Make
# sure to only edit values for variables that are listed. Do not add or
# delete anything, since this file will be automatically regenerated
# when you do a "Edit Configuration->Save Configuration" in the menu and those
# changes will be lost.
#
# This config file is saved to disk and reread into FileRunner when you
# press the OK button in the config browser. You can also edit this file
# with a regular text editor and re-read it into FileRunner with
# "Configuration->Reread Configuration"

#-----------------------------------------------------------------------
# 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 & User configuration file
=============================================================================

You can define your own buttons and your own commands to use with these. These are read at startup from the "cmds" file in the .fr directory.  You can also include user only arbitrary configure options commands here.

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 a set of user configure options.  Most any tcl can go here. As an example
# we will set the env variable to set the man page with:

global env
set env(MANWIDTH) 80


# 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
# "balloon text"  is optional (see example bellow):
# { { <button-title> <procedure-name> {"balloon text" } } {..} {..} }
# Note, the space after " is required.

set config(usercommands) { 
  { MyBut MyButton "My Button balloon\nmessage" }
  { 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: 
#              0:menu 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 } { 
  global glob
  global FindFileHint
  # Handeling the "hint" this way keeps it around for next time	
  if {![info exists FindFileHint]} {
    set FindFileHint {}
  }
  set  FindFileHint [simple_smart_dialog .  "Find..." "Please enter substring of filename to search for" $FindFileHint ]
  if {$FindFileHint == ""} return
  cd $srcdir
  set out [exec find . -name "*${FindFileHint}*" -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 "")
EditText            filename script-to-run-when-saved   (set the last arg to "")
EntryDialog *obsolete* master title info-text start-entry  
                    (returns the entry-text or "" if aborted)
                    EntryDialog has been replaced by:
simple_smart_dialog master title info-text/question start-entry
		    (returns the entry-text or "" if aborted)
                    master is a window name, may be "."  
PopInfo             info-text              
PopWarn             warn-text
PopError            error-text
Log                 log-text

And all normal Tcl/Tk stuff of course.

7.1 The spell check filter
=============================================================================

The spell check filters preselect parts of a line to spell check.  This is what you need if you want to spell check source code.  Usually you are only interested is checking the comments and the quoted strings of such files.  You can write your own filter(s) or configure the ones provided.  Here is a quick rundown on what is available to start with:

rquote quote start/end string  

       rquote will check to see if the character it finds is escaped (this is only needed for single character quote strings).  It returns the index of the found quote or -1 if no quote is found. The rquote routine takes three parameters:

       quote      should be a list with two entries, the beginning and ending 
                  quote for example, for C this should be {/* */} while for simple
                  quoted strings you would want {\" \"} (the "\" is needed to
                  prevent tcl from acting on the character.
       start/end  is a Boolean (i.e. 1 or 0) which tells rquote which of the two
                  quotes to look for (i.e. beginning or end).
       string     is the string to search.
       
qstrings quote schar string line

       qstrings   handles multiline quoted strings.  It returns a list of lists.  Each entry in the list is the first and last string index of those parts of the string that should be checked.  It checks for leading character comments as well as the sorts of strings that rquote finds.  It, of course, uses rquote to do most of the heavy lifting.  The parameters are:

       quote      Same as rquote above.
       schar      The leading character comment id string.  For tcl and most
                  script languages this is "#".  For C++ it is "//".  This 
                  string may be preceded by white space in the line.
       string     The string to be filtered.
       line       The strings line number.  This is used to keep track of multiline-line
                  quotes.  If a line number is not contiguous with the prior line
                  the quote in progress flag is cleared.

thisstr which script string line

       The thisstr routine calls 'script' after appending 'string' and 'line' and returns the element of the resulting list defined by 'which'.

The spell check code calls the designated filter adding the 'string' and 'line' parameters and expects a, possibly empty, list of string indexes back.  If the list is empty, the line is not spell checked.  

The shipped spelling filters are in the file spell-filters.tcl.


8. VFS (Virtuial File System)
=============================================================================

Filerunner implements two somewhat different Virtual File Systems (VFSs):
1. Access to other machines somewhere on the network.
2. Access to various resources on the local system (including locally mounted
   files on other systems).

For type 1 VFSs the other systems files appear in one or both directory panes. The support for various operations via this VFS is limited to what the particular VFS actually supports. For example VFSrsync does not support CopyAs, while VFSadb, VFSftp and VFSsftp do support CopyAs. In some cases, short comings of a VFS are overcome by code in Filerunner. For example, if a VFS does not support a copy from one location to another within the VFS, Filerunner will copy to a local file and then back to the desired destination on that system. (This is really just a special case of copy from one VFS to another, which is supported.)

The following type I. VFSs are currently supported:
VFSftn   (File Transfer Protocol)
VFSsftn  (Secure File Transfer Protocol)
VFSrsync (The rsync protocol)
VFSadb   (The Andriod Debug Bridge)


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

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

To log on to most VFS sites you will need a name and a password. On
sftp sites you may also need to supply a pass phrase and the location
of your security files. Filerunner gets the user name from the supplied URL (e.g. ftp://tom@GandK.site). The subsequent password will be looked for in the "passwordLocker" under the given URL. If not found it will be prompted for. In the prompt window you will have the option of saving the password.

There are some things you cannot do on an VFS file/directory:
- You can't make soft links to an VFS file. Wouldn't be useful...

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

Each VFS has different options, such as port and subset options. These are available via the config file. For example, if you want to VFS 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
=============================================================================

As of 2018 releases anonymous FTP is entered by using the user name "anonymous". For example:

ftp://anonymous@ftp.foo.com

This allows anonymous and normal ftp links to exist at the same time.

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

Usually, VFS 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 VFS site. Just click OK on this popup and try the command again, and the VFS connection will automatically be reopened.

8.5 Closing VFS Connections
=============================================================================

You don't have to close VFS connections explicitly. They are closed automatically by the site, usually on time out. Filerunner does not implement a VFS close.

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

When you receive files through VFS 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 VFS 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 VFS Logins
=============================================================================
This section deleted, no longer supported.
End of deleted section.....

For sftp connections the 'password info' is expanded to contain three possible entries, a password, the 'disk address of the private ssh key' and the 'pass phase'.  Any or all of these can be blank with sftp and you can still do a connection.  Here are the options:

1. If you have not set up your public key on the server you are connecting to, you
   will need to use a password, but the other two entries are not used.

2. If you have set up your public key on the server and have your key in the 
   standard location (~/.ssh/ on linux/unix) you can leave the password blank.
   In this case you may have protected your key with a 'pass phrase', in which
   case you will need to supply the 'pass phrase' part.  Your entry might look
   like {my_site {joe_user {{} {} {pass phrase}}}}.  Note the '{}' entries to
   indicate blank password and disc locations.

3. You can also put your private key elsewhere, in which case you might enter:
   {my_site {joe_user {{} {/very/private/disk/address/id_dsa} {pass phrase}}}}
   Again note the empty password as the ssh key will do all the work.

4. You can also have private key in the standard location (~/.ssh/ on windows
   or linux but give it a different name.  In this case you might enter:
   {my_site {joe_user {{} {my_dsa_key} {pass phrase if needed}}}}

5. The all blank case is when the private ssh key is in the standard place and
   it is not protected with a 'pass phrase'. {my_site joe_user}

For security reasons, filerunner encripts the 'password info'.  The encripted version is a string that starts with '>>' and ends with '<<' and is otherwise all number and spaces.  The encripted version contains all three parts of the 'password info'.  If you need to change the 'password info' you will need to replace the whole string including the '>>' and the '<<'.  Filerunner will encript the new password when it first encounters the unencripted version.  If you edit the config file on the disk this will happen when filerunner next reads the file and the disk version will be changed when filerunner next writes the configure file.

A note about security:

Even though the 'pass phrase' is encripted, filerunner's encription is rather easy to break, expecially by someone who is serious about it.  As an additional measure it is recommended that you change the read permissions on the config file!

This is how you do this:
> chmod go-rw ~/.fr/config
or you could use the 'Chmod' button in filerunner.

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.11 Other VFS modes (sftp & aftp)
=============================================================================
sftp uses secure FTP to connect with the remote.  It does this by using the Expect package to talk to the sftp program on your system (so, yes you must have it installed).  Likewise aftp uses Expect to connect to the adb program.

FTP sFTP & aFTP all require 'password info' which has the following three parts:
1.) A password (may be {} for sftp connections useing ssh keys)
2.) The disk address of the ssh private key (may be a full address or 
    the file name if the key is in env(HOME)/.ssh)
3.) The pass phrase.
(Note that the three part 'password info' is only fully filled out for sFTP)

For aFTP, since it all local, we use the user/password in the following way:
<user>
usb	Use a usb connection to the Andriod device
emu	The Andriod emulator is accessed
ser     Connect to device serial number <host> using a usb connection
pro     Connect by product number  <host> is taken as the product number
con     Connect by LAN using <host>[:<port>] port is used 5555 if not set

All connections will use super user mode if 'su' is found in the password.



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


9.1  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.  You can abort a command by typing cntl-C in the command window (handy when you forget the file list in grep).


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


9.3 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 make a list of all possible completions and fills in as much as is common to all of these.  If there are no common characters, a flashing message will appear indicating how many options there are. If you then type the Tab button again filerunner will display a list of the possible completions from which you may select one with the mouse.  You may, at any time, continue typing and again type Tab.  Each completion stops at the directory boundry (i.e. the '\') at which you can again type Tab.  You can also click mouse 3 (usually the right button) in the command entry window which will bring up a file selection window.  Note, this window will only let you select files, it will not allow you to just select a directory on the way to a file. 

The completion code is sensitive to where you are in the command line.  If it is the command entry (and not a parameter) and there are no '/'s in the line sofar, the possible selections include all executable files findable via the PATH environment variable plus the aliases pluse the internal commands.  This same selection is also available if the command is 'type' (in unix like systems).

Command completion is also available to the Run command when entering a command name, however, in this case the aliases and the internal commands are not available nor offered.

9.4 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.
type command  - Gives the location of the command.


9.5 Aliases:

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


9.6 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 other 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 VFS 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 by 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) 2010-2020 by Tom Turkey
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 may have found a bug. That means something really serious just happened and FileRunner may 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).  You can attempt to ignor the bug which works most of the time but some times the code is completely lost and only a restart will do. On the other hand I have been somewhat lax in seperating errors generated by doing something you just can not do (e.g. write over roots files) from program errors, so, please look at the message to see if it might be one of these before sending it to me. Likewise, some programming errors may endup in the error window. In this case, attempt to recreate the error with "Expanded Error Messages" (Configuration menu) and send the expanded result to me.



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: tom@GandK.site (only, Henrick seems to have disappeared)

There is a sourceforge mailing list with announcements for FileRunner. Send mail to filerunner-news-support@lists.sourceforge.net and I will add you to the list (i.e. you will need to wait for me to approve your first post but when doing so I will add you to the list).

