added intro

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@5547 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 17 insertions, 2 deletions

diff --git a/docutils/docs/api/publisher.txt b/docutils/docs/api/publisher.txt
index f07ba6401..8974b597c 100644
--- a/docutils/docs/api/publisher.txt
+++ b/docutils/docs/api/publisher.txt
@@ -11,13 +11,28 @@
 .. contents::
 
 
+The ``docutils.core.Publisher`` class is the core of Docutils,
+managing all the processing and relationships between components.  See
+`PEP 258`_ for an overview of Docutils components.
+
+The ``docutils.core.publish_*`` convenience functions are the normal
+entry points for using Docutils as a library.
+
+See `Inside A Docutils Command-Line Front-End Tool`_ for an overview
+of a typical Docutils front-end tool, including how the Publisher
+class is used.
+
+.. _PEP 258: ../peps/pep-0258.html
+.. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html
+
+
 Publisher Convenience Functions
 ===============================
 
 Each of these functions set up a ``docutils.core.Publisher`` object,
 then call its ``publish`` method.  ``docutils.core.Publisher.publish``
-handles everything else.  There are five convenience functions in the
-``docutils.core`` module:
+handles everything else.  There are several convenience functions in
+the ``docutils.core`` module:
 
 :_`publish_cmdline`: for command-line front-end tools, like
   ``rst2html.py``.  There are several examples in the ``tools/``