gFTP Users Guide, version 0.2 (12/03/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.

1. Connecting to a remote site
   1.1. Connecting using the toolbar
   1.2. Connecting using the openurl button
   1.3. Connecting using bookmarks
   1.4. Connecting using command line parameters
2. Transfering files
   2.1. Transfering Files
   2.2. Transfering files with Drag and Drop
   2.3. Differences between downloading in ASCII and BINARY mode
3. Configuring gFTP
   3.1. Proxy server setup
   3.2. Configuring file extensions

1. Connecting to a remote site

This section describes the various ways that you can connect to a remote
site in gFTP.

1.1. Connecting using the toolbar

   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 type
in a directory on the remote side, and it will go into that directory after
it connects. Once you have all your information filled in, you can either
hit enter in the host, port, user or pass field, or you could hit the
openurl button (see below for an explanation of why).

1.2. Connecting using the openurl button

   The openurl button located on the toolbar does have several uses. One
thing that you can do is drag a url from another application (say Netscape),
and drop it on the openurl button. gFTP will automatically disconnect from
any site that you are connected to, and connect to that site specified by
the url. When you click on the openurl button, several things are checked
(in the following order):

	- If you are already connected to a site and you click the openurl
	  button, you will be disconnected from the site that you are
	  connected to.

	- If you have a hostname entered on the toolbar, it will connect to
	  that host.

	- If the above 2 conditions are false, then it will bring up the
	  openurl dialog where you can enter a FTP url to connect to. FTP
	  url's can look like some of the following:

		ftp://ftp.myhostname.com/pub (this will log in as anonymous)
		ftp://user@ftp.myhostname.com/pub (log in as user. You will be 
						prompted for a password)
		ftp://user:pass@ftp.myhostname.com/pub (log in as user/pass)


1.3. Connecting using bookmarks

   Bookmarks are the easiest way to connect to a remote site. Just go to the
Bookmarks menu, and select which site you want to connect to. If gFTP
doesn't have a password for the site you are trying to connect to, it will
prompt you for one. Due to security reasons, gFTP will not save this
password in your config file when it prompts you for it. If you want to save
your password for a bookmarked site in the config file, then you could
either add it manually to the config file, or you could go under Edit
Bookmarks and add it there.

1.4. Connecting using command line parameters

   You can tell gFTP to connect to a particular site on startup. Just type
gFTP ftp://ftp.myhostname.com/pub and gFTP will connect to that site when it
starts up. (See the openurl description above for more examples of valid
urls).


2. Transfering Files
 
   This section describes the ways that you can transfer files in gFTP. One
of the features of gFTP is that you can have multiple file transfers going
at the same time. Once you have a file transfer started, you can safely
disconnect from the remote site, and it won't harm the transfer in progress.
You can then connect to another site, and have even more file transfers
going at the same time. If gFTP is in the process of downloading some files
and the connection closes for some reason, gFTP will try to reconnect again
and continue with the file transfer where it left off. You can set how many
times to reconnect and how long to wait in the options dialog.

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

   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.

2.2. Transfering files with Drag and Drop

   You can also transfer files through drag and drop between the two
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.

2.3. Differences between downloading in ASCII and BINARY mode

   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.

3.1. Proxy server setup

   To setup your proxy server configuration, go to FTP->Options. You can go
under HTTP Proxy and FTP Proxy to setup your proxy hosts, usernames and
passwords. In the FTP Proxy, you can setup how you want gFTP to log into the
proxy server. I already have many of the common types of proxy servers that
you will encounter already in gFTP.

3.2. Configuring file extensions

   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.
