Add documentation

2 files changed, 98 insertions, 0 deletions

diff --git a/bin/comirror b/bin/comirror
index df157cf..4ab8251 100755
--- a/bin/comirror
+++ b/bin/comirror
@@ -123,20 +123,66 @@ __END__
 
 =head1 NAME
 
+B<comirror> - Generic webcomic mirrorer
+
 =head1 SYNOPSIS
 
+B<comirror> [I<comic url>]
+
 =head1 DESCRIPTION
 
+B<comirror> "reads" a webcomic while saving the comic images to the current
+working directory.
+
 =head1 OPTIONS
 
+B<comirror> takes no options.
+
 =head1 EXIT STATUS
 
+Zero if interrupted by the user (eg SIGINT), non-zero if terminating after
+reaching the end of the comic (loop or no "next" link).  So, a non-zero exit
+status is normal.  However, this behaviour may be changed in the near future.
+
 =head1 CONFIGURATION
 
+B<comirror> is designed to operate in the current working directory.  Images
+are saved to it and a few files ard read by B<comirror> as configuration
+parameters.
+
+=over
+
+=item F<image_re>
+
+A regular expression matching the URL of the webcomic image to be saved.
+You can either create the file manually or let it be created by
+comirror-setup(1).
+
+=item F<last_uri>
+
+The URI to the last but one comic site before B<comirror> exited is
+automatically written to this file.  If this file exists and B<comirror> is
+called without arguments, it will automatically resume crawling the webcomic
+from that point on.
+
+=back
+
 =head1 DEPENDENCIES
 
+B<comirror> requires the perl module WWW::Mechanize
+
 =head1 BUGS AND LIMITATIONS
 
+This script has no brain.  It has very limited knowledge about the usual
+layout of a webcomic and makes a few guesses which happen to work in a lot of
+cases.  However, there may well be webcomics which (combined with a
+unrestrictive image_re) lead B<comirror> to crawling lots of non-comic images.
+So of course, use at your own risk.
+
+=head1 SEE ALSO
+
+comirror-setup(1)
+
 =head1 AUTHOR
 
 Copyright (C) 2010 by Daniel Friesel E<lt>derf@chaosdorf.deE<gt>
diff --git a/bin/comirror-setup b/bin/comirror-setup
index b38cfe4..05661bf 100755
--- a/bin/comirror-setup
+++ b/bin/comirror-setup
@@ -98,3 +98,55 @@ line_to_file($image_re, 'image_re');
 print "\nimage_re: ${image_re}\n\n";
 say "\"next\" link text: ${next_link}";
 say "If this is correct, type 'comirror' to start mirroring";
+
+__END__
+
+=head1 NAME
+
+B<comirror-setup> - Set up a directory to be used by B<comirror>
+
+=head1 SYNOPSIS
+
+B<comirror-setup> I<comis urls...>
+
+=head1 DESCRIPTION
+
+B<comirror-setup> takes three URL argumets: The very first page of the web
+comic, the second page, and the last but one page.
+
+Based on these arguments, it tries to set up the current working directory so
+that you only need to call B<comirror> to mirror the webcomic you were
+pointing to.  It does this by comparing the last two URLs to determine a
+correct image_re and then creating last_uri with the first URL so that
+B<comirror> will start at the right point and download the right images.
+
+=head1 OPTIONS
+
+B<comirror-setup> takes no options yet.
+
+=head1 EXIT STATUS
+
+Non-zero on grave errors, zero otherwise.
+
+=head1 CONFIGURATION
+
+B<comirror-setup> is not configurable.
+
+=head1 DEPENDENCIES
+
+This script requires the perl module WWW::Mechanize.
+
+=head1 BUGS AND LIMITATIONS
+
+As with B<comirror> itself: This script has no brain.
+So far, this script is very dumb and fragile.  It's recommended to take a
+quick glance at the image_re before actually calling comirror to make sure you
+get what you want.
+
+=head1 AUTHOR
+
+Copyright (C) @@year@@ by Daniel Friesel E<lt>derf@chaosdorf.deE<gt>
+
+=head1 LICENSE
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.