gFTP Users Guide, version 0.1 (07/06/1999)
Copyright (C) 1998-1999 Brian Masney <masneyb@seul.org>

   This document is a short tutorial on how to use gFTP and describes some
of its functionality. It is by far not complete at this stage, but I hope to
improve on it over time. I welcome any changes or additions to this document 
to make it better, and easier to read.

- Connecting to a remote site

   You can use the toolbar at the top of the window to connect to a remote
site. The only mandantory field to fill in is the hostname, all of the other
fields are optional. If you don't fill in the port, it will default to the ftp 
port in your /etc/services file (usually port 21). If you don't fill in a 
username, it will default to logging you in as anonymous. You can also open
a site via a url. You can either goto Remote->Open URL, or click on the
Open URL button on the toolbar. Just type in the url you want to connect to,
and gftp will automatically parse it for you. You can also drag a url from
netscape, and drop it on the open url button on the toolbar. If you are
using a proxy server with gftp and you want to connect through it, make sure
FTP->Use Proxy is turned on. 

- Using Bookmarks

   The bookmarks work about the same as they do in Netscape. If you are at a
site you want to bookmark, go to Bookmarks->Add Bookmark. It will then ask
you to give this bookmark a name. After you do this, it will save the
settings for the current site you are connected to. If you want to pull up
this site again, all you have to do is go to Bookmarks->YourDescription.
   If you want to edit a bookmark, you can go to Bookmarks->Edit Bookmarks.
It will pull up a tree view of your current bookmarks. You can move items
around with the mouse (note: this behavior is broken in gtk+ 1.2.2, but it's
fixed in 1.2.3). You can also create new folders, and new items, along with
deleting items as well. If you want to edit an item, you can double click (or
hit enter) on an item to pull up it's properties. You can rename, edit the 
host, port, user, pass, account, and use proxy. There may be two confusing 
items here: the account and the proxy option. Some older ftp servers require 
the account feature, and I have had some people ask about it so I added it in. 
I didn't add a account field on the toolbar because I don't think that many 
people will be using it. So, that's why it only shows up here. The proxy 
option here will tell gftp whether or not to connect through the proxy server. 
When you load a bookmark, gftp ignores the setting of the Use Proxy under the 
ftp menu...it looks at what this value is set to. This makes it nice if you 
have some ftp sites behind your proxy server you want to connect to, and for 
sites outside the proxy server. You won't always have to keep toggling this 
setting.

- Transfering Files

   It is relatively simple to transfer files in gftp. If you want to
download some files, just select what files you want to download, and hit
the arrow pointing to the left. You will see the downloads appear in the
download manager towards the bottom of the screen. The download may or may
not start, depending on how some configuration options are set (go under
FTP->Options to get the options dialog). There is an option Start File
Transfers, that when set will always try to start the transfer as soon as it
can. This feature is good to turn off if you are using a modem, and you have
multiple sites you want to get files from. You can queue up all of the
transfers, and when you are finished, just turn on start file transfers, and
they will start to go. There is another option, do one transfer at a time.
When this is set, it'll do what it says: only one transfer at a time. This
also benefits you if you are using a modem. When you start some downloads,
you can disconnect from the remote site, and connect to another one.
   gFTP will only keep one control connection open to the ftp server as long
as it can. When you start a file transfer, it will use the control
connection gftp already had open to the ftp server. That is why you'll see
cached appear at the top of the remote window. After the file transfer is
complete, it'll give the control connection back to the main window as long
as that's the same site you had open. If you try to change directories, or
download files in the remote window while it doesn't have a control
connection, it'll open up a second one to the ftp server and use that.
   There is an option called Preserve permissions that some users may find
useful. After you transfer a file, it will set the permissions on the file
you transfered to be the same as the source.

- Transfering files with Drag and Drop

   You can drag and drop items to/from the local and remote windows. For
example, you can drag some files from the local window to the remote window.
This isn't too much use, but you can also drag files from midnight commander
and drop them on the remote side to have the files uploaded. You can also
drag ftp urls from netscape, and drop them onto the local window to
automatically have them download. Note: to drag an item from gftp, you have
to hold down button 3, which for a 2 button mouse is usually both buttons.
If you have a 2 button mouse, you have to make sure Emulate3Buttons is
enabled in the Pointer section of your XF86Config file.

- The difference between downloading files with ascii and binary

   If you download a file in binary mode, it will transfer the file as is,
making no modifications to it. But, if you are transfering text files, you
should transfer them as ascii (unless you're transfering it to another unix
machine, which then you can use ascii or binary). In DOS, the lines in text
files will have a carriage return and line feed after them. 

This is a line in a DOS text file\r\n

But, in unix the file will just be stored with a line feed at the end.

This is a line in a UNIX text file\n

If you transfer a text file from a DOS machine as binary, and open it up in
vi, you will see some weird Ms at the end of each line. These are the
carriage returns. To get around this, transfer the file in ascii mode, and
gftp will do the proper conversion for you. You can change between ascii and
binary in the ftp menu.

- The stop button

   There is a stop button on the toolbar which will let you stop gftp trying
to connect to a site. Right now, the stop button is only active when it is
connecting to a site, or when it is getting a directory listing. There is an
option that you can disable, bring up reconnect dialog, that will suppress
the dialog that comes up when you hit stop, or when you can't connect.

- When connecting to a site, make gftp auto-retry to log in again

   Sometimes you have a hard time getting into a site. Under options, you
can set Connection retries to the maximum amount of times you want gftp to
retry the connection. If you set this to 0, gftp will try indefinately until
it gets in. There is another option Retry sleep time which tells gftp how
long to wait until trying to connect to a site again. One final option is
Connect timeout, which is the max amount of time gftp will allow a
connection to a remote site. When this time expires, gftp will sleep the
amount of seconds specified in Retry sleep time, and it will try to connect
again

- Caching of Directories

   You may notice that if you have Use cache on, that when you back track to
some directories you already visited, that they come up quicker, and cached
appears at the top of the remote window. gFTP will save the directory
listings of the directories you already visited. It will only remember the
directories you visited since gftp was first started (unless it happens to
crash prematurely for some reason). The current cache system does need some
improvements to it, but it does help to reduce network traffic.

- Other config file options

   Most of the settings to gftp can be changed under FTP->Options, but I
don't have all of the settings there yet. If you want to see all of the
configurable options, edit your ~/.gftp/gftprc file. The file will be well
commented, and each option will be explained. I won't go into detail here
about any of them. If some of the descriptions aren't clear, please let me
know and I'll try to get it cleared up there.

- Setting up your proxy server

   gFTP does support a wide range of ftp and http proxy servers. The first
thing you will have to do is determine how you have to log into your proxy
server. You can either change it under Options in gftp, or in your config
file. The config file has much better descriptions of how each proxy type
will log into the server. The ftp proxy code will be improved to handle much
more servers. I'm going to make some form of generic scripting in a future
version to log into the proxy server, which will simplify the proxy code, and 
will provide maximum flexibility to the user.

- Setting up file extensions in the config file

   Towards the bottom of the config file, there is a section that has some
ext= lines. Here you can control via a file extension, the icon in the
listbox for it, the default download method (ascii or binary), and a default
view/edit program. For example, let's take the line

ext=.xcf:gimp.xpm:B:gimp

The first token, .xcf, is the file extension. The next token, gimp.xpm, is
the default icon to use in the listboxes. You don't have to specify one if
you don't have to. By default, gftp will search ~/.gftp,
$(PREFIX)/share/gftp (where prefix is your installation prefix), and then
/usr/share/icons in that order. The files have to be a valid xpm file. The
next token, B, specifies whether or not to download it as Binary or Ascii.
If you want to have something download as Ascii, just put an A there. If you
omit this field, then gftp will download the file according to whether ascii
or binary is selected in the FTP menu. The final token, gimp, specifies the
name of the program to run to view or edit a file with that extension. You
can omit this as well if you like.
