From edf21151a9adcfa787b27908d0e87f4c3f9c02f9 Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 27 Jun 2004 03:47:39 +0000 Subject: added to project git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2394 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/runtime-settings.txt | 180 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 docs/api/runtime-settings.txt (limited to 'docs/api/runtime-settings.txt') 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 -- cgit v1.2.1 From 84d659ccead1da2bcb344a44cd56c4ad8c64852d Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 27 Jun 2004 03:58:47 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2397 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/runtime-settings.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/api/runtime-settings.txt') diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt index 0f591143d..b0666537d 100644 --- a/docs/api/runtime-settings.txt +++ b/docs/api/runtime-settings.txt @@ -56,8 +56,8 @@ 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. + ``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`` -- cgit v1.2.1 From 4fa8cca5a4bbc68b9e47d21d16d86a1d7e401eaf Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 27 Jun 2004 04:01:57 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2398 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/runtime-settings.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/api/runtime-settings.txt') diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt index b0666537d..110b1b2f9 100644 --- a/docs/api/runtime-settings.txt +++ b/docs/api/runtime-settings.txt @@ -168,8 +168,8 @@ interface. Although an application may also call 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 +``publish_programmatically`` accepts the same `convenience function +parameters`_ as ``publish_cmdline``. Where things differ is that programmatic use does not TO BE COMPLETED. -- cgit v1.2.1 From d034202bedfbd439215f3feced627142d86c7928 Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 27 Jun 2004 20:50:54 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2402 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/runtime-settings.txt | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'docs/api/runtime-settings.txt') diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt index 110b1b2f9..b66009726 100644 --- a/docs/api/runtime-settings.txt +++ b/docs/api/runtime-settings.txt @@ -55,6 +55,10 @@ docstring): Runtime Settings Processing for Command-Line Tools ================================================== +Following allong with the actual code is recommended. The +``docutils/__init__.py``, ``docutils/core.py``, and +``docutils.frontend`` 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. @@ -67,7 +71,7 @@ Runtime Settings Processing for Command-Line Tools 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 + If ``settings`` is not defined, ``self.process_command_line`` is called with the following relevant arguments: * ``settings_spec`` @@ -81,9 +85,10 @@ Runtime Settings Processing for Command-Line Tools 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: + 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)`` -- cgit v1.2.1 From 2e67d032d1b5c498105cde064be20290e86c67e1 Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 27 Jun 2004 21:00:40 +0000 Subject: typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2403 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/runtime-settings.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/api/runtime-settings.txt') diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt index b66009726..5177cefb1 100644 --- a/docs/api/runtime-settings.txt +++ b/docs/api/runtime-settings.txt @@ -55,7 +55,7 @@ docstring): Runtime Settings Processing for Command-Line Tools ================================================== -Following allong with the actual code is recommended. The +Following along with the actual code is recommended. The ``docutils/__init__.py``, ``docutils/core.py``, and ``docutils.frontend`` modules are described. @@ -96,7 +96,7 @@ Following allong with the actual code is recommended. The 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 + which consists of ``self`` pre-pended to the ``components`` tuple it received. ``self`` (``docutils.frontend.OptionParser``) defines general Docutils settings. @@ -167,9 +167,9 @@ 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 +``publish_programmatically``, which implements a generic programmatic interface. Although an application may also call -``publish_programatically`` directly, it is not recommended (if it +``publish_programmatically`` directly, it is not recommended (if it does seem to be necessary, please write to the `Docutils-Develop mailing list`_). -- cgit v1.2.1 From 170173ed773c5ee29a3b9126f812929d82a83ad3 Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 27 Jun 2004 21:18:22 +0000 Subject: fix git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2404 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/runtime-settings.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api/runtime-settings.txt') diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt index 5177cefb1..4893e5b3a 100644 --- a/docs/api/runtime-settings.txt +++ b/docs/api/runtime-settings.txt @@ -96,7 +96,7 @@ Following along with the actual code is recommended. The 6. The ``docutils.frontend.OptionParser`` object's ``__init__`` method calls ``self.populate_from_components`` with ``self.components``, - which consists of ``self`` pre-pended to the ``components`` tuple it + which consists of ``self`` prepended to the ``components`` tuple it received. ``self`` (``docutils.frontend.OptionParser``) defines general Docutils settings. -- cgit v1.2.1 From 69a5948b99fd454329093e7a2d250a0a99fd10ed Mon Sep 17 00:00:00 2001 From: wiemann Date: Sun, 19 Sep 2004 10:37:25 +0000 Subject: typo git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2627 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/runtime-settings.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api/runtime-settings.txt') diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt index 4893e5b3a..4f87c48de 100644 --- a/docs/api/runtime-settings.txt +++ b/docs/api/runtime-settings.txt @@ -157,7 +157,7 @@ Following along with the actual code is recommended. The that ``self.set_source`` does for the source (the default ``self.destination_class`` is ``docutils.io.FileOutput``). -.. _Docutils Configuration Files: ../user/tools.html +.. _Docutils Configuration Files: ../user/config.html Runtime Settings Processing From Applications -- cgit v1.2.1 From f68980b0781f68739a35aa0fd58d5c9dc6961875 Mon Sep 17 00:00:00 2001 From: goodger Date: Fri, 25 Feb 2005 02:36:17 +0000 Subject: clarified & extended git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2982 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/runtime-settings.txt | 47 +++++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 20 deletions(-) (limited to 'docs/api/runtime-settings.txt') diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt index 4f87c48de..d6b8997cd 100644 --- a/docs/api/runtime-settings.txt +++ b/docs/api/runtime-settings.txt @@ -37,16 +37,22 @@ 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). +* 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. + defaults of the components (from their settings specs). -* ``config_section`` sets or overrides an application-specific +* ``config_section`` specifies the name of an application-specific configuration file section. @@ -57,7 +63,7 @@ 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`` modules are described. +``docutils.frontend.py`` modules are described. 1. A command-line front-end tool imports and calls ``docutils.core.publish_cmdline``. The relevant `convenience @@ -163,21 +169,22 @@ Following along with the actual code is recommended. The 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_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`_). +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 not - -TO BE COMPLETED. +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? -- cgit v1.2.1