== Dosage ==
-- Contents --
1.0. Introduction
1.1. Dependencies
1.2. Technical Description
1.3. Installation
1.4. Offensive Comics
2.0. Commandline Options
2.1. Special Commandline Characters
2.2. Module Syntax
2.3. Notes
3.0. Extending Dosage
4.0. Reporting Bugs
4.1. Getting Dosage
5.0. Notice
5.1. Copyright
-- 1.0. Introduction --
Dosage is an application designed to keep a local "mirror" of specific web
comics, and other picture-based content such as Picture of the Day sites,
with a variety of options for updating and maintaining comics.
Dosage supports a recursive "catch-up" method, where it traverses a comic
by essentially "visiting" previous comics and picking out the comics.
Dosage is written entirely in Python, and relies on regular expressions to
do most of the grunt work.
-- 1.1. Dependencies --
Dosage is written in Python, and so requires a Python interpreter and the
Python standard libraries.
Dosage is targetted to run on the latest version of Python, but earlier versions will probably work; the older the version, the less likely that it will work. When in doubt, just try it out.
-- 1.2. Technical Description --
Dosage has individual modules, found in the "modules" sub-directory of the
main Dosage directory, which are instantiated and called according to the
specifics of the commandline options and arguments. There are base classes
on which most of the current modules are based on, this eliminates alot
of duplicate code, as there are very few instances where more than a regex
for picking out the previous link and actual comic strip are necessary.
Some comic syndicates (ucomics, etc.) have a very standard layout for all
comics, these have more general base classes which cut out alot of the work
regarding regular expressions and such.
-- 1.3. Installation --
You can invoke Dosage directly from the bin directory. Alternatively,
you can install Dosage using python distutils by invoking setup.py in
the root of the distribution. For example:
python setup.py install
The primary method of using Dosage is via the "mainline" command-line script (previously called "dosage").
### WINDOWS USAGE NOTE ###
Since Windows does not have an executable flag for files, the scripts
have a .py extension appended during the installation process so
that you can invoke them directly. Therefore, in the usage examples
elsewhere, replace "mainline" with "mainline.py" for Windows usage.
-- 1.4. Offensive Comics --
There are some modules in Dosage that may be offensive to sensitive readers.
SexyLosers is one module that has been discussed. Dosage offers a mechanism
to disable such modules. Modules listed in "/etc/dosage/disabled" and
"~/.dosage/disabled" will be disabled. These files should contain only one
module name per line. Note: Under Windows "~" will also expand to the user's
home directory, usually "C:\Documents and Settings\UserName".
-- 2.0. Commandline Options --
There are a number of commandline options for use with Dosage. In a lot of
cases the description given by the help option is insufficient to fully
understand the option. Following are more verbose explanations.
-h, --help:
Display the available commandline options, and a short description for each
one.
-v, --verbose:
Increases the info level used for output. Can be used multiple times
for greater effect.
-q, --quiet:
Decreases the info level used for output; since the default info level is 0,
passing this flag once will suppress essentially all unnecessary output.
-c, --catch-up:
Traverses all available strips until an (identical) existing one is found.
This can be useful if your collection was previously up to date, but you've
missed a few days worth of strips. Alternatively you can use -c twice for a
"full catch up". Catchups can be "resumed" by using the index syntax, see
the notes following the commandline options.
(Note: strips with identical sizes and (local) filenames will not be
overwritten, or re-retrieved.)
-bPATH, --base-path=PATH:
Specifies the base path to put comic subdirectories. The default is "Comics".
--base-url=URL:
Specifies the base URL for output events. The default is a local file URI.
-l, --list:
Lists all available comic modules in multi-column fashion.
--single-list:
Lists all available comic modules in single-column fashion.
-m, --module-help:
Display module-specific help for the modules specified on the
command-line; this includes information like the format of indices.
-t, --timestamps:
Display timestamps to the left of any output, -vv implies -t.
-p, --progress:
Display a progress bar while downloading comics; only tested in Linux,
and definitely non-working in Windows, for the moment.
-oOUTPUT, --output=OUTPUT:
Current options are:
text - Doesn't actually provide any additional output.
html - Writes an HTML file linking to the strips actually downloaded
in the current run, named by date (ala dailystrips). rss - Outputs an RSS feed, for use with your favourite RSS aggregator.
- Notes
- You can download individual strips by index, or start a catchup at a specific index by using indexed syntax: simply suffix the comic module names with comma-seperated lists of strips to retrieve. For example: mainline Blah:123,foo,bar,456 Etc:baz,blam,789
This will retrieve the strips: 123, foo, bar, 456 from the comic "Blah". It will also retrieve the strips: baz, blam, 789 from the comic "Etc". As these indices are comic specific you may want to consider checking the module's help, via the --module-help option, for more information.
Catchup mode is similar, but only the first index passed will actually be used. In either case, if no index is specified, the latest available strip will be used.
-- 2.1. Special Commandline Characters
In previous versions of Dosage there were helper scripts to help users with
simple, but common, tasks. These are not always ideal, as some platforms
(namely Windows) don't have the necessary facilities to make these scripts
worthwhile. Since 0.3.0 these scripts are integrated into Dosage itself, and
are accessible via the comic wildcards "@" and "@@" (without the quotes.)
@ expands to all of the comics present in the specified comic directory, while @@ expands to all of the comics available in Dosage. The most common uses for these wildcards are probably:
mainline -cv @
mainline -cv @@
or similar. The first command will run a catchup on only the comics already in your collection, while the second command is useful for maintaining a full archive of all the comics suported by Dosage.
The comic wildcards can make use of the index syntax too, eg:
mainline -vc @:123
would start a catchup from index 123 for all the comics in the specified comic directory; this is not useful most of the time, however.
-- 2.2. Module Syntax --
Some modules, virtual modules specifically, have a slightly different syntax
to normal modules. Virtual modules use a "/" to indicate the sub-module's
name. eg:
mainline MegaTokyo KeenSpot/SoreThumbs UComics/garfield
The per module help system gives details on index formatting for indexed retrieval, see "2.0 Commandline Options" for more information.
-- 2.3. Notes --
Although Dosage does not have an http-proxy command-line option it will make
use of an "HTTP_PROXY" environment variable. Additionally, in a Windows
environment it will use the proxy server configured in "Internet Settings"
or in a Macintosh environment it will use the proxy server information from
"Internet Config", if no environment variable is set.
-- 3.0. Extending Dosage --
Adding additional modules is a matter of creating a new source file in the
modules sub-directory. Certain modules are "virtual" modules, which act
like a real module except they actually retrieve a number of comics, current
examples of such modules are KeenSpot and UComics. In order to create
totally new modules, please use the already present scripts to base new
modules on, or alternatively suggest them, as mentioned in "4.0 Reporting
Bugs".
-- 4.0. Reporting Bugs --
No project is without its own set of bugs, problems and potential
improvements, should you feel the need to report any of these you can create
a ticket in the Dosage Trac instance available at:
http://trac.slipgate.za.net/dosage
Dosage currently supports a large number of comics and that number grows on a regular basis. If you feel that there are comics that Dosage does not currently support and should be supported, provided they are not already in the list to be supported, please feel free to add them to the Trac instance.
Trac things you should...
- ...add useful comments, like whether the site is a syndicate or not and any other quirks.
- ...make sure that your comic suggestions are created for the relevant component, namely modules.
- ...make sure that your bug report and/or comic suggestions have not already been reported. ...and should not...
- ...create vague tickets. ...do.
-- 4.1. Getting Dosage --
Tarballs of all Dosage releases are available at the website:
Alternatively, if you like living on the bleeding edge, you can check the latest revision out of any of the following darcs repositories:
http://slipgate.za.net/~mithrandi/darcs/dosage http://slipgate.za.net/~korpse/darcs/dosage
For example:
darcs get http://slipgate.za.net/~mithrandi/darcs/dosage
NOTE: Please be aware that at any given time the above darcs repositories may not be identical.
-- 5.0. Notice --
This software is in no way intended to publically "broadcast" comic strips,
it is purely for personal use. Please be aware that by making these strips
publically available (without the explicit permission of the author) you
may be infringing upon various copyrights.
-- 5.1. Copyright --
Dosage Copyright (C) 2004-2005 Jonathan Jacobs and Tristan Seligmann
This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
(A copy of the GNU GPL is included in the file COPYING)