# HG changeset patch
# User cmlenz
# Date 1181338844 0
# Node ID dd5c3ba59eae43fb72fa0bc46df5e893fe179314
# Parent  4dcdb1d367ecd0b873370519606f3b108b8ff4aa
Extended the docs a bit.

diff --git a/doc/catalogs.txt b/doc/catalogs.txt
--- a/doc/catalogs.txt
+++ b/doc/catalogs.txt
@@ -165,24 +165,41 @@
 Writing Extraction Methods
 --------------------------
 
-(TODO: write)
-
-
-
-Extended ``Translations`` Class
-===============================
-
-Many web-based applications are composed of a variety of different components
-(possibly using some kind of plugin system), and some of those components may
-provide their own message catalogs that need to be integrated into the larger
-system.
-
-To support this usage pattern, Babel provides a ``Translations`` class that is
-derived from the ``GNUTranslations`` class in the ``gettext`` module. This
-class adds a ``merge()`` method that takes another ``Translations`` instance,
-and merges its contents into the catalog:
+Adding new methods for extracting localizable methods is easy. First, you'll
+need to implement a function that complies with the following interface:
 
 .. code-block:: python
 
-    translations = Translations.load('main')
-    translations.merge(Translations.load('plugin1'))
+    def extract_xxx(fileobj, keywords, options):
+        """Extract messages from XXX files.
+        
+        :param fileobj: the file-like object the messages should be extracted
+                        from
+        :param keywords: a list of keywords (i.e. function names) that should
+                         be recognized as translation functions
+        :param options: a dictionary of additional options (optional)
+        :return: an iterator over ``(lineno, funcname, message)`` tuples
+        :rtype: ``iterator``
+        """
+
+Next, you should register that function as an entry point. This requires your
+``setup.py`` script to use `setuptools`_, and your package to be installed with
+the necessary metadata. If that's taken care of, add something like the
+following to your ``setup.py`` script:
+
+.. code-block:: python
+
+    def setup(...
+
+        entry_points = """
+        [babel.extractors]
+        xxx = your.package:extract_xxx
+        """,
+
+That is, add your extraction method to the entry point group
+``babel.extractors``, where the name of the entry point is the name that people
+will use to reference the extraction method, and the value being the module and
+the name of the function (separated by a colon) implementing the actual
+extraction.
+
+.. _`setuptools`: http://peak.telecommunity.com/DevCenter/setuptools
diff --git a/doc/cmdline.txt b/doc/cmdline.txt
--- a/doc/cmdline.txt
+++ b/doc/cmdline.txt
@@ -23,6 +23,10 @@
       --version             show program's version number and exit
       -h, --help            show this help message and exit
 
+    subcommands:
+      extract   extract messages from source files and generate a POT file
+      init      create new message catalogs from a template
+
 The ``babel`` script provides a number of sub-commands that do the actual work.
 Those sub-commands are described below.
 
@@ -55,3 +59,37 @@
                             set output line width (default 76)
       --no-wrap             do not break long message lines, longer than the
                             output line width, into several lines
+
+
+init
+====
+
+The `init` sub-command creates a new translations catalog based on a PO
+template file::
+
+    $ babel init --help
+    usage: babel init [options] 
+    
+    create new message catalogs from a template
+    
+    options:
+    -h, --help      show this help message and exit
+    -D DOMAIN, --domain=DOMAIN
+                    domain of PO file (defaults to lower-cased project
+                    name)
+    -i INPUT_FILE, --input-file=INPUT_FILE
+                    name of the input file
+    -d OUTPUT_DIR, --output-dir=OUTPUT_DIR
+                    path to output directory
+    -o OUTPUT_FILE, --output-file=OUTPUT_FILE
+                    name of the output file (default
+                    '<output_dir>/<locale>/<domain>.po')
+    -l LOCALE, --locale=LOCALE
+                    locale for the new localized catalog
+    --first-author=FIRST_AUTHOR_NAME
+                    name of first author
+    --first-author-email=FIRST_AUTHOR_EMAIL
+                    email of first author
+    --project-name=NAME   the project name
+    --project-version=VERSION
+                    the project version
diff --git a/doc/index.txt b/doc/index.txt
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -19,12 +19,13 @@
 internationalizing and localizing Python applications, with an
 emphasis on web-based applications.
 
-* `Working with Message Catalogs <catalogs.html>`_
-* `Locale Display Names <display.html>`_
-* `Number and Date Formatting <formatting.html>`_
-* `Command-Line Interface <cmdline.html>`_
-* `Distutils/Setuptools Integration <setup.html>`_
-* `Generated API Documentation <api/index.html>`_
+ * `Working with Message Catalogs <catalogs.html>`_
+ * `Locale Display Names <display.html>`_
+ * `Number and Date Formatting <formatting.html>`_
+ * `Command-Line Interface <cmdline.html>`_
+ * `Distutils/Setuptools Integration <setup.html>`_
+ * `Support Classes and Functions <support.html>`_
+ * `Generated API Documentation <api/index.html>`_
 
 Introduction
 ------------