493 lines
17 KiB
XML
493 lines
17 KiB
XML
<?xml version="1.0" standalone="no"?>
|
|
<?xml-stylesheet
|
|
href="http://docbook.sourceforge.net/release/xsl/1.62/manpages/docbook.xsl"
|
|
type="text/xsl"?>
|
|
<!--
|
|
<!DOCTYPE refentry
|
|
PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<!DOCTYPE refentry
|
|
PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"/usr/local/docbook/docbookx.dtd">
|
|
-->
|
|
|
|
<!DOCTYPE refentry
|
|
PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">
|
|
|
|
<refentry>
|
|
<refentryinfo>
|
|
<author>
|
|
<firstname>Aaron</firstname><surname>Trickey</surname>
|
|
<email>aaron@amtrickey.net</email>
|
|
</author>
|
|
<copyright>
|
|
<year>2001</year>
|
|
<year>2002</year>
|
|
<year>2003</year>
|
|
<holder>Aaron Trickey</holder>
|
|
</copyright>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>wmget</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>wmget</refname>
|
|
<refpurpose>Background download manager in a dockapp</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>wmget</command>
|
|
<arg choice="plain">dock</arg>
|
|
<arg choice="opt"><replaceable>options</replaceable></arg>
|
|
</cmdsynopsis>
|
|
<cmdsynopsis>
|
|
<command>wmget</command>
|
|
<arg choice="opt"><replaceable>options</replaceable></arg>
|
|
<arg choice="req"><replaceable>URL</replaceable></arg>
|
|
</cmdsynopsis>
|
|
<cmdsynopsis>
|
|
<command>wmget</command>
|
|
<arg choice="plain">cancel</arg>
|
|
<arg choice="req"><replaceable>job-id</replaceable></arg>
|
|
</cmdsynopsis>
|
|
<cmdsynopsis>
|
|
<command>wmget</command>
|
|
<arg choice="plain">list</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Starting Up</title>
|
|
<para>
|
|
To start the dockapp, just run <command>wmget dock
|
|
&</command>. 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
|
|
<guimenuitem>Settings</guimenuitem>, and select <guilabel>Start
|
|
when Window Maker is started</guilabel>.
|
|
</para>
|
|
|
|
<para>
|
|
If you are running AfterStep, you can add it to your Wharf by
|
|
adding the following line to your
|
|
<filename>~/GNUstep/Library/AfterStep/wharf</filename> file:
|
|
</para>
|
|
|
|
<informalfigure>
|
|
<programlisting>
|
|
*Wharf wmget - Swallow "wmget" wmget dock &
|
|
</programlisting>
|
|
</informalfigure>
|
|
|
|
<para>
|
|
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".
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Using wmget</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<refsect2>
|
|
<title>Requesting Downloads with the Mouse</title>
|
|
<para>
|
|
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 <guimenuitem>Copy Link
|
|
Location</guimenuitem>), and middle-click on one of the progress
|
|
meter boxes in wmget.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Requesting Downloads from the Command Line</title>
|
|
<para>
|
|
The <command>wmget</command> command also lets you directly
|
|
request downloads from the command line, or from within a script
|
|
or another program. The syntax is <command>wmget
|
|
<replaceable>URL</replaceable></command>, plus any of the
|
|
options documented below.
|
|
</para>
|
|
<para>
|
|
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
|
|
<command>wmget cancel</command> command.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Download Failures</title>
|
|
<para>
|
|
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 <filename>file.ERROR</filename>, where
|
|
<filename>file</filename> 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.
|
|
</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Viewing and Canceling Downloads</title>
|
|
<para>
|
|
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).
|
|
</para>
|
|
<para>
|
|
At any time, you can also run the <command>wmget list</command>
|
|
command, which displays all the running downloads as well as any
|
|
queued-up requests. The listing contains entries like this:
|
|
</para>
|
|
<informalfigure><screen
|
|
>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
|
|
</screen></informalfigure>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
You can cancel any requested or running download from the
|
|
command line by specifying <command>wmget cancel
|
|
<replaceable>job-id</replaceable></command>.
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Command-Line Options and the Configuration File</title>
|
|
<para>
|
|
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
|
|
<command>wmget dock</command> command at startup, or you can
|
|
specify options for one specific download by adding options to the
|
|
<command>wmget <replaceable>URL</replaceable></command> 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.
|
|
</para>
|
|
<para>
|
|
The configuration file is an optional file named
|
|
<filename>.wmgetrc</filename> 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.
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>--version</term>
|
|
<term>-v</term>
|
|
<listitem>
|
|
<para>
|
|
Regardless of any other options, this prints out version and
|
|
copyright information and exits.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--help</term>
|
|
<term>-h</term>
|
|
<listitem>
|
|
<para>
|
|
Regardless of any other options, this prints out a help
|
|
message and exits.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--silent</term>
|
|
<term>-s</term>
|
|
<listitem>
|
|
<para>
|
|
Suppress any output text other than error messages.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--verbose</term>
|
|
<term>-V</term>
|
|
<listitem>
|
|
<para>
|
|
Write extra debugging information; not very useful unless
|
|
you're debugging or extending the software.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--output <replaceable>pathname</replaceable></term>
|
|
<term>-o <replaceable>pathname</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--display <replaceable>name</replaceable></term>
|
|
<term>-d <replaceable>name</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Display the first nine characters of
|
|
<replaceable>name</replaceable> in the progress display for
|
|
this file.
|
|
(Only valid on specific download requests, not on the
|
|
dockapp or in the config file.)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--overwrite</term>
|
|
<term>-O</term>
|
|
<listitem>
|
|
<para>
|
|
Allow wmget to overwrite an existing file when downloading.
|
|
Normally, it will refuse to do so.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--continue</term>
|
|
<term>-C</term>
|
|
<listitem>
|
|
<para>
|
|
When fetching a file that already exists locally, assume the
|
|
local copy was an aborted download and try to download just
|
|
the remainder.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--auth <replaceable>username</replaceable>:<replaceable>password</replaceable></term>
|
|
<term>-a <replaceable>username</replaceable>:<replaceable>password</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Provides login information for the server from which you're
|
|
downloading.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--proxy
|
|
<replaceable>server</replaceable>:<replaceable>port</replaceable>
|
|
</term>
|
|
<term>-p
|
|
<replaceable>server</replaceable>:<replaceable>port</replaceable>
|
|
</term>
|
|
<term>--proxy_auth
|
|
<replaceable>user</replaceable>:<replaceable>password</replaceable>
|
|
</term>
|
|
<term>-P
|
|
<replaceable>user</replaceable>:<replaceable>password</replaceable>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a proxy server and optionally a proxy-server
|
|
username/password pair for getting past firewalls.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--follow <replaceable>N</replaceable></term>
|
|
<term>-f <replaceable>N</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
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...)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--user-agent <replaceable>string</replaceable></term>
|
|
<term>-U <replaceable>string</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--ascii</term>
|
|
<term>-B</term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--referer <replaceable>string</replaceable></term>
|
|
<term>-e <replaceable>string</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Provides a ``referer'' string to the Web server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--interface <replaceable>interface</replaceable></term>
|
|
<term>--n <replaceable>interface</replaceable></term>
|
|
<listitem>
|
|
<para>
|
|
Names a specific network interface to use (e.g., eth0 for
|
|
the first Ethernet interface on a Linux system). Rarely
|
|
needed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>--headers</term>
|
|
<term>-h</term>
|
|
<listitem>
|
|
<para>
|
|
When performing an HTTP retrieval, include the HTTP message
|
|
header in the saved file. This is only really useful for
|
|
testing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Files</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><filename>~/.wmgetrc</filename></term>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><filename>~/.wmget.iq</filename></term>
|
|
<listitem>
|
|
<para>
|
|
A Unix-domain socket created by the wmget dockapp to accept
|
|
requests from wmget commands. Created at startup
|
|
automatically.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|