OS/2 Shareware BBS: 35 Internet/35-Internet.zip/xdown13.zip/README.en

Text File | 2001-07-01 | 24KB | 570 lines

Instructions for using the program "Downloader for X" version 1.16
(c) 1999--2000, Maxim Koshelev

Contents
0. Introduction
1. What is this Program Needed For?
    1.1 License
    1.2 Features
    1.3 Installing the Program
    1.4 Usage Examples
2. The Program's Main Window
    2.1 The Menu
    2.2 The Button Bar
    2.3 Download Queue
    2.4 Main Log
    2.5 Status Line
3. Configuration Dialog
    3.1 Geneneral Options
    3.2 Limits
    3.3 Other Options
    3.4 Main Log Options
    3.5 Selecting Columns to Display
    3.6 Proxy Server Options
    3.7 Confirmation Options
    3.8 Download Speed Options
4. Limits Window
5. Default Passwords
6. Drag-and-Drop Basket
    6.1 Basket Menu
7. Interface Options
8. Command Line Parameters
9. Appending New Downloads
    9.1 Download Editing Dialog
    9.2 Other Ways of Adding Downloads
10. Conclusion
---------------------------------------------------------------------

0. Introduction

These instructions are at attempt at a full description of the characteristics
of "Downloader for X" (henceforth "the program").  If you find in the text
here presented any discrepancy or inaccuracy, please inform the author of
this program.  Of course, the author does not assume any responsibility for
harm suffered as a result of the use of this program, for as much as the
program is furnished free of charge, in the hope that it will be useful.

1. What is this Program Needed For?

This program is intended to make it possible to download files from Internet
sites by means of the FTP and HTTP protocols.  Because it supports
resuming of downloads  and automatic re-connection to servers after
failures, it will prove absolutely indespensible when connections to Internet
sites are unstable, for downloading files from distant servers, and for
fetching large numbers of files.

1.1 License

Alas, the license is not the GPL.  What does this mean?  This program is
distributed without fee, even with open source code.  Accordingly, the author
assumes no responsibility for any damage which might be inflicted by this
program.  But the author reserves unto himself the inviolable right of
exclusive modification of the source code.  This means that any other
person may distribute this program only "as is," that is without modification
of the source code.  If you are considering introducing some sort of modification
you are OBLIDGED to send it to the author for incorporation into the program's
official code.  NO ONE other than the author of this program HAS THE RIGHT
to distribute MODIFIED versions of this program.  This restriction is made
chiefly in order to centralize the project, to avoid the appearance of various
"offshoots" of this single program.  Naturally, upon the completion of work on
the program, the present license will give way to the GPL.

1.2 Features

Here I shall attempt to present a complete list of the features available
in the version described:

    * Downloading using the FTP and HTTP protocols
    * Support for FTP and HTTP proxies
    * Recursive FTP downloads
    * Recursive HTTP downloads
    * Support for "masks" in FTP downloads
    * The ability to limit the depth of recursion
    * The ability to postpone file downloads until a specified time
    * Support for the resumption of downloads
    * Automatic reconnection to the server after a break in the connection
    * The ability to limit the maximum download speed used for all downloads
      as well as for selected downloads
    * The ability to limit the number of simultainious connections to any
      given server
    * The keeping of a log of each download
    * Support for "Drag and Drop", for example from Netscape
    * The ability to add a new download by means of teh command line
    * monitor clipboard
    * The keeping of a main log which may be written to a file
    * Automatic preservation of all configuration options and interfaces
    * The ability to configure the appearence of the columns in the
      download queue
    * The ability to configure the button bar
    * Internationalization (translation) into 14 languages
    * Extensive configurability
    * The ability to download one file in several streams (mass download)
    * Startup without the X interface, from the command line

1.3 Installing the Program

If you have RedHat Linux 6.1 installed on your machine and it is an x86
compatible computer, you can simply install the program from an RPM file
which you may obtain from the programs home page at:

    http://www.krasu.ru/soft/chuchelo/

If you have an older version of RedHat Linux, then you can make an RPM
file from the .src.rpm file (which you can find in the same place).  In
order to do this, use the command:

$ rpm --rebuild lalala.src.rpm

where "lalala.src.rpm" is the name of the program's source RPM file.
For owners of other versions of Linux and for owners of other Unix variants,
it is necessary to install the program from the source, which is described in
the README file which comes in the tar.gz archive which may be obtained from
the same place.  If you have the GNOME or Afterstep desktop shell, then after
the installation of the program it will become possible to launch it from the
cooresponding menu.  (The program's name for launching it from the command line
is "nt".)

1.4 Usage Example

Launch the program and press the key combination Ctrl-N.  In the window that
appears, on the "URL" line, enter the the address of the file (or directory)
which you wish to fetch on the line labeled "URL".  On the next line,
indicate the folder into which you wish the file to be deposited.  Having done
that, you may simply press the "OK" button.  You will notice that a new line
appears in the main window.  It is various information about the current status
of the downloading of the file.

2. The Program's Main Window

After launching the program, hopefully you will see the program's main window.
It contains the main menu, buttons bar, download queue listing, main log,
and status line.

2.1 The Menus

Through the main menu you can gain access to almost all of the functions of the
program.

2.2 Button Bar

The button bar is intended for quick access to the most frequently used
functions of the program.  The functions of the buttons (from left to right)
are:

* Add downloads
* Add downloads using the contents of the cut-and-paste buffer
* Remove the selected downloads
* Start or restart the selected downloads
* Stop the selected downloads
* Remove finished
* Move the selected downloads to the front of the queue
* Move the selected downloads to the end of the queue
* Open the log window for the selected download
* Three buttons for limiting speed
* Purge the download queue
* Write the queue listing to a file
* Toggle the Drag-n-Drop basket on and off

You may choose which buttons will be visible by means of the main menu (see
section 6).  Pressing the right mouse button on a button of writing queue
will record its present state in a file which is loaded at program start.

2.3 The Download Queue

Any download added in Downloader for X enters the Download Queue.  The process
of loading the file begins only if it would not cause the user-established
limits to be exceeded.  These include the number of simultainious downloads,
the limit on connections to the server, and the start time.  Otherwise, the
download will "wait" for an easing of the limits, for example, the halting of
other downloads (in case of their completion, a communications error connection breaks , or a
user action).  The queue listing may have a maximum of 13 columns:

* Status - Here little pictograms displays the current status of
  the download.
* File Name
* File Type (Directory, File, link, device)
* File Size
* Downloaded Size - size of the part of the file already loaded
* Remainder - size of the part of the file yet to be loaded
* Percent - the percentage of the loaded part of the file as compared to the whole
* Speed - Average download speed
* Elapsed Time
* Estimated Time - time remaining until completion
* Time of Pause - the amount of time that has elapsed from the moment of reading
  data (This becomes visible only after 30 seconds.)
* Number of Attempts - the number of attempts to fetch the file made so far
* URL - full address of the file

Any column may be turned off in "Program Configuration" in the section "Columns".
By default ALL columns are presented.  The formats for representing time and sizes
are changed there too.

You may likewise press the right mouse button over a download in the queue
listing in order to get quick access to these key functions: Modify, Move Up,
Move Down, Start, Stop, Set Limits, Open Log.

In order to move the selected downloads up or down you can use the following
key combinations:

Shift+Up - up by one

Shift+Down - down by one

Shift+PageUp - to the very top of the queue

Shift+PageDown - to the very bottom of the queue

Double clicking the left mouse button on a download line will call up the log
for that download.  The will likewise be opened if one presses the Enter key.

The user can add a download simply dragging a link from somewhere and
dropping it directly into this queue.


2.4 Main Log

The main log serves to descibe events which occur in the program, for example
the completion of a download.  The log may be written to a file.  To do this,
indicate the name of the file in the Program Options in the section "Main Log".
There one may turn on the output of all messages  (to produced detailed
information). You can remove a line from the main log (but not from the file
in which it is written).  Press the right mouse button on the desired line,
choosing "Remove line".  In order to copy a line from the log, simply double
click on the line and select the line in the dialog box that appears.
Access to this dialog box may also be obtained through the menu that
appears when the right mouse button is pressed on the line.

2.5 Status Line

The Status Line serves to bring out auxiliary program information.  It is
divided into four parts:

I The file name of the last download

II The total number of bytes read, starting from the launching of the program,
and the current speed in bytes per second

III Percent completed of the selected download

IV Speed Graph, depicted in four colors.  By default:  the color black represents
tops , dark gray average speed, light gray the speed of the selected download.

3. Options Dialog

Most configuration of the program is performed by means of the options
dialog which may be opened by choosing Options/General  from the main menu or
by pressing Ctrl-C.

3.1 General Options

"Use title" - with regard to the title of the main window

"Use title for information" - Present information about the selected download
in the title of the main window.

"Display queue statistics too" - in addition, queue statistics will
be displayed

"Scroll Title" - scrolling the title.

"Automatically remove completed downloads" - Upon completion of the download
it will be automatically removed from the queue of downloads.

"Automatically remove failed downloads" - Same as above but if the
download didn't succeed.

"Optimize recursion" - If you fetch a directory through FTP, then when this
option is enabled the program will not determine the size and other information
for each file in the directory separately.

"Restart if download won't resume" - Even if the server does not support
resuming, attempt to download the file anew.

"Open a window for Drag-n-Drop" - If you want the program to open a window
for adding a new download when drag-n-drop is used, depress this option.

"Iconify window on close" - If you attempt to close the program's main window,
it will be iconified instead.

"Save download listing every N minutes" - Is that completely clear?

"Take date from server" - Set the file's date and time to what they were on
the server.

"Take file permissions from server (FTP only)" -  file permissions, for
dirctories permission by execute will be added automaticaly, read, and write permissions for the owner.

"Monitor clipboard" - If you want the program to automatically present a window
for adding a new download whenever a reference appears in the cut-and-past
buffer (for instance if you have copied a reference from Netscape), then choose
this option.

"Draw a graph in reverse order" - by default a chart in the lower
right corner of the main window advancing from right to left.

"Default file permissions" - when downloading by the HTTP the program will
set up these permissions on files.

"Show the 'Basket'" - this is the same as the far right button on the
button bar in the main window.

"Exit if nothing happens for N minutes" - If there are no waiting or active
downloads, then exit after the indicated amount of time.

3.2 Limitation

In this section the user may establish parameters which the program will use
as defaults for all downloads, though they may later be modified for each
download.

"Maximum number of active downloads" - maximum number of simulataineously
"activated" downloads.  The program will NEVER activate more downloads than
you specify in this spot.

"Delay before retrying a connection (in seconds)" - this parameter specifies
the amount of time which the program will wait before connecting to the server
again.

"Timeout for reading from socket (in seconds)" - This parameter indicates how
long to wait for data from the server.  The program will automatically
break the connection if this limit exceeded.

"Maximum lines in log" - I hope it's self described

"Number of attempts (0 unlimited)" - how many times to attempt to to connect
to the server in an attempt to fetch the file.

"Rollback after reconnecting (in bytes)" - certain old modems (according
to users) and defective proxy servers return garbage when the
connection breaks.  In order to download sucessfully under these conditions,
set this parameter to 2--10 kilobytes.  Then, during each new attempt the
program will attempt to continue loading not from the very end of the file which
has already been loaded, but with a step back toward the begining of the file.

"Depth of recursion (0 unlimited, 1 no recursion)" - this one speaks for
itself.

3.3 Other Options

"Save downloads to this folder" - the directory in which downloads will
be saved by default

"Execute this on exit" - enter a command line which should be executed on
program exit.  For example, a pppdown script.

"File name for saving if it is unknown" - In a number of circumstances,
the program will not know the name of the file being downloaded (for instance,
if you entered http://www.linux.org/).  Enter here the desired file name for
such situations.  By default "index.html".

"User-Agent for HTTP requests" - If you want to program to present itself as
something other than "Downloader for X" when downloading by HTTP, replace
the parameter "%version", which is the default.

"Skip these extensions in the clipboard" - When the "Monitor Clipboard"
function is in use, almost all links passing through it are simply unnecessary
and a hindrance.  In this space enter, separated by blanks, a list of
extensions which you want to "not notice" when using "monitoring".

"Use passive mode for FTP" - The name speaks for itself.
Behind Some firewalls permit only passive mode FTP connections to pass.

"Remember passwords" - If you want the program to remember passwords from the
password input field, and make a record of them, choose this option.  But
then all of the lines for the entry of passwords begin to show the entered
information and not the symbol "*".

3.4 Main Log Options

In case you have to write the log to a file, you can, in this portion of the
options, indicate the file into which the log should be written.  Likewise you
can require the keeping of a "detailed" log, in which case you will get much
more detailed information.  The log may likewise be appended to the file or
be written anew each time.  This pertains to restarts of the program, that
is if you instruct it to overwrite the log, then at every program launch
the log file will be truncated.

3.5 Selecting Columns to Display

In this section of the tunables, you can setup the representation of the
columns and likewise the format of the sizes and times which will be
represented in them.

3.6 Settings of Proxy Servers

In the proxy server settings, you can designate proxy servers for the FTP
and HTTP protocols separately.  And you can specify whether a username and
password are required, and if required, the username and password.  A number of
FTP proxy servers known to the author do not require a password.

3.7 Confirmation Options

Here you can indicate whether the program will ask you to confirm various
"dangerous" actions:

* Exiting the program
* Removal of a queue entry
* Removal of completed queue entries
* Removal of failed queue entries
* Removing all queue entries

3.8 Speed

In this section of the options you can set two parameters:  the first and
second speed levels.  These speeds set the read and yellow buttons on the
button bar.

4. Limits Window

This window is called up from the program's main menu.  Choose "Limits" from
the "Options" menu.  Before you there will appear a window with an empty list
consisting of three columns.  If you want to establish a limit on number of
connections with respect to any given server, press the "Add" button and, in the
window that appears, enter the address of the server, the port number, and
the maximum permissible number of simultaineous downloads.  After you press
the "OK" button, a line with the information will appear in the limits window.
In the last column, the number of current connections to the server at any
given time will be indicated.  You can modify a limit by double clicking
the mouse on the line with the limit.  In order to remove a limit, select the
line to be removed and press the "Delete" button.

5. Default Password

The program permits one to specify for any server a user name and password
which are used by default.  To enter these parameters, go to the main menu
in the submenu "Options" and choose "Passwords".  In the window that appears,
press the "Add" button in order to enter a new default password.
You will notice that for any one server there can be only one
username-password pair.  In order to edit an existing entry, press the mouse
button two times quickly over the cooresponding line.

The program will use the default password only if you do not enter a password
when adding the download to the queue.

6. Drag-n-Drop Basket

This is a separate window which is always above  all windows (or at least
ought to be there).  Into this little window you can drag and drop links,
for instance from Netscape or from the Gnome desktop.  A double mouse click on
this little window calls up the program's main window or hides it if it is
currently visible.  You can likewise relocate the window by holding the mouse
button on it and dragging to desired location.  Clicking the left mouse button
brings up a menu, for quick access to certain functions.  Clicking the middle
button of the mouse on the basket brings up a dialog box for adding new
downloads.

6.1 Basket Menu

By means of this menu the user receives access to next functions of the
program:

* Adding downloads
* Adding downloads from the cut buffer
* Alteration of speed limits
* Opening configuration dialog
* Exiting the Program

7. Interface Options

In addition to the fact that one may set up columns for the presentation
of information in the download queue (3.5) one may likewise adjust the
button bar.  To do that go to the menu "Options" and in the sub-menu "Buttons"
select the desired button.

8. Command Line Parameters

In the version of the program here discribed, the following command line
parameters work:

--help, -h  Display the full list of command line parameters and exit.

--version, -v Display the name of the program and the version number and exit.

--info, -i Display statistics about downloads if the program has already been
  started.

--speed, -s print the current speed (that is, the speed at the given instant)

-t1, --traffic-low - activate the lowest download speed limit, equivelent to
pressing the red button.  This parameter works even if the program has already
been started.

-t2, --traffic-medium - the same except the middle limit.  Equivelent to the
yellow button on the buttons bar.

-t3, --traffic-high - no speed limit.  Equivelent to the green button on the
button bar.

-d,--directory - set the directory for a download added by from the command
line, by default it is the same as for downloading from the main window.

-c,--delete-completed - Remove completed downloads from the queue.  This option
works only if the program is already running.

-m,--max-running - set the maximum number of simultaineously running downloads.

-w,--without-gui - Launch the program without its graphical user interface,
in command line mode, with this option the program will continue to accept
commands for example, from a gnome-applet.

-r, --rerun-failed - restart all failed downloads.

In order to add a download by means of the command line, simply type:

nt address_of_file

One may specify serveral addresses by using blanks.  An address is
differentiated from an option in that it does not begin with a dash.

9. Appending a New Download

A new download can be appended through a couple different facilities:  through
the menu or through the button bar.  In such a case, there will appear on the
screen a download editing window in which one may set all the parameters
of the download.

9.1 Dialog for Appending Downloads

The download editing dialog, which appears in particular when you add a download,
is divided into four parts, each of which is presented as a tabbed layer.  I
will not here discribe the "Proxy" and "Other" tabs because they duplicate
certain functions of the tunables.  I describe only the first layer "Main" and
the last "Time".

On the first line "URL" enter the address of a file (or directory) for
downloading on the second - the path to the directory into which the fail
is to be written.  Downloader for X will attempt to create the folder (and any
intervening folders) if they do not exist.  If you wish to write the download
into a file with a name different from the original, then on the following
line indicate the file name.  The line User-Agent is for the HTTP
requests , If you do not know what this is, leave it unmodified.
If a site needs a password then go on and enter it too.  If you do not want
the download to be started automatically after it is added to the queue,
then check the last checkbox under the "Main" tab - "Pause immediately
after adding".

9.2 Other Ways to Add Downloads

In addition to adding by means of the menu and button bar, the user can
add downloads by the following means:

* Through the command line (7)

* By dragging links from another program and dropping them somewhere in the
middle of the download queue (2.3)

* Or through the special "basket" which can be turned on from options (3.1) orr from the buttons bar (2.2)

10. Conclusion

The program Downloader for X is under continual developement, so if you don't
find a necessary feature, it most likely it will appear soon.  The author
appeals to all users with new feature ideas to carefully read through
this document before sending suggestions about new features.  It is possible
that what you want to do can already be done by using an available features.
Likewise it does not make sense to send a suggestion for a feature not required
for the simple management of downloads, for example MP3 playing or archives
management. :)  Such features have already been implemented in various other
programs.