added to project

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

3 files changed, 321 insertions, 0 deletions

diff --git a/docs/api/cmdline-tool.txt b/docs/api/cmdline-tool.txt
new file mode 100644
index 000000000..3d3d4a635
--- /dev/null
+++ b/docs/api/cmdline-tool.txt
@@ -0,0 +1,68 @@
+===============================================
+ Inside A Docutils Command-Line Front-End Tool
+===============================================
+
+:Author: David Goodger
+:Contact: goodger@python.org
+:Date: $Date$
+:Revision: $Revision$
+:Copyright: This document has been placed in the public domain.
+
+`The Docutils Publisher`_ class was set up to make building
+command-line tools easy.  All that's required is to choose components
+and supply settings for variations.  Let's take a look at a typical
+command-line front-end tool, ``tools/rst2html.py``, from top to
+bottom.
+
+On Unixish systems, it's best to make the file executable (``chmod +x
+file``), and supply an interpreter on the first line, the "shebang" or
+"hash-bang" line::
+
+    #!/usr/bin/env python
+
+Windows systems can be set up to associate the Python interpreter with
+the ``.py`` extension.
+
+Next are some comments providing metadata::
+
+    # Author: David Goodger
+    # Contact: goodger@python.org
+    # Revision: $Revision: ...
+    # Date: $Date: ...
+    # Copyright: This module has been placed in the public domain.
+
+The module docstring describes the purpose of the tool::
+
+    """
+    A minimal front end to the Docutils Publisher, producing HTML.
+    """
+
+This next block attempts to invoke locale support for
+internationalization services, specifically text encoding.  It's not
+supported on all platforms though, so it's forgiving::
+
+    try:
+        import locale
+        locale.setlocale(locale.LC_ALL, '')
+    except:
+        pass
+
+The real work will be done by the code that's imported here::
+
+    from docutils.core import publish_cmdline, default_description
+
+We construct a description of the tool, for command-line help::
+
+    description = ('Generates (X)HTML documents from standalone '
+                   'reStructuredText sources.  ' + default_description)
+
+Now we call the Publisher convenience function, which takes over.
+Most of it's defaults are used ("standalone" Reader,
+"reStructuredText" Parser, etc.).  The HTML Writer is chosen by name,
+and a description for command-line help is passed in::
+
+    publish_cmdline(writer_name='html', description=description)
+
+That's it!  `The Docutils Publisher`_ takes care of the rest.
+
+.. _The Docutils Publisher: ./publisher.html
diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt
new file mode 100644
index 000000000..4c7f7831c
--- /dev/null
+++ b/docs/api/publisher.txt
@@ -0,0 +1,73 @@
+========================
+ The Docutils Publisher
+========================
+
+:Author: David Goodger
+:Contact: goodger@python.org
+:Date: $Date$
+:Revision: $Revision$
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+
+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:
+
+* ``publish_cmdline``: for command-line front-end tools, like
+  ``rst2html.py``.  There are several examples in the ``tools/``
+  directory.
+
+* ``publish_file``: for programmatic use with file-like I/O.  In
+  addition to writing the encoded output to a file, also returns the
+  encoded output as a string.
+
+* ``publish_string``: for programmatic use with string I/O.  Returns
+  the encoded output as a string.
+
+* ``publish_parts``: for programmatic use with string input; returns a
+  dictionary of document parts.  Dictionary keys are the names of
+  parts, and values are Unicode strings; encoding is up to the client.
+  Useful when only portions of the processed document are desired.
+  Currently only implemented for the HTML Writer.
+
+  There are examples in the ``docutils/examples.py`` module.
+
+* ``publish_programmatically``: for custom programmatic use.  This
+  function implements common code and is used by ``publish_file``,
+  ``publish_string``, and ``publish_parts``.  It returns a 2-tuple:
+  the encoded string output and the Publisher object.
+
+
+Configuration
+-------------
+
+To pass application-specific setting defaults to the Publisher
+convenience functions, use the ``settings_overrides`` parameter.  Pass
+a dictionary of setting names & values, like this::
+
+    overrides = {'input_encoding': 'ascii',
+                 'output_encoding': 'latin-1'}
+    output = publish_string(..., settings_overrides=overrides)
+
+Settings from command-line options override configuration file
+settings, and they override application defaults.  For details, see
+`Docutils Runtime Settings`_.  See `Docutils Configuration Files`_ for
+details about individual settings.
+
+.. _Docutils Runtime Settings: ./runtime-settings.html
+.. _Docutils Configuration Files: ../user/tools.html
+
+
+Encodings
+---------
+
+The default output encoding of Docutils is UTF-8.  If you have any
+non-ASCII in your text, you may have to do a bit more setup.  Docutils
+may introduce some non-ASCII text if you use symbol-footnotes or
+section numbering.
diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt
new file mode 100644
index 000000000..0f591143d
--- /dev/null
+++ b/docs/api/runtime-settings.txt
@@ -0,0 +1,180 @@
+===========================
+ Docutils Runtime Settings
+===========================
+
+:Author: David Goodger
+:Contact: goodger@python.org
+:Date: $Date$
+:Revision: $Revision$
+:Copyright: This document has been placed in the public domain.
+
+.. contents::
+
+
+Introduction
+============
+
+Docutils runtime settings are assembled from several sources:
+component settings specifications, application settings
+specifications, configuration files, and command-line options.
+Docutils overlays default and explicitly specified values from these
+sources such that settings behave the way we want and expect them to
+behave.
+
+To understand how Docutils deals with runtime settings, the attributes
+and parameters involved must first be understood.  Begin with the the
+docstrings of the attributes of the ``docutils.SettingsSpec`` base
+class (in the ``docutils/__init__.py`` module):
+
+* ``settings_spec``
+* ``settings_defaults``
+* ``settings_default_overrides``
+* ``relative_path_settings``
+* ``config_section``
+* ``config_section_dependencies``
+
+Next, several _`convenience function parameters` are also significant
+(described in the ``docutils.core.publish_programmatically`` function
+docstring):
+
+* ``settings``, if present, is assumed to be complete and no further
+  runtime settings processing is done.
+
+* ``settings_spec`` is treated as a fourth component (after the
+  Parser, Reader, and Writer).
+
+* ``settings_overrides`` is a dictionary which will override the
+  defaults of the components.
+
+* ``config_section`` sets or overrides an application-specific
+  configuration file section.
+
+
+.. _command-line tools:
+
+Runtime Settings Processing for Command-Line Tools
+==================================================
+
+1. A command-line front-end tool imports and calls
+   ``docutils.core.publish_cmdline``.  The relevant _`convenience
+   function parameters` are described above.
+
+2. ``docutils.core.publish_cmdline`` initializes a
+   ``docutils.core.Publisher`` object, then calls its ``publish``
+   method.
+
+3. The ``docutils.core.Publisher`` object's ``publish`` method checks
+   its ``settings`` attribute to see if it's defined.  If it is, no
+   further runtime settings processing is done.
+
+   If no ``settings`` is defined, ``self.process_command_line`` is
+   called with the following relevant arguments:
+
+   * ``settings_spec``
+   * ``config_section``
+   * ``settings_overrides`` (in the form of excess keyword
+     arguments, collected in the ``defaults`` parameter)
+
+4. ``self.process_command_line`` calls ``self.setup_option_parser``,
+   passing ``settings_spec``, ``config_section``, and ``defaults``.
+
+5. ``self.setup_option_parser`` checks its ``config_section``
+   parameter; if defined, it adds that config file section to
+   ``settings_spec`` (or to a new, empty ``docutils.SettingsSpec``
+   object), replacing anything defined earlier.  Then it instantiates
+   a new ``docutils.frontend.OptionParser`` object, passing the
+   following relevant arguments:
+
+   * ``components``: A tuple of ``docutils.SettingsSpec`` objects,
+     ``(self.parser, self.reader, self.writer, settings_spec)``
+   * ``defaults`` (originally from ``settings_overrides``)
+
+6. The ``docutils.frontend.OptionParser`` object's ``__init__`` method
+   calls ``self.populate_from_components`` with ``self.components``,
+   which consists of ``self`` prepended to the ``components`` tuple it
+   received.  ``self`` (``docutils.frontend.OptionParser``) defines
+   general Docutils settings.
+
+7. In ``self.populate_from_components``, for each component passed,
+   ``component.settings_spec`` is processed and
+   ``component.settings_defaults`` is applied.  Then, for each
+   component, ``component.settings_default_overrides`` is applied.
+   This two-loop process ensures that
+   ``component.settings_default_overrides`` can override the default
+   settings of any other component.
+
+8. Back in ``docutils.frontend.OptionParser.__init__``, the
+   ``defaults`` parameter (derived from the ``settings_overrides``
+   parameter of ``docutils.core.Publisher.publish``) is overlaid over
+   ``self.defaults``.  So ``settings_overrides`` has priority over all
+   ``SettingsSpec`` data.
+
+9. Next, ``docutils.frontend.OptionParser.__init__`` checks if
+   configuration files are enabled (its ``read_config_files``
+   parameter is true, and ``self.defaults['_disable_config']`` is
+   false).  If they are enabled (and normally, they are),
+   ``self.get_standard_config_settings`` is called.  This reads the
+   `docutils configuration files`_, and returns a dictionary of
+   settings.  This is then overlaid on ``self.defaults``.  So
+   configuration file settings have priority over all software-defined
+   defaults.
+
+10. Back in the ``docutils.core.Publisher`` object,
+    ``self.setup_option_parser`` returns the ``option_parser`` object
+    to its caller, ``self.process_command_line``.
+
+11. ``self.process_command_line`` calls ``option_parser.parse_args``,
+    which parses all command line options and returns a
+    ``docutils.frontend.Values`` object.  This is assigned to the
+    ``docutils.core.Publisher`` object's ``self.settings``.  So
+    command-line options have priority over configuration file
+    settings.
+
+    When ``option_parser.parse_args`` is called, the source and
+    destination command-line arguments are also parsed, and assigned
+    to the ``_source`` and ``_destination`` attributes of what becomes
+    the ``docutils.core.Publisher`` object's ``self.settings``.
+
+12. From ``docutils.core.Publisher.publish``, ``self.set_io`` is
+    called with no arguments.  If either ``self.source`` or
+    ``self.destination`` are not set, the corresponding
+    ``self.set_source`` and ``self.set_destination`` are called,
+    effectively with no arguments.
+
+13. ``self.set_source`` checks for a ``source_path`` parameter, and if
+    there is none (which is the case for command-line use), it is
+    taken from ``self.settings._source``.  ``self.source`` is set by
+    instantiating a ``self.source_class`` object.  For command-line
+    front-end tools, the default ``self.source_class`` is used,
+    ``docutils.io.FileInput``.
+
+14. ``self.set_destination`` does the same job for the destination
+    that ``self.set_source`` does for the source (the default
+    ``self.destination_class`` is ``docutils.io.FileOutput``).
+
+.. _Docutils Configuration Files: ../user/tools.html
+
+
+Runtime Settings Processing From Applications
+=============================================
+
+Applications process runtime settings in a significantly different way
+than `command-line tools`_ do.  Instead of calling
+``publish_cmdline``, the application calls one of ``publish_file``,
+``publish_string``, or ``publish_parts``.  These in turn call
+``publish_programatically``, which implements a generic programmatic
+interface.  Although an application may also call
+``publish_programatically`` directly, it is not recommended (if it
+does seem to be necessary, please write to the `Docutils-Develop
+mailing list`_).
+
+``publish_programmatically`` accepts the same _`convenience function
+parameters` as ``publish_cmdline``.  Where things differ is that
+programmatic use does not
+
+TO BE COMPLETED.
+
+.. copy & modify the list from command-line tools?
+
+
+.. _Docutils-Develop mailing list: docutils-develop@lists.sf.net