Updated manpage.

This commit is contained in:
Bastian Kleineidam 2012-10-11 14:17:10 +02:00
parent 6319773cb9
commit 87061d1fa6
3 changed files with 143 additions and 107 deletions

9
doc/Makefile Normal file
View file

@ -0,0 +1,9 @@
MANFILES:=dosage.1.html
man: $(MANFILES)
dosage.1.html: dosage.1
man2html -r $< | tail -n +2 | sed 's/Time:.*//g' | sed 's@/:@/@g' > $@
# patch --no-backup-if-mismatch --quiet $@ dosage.1.html.diff
.PHONY: all man

View file

@ -1,37 +1,39 @@
.TH MAINLINE 1 .TH DOSAGE 1
.SH NAME .SH NAME
mainline \- command line interface to Dosage dosage \- comic strip downloader
.SH SYNOPSIS .SH SYNOPSIS
.B mainline .B dosage
.RI [ options ] .RI [ options ]
.I module .I module
.RI [ module .\|.\|.] .RI [ module .\|.\|.]
.SH DESCRIPTION .SH DESCRIPTION
.B mainline .B dosage
is a command line interface to Dosage. Dosage is a an application designed is an application designed to keep a local \(oqmirror\(cq of specific
to keep a local \(oqmirror\(cq of specific web comics and other picture\-based web comics and other picture\-based content, such as
content, such as \(oqPicture Of The Day\(cq sites, with a variety of options \(oqPicture Of The Day\(cq sites, with a variety of options
for updating and maintaining collections. for updating and maintaining collections.
.SH OPTIONS .SH OPTIONS
.TP .TP
.BI \-b " PATH" "\fR,\fP \-\^\-base\--path=" PATH .BI \-b " PATH" "\fR,\fP \-\^\-basepath=" PATH
Specifies a base path to put comic subdirectories. The default is \(oqComics\(cq. Specifies a base path to put comic subdirectories. The default is \(oqComics\(cq.
.TP .TP
.BI \-\^\-base\-url= PATH .BI \-\^\-baseurl= PATH
Specifies the base URL for output events. The default is a local file URI. Specifies the base URL for output events. The default is a local file URI.
.TP .TP
.BR \-c ", " \-\^\-catch-up .BR \-a ", " \-\^\-all
Traverses all available strips until an (identical) existing one is found. Traverses all available strips backwards from the current one.
This can be useful if your collection was previously up to date, This can be useful you want a full collection of a new comic strip,
but you've missed a few days worth of strips. Alternatively you can specify or update an existing one where files are missing.
.B \-c .
twice for a \(oqfull catchup\(cq, which will not stop until all comics Catchups can start at a specific image by using the index syntax, see
have been traversed. Catchups can \(oqresumed\(cq by using the index syntax, see
the the
.B INDEX SYNTAX .B INDEX SYNTAX
and and
.B SPECIAL SYNTAX .B SPECIAL SYNTAX
sections for more information. 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 .TP
.BR \-h ", " \-\^\-help .BR \-h ", " \-\^\-help
Output brief help information. Output brief help information.
@ -39,10 +41,10 @@ Output brief help information.
.BR \-l ", " \-\^\-list .BR \-l ", " \-\^\-list
List available comic modules in multi\-column fashion. List available comic modules in multi\-column fashion.
.TP .TP
.BR \-\^\-single\-list .BR \-\^\-singlelist
List available comic modules in single-column fashion. List available comic modules in single-column fashion.
.TP .TP
.BI \-m " MODULE" "\fR,\fP \-\^\-module-help=" MODULE .BI \-m " MODULE" "\fR,\fP \-\^\-modulehelp=" MODULE
Output module-specific help for Output module-specific help for
.IR MODULE . .IR MODULE .
.TP .TP
@ -51,11 +53,6 @@ Output module-specific help for
may be any one of the following: may be any one of the following:
.PP .PP
.RS .RS
.BR "text " \-
Provides no additional output and is the default value.
.RE
.PP
.RS
.BR "html " \- .BR "html " \-
Writes out an HTML file linking to the strips actually downloaded in the 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 current run, named by date (ala dailystrips). The files can be found in the
@ -93,20 +90,17 @@ must be specified. A list of valid modules can be found by passing the
option. Multiple option. Multiple
.I module .I module
arguments can be specified on the command line. 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 .SH INDEX SYNTAX
One can indicate the start of a list of One can indicate the start of a list of
.B comma seperated .B comma seperated
indices using a indices using a
.RB \(oq : "\(cq." .RB \(oq : "\(cq."
.PP .PP
If The index format is documented when using the \fB\-\-modulehelp\fP option.
.I \-c An alternative method is to use an existing filename as index, since images
is specified with index syntax then \(oqresume\(cq mode is activated, are always stored in index format.
where a \(oqcatchup\(cq will start at the given index.
.PP
Refer to
.B EXAMPLES
for samples.
.SH OFFENSIVE COMICS .SH OFFENSIVE COMICS
Some users may find certain comics offensive and wish to disable them. Some users may find certain comics offensive and wish to disable them.
Modules listed in Modules listed in
@ -118,30 +112,44 @@ will be disabled. These files should contain only one module name per line.
.TP .TP
.B @ .B @
This expands to mean all the comics currently in your \(oqComics\(cq This expands to mean all the comics currently in your \(oqComics\(cq
directory. directory. All other specified comic module names will be ignored.
.TP .TP
.B @@ .B @@
This expands to mean all the comics available to Dosage. This expands to mean all the comics available to Dosage.
.PP .PP
.B INDEX SYNTAX .B INDEX SYNTAX
can be used with can not be used with
.B SPECIAL SYNTAX .B SPECIAL SYNTAX
but this is unlikely to be useful. .
.SH EXAMPLES .SH EXAMPLES
Retrieve the latest Mega Tokyo comic: Retrieve all Mega Tokyo comics:
.RS .RS
.B mainline MegaTokyo .B dosage \-a megatokyo
.RE .RE
.PP .PP
Retrieve every strip from every comic that there is a module for: Retrieve the current comic of Cyanide and Happiness:
.RS .RS
.B mainline \-c @@ .B dosage cyanideandhappiness
.RE .RE
.PP .PP
Retrieve all Penny Arcade strips from (and including) a given index to Retrieve the current strip of all comics in your \(oqComics\(cq directory:
the beginning regardless of whether they already exist or not:
.RS .RS
.B mainline \-c PennyArcade:2004\-07\-22 .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 .RE
.SH ENVIRONMENT .SH ENVIRONMENT
.IP HTTP_PROXY .IP HTTP_PROXY
@ -159,11 +167,9 @@ At the time of writing, a
.B complete .B complete
Dosage collection weighs in at around 3.0GB. Dosage collection weighs in at around 3.0GB.
.SH RETURN VALUE .SH RETURN VALUE
The return value is 2 when The return value greater than zero when
.IP \(bu .IP \(bu
a program error occurred. a program error occurred.
.PP
The return value is 1 when
.IP \(bu .IP \(bu
comics could not be found or downloaded comics could not be found or downloaded
.IP \(bu .IP \(bu
@ -174,12 +180,19 @@ Else the return value is zero.
See See
.I http://trac.slipgate.za.net/dosage .I http://trac.slipgate.za.net/dosage
for a list of current development tasks and suggestions. for a list of current development tasks and suggestions.
.SH FILES .SH FILES
.IP "\fB/etc/dosage/disabled\fR" .IP "\fB/etc/dosage/disabled\fR"
Disables comic modules on a global scale. Disables comic modules on a global scale.
.IP "\fB~/.dosage/disabled\fR" .IP "\fB~/.dosage/disabled\fR"
Disables comic modules on a local scale. Disables comic modules on a local scale.
.SH AUTHORS .SH AUTHORS
.BR mainline " and " Dosage Jonathan Jacobs <korpse@slipgate.za.net>
were written by Jonathan Jacobs <korpse@slipgate.za.net> and Tristan Seligmann .br
<mithrandi@slipgate.za.net>. This manual page was written by Jonathan Jacobs. 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

View file

@ -1,19 +1,19 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of MAINLINE</TITLE> <HTML><HEAD><TITLE>Man page of DOSAGE</TITLE>
</HEAD><BODY> </HEAD><BODY>
<H1>MAINLINE</H1> <H1>DOSAGE</H1>
Section: User Commands (1)<BR><A HREF="#index">Index</A> Section: User Commands (1)<BR><A HREF="#index">Index</A>
<A HREF="../index.html">Return to Main Contents</A><HR> <A HREF="../index.html">Return to Main Contents</A><HR>
<A NAME="lbAB">&nbsp;</A> <A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2> <H2>NAME</H2>
mainline - command line interface to Dosage dosage - comic strip downloader
<A NAME="lbAC">&nbsp;</A> <A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2> <H2>SYNOPSIS</H2>
<B>mainline</B> <B>dosage</B>
[<I>options</I>] [<I>options</I>]
@ -24,41 +24,41 @@ mainline - command line interface to Dosage
<A NAME="lbAD">&nbsp;</A> <A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2> <H2>DESCRIPTION</H2>
<B>mainline</B> <B>dosage</B>
is a command line interface to Dosage. Dosage is a an application designed is an application designed to keep a local 'mirror' of specific
to keep a local 'mirror' of specific web comics and other picture-based web comics and other picture-based content, such as
content, such as 'Picture Of The Day' sites, with a variety of options 'Picture Of The Day' sites, with a variety of options
for updating and maintaining collections. for updating and maintaining collections.
<A NAME="lbAE">&nbsp;</A> <A NAME="lbAE">&nbsp;</A>
<H2>OPTIONS</H2> <H2>OPTIONS</H2>
<DL COMPACT> <DL COMPACT>
<DT><B>-b</B><I> PATH</I><B></B>, --base--path=<I>PATH</I> <DT><B>-b</B><I> PATH</I><B></B>, --basepath=<I>PATH</I>
<DD> <DD>
Specifies a base path to put comic subdirectories. The default is 'Comics'. Specifies a base path to put comic subdirectories. The default is 'Comics'.
<DT><B>--base-url=</B><I>PATH</I> <DT><B>--baseurl=</B><I>PATH</I>
<DD> <DD>
Specifies the base URL for output events. The default is a local file URI. Specifies the base URL for output events. The default is a local file URI.
<DT><B>-c</B>, <B>--catch-up</B> <DT><B>-a</B>, <B>--all</B>
<DD> <DD>
Traverses all available strips until an (identical) existing one is found. Traverses all available strips backwards from the current one.
This can be useful if your collection was previously up to date, This can be useful you want a full collection of a new comic strip,
but you've missed a few days worth of strips. Alternatively you can specify or update an existing one where files are missing.
<B>-c</B> Catchups can start at a specific image by using the index syntax, see
twice for a 'full catchup', which will not stop until all comics
have been traversed. Catchups can 'resumed' by using the index syntax, see
the the
<B>INDEX SYNTAX</B> <B>INDEX SYNTAX</B>
and and
<B>SPECIAL SYNTAX</B> <B>SPECIAL SYNTAX</B>
sections for more information. 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).
<DT><B>-h</B>, <B>--help</B> <DT><B>-h</B>, <B>--help</B>
<DD> <DD>
@ -67,11 +67,11 @@ Output brief help information.
<DD> <DD>
List available comic modules in multi-column fashion. List available comic modules in multi-column fashion.
<DT><B>--single-list</B> <DT><B>--singlelist</B>
<DD> <DD>
List available comic modules in single-column fashion. List available comic modules in single-column fashion.
<DT><B>-m</B><I> MODULE</I><B></B>, --module-help=<I>MODULE</I> <DT><B>-m</B><I> MODULE</I><B></B>, --modulehelp=<I>MODULE</I>
<DD> <DD>
Output module-specific help for Output module-specific help for
@ -86,14 +86,6 @@ may be any one of the following:
</DL> </DL>
<P> <P>
<DL COMPACT><DT><DD>
<B>text </B>-
Provides no additional output and is the default value.
</DL>
<P>
<DL COMPACT><DT><DD> <DL COMPACT><DT><DD>
<B>html </B>- <B>html </B>-
@ -149,6 +141,8 @@ option. Multiple
<I>module</I> <I>module</I>
arguments can be specified on the command line. 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.
</DL> </DL>
<A NAME="lbAF">&nbsp;</A> <A NAME="lbAF">&nbsp;</A>
<H2>INDEX SYNTAX</H2> <H2>INDEX SYNTAX</H2>
@ -161,17 +155,9 @@ indices using a
<P> <P>
If The index format is documented when using the <B>--modulehelp</B> option.
<I>-c</I> An alternative method is to use an existing filename as index, since images
are always stored in index format.
is specified with index syntax then 'resume' mode is activated,
where a 'catchup' will start at the given index.
<P>
Refer to
<B>EXAMPLES</B>
for samples.
<A NAME="lbAG">&nbsp;</A> <A NAME="lbAG">&nbsp;</A>
<H2>OFFENSIVE COMICS</H2> <H2>OFFENSIVE COMICS</H2>
@ -191,7 +177,7 @@ will be disabled. These files should contain only one module name per line.
<DD> <DD>
This expands to mean all the comics currently in your 'Comics' This expands to mean all the comics currently in your 'Comics'
directory. directory. All other specified comic module names will be ignored.
<DT><B>@@</B> <DT><B>@@</B>
<DD> <DD>
@ -201,33 +187,54 @@ This expands to mean all the comics available to Dosage.
<B>INDEX SYNTAX</B> <B>INDEX SYNTAX</B>
can be used with can not be used with
<B>SPECIAL SYNTAX</B> <B>SPECIAL SYNTAX</B>
but this is unlikely to be useful.
<A NAME="lbAI">&nbsp;</A> <A NAME="lbAI">&nbsp;</A>
<H2>EXAMPLES</H2> <H2>EXAMPLES</H2>
Retrieve the latest Mega Tokyo comic: Retrieve all Mega Tokyo comics:
<DL COMPACT><DT><DD> <DL COMPACT><DT><DD>
<B>mainline MegaTokyo</B> <B>dosage -a megatokyo</B>
</DL> </DL>
<P> <P>
Retrieve every strip from every comic that there is a module for: Retrieve the current comic of Cyanide and Happiness:
<DL COMPACT><DT><DD> <DL COMPACT><DT><DD>
<B>mainline -c @@</B> <B>dosage cyanideandhappiness</B>
</DL> </DL>
<P> <P>
Retrieve all Penny Arcade strips from (and including) a given index to Retrieve the current strip of all comics in your 'Comics' directory:
the beginning regardless of whether they already exist or not:
<DL COMPACT><DT><DD> <DL COMPACT><DT><DD>
<B>mainline -c PennyArcade:2004-07-22</B> <B>dosage @</B>
</DL>
<P>
Retrieve the current strip of every comic that there is a module for:
<DL COMPACT><DT><DD>
<B>dosage @@</B>
</DL>
<P>
Retrieve the Penny Arcade strip for a given index:
<DL COMPACT><DT><DD>
<B>dosage pennyarcade:2004-07-22</B>
</DL>
Retrieve Calvin and Hobbes strips from a given index going backwards to
the beginning until an existing file is found:
<DL COMPACT><DT><DD>
<B>dosage -c calvinandhobbes:20120722</B>
</DL> </DL>
@ -260,15 +267,10 @@ Dosage collection weighs in at around 3.0GB.
<A NAME="lbAL">&nbsp;</A> <A NAME="lbAL">&nbsp;</A>
<H2>RETURN VALUE</H2> <H2>RETURN VALUE</H2>
The return value is 2 when The return value greater than zero when
<DL COMPACT> <DL COMPACT>
<DT>&bull;<DD> <DT>&bull;<DD>
a program error occurred. a program error occurred.
</DL>
<P>
The return value is 1 when
<DL COMPACT>
<DT>&bull;<DD> <DT>&bull;<DD>
comics could not be found or downloaded comics could not be found or downloaded
<DT>&bull;<DD> <DT>&bull;<DD>
@ -284,6 +286,7 @@ See
<I><A HREF="http://trac.slipgate.za.net/dosage">http://trac.slipgate.za.net/dosage</A></I> <I><A HREF="http://trac.slipgate.za.net/dosage">http://trac.slipgate.za.net/dosage</A></I>
for a list of current development tasks and suggestions. for a list of current development tasks and suggestions.
<P>
<A NAME="lbAN">&nbsp;</A> <A NAME="lbAN">&nbsp;</A>
<H2>FILES</H2> <H2>FILES</H2>
@ -296,10 +299,20 @@ Disables comic modules on a local scale.
<A NAME="lbAO">&nbsp;</A> <A NAME="lbAO">&nbsp;</A>
<H2>AUTHORS</H2> <H2>AUTHORS</H2>
<B>mainline</B> and <B>Dosage</B> Jonathan Jacobs &lt;<A HREF="mailto:korpse@slipgate.za.net">korpse@slipgate.za.net</A>&gt;
<BR>
were written by Jonathan Jacobs &lt;<A HREF="mailto:korpse@slipgate.za.net">korpse@slipgate.za.net</A>&gt; and Tristan Seligmann Tristan Seligmann &lt;<A HREF="mailto:mithrandi@slipgate.za.net">mithrandi@slipgate.za.net</A>&gt;
&lt;<A HREF="mailto:mithrandi@slipgate.za.net">mithrandi@slipgate.za.net</A>&gt;. This manual page was written by Jonathan Jacobs. <BR>
Bastian Kleineidam &lt;<A HREF="mailto:calvin@users.sourceforge.net">calvin@users.sourceforge.net</A>&gt;
<A NAME="lbAP">&nbsp;</A>
<H2>COPYRIGHT</H2>
Copyright &#169; 2004-2005 Tristan Seligmann and Jonathan Jacobs
<BR>
Copyright &#169; 2012 Bastian Kleineidam
<P> <P>
<HR> <HR>
@ -319,6 +332,7 @@ were written by Jonathan Jacobs &lt;<A HREF="mailto:korpse@slipgate.za.net">korp
<DT><A HREF="#lbAM">BUGS</A><DD> <DT><A HREF="#lbAM">BUGS</A><DD>
<DT><A HREF="#lbAN">FILES</A><DD> <DT><A HREF="#lbAN">FILES</A><DD>
<DT><A HREF="#lbAO">AUTHORS</A><DD> <DT><A HREF="#lbAO">AUTHORS</A><DD>
<DT><A HREF="#lbAP">COPYRIGHT</A><DD>
</DL> </DL>
<HR> <HR>
This document was created by This document was created by