NAME

       wmget - Background download manager in a dockapp

SYNOPSIS

       wmget dock [options]

       wmget [options] {URL}

       wmget cancel {job-id}

       wmget list

DESCRIPTION

       wmget is a ``dockapp'' which makes it more convenient to retrieve files in the background.
       Dockapps are applications which run in small windows intended to be ``docked''  in  window
       manager-provided  locations.  wmget  was  developed  primarily under GNU Window Maker, the
       author's preferred WM, but is known to work under AfterStep as well, and should work  with
       other dockapp-aware window managers and docks.

       It  uses  the  excellent  libcurl library, part of the Curl automated-download program, to
       perform file retrieval from Web servers, FTP servers, and other sources.

       wmget allows you to perform multiple downloads without keeping a terminal open (for FTP or
       curl or something) or another window on your desktop (e.g. for Mozilla download progress);
       download progress is visible any time the Dock is visible.

       You start downloads either by ``pasting'' URLs from Web browsers or other applications, or
       by  invoking wmget from the command line (or another script or program) with a source URL.
       The dockapp has a handful of configurable download options, such as target directory, HTTP
       proxy server, etc.

STARTING UP

       To start the dockapp, just run wmget dock &. If you are running Window Maker, you can then
       just drag the new appicon onto your Dock, right-click on an area outside the four progress
       bars, select Settings, and select Start when Window Maker is started.

       If you are running AfterStep, you can add it to your Wharf by adding the following line to
       your ~/GNUstep/Library/AfterStep/wharf file:

               *Wharf wmget - Swallow "wmget" wmget dock &

       Other window managers support dockapps in different ways. Even in window managers  without
       any special dockapp support, you can run wmget as noted above; it will simply show up as a
       small window or "icon".

USING WMGET

       wmget's  user  interface  is  simple:  four  stacked  progress  bars,   initially   empty,
       representing  four  possible  simultaneous  downloads. The top bar will say ``wmget'' when
       there isn't a download running there, but any download will cover that up.

       Each running download normally shows up to nine characters of its filename, overlaid  with
       a  progress  bar.  You  can click on any progress bar to reveal a percentage display and a
       stop button; clicking on the percentage display switches back, while clicking on the  stop
       button stops the download. There is currently no confirmation; it just stops.

       You  can  ``request''  downloads  at  any time. If all four places show running downloads,
       additional requests will queue up, waiting for  one  to  complete;  wmget  will  never  be
       downloading more than four files at a time.

       By  default,  wmget  figures out a reasonable filename for any requested downloads, writes
       them to your home directory, and won't overwrite an existing file by the same name. All of
       these, along with a few other options, are configurable. See below.

   Requesting Downloads with the Mouse
       The  easiest  way  to  request a download is by copying and pasting a link. wmget lets you
       paste a URL by middle-clicking anywhere on any of its status bars. Simply copy a link from
       some  other  source  (for  example, by right-clicking on a link in Mozilla or Netscape and
       picking Copy Link Location), and middle-click on one of the progress meter boxes in wmget.

   Requesting Downloads from the Command Line
       The wmget command also lets you directly request downloads from the command line, or  from
       within  a  script  or  another  program.  The syntax is wmget URL, plus any of the options
       documented below.

       Once you run this command, you'll either get an error message or a ``job ID''. The job  ID
       is only useful in conjunction with the wmget cancel command.

   Download Failures
       Downloads  can  fail  for  a  variety  of reasons, from running out of disk space to modem
       hangups. Since wmget is designed not to interrupt  your  workflow  or  exceed  its  little
       square  window,  it responds to any download error by aborting the download and writing an
       error file to your download directory. This error file has the name file.ERROR, where file
       is the name of the actual download target. This error file is a plain text file containing
       information on what you were downloading and what went wrong.

   Viewing and Canceling Downloads
       As noted above, you can see the currently-running downloads in the four progress boxes  on
       the  dockapp.  Clicking  on  a bar reveals a stop button, and clicking on that stop button
       cancels the download (but leaves the partially-downloaded file on your computer).

       At any time, you can also run the wmget list  command,  which  displays  all  the  running
       downloads as well as any queued-up requests. The listing contains entries like this:

              Job 10 [linux-2.6]: 1658544/33073407 RUNNING
              ftp://ftp.kernel.org/pub/linux/kernel/v2.6/linux-2.6.0-test6.tar.bz2
              => /home/aaron/DOWNLOAD/linux-2.6.0-test6.tar.bz2

       What  you  see in that (admittedly dense) listing are the job ID, the name of the download
       as displayed on the dockapp (surrounded in brackets), the progress  in  bytes,  the  total
       bytes  to  download,  the  current  status,  the  source  URL, and the target file on your
       computer. Whew.

       You can cancel any requested or running download from the command line by specifying wmget
       cancel job-id.

COMMAND-LINE OPTIONS AND THE CONFIGURATION FILE

       wmget  supports  a  handful  of  configuration  options.  You can specify defaults for all
       downloads by putting them in a configuration file or adding command-line  options  to  the
       wmget  dock  command  at  startup, or you can specify options for one specific download by
       adding options to the wmget URL command when you request them.  There  isn't  any  way  to
       specify  options on URLs you paste with the mouse. Dockapp command-line arguments override
       config-file settings, and per-URL settings override dockapp settings.

       The configuration file is an optional file named .wmgetrc in your home directory. If  it's
       there,  it's  parsed by the dockapp at startup. The syntax is simple: one option per line,
       all options consisting of a name and possibly a value. Blank lines  are  okay,  and  lines
       starting with # are ignored (so you can disable options easily). Option names are just the
       same as the command-line option names  given  below,  except  you  don't  put  the  dashes
       (``--'') and you can't use the one-letter abbreviations.

       --version, -v
              Regardless  of any other options, this prints out version and copyright information
              and exits.

       --help, -h
              Regardless of any other options, this prints out a help message and exits.

       --silent, -s
              Suppress any output text other than error messages.

       --verbose, -V
              Write extra debugging information; not  very  useful  unless  you're  debugging  or
              extending the software.

       --output pathname, -o pathname
              Specifies  where  to  write  downloaded files. In the config file or on the dockapp
              command line, this can only be used to specify your default download directory;  it
              must  be  an  existing directory, and if it's not absolute then it is assumed to be
              relative to your home directory. On a specific download request, this  can  provide
              an  alternate  save  directory  or  even  an  alternate  filename;  in that case, a
              non-absolute path is relative to the default download directory.

       --display name, -d name
              Display the first nine characters of name in the progress display  for  this  file.
              (Only  valid  on  specific  download  requests, not on the dockapp or in the config
              file.)

       --overwrite, -O
              Allow wmget to overwrite an existing  file  when  downloading.  Normally,  it  will
              refuse to do so.

       --continue, -C
              When  fetching  a  file  that  already exists locally, assume the local copy was an
              aborted download and try to download just the remainder.

       --auth username:password, -a username:password
              Provides login information for the server from which you're downloading.

       --proxy server:port, -p server:port, --proxy_auth user:password, -P user:password
              Specifies a proxy server and optionally a proxy-server username/password  pair  for
              getting past firewalls.

       --follow N, -f N
              Specifies  how  many  HTTP  redirects  to follow when resolving a page; by default,
              wmget is configured to follow up to 5. Set this to 0 to  disable  redirection.  (In
              any real-world situation, if you're getting redirected more than 5 times, there's a
              problem...)

       --user-agent string, -U string
              Specifies which User-Agent string  to  provide  to  servers  when  performing  HTTP
              downloads. The default User-Agent names both the wmget and libcurl versions in use.

       --ascii, -B
              Force  FTP  downloads  to use ASCII mode; normally, they use binary mode. If you're
              downloading text documents, ASCII mode will take care of any necessary  conversions
              between the text formats of the server and your computer.

       --referer string, -e string
              Provides a ``referer'' string to the Web server.

       --interface interface, --n interface
              Names  a  specific  network  interface  to  use  (e.g., eth0 for the first Ethernet
              interface on a Linux system). Rarely needed.

       --headers, -h
              When performing an HTTP retrieval, include the HTTP message  header  in  the  saved
              file. This is only really useful for testing.

FILES

       ~/.wmgetrc
              The  (optional) configuration file for the wmget dockapp. Settings in this file are
              used to specify defaults for the  dockapp  when  it  starts;  see  the  section  on
              configuration and command-line options for more details.

       ~/.wmget.iq
              A  Unix-domain  socket  created  by the wmget dockapp to accept requests from wmget
              commands. Created at startup automatically.

AUTHOR

       Aaron Trickey.