Paginate help on ttys and add examples.

dosage

@@ -7,6 +7,7 @@ from __future__ import print_function
 import sys
 import os
 import argparse
+import pydoc
 from collections import OrderedDict
 
 from dosagelib import events, scraper
@@ -15,16 +16,54 @@ from dosagelib.util import internal_error, getDirname, strlimit
 from dosagelib.ansicolor import get_columns
 from dosagelib.configuration import App, Freeware, Copyright, SupportUrl
 
+
+class ArgumentParser(argparse.ArgumentParser):
+    """Custom argument parser."""
+
+    def print_help(self, file=None):
+        """Paginate help message on TTYs."""
+        msg = self.format_help()
+        if file is None:
+            file = sys.stdout
+        if hasattr(file, "isatty") and file.isatty():
+            pydoc.pager(msg)
+        else:
+            print(msg, file=file)
+
+
+Examples = """\
+EXAMPLES
+List available comics (ca. 3000 at the moment):
+  dosage -l
+
+Get the latest comic of for example CalvinAndHobbes and save it in the "Comics"
+directory:
+  dosage CalvinAndHobbes
+
+If you already have downloaded several comics and want to get the latest
+strips of all of them:
+  dosage --continue @
+
+On Unix, xargs(1) can download several comic strips in parallel,
+for example using up to 4 processes:
+  cd Comics && find . -type d | xargs -n1 -P4 dosage -b . -v
+"""
+
+
 def setupOptions():
     """Construct option parser.
     @return: new option parser
     @rtype argparse.ArgumentParser
     """
-    kwargs = {"description": "A commandline webcomic downloader and archiver."}
+    kwargs = dict(
+        description = "A commandline webcomic downloader and archiver.",
+        epilog = Examples,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
     if sys.argv[0].endswith("mainline"):
         out.warn("the 'mainline' program is deprecated, please use the new 'dosage' program")
         kwargs["prog"] = "dosage"
-    parser = argparse.ArgumentParser(**kwargs)
+    parser = ArgumentParser(**kwargs)
     parser.add_argument('-v', '--verbose', action='count', default=0, help='provides verbose output, use multiple times for more verbosity')
     parser.add_argument('-n', '--numstrips', action='store', type=int, default=0, help='traverse and retrieve the given number of comic strips; use --all to retrieve all comic strips')
     parser.add_argument('-a', '--all', action='store_true', default=None, help='traverse and retrieve all comic strips')