dosage/doc/dosage.1

.TH DOSAGE 1
.SH NAME
dosage \- comic strip downloader
.SH SYNOPSIS
.B dosage
.RI [ options ]
.I module
.RI [ module .\|.\|.]
.SH DESCRIPTION
.B dosage
is an application designed to keep a local \(oqmirror\(cq of specific
web comics and other picture\-based content, such as
\(oqPicture Of The Day\(cq sites, with a variety of options
for updating and maintaining collections.
.SH OPTIONS
.TP
.BI \-b " PATH" "\fR,\fP \-\^\-basepath=" PATH
Specifies a base path to put comic subdirectories. The default is \(oqComics\(cq.
.TP
.BI \-\^\-baseurl= PATH
Specifies the base URL for output events. The default is a local file URI.
.TP
.BR \-a ", " \-\^\-all
Traverses all available strips backwards from the current one.
This can be useful you want a full collection of a new comic strip,
or update an existing one where files are missing.
.
Catchups can start at a specific image by using the index syntax, see
the
.B INDEX SYNTAX
and
.B SPECIAL SYNTAX
sections for more information. This is useful when you missed some days 
and want only to download the missing files. To make this task easy,
the traversal ends at the first existing image file when starting from
an index (excluding the index itself).
.TP
.BR \-h ", " \-\^\-help
Output brief help information.
.TP
.BR \-l ", " \-\^\-list
List available comic modules in multi\-column fashion.
.TP
.BR \-\^\-singlelist
List available comic modules in single-column fashion.
.TP
.BI \-m " MODULE" "\fR,\fP \-\^\-modulehelp=" MODULE
Output module-specific help for
.IR MODULE .
.TP
.BI \-o " OUTPUT" "\fR,\fP \-\^\-output=" OUTPUT
.I OUTPUT
may be any one of the following:
.PP
.RS
.BR "html " \-
Writes out an HTML file linking to the strips actually downloaded in the
current run, named by date (ala dailystrips). The files can be found in the
\'html' directory of your Comics directory.
.RE
.PP
.RS
.BR "rss " \-
Writes out an RSS feed detailing what strips were downloaded in the last 24
hours. The feed can be found in Comics/dailydose.xml.
.RE
.PP
.RS
.BR "rss " \-
Writes an RSS feed with all of the strips downloaded during the run, for use
with your favourite RSS aggregator.
.RE
.TP
.BR \-p ", " \-\^\-progress
Display a progress bar while downloading comics.
.TP
.BR \-t ", " \-\^\-timestamps
Print timestamps for all output at any level.
.TP
.BR \-v ", " \-\^\-verbose
Increase the output level by one with each occurence.
.TP
.BR \-V ", " \-\^\-version
Display the version number.
.I module
At least one valid
.I module
must be specified. A list of valid modules can be found by passing the
.B \-l
option. Multiple
.I module
arguments can be specified on the command line.
Module names are case insensitive, and it is sufficient to specify a
unique substring of the module name.
.SH INDEX SYNTAX
One can indicate the start of a list of
.B comma seperated
indices using a
.RB \(oq : "\(cq."
.PP
The index format is documented when using the \fB\-\-modulehelp\fP option.
An alternative method is to use an existing filename as index, since images
are always stored in index format.
.SH OFFENSIVE COMICS
Some users may find certain comics offensive and wish to disable them.
Modules listed in
.B /etc/dosage/disabled
and
.B ~/.dosage/disabled
will be disabled. These files should contain only one module name per line.
.SH SPECIAL SYNTAX
.TP
.B @
This expands to mean all the comics currently in your \(oqComics\(cq
directory. All other specified comic module names will be ignored.
.TP
.B @@
This expands to mean all the comics available to Dosage.
.PP
.B INDEX SYNTAX
can not be used with
.B SPECIAL SYNTAX
.
.SH EXAMPLES
Retrieve all Mega Tokyo comics:
.RS
.B dosage \-a megatokyo
.RE
.PP
Retrieve the current comic of Cyanide and Happiness:
.RS
.B dosage cyanideandhappiness
.RE
.PP
Retrieve the current strip of all comics in your \(oqComics\(cq directory:
.RS
.B dosage @
.RE
.PP
Retrieve the current strip of every comic that there is a module for:
.RS
.B dosage @@
.RE
.PP
Retrieve the Penny Arcade strip for a given index:
.RS
.B dosage pennyarcade:2004\-07\-22
.RE
Retrieve Calvin and Hobbes strips from a given index going backwards to
the beginning until an existing file is found:
.RS
.B dosage \-c calvinandhobbes:20120722
.RE
.SH ENVIRONMENT
.IP HTTP_PROXY
.B mainline
will use the specified HTTP proxy whenever possible.
.SH NOTES
Should retrieval fail on any given strip
.B mainline
will attempt to retry. However the retry information is only outputted
in the
.B second
and successive output levels.
.PP
At the time of writing, a
.B complete
Dosage collection weighs in at around 3.0GB.
.SH RETURN VALUE
The return value greater than zero when
.IP \(bu
a program error occurred.
.IP \(bu
comics could not be found or downloaded
.IP \(bu
the program run was aborted with Ctrl-C
.PP
Else the return value is zero.
.SH BUGS
See
.I http://trac.slipgate.za.net/dosage
for a list of current development tasks and suggestions.

.SH FILES
.IP "\fB/etc/dosage/disabled\fR"
Disables comic modules on a global scale.
.IP "\fB~/.dosage/disabled\fR"
Disables comic modules on a local scale.
.SH AUTHORS
Jonathan Jacobs <korpse@slipgate.za.net>
.br
Tristan Seligmann <mithrandi@slipgate.za.net>
.br
Bastian Kleineidam <calvin@users.sourceforge.net>
.SH COPYRIGHT
Copyright \(co 2004-2005 Tristan Seligmann and Jonathan Jacobs
.br
Copyright \(co 2012 Bastian Kleineidam