Update the Runtime Settings API documentation.

Update API documentation.

Split implementation details into a separate document
for core developers.

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

3 files changed, 518 insertions, 184 deletions

diff --git a/docutils/docs/api/publisher.txt b/docutils/docs/api/publisher.txt
index a747c60ee..1d6ad5287 100644
--- a/docutils/docs/api/publisher.txt
+++ b/docutils/docs/api/publisher.txt
@@ -34,36 +34,36 @@ then call its ``publish`` method.  ``docutils.core.Publisher.publish``
 handles everything else.  There are several convenience functions in
 the ``docutils.core`` module:
 
-:_`publish_cmdline`: for command-line front-end tools, like
+:_`publish_cmdline()`: for command-line front-end tools, like
   ``rst2html.py``.  There are several examples in the ``tools/``
   directory.  A detailed analysis of one such tool is in `Inside A
   Docutils Command-Line Front-End Tool`_
 
-:_`publish_file`: for programmatic use with file-like I/O.  In
+:_`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
+:_`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
+:_`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.
-  See `publish_parts Details`_ below.
+  See `publish_parts() Details`_ below.
 
   There are usage examples in the `docutils/examples.py`_ module.
 
-:_`publish_doctree`: for programmatic use with string input; returns a
+:_`publish_doctree()`: for programmatic use with string input; returns a
   Docutils document tree data structure (doctree).  The doctree can be
   modified, pickled & unpickled, etc., and then reprocessed with
-  `publish_from_doctree`_.
+  `publish_from_doctree()`_.
 
-:_`publish_from_doctree`: for programmatic use to render from an
+:_`publish_from_doctree()`: for programmatic use to render from an
   existing document tree data structure (doctree); returns the encoded
   output as a string.
 
-:_`publish_programmatically`: for custom programmatic use.  This
+:_`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.
@@ -105,10 +105,10 @@ Docutils may introduce some non-ASCII text if you use
    ../ref/rst/directives.html#table-of-contents
 
 
-``publish_parts`` Details
-=========================
+``publish_parts()`` Details
+===========================
 
-The ``docutils.core.publish_parts`` convenience function returns a
+The ``docutils.core.publish_parts()`` convenience function returns a
 dictionary of document parts.  Dictionary keys are the names of parts,
 and values are Unicode strings.
 
diff --git a/docutils/docs/api/runtime-settings.txt b/docutils/docs/api/runtime-settings.txt
index 2648ce778..eee112bce 100644
--- a/docutils/docs/api/runtime-settings.txt
+++ b/docutils/docs/api/runtime-settings.txt
@@ -2,7 +2,7 @@
  Docutils Runtime Settings
 ===========================
 
-:Author: David Goodger
+:Author: David Goodger, Günter Milde
 :Contact: docutils-develop@lists.sourceforge.net
 :Date: $Date$
 :Revision: $Revision$
@@ -15,178 +15,209 @@ Introduction
 ============
 
 Docutils runtime settings are assembled from several sources:
-component settings specifications, application settings
-specifications, configuration files, and command-line options.
+
+* Settings specifications of the selected components_,
+* `application settings specifications`_,
+* `configuration files`_ (if enabled), and
+* command-line options (if enabled).
+
 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):
-
-* The ``settings`` parameter is a runtime settings
-  (``docutils.frontend.Values``) object which, if present, is assumed
-  to be complete (it must include all runtime settings).  Also, if the
-  ``settings`` parameter is present, no further runtime settings
-  processing is done.  In other words, the other parameters, described
-  below, will have no effect.
-
-* ``settings_spec``, a `docutils.SettingsSpec` subclass or object, is
-  treated like a fourth component (after the Parser, Reader, and
-  Writer).  In other words, it's the settings specification for the
-  "Application" itself.
-
-* ``settings_overrides`` is a dictionary which will override the
-  defaults of the components (from their settings specs).
-
-* ``config_section`` specifies the name of an application-specific
-  configuration file section.
-
-
-.. _command-line tools:
-
-Runtime Settings Processing for Command-Line Tools
-==================================================
-
-Following along with the actual code is recommended.  The
-``docutils/__init__.py``, ``docutils/core.py``, and
-``docutils.frontend.py`` modules are described.
-
-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 ``settings`` is not 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.  (See `Docutils
-   Configuration Files`_ for details.)  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/config.html
-
-
-Runtime Settings Processing From Applications
-=============================================
-
-Applications process runtime settings in a 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_programmatically``,
-which implements a generic programmatic interface.  Although an
-application may also call ``publish_programmatically`` 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 no command-line processing.  Instead of calling
-``docutils.Publisher.process_command_line`` (as ``publish_cmdline``
-does, via ``docutils.Publisher.publish``),
-``docutils.Publisher.process_programmatic_settings`` is called to set
-up the runtime settings.
-
-.. copy & modify the list from command-line tools?
-
-
-.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop
+
+Settings priority
+=================
+
+The sources are overlaid in the following order (later sources
+overwrite earlier ones):
+
+1. Defaults specified in the `settings_spec`__ and
+   `settings_defaults`__ attributes for each component_.
+
+   __ SettingsSpec.settings_spec_
+   __ SettingsSpec.settings_defaults_
+
+2. Defaults specified in the `settings_default_overrides`__ attribute
+   for each component_.
+
+   __ SettingsSpec.settings_default_overrides_
+
+3. Settings specified in the `settings_overrides`__ parameter of the
+   `convenience functions`_ resp. the `settings_overrides` attribute of
+   a `Publisher`_ instance.
+
+   __ `settings_overrides parameter`_
+
+4. Settings specified in `active sections`_ of the `configuration files`_
+   in the order described in `Configuration File Sections & Entries`_.
+
+5. Command line arguments.
+
+
+7. Settings specified in the `settings parameter`_ of the `convenience
+   functions`_ or the `settings` attribute of the ``Publisher.settings``
+   attribute.
+
+For details see the ``docutils/__init__.py``, ``docutils/core.py``, and
+``docutils.frontend.py`` modules and the implementation description in
+`Runtime Settings Processing`_.
+
+
+.. _SettingsSpec:
+
+SettingsSpec base class
+=======================
+
+.. note::
+   Implementation details will change with the move to replace the
+   deprecated optparse_ module with argparse_.
+
+The `docutils.SettingsSpec` base class is inherited by Docutils
+components_ and `frontend.OptionParser`.
+It defines the following six **attributes**:
+
+.. _SettingsSpec.settings_spec:
+
+`settings_spec`
+   a sequence of
+
+   1. option group title (string or None)
+
+   2. description (string or None)
+
+   3. option tuples with
+
+      a) help text
+      b) options string(s)
+      c) dictionary with keyword arguments for `OptionParser.add_option()`_
+         and an optional "validator", a `frontend.validate_*()` function
+         that processes the values (e.g. convert to other data types).
+
+   For examples, see the source of ``frontend.OptionParser.settings_spec``
+   or the `settings_spec` attributes of the Docutils components_.
+
+   .. _SettingsSpec.settings_defaults:
+
+`settings_defaults`
+   for purely programmatic settings
+   (not accessible from command line and configuration files).
+
+   .. _SettingsSpec.settings_default_overrides:
+
+`settings_default_overrides`
+   to override defaults for settings
+   defined in other components' `setting_specs`.
+
+`relative_path_settings`
+   listing settings containing filesystem paths.
+
+   .. _active sections:
+
+`config_section`
+   the configuration file section specific to this
+   component.
+
+`config_section_dependencies`
+   lists configuration files sections
+   that should also be read (before the `config_section`).
+
+The last two attributes define which configuration file sections are
+"active". See also `Configuration File Sections & Entries`_.
+
+
+Glossary
+========
+
+.. _component:
+
+components
+----------
+
+Docutils front-ends and applications combine a selection of
+*components* of the `Docutils Project Model`_.
+
+All components inherit the `SettingsSpec`_ base class.
+This means that all instances of ``readers.Reader``, ``parsers.Parser``, and
+``writers.Writer`` are also instances of ``docutils.SettingsSpec``.
+
+For the determination of runtime settings, ``frontend.OptionParser`` and
+the `settings_spec parameter`_ in application settings specifications
+are treated as components as well.
+
+
+.. _application settings specifications:
+.. _convenience function:
+
+convenience functions
+---------------------
+
+Applications usually deploy Docutils by one of the
+`Publisher convenience functions`_.
+All convenience functions accept the following optional **parameters**:
+
+.. _settings parameter:
+
+`settings`
+  a ``frontend.Values`` instance.
+  If present, it must be complete.
+
+  No further runtime settings processing is done and the
+  following parameters have no effect.
+
+  .. _settings_spec parameter:
+
+`settings_spec`
+  a `SettingsSpec`_ subclass or instance containing the settings
+  specification for the "Application" itself.
+  The instance is added to the components_ (after the generic
+  settings, parser, reader, and writer).
+
+  .. _settings_overrides parameter:
+
+`settings_overrides`
+  a dictionary which is used to update the
+  defaults of the components' settings specifications.
+
+  .. _config_section parameter:
+
+`config_section`
+  the name of an application-specific
+  `configuration file section`_ for this application.
+
+  Can be specified instead of a `settings_spec` (a new SettingsSpec_
+  instance that just defines a configuration section will be created)
+  or in addition to a `settings_spec`
+  (overriding its `config_section` attribute).
+
+
+settings_spec
+-------------
+
+The name ``settings_spec`` may refer to
+
+a) an instance of the SettingsSpec_ class, or
+b) the data structure `SettingsSpec.settings_spec`_ which is used to
+   store settings details.
+
+
+.. References:
+
+.. _Publisher: publisher.html
+.. _Publisher convenience functions:
+    publisher.html#publisher-convenience-functions
+.. _front-end tools: ../user/tools.html
+.. _configuration files:
+.. _Docutils Configuration: ../user/config.html#configuration-files
+.. _configuration file section:
+.. _Configuration File Sections & Entries:
+    ../user/config.html#configuration-file-sections-entries
+.. _Docutils Project Model: ../peps/pep-0258.html#docutils-project-model
+.. _Reader: ../peps/pep-0258.html#reader
+.. _Runtime Settings Processing: ../dev/runtime-settings-processing.html
+
+.. _optparse: https://docs.python.org/dev/library/optparse.html
+.. _argparse: https://docs.python.org/dev/library/argparse.html
+.. _OptionParser.add_option():
+    https://docs.python.org/dev/library/optparse.html
+    #optparse.OptionParser.add_option
diff --git a/docutils/docs/dev/runtime-settings-processing.txt b/docutils/docs/dev/runtime-settings-processing.txt
new file mode 100644
index 000000000..fe9833225
--- /dev/null
+++ b/docutils/docs/dev/runtime-settings-processing.txt
@@ -0,0 +1,303 @@
+=============================
+ Runtime Settings Processing
+=============================
+
+:Author: David Goodger, Günter Milde
+:Contact: docutils-develop@lists.sourceforge.net
+:Date: $Date$
+:Revision: $Revision$
+:Copyright: This document has been placed in the public domain.
+
+:Abstract: A detailled description of Docutil's settings processing
+           framework.
+           
+           See `Docutils Runtime Settings`_ for a high-level description
+           of the core API and `Docutils Configuration`_ for a
+           description of the individual settings.
+
+.. contents::
+
+.. note::
+   This document is informal.
+   It describes the state in Docutils 0.18.1.
+   Implementation details will change with the move to replace the
+   deprecated optparse_ module with argparse_.
+
+
+Settings priority
+=================
+
+Docutils overlays default and explicitly specified values from various
+sources such that settings behave the way we want and expect them to
+behave.
+
+The souces are overlaid in the following order (later sources
+overwrite earlier ones):
+
+1. Defaults specified in `settings_spec`__ and
+   `settings_defaults`__ attributes for each component_.
+   (details__)
+
+   __ ../api/runtime-settings.html#settingsspec-settings_spec
+   __ ../api/runtime-settings.html#settingsspec-settings_defaults
+   __ `OptionParser.populate_from_components()`_
+
+2. Defaults specified in `settings_default_overrides`__ attribute for
+   each component_. 
+   (details__)
+
+   __ ../api/runtime-settings.html#settingsspec-settings_default_overrides
+   __ component.settings_default_overrides_
+
+3. Settings specified in the `settings_overrides parameter`_ of the
+   `convenience functions`_ rsp. the `settings_overrides` attribute of
+   a `core.Publisher` instance.
+   (details__)
+
+   __ OptionParser.defaults_
+
+4. Settings specified in `active sections`_ of the `configuration files`_
+   in the order described in `Configuration File Sections & Entries`_. 
+   (details__)
+
+   See also `Configuration File Sections & Entries`_.
+
+   __ `OptionParser.get_standard_config_settings()`_
+
+5. Command line arguments (details__).
+
+   __ `Publisher.process_command_line()`_
+
+7. Settings specified in the `settings parameter`_ of the `convenience
+   functions`_ or the `settings` attribute of the ``Publisher.settings``
+   attribute (details for `command-line tools`__ and `other applications`__).
+
+   __ `pub.publish()`_
+   __ `pub.process_programmatic_settings()`_
+
+
+
+The ``docutils/__init__.py``, ``docutils/core.py``, and
+``docutils.frontend.py`` modules are described.
+Following along with the actual code is recommended.
+
+
+.. _command-line tools:
+
+Runtime settings processing for command-line tools
+==================================================
+
+The command-line `front-end tools`_ usually import and call
+the `convenience function`_ ``docutils.core.publish_cmdline()``.
+
+1. ``docutils.core.publish_cmdline()`` creates a `Publisher`_ instance::
+
+       pub = core.Publisher(…, settings)
+
+   eventually sets the components_ from the respective names, and calls ::
+
+       pub.publish(argv, …,
+                   settings_spec, settings_overrides, config_section, …)
+
+   .. _pub.publish():
+
+2. If `pub.settings` is None [#]_, ``pub.publish()`` calls::
+
+       pub.process_command_line(…, settings_spec, config_section, **defaults)
+
+   with `defaults` taken from `pub.settings_overrides`.
+
+   .. [#] If `pub.settings` is defined, steps 3 to 5 are skipped.
+
+3. ``pub.process_command_line()`` calls::
+
+       opa = pub.setup_option_parser(…,
+                 settings_spec, config_section, **defaults)
+
+   .. _pub.setup_option_parser():
+
+4. ``pub.setup_option_parser()``
+
+   - merges the value of the `config_section parameter`_ into
+     `settings_spec` and
+
+   - creates an `OptionParser` instance ::
+
+        opa = docutils.frontend.OptionParser(components, defaults)
+
+     with `components` the tuple of the `SettingsSpec`_ instances
+     ``(pub.parser, pub.reader, pub.writer, settings_spec)``
+
+   .. _OptionParser.populate_from_components():
+
+5. The `OptionParser` instance prepends itself to the `components` tuple
+   and calls ``self.populate_from_components(components)``, which updates
+   the attribute ``self.defaults`` in two steps:
+
+   a) For each component passed, ``component.settings_spec`` is processed
+      and ``component.settings_defaults`` is applied.
+
+      .. _component.settings_default_overrides:
+
+   b) In a second loop, for each component
+      ``component.settings_default_overrides`` is applied. This way,
+      ``component.settings_default_overrides`` can override the default
+      settings of any other component.
+
+   .. _OptionParser.defaults:
+
+6. Back in ``OptionParser.__init__()``, ``self.defaults`` is updated with
+   the `defaults` argument passed to ``OptionParser(…)`` in step 5.
+
+   This means that the `settings_overrides` argument of the
+   `convenience functions`_ has priority over all
+   ``SettingsSpec.settings_spec`` defaults.
+
+   .. _OptionParser.get_standard_config_settings():
+
+7. If configuration files are enabled,
+   ``self.get_standard_config_settings()`` is called.
+
+   This reads the Docutils `configuration files`_, and returns a
+   dictionary of settings in `active sections`_ which is used to update
+   ``opa.defaults``. So configuration file settings have priority over
+   all software-defined defaults.
+
+   .. _Publisher.process_command_line():
+
+8. ``pub.process_command_line()`` calls ``opa.parse_args()``.
+   The OptionParser parses all command line options and returns a
+   `docutils.frontend.Values` object.
+   This is assigned to ``pub.settings``.
+   So command-line options have priority over configuration file
+   settings.
+
+9. The `<source>` and `<destination>` command-line arguments
+   are also parsed, and assigned to ``pub.settings._source``
+   and ``pub.settings._destination`` respectively.
+
+10. ``pub.publish()`` calls ``pub.set_io()`` with no arguments.
+    If either ``pub.source`` or ``pub.destination`` are not set, the
+    corresponding ``pub.set_source()`` and ``pub.set_destination()``
+    are called:
+
+    ``pub.set_source()``
+      checks for a ``source_path`` argument, and if there is none (which
+      is the case for command-line use), it is taken from
+      ``pub.settings._source``.  ``pub.source`` is set by instantiating a
+      ``pub.source_class`` object.  For command-line front-end tools, the
+      default ``pub.source_class`` (i.e. ``docutils.io.FileInput``) is
+      used.
+
+    ``pub.set_destination()``
+      does the same job for the destination. (the default
+      ``pub.destination_class`` is ``docutils.io.FileOutput``).
+
+    .. _acessing the runtime settings:
+
+11. ``pub.publish()`` passes ``pub.settings`` to the reader_ component's
+    ``read()`` method.
+
+12. The reader component creates a new `document root node`__.
+    ``nodes.document.__init__()`` adds the settings to the internal
+    attributes.
+
+    __ ../ref/doctree.html#document
+
+    All components acting on the Document Tree are handed the
+    ``document`` root node and can access the runtime settings as
+    ``document.settings``.
+
+
+Runtime settings processing for other applications
+==================================================
+
+The `convenience functions`_ , ``core.publish_file()``,
+``core.publish_string()``, or ``core.publish_parts()`` do not parse the
+command line for settings.
+
+1. The convenience functions call the generic programmatic interface
+   function ``core.publish_programmatically()`` that creates a
+   `core.Publisher` instance ::
+
+       pub = core.Publisher(…, settings)
+
+   eventually sets the components_ from the respective names, and calls ::
+
+       pub.process_programmatic_settings(
+           settings_spec, settings_overrides, config_section)
+
+   .. _pub.process_programmatic_settings():
+
+2. If `pub.settings` is None [#]_,
+   ``pub.process_programmatic_settings()`` calls::
+
+       pub.get_settings(settings_spec, config_section, **defaults)
+
+   with `defaults` taken from `pub.settings_overrides`.
+
+   .. [#] If `pub.settings` is defined, the following steps are skipped.
+
+3. ``pub.get_settings()`` calls::
+
+       opa = pub.setup_option_parser(…,
+                 settings_spec, config_section, **defaults)
+
+4. The OptionParser instance determines setting defaults
+   as described in `steps 4 to 7`__ in the previous section.
+
+   __ `pub.setup_option_parser()`_
+
+5. Back in ``pub.get_settings()``, the ``frontend.Values`` instance
+   returned by ``opa.get_default_values()`` is stored in
+   ``pub.settings``.
+
+6. ``publish_programmatically()`` continues with setting ``pub.source`` and
+   ``pub.destination``.
+
+7. Finally, ``pub.publish()`` is called. As ``pub.settings`` is not None,
+   no new command line processing takes place.
+
+8. All components acting on the Document Tree are handed the
+   ``document`` root node and can access the runtime settings as
+   ``document.settings`` (cf. `steps 11 and 12`__ in the previous section).
+
+   __ accessing the runtime settings_
+
+
+.. References:
+
+.. _optparse: https://docs.python.org/dev/library/optparse.html
+.. _argparse: https://docs.python.org/dev/library/argparse.html
+
+.. _Docutils Runtime Settings:
+   ../api/runtime-settings.html
+.. _active sections:   
+   ../api/runtime-settings.html#active-sections
+.. _SettingsSpec:
+   ../api/runtime-settings.html#settingsspec
+.. _component:
+.. _components:
+    ../api/runtime-settings.html#components
+.. _application settings specifications:
+.. _convenience function: 
+.. _convenience functions: 
+    ../api/runtime-settings.html#convenience-functions
+.. _settings_overrides parameter:
+    ../api/runtime-settings.html#settings-overrides-parameter
+.. _settings parameter:
+   ../api/runtime-settings.html#settings-parameter
+.. _config_section parameter:
+   ../api/runtime-settings.html#config-section-parameter
+
+.. _Publisher convenience functions:
+    ../api/publisher.html#publisher-convenience-functions
+.. _front-end tools: ../user/tools.html
+.. _configuration file:
+.. _configuration files:
+.. _Docutils Configuration: ../user/config.html#configuration-files
+.. _Configuration File Sections & Entries:
+    ../user/config.html#configuration-file-sections-entries
+.. _Docutils Project Model: ../peps/pep-0258.html#docutils-project-model
+.. _Publisher: ../peps/pep-0258.html#publisher
+.. _Reader: ../peps/pep-0258.html#reader