grabcartoons
------------
Web page: http://grabcartoons.sourceforge.net/

This is the program I use for viewing comics on the web. It's not as
sophisticated as many of the other nice programs out there (check
freshmeat.net, search for "comics" or "strips"), but it does the job
for me. YMMV.

######################################################################
PLEASE NOTE

To avoid depriving free comic web sites of their well-deserved
traffic, grabcartoons does not download the comics to the local
machine. Instead, it creates a page with links to the comics at their
original locations. Therefore, when a page generated by grabcartoons
is viewed, the comics are downloaded from their original pages and not
from local copies. Furthermore, the link to the graphics are extracted
from the comics' web pages, which grabcartoons downloads when it
runs. Finally, each comic in a grabcartoons-generated page is a link
to the original web page.

Grabcartoons is intended for personal use only, not for providing
public access to web comics.

######################################################################


How to install:
---------------

You need to have either:
        LWP::UserAgent and HTTP::Request modules
     or wget in your path (grabcartoons knows how to use it)
     or lynx or some other utility (modify $XTRN_CMD in grabcartoons.pl)

Other than that, you should be able to just run grabcartoons.pl from the
directory where you unpacked the distribution, and it should
automatically find its modules/ directory.

You can also run "make install", after editing the Makefile to check
the value of PREFIX (or run "make install PREFIX=/some/path".

How to use:
-----------

Usage: ./grabcartoons.pl [ option | comic_id ...]

--all     or -a   generate a page with all the known comics on stdout.
--list    or -l   produce a list of the known comic_id's on stdout.
--htmllist        produce HTML list of known comic_id's on stdout.
--file    or -f   read list of comics from specified file.
--write   or -w   write output to specified file instead of stdout.
--version or -V   print version number
--verbose or -v   be verbose
--help    or -h   print help message.

Otherwise, it will produce a page with the given comics on stdout.

Any errors will be included in the generated page.

How to define your own comics:
------------------------------

Subroutines for grabbing comics are defined in the modules/
directory. It also loads any files with .pl extension found in your
$HOME/.grabcartoons/ directory, or on any directories (separated by
colons) contained in the GRABCARTOONS_DIRS environment variable.

A single file can contain more than one subroutine. Each subroutine
must be named get_url_xxx, where xxx is an identifier for the
comic.

Each subroutine must return a three-element array where the first
element is the URL for the image of the current cartoon, the second is
the URL for the main page of the comic (or the one you want linked to
from the image) and the third one is the full name of the comic.

If any of the first two elements is undef, it is considered as an
error, and the string stored in the $err variable is used as an error
message, so you can set it to indicate the source of the error.

If the third return element is undef, the comic's id is used as a
title.

You normally call fetch_url() with the URL to grab, and then examine
it one line at a time using get_line() until you find the pattern that
contains the URL of the image you want. You can also get the full page
(or the rest of the page) as a single string using get_fullpage().

The easiest way is probably to take one of the existing modules (for
example, foxtrot.pl) and base yours on that.

Notes:
------

I developed this program for personal use. If you have any problems,
try looking at the code first. Feel free to email me with any
questions, suggestions or code. I cannot promise any kind of support,
but I would be happy to hear from you if you use grabcartoons.

Contributors:
-------------

Ben Kuperman - first user apart from me, developer and maintainer of
               many modules.

Module contributors: Nick Adams, Alain Brunet, Scott Baker, Yanick. 


Enjoy,
--Diego Zamboni
  zamboni@users.sourceforge.net
