== 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:

    http://slipgate.za.net/dosage
    
  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)
