                      LoadMaster User Manual
                      ======================

Contents
~~~~~~~~
  What is LoadMaster?
  Why use LoadMaster?
  Installing LoadMaster
  Running LoadMaster
  Configuring LoadMaster
  Quitting LoadMaster
  Starting new downloads
  The download queue
  Using LoadMaster with Browse
  Using LoadMaster with Fresco
  Using LoadMaster with Oregano
  Using LoadMaster with Webster XL
  Known Problems
  Reporting problems


What is LoadMaster?
~~~~~~~~~~~~~~~~~~~

LoadMaster is a download management tool for RISC OS computers.
It is not a web browser, but rather works in concert with traditional
web browsers to enhance your surfing experience.

  * A list of downloads can be queued, and will be downloaded
    automatically one at a time.

  * If the connection to the Internet is lost during a download the
    state is remembered and automatically picked up again when the
    link comes up again.

  * If a connection 'dries up', but the Internet link is still up the
    download will be reconnected automatically and will continue from
    where it left off.

  * The downloading is done 'in the background', so will continue even
    while the foreground of the machine continues to work on other
    tasks (even single-tasking ones).

  * A multitasking frontend provides simple WIMP based controls that
    integrate with all the popular web browsers including Fresco,
    Oregano, Webster XL and Browse.

  * Both HTTP and FTP protocols are supported.


Why use LoadMaster?
~~~~~~~~~~~~~~~~~~~

Web browsers have always offered the facility to fetch files from the
internet, but there have always been limitations in their abilities
which are becoming more and more apparent as the internet develops.

At busy periods on the Internet servers often 'dry up' and stop
sending data, perhaps mistakenly because congestion makes them think
that the receiving computer has given up. This can be extremely
frustrating when you get 80% of the way through a download and it dies
on you.

As the average size of software downloads increases this problem has
become worse; to partially counteract this software is often released
in multiple sections. Trying to download these multiple sections at
the same time just adds to the congestion, so most people resort to
downloading them in sequence. Unfortunately there has been no easy way
to queue multiple downloads, meaning that people have been forced to
wait around for each part of finish to start the next.

It is also a sad fact of life that web browsers aren't the World's
most reliable bits of software; faced with the wide variety of badly
written pages out there it is perhaps not surprising that they
sometimes crash. At best this loses the current download, at worst
killing the whole machine.

Finally, telephone based Internet connections have long been known to
'drop' at unexpected moments, either due to faulty modems at the
remote end, poor telephone connections, or even to family members
picking up other extensions. With the (slow) introduction of unmetered
access that currently regulates load by kicking people out after
periods of time this looks set to get worse before it gets better.

LoadMaster addresses all these concerns: Use your normal web browser
to surf as usual, and pass any lengthy downloads to LoadMaster for
queueing. If the browser itself dies, then LoadMaster carries on in
the background. If the whole machine dies then on a restart LoadMaster
will remember where it was and will continue onwards. If the
connection drops then LoadMaster will simply wait for it to start
again whereupon it will carry on where it left off.


Installing LoadMaster
~~~~~~~~~~~~~~~~~~~~~

See Docs.QuickStart for information on how to install LoadMaster.


Running LoadMaster
~~~~~~~~~~~~~~~~~~

Double click LoadMaster, and it will install on the iconbar. It will
automatically continue with any downloads queued from a previous
session.


Configuring LoadMaster
~~~~~~~~~~~~~~~~~~~~~~

In most cases LoadMaster should operate perfectly well with no extra
configuration, but for some users (particularly those behind
firewalls) the configuration window can be used to tune the behaviour
of LoadMaster.

To open the configuration window choose the 'Configuration...' item
on the menu available from the icon bar icon.

The FTP and HTTP Proxy entries should be self explanatory; consult
your network administrator or ISP connection details for what values
to put in here. A customer of Bogonet ISP might use the following
settings:

  FTP Proxy
    Machine: ftp-cache.bogonet.co.uk
       Port: 21

  HTTP Proxy:
    Machine: www-cache.bogonet.co.uk
       Port: 8080

The FTP Email address entry can be used to specify what string is
sent as the username when doing anonymous FTP requests. Typically
sites ask that you send your email address here so they can track
who is using the site, but normally almost any string will do.
LoadMaster sends 'bill@microsoft.com' as a default.

The Extra HTTP Headers section of the dialogue can be used to
specify other headers to be sent before the HTTP GET request.
Multiple Headers can be separated by using \n. For example:

  icy-metadata: 1\nsecret-microsoft-extensions: 0

Finally, the number of downloads that LoadMaster will automatically
start at the same time can be set. You can of course always start
more by clicking 'Start' on more downloads. LoadMaster defaults to
just 1.
  

Quiting LoadMaster
~~~~~~~~~~~~~~~~~~

Quitting LoadMaster is best acheived from the menu on the icon bar
icon; Quit or Quit => Frontend will kill the WIMP application, leaving
any queued downloads running in the background. To completely quit
everything you should choose Quit => All from the icon bar menu.


Starting new downloads
~~~~~~~~~~~~~~~~~~~~~~

There are several ways to start downloads; we will describe the
simplest here, but more are listed in the browser specific sections of
the manual below.

Click Select (the left hand mouse button) on the icon bar icon and the
current downloads window will appear. This shows all the outstanding
downloads, hence will be empty when you run LoadMaster for the first
time.

Below this window is a pane window containing an input box; click in
here and type in the URL you wish to download; for instance:

	http://www.wss.co.uk/

When you press RETURN a RISC OS save box will appear, with the 'best
guess' at a filename in. To queue the download you simply drag the
data file out to a Filer window. The Savebox will close, and the caret
will return to the URL entry icon.

Alternatively, if you have part of a download already on your harddisc
you can drop this into the save box to continue the download from
where it left off.

In both these cases the new download is added at the bottom of the
list.

Both the URL entry icon and the text icon in the savebox offer a
'history' function; use up and down to move between the previous 10
entries. This means that you can easily queue a series of downloads
whose URLs/Filenames differ only slightly by simply editing the
previous one to match.


The download queue
~~~~~~~~~~~~~~~~~~

The current download queue is shown in the downloads window (obtained
by clicking select on the icon bar icon). Each entry takes 2 lines in
the window, and has several bits of information:

 [Button] [TL] From: [ Source URL           ] [ Bytes so far ]
 [   State   ]  To:  [ Destination Filename ] [ Total size   ]

Of these, the most obvious are the From and To fields; they simply
show the source URL and the destination filename for the download.

The 'bytes so far' field shows how much of the download has arrived,
and the 'total size' (if known) shows how big it will be when it
finally arrives.

'State' shows what the download is doing at the moment; for example,
Ready, Resolving, Connecting, Fetching etc.

The 'TL' is the 'traffic light' indicator. This is the best quick
indicator to the state of the download. Amber means 'Ready to go',
Green means 'Going' and Red means 'Stopped'. All downloads are
initially Amber (although the first one will very quickly go to
Green).

In normal use LoadMaster is smart enough to move the downloads through
the traffic light sequence by itself; all downloads start at amber,
move in turn to green, and either disappear when they are complete, or
end up as red. LoadMaster watches the machine so that when you dial up
(or reconfigure your ethernet card) it will automatically put all the
red downloads back to amber again (so that they can be retried).

On odd occasions you may want to force LoadMaster to do something
different; perhaps to start more than one download at once, or to
stop one in favour of another. This is what the [Button] does.

When the traffic light is amber, the button will say 'Go', and
clicking it will advance the light to green.

When the traffic light is green, the button will say 'Stop', and
clicking it will advance the light to red.

When the traffic light is red, the button will say 'Reset', and
clicking it will advance the light to amber, allowing the download to
be tried in turn again.

By default LoadMaster will never start a new download while there is
already one running; if you want several to run at once you'll either
need to click the download buttons yourself, or tell LoadMaster how
many downloads you think it is reasonable for it to do at the same
time. This is controlled by the settings in the Options window.

If you change your mind about a download, simply click menu (the
middle mouse button) over the download in the list and choose 'Remove'
to remove it.


Using LoadMaster with Browse
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you surf with Browse and find a page containing a link you wish
LoadMaster to download for you, simply click menu on it to bring up a
menu. Move through "File => Link" and drag the save icon to
LoadMaster. The links address will appear in the URL entry window
enabling you to edit it if you require, or to press return for the
save box.


Using LoadMaster with Fresco
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you surf with Fresco and find a page containing a link you wish
LoadMaster to download for you, simply click menu on it to bring up a
menu. Move through "Link => Save as Link" and drag the save icon to
LoadMaster. The links address will appear in the URL entry window
enabling you to edit it if you require, or to press return for the
save box.

Alternatively, if you have a page displayed in Fresco that you wish to
download (perhaps you have started the download in Fresco) simply drag
the Fresco URL display itself to LoadMaster.


Using LoadMaster with Oregano
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you surf with Oregano and find a page containing a link you wish
LoadMaster to download for you, simply click menu on it to bring up a
menu. Move through "File => Save => Link" (or even "File => Object =>
Save Link") and drag the save icon to LoadMaster. The links address
will appear in the URL entry window enabling you to edit it if you
require, or to press return for the save box.


Using LoadMaster with WebsterXL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The authors have not used Webster XL at the time of writing, but they
are informed that WebsterXL does offer a way of saving a link out much
as the other browsers mentioned above do. This being the case simply
save the link to LoadMaster, and either edit it or press return for
the save box.


Known problems
~~~~~~~~~~~~~~

  Proxies:

    Normally LoadMaster only use proxies if informed to in the
    configuration window.
    
    Some ISPs however have 'transparent' proxies that work on any
    access to a 'normally configured' webserver (in particular
    RedHotAnt, Freeserve and NTL are known to operate like that, but
    there are undoubtably many others). While this does not in general
    cause a problem, there can be rare cases when (coupled with poor
    webservers) this can cause LoadMaster to be unable to fetch a
    whole file.

    Some (rare) Webservers are very prone to 'drying up' after sending
    just 100 or 200K of data. LoadMaster works well to retrieve data
    from these servers as it can cope with grabbing them in small
    lumps. If however these servers are coupled with a transparent
    proxy, then the proxy itself can never manage to get the whole
    file served to it - because of this the proxy refuses to serve
    'sections' of a file, and LoadMasters request for a section of the
    file is denied; it is therefore forced to start over each time it
    retries.
    
    There is currently no way around this except to (a) try to use FTP
    rather than HTTP to fetch the files, (b) try to use a different
    ISP, or (c) to find a mirror somewhere else. In practise this
    should be a very rare problem.
    

  Active Server Pages:

    Some pages 'hide' the URLs of the files they offer you so that
    they 'automatically' start downloading. This can be done by
    embedding the details in the HTML itself, or sometimes even by
    using scripting, server-push, or cookie-based techniques.
    
    All of these methods cause problems for LoadMaster because it is
    not an integral part of the browser. These problems can often be
    worked around by loading things from mirror sites, by using FTP
    rather than HTTP, or even by examining the HTML yourself.


  Passworded sites:
  
    LoadMaster doesn't know about any of the passwords that your
    browser does. This means you must tell it explicitly in the URL
    you use. To do this, use the standard URL scheme as below:
    
      http://username:password@hostname/path
      
    for instance:
    
      http://bill:666@gates.microsoft.com/net-worth.txt
      
    or
    
      ftp://pfrancesco:clarice@fbi.org/hannibal-lecter.jpg


Reporting Problems
~~~~~~~~~~~~~~~~~~

If you encounter a bug the first thing to do is to confirm that it
really is a bug - if it is that a given URL will not fetch, then start
a fresh copy of a browser, type the URL in there directly (i.e. do not
arrive at it by navigating through other pages) and then see if the
browser fetches it correctly.

If it does, then you may have found a bug in LoadMaster. Please
send details of the URL to info@wss.co.uk.

It is probably also worth visiting http://www.wss.co.uk/list.html and
signing up to our mailing list to be kept abreast of developments.

If LoadMaster gives an error message or a postmortem, please WRITE IT
DOWN EXACTLY AS IT APPEARS ON THE SCREEN. Telling us that "I did
something and it crashed" is much less likely to get a useful response
than a better documented problem will. Ideally we would like a step by
step guide from a freshly booted machine that causes the application
to crash repeatably, though we appreciate that this is not always
possible.
