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/cmdline-tool.txt | 68 ++++++++++++++++ docs/api/publisher.txt | 73 +++++++++++++++++ docs/api/runtime-settings.txt | 180 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 321 insertions(+) create mode 100644 docs/api/cmdline-tool.txt create mode 100644 docs/api/publisher.txt create mode 100644 docs/api/runtime-settings.txt (limited to 'docs/api') 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 -- 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') 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') 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 e001aacf90267adb95c3ba197fc13d8dd39a5d0f Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 27 Jun 2004 17:36:49 +0000 Subject: updated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2401 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/publisher.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/api') diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt index 4c7f7831c..2eb8f1b71 100644 --- a/docs/api/publisher.txt +++ b/docs/api/publisher.txt @@ -21,7 +21,8 @@ handles everything else. There are five convenience functions in the * ``publish_cmdline``: for command-line front-end tools, like ``rst2html.py``. There are several examples in the ``tools/`` - directory. + 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 addition to writing the encoded output to a file, also returns the @@ -43,6 +44,8 @@ handles everything else. There are five convenience functions in the ``publish_string``, and ``publish_parts``. It returns a 2-tuple: the encoded string output and the Publisher object. +.. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html + Configuration ------------- -- 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') 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') 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') 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 edd9665643cbfab050578272b4dd4b0770b5e715 Mon Sep 17 00:00:00 2001 From: wiemann Date: Tue, 14 Sep 2004 10:07:57 +0000 Subject: updated; added link git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2612 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/publisher.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs/api') diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt index 2eb8f1b71..95bf4d62e 100644 --- a/docs/api/publisher.txt +++ b/docs/api/publisher.txt @@ -71,6 +71,9 @@ 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. +non-ASCII in your input text, you may have to do a bit more setup. +Docutils may introduce some non-ASCII text if you use +symbol-footnotes_. + +.. _symbol-footnotes: + ../ref/rst/restructuredtext.html#auto-symbol-footnotes -- 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') 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 1ad0b81c3591c9d3c085dc5ae873a08f26e70297 Mon Sep 17 00:00:00 2001 From: wiemann Date: Sat, 1 Jan 2005 15:54:45 +0000 Subject: added link to examples.py git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@2920 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/publisher.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/api') diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt index 95bf4d62e..b018bbe90 100644 --- a/docs/api/publisher.txt +++ b/docs/api/publisher.txt @@ -37,7 +37,7 @@ handles everything else. There are five convenience functions in the 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. + 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``, @@ -45,6 +45,7 @@ handles everything else. There are five convenience functions in the the encoded string output and the Publisher object. .. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html +.. _docutils/examples.py: ../../docutils/examples.py Configuration -- 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') 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 From 03da26f3c9d0d99ea4afd99cf5330fe307ce3bb3 Mon Sep 17 00:00:00 2001 From: goodger Date: Sun, 24 Apr 2005 23:21:48 +0000 Subject: Added ``html_body``, ``html_title``, & ``html_subtitle`` to HTML writer parts dictionary exposed by ``docutils.core.publish_parts``; updated tests. Added "``publish_parts`` Details" section to docs/api/publish.txt. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3251 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/publisher.txt | 83 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 79 insertions(+), 4 deletions(-) (limited to 'docs/api') diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt index b018bbe90..5d793f003 100644 --- a/docs/api/publisher.txt +++ b/docs/api/publisher.txt @@ -35,9 +35,9 @@ handles everything else. There are five convenience functions in the 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. + See `publish_parts Details`_ below. - There are examples in the `docutils/examples.py`_ module. + There are usage examples in the `docutils/examples.py`_ module. * ``publish_programmatically``: for custom programmatic use. This function implements common code and is used by ``publish_file``, @@ -74,7 +74,82 @@ Encodings The default output encoding of Docutils is UTF-8. If you have any non-ASCII in your input text, you may have to do a bit more setup. Docutils may introduce some non-ASCII text if you use -symbol-footnotes_. +`auto-symbol footnotes`_ or the `"contents" directive`_. -.. _symbol-footnotes: +.. _auto-symbol footnotes: ../ref/rst/restructuredtext.html#auto-symbol-footnotes +.. _"contents" directive: + ../ref/rst/directives.html#table-of-contents + + +``publish_parts`` Details +========================= + +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. + +Each Writer component may publish a different set of document parts, +described below. Currently only the HTML Writer implements more than +the "whole" part. + + +Parts Provided By All Writers +----------------------------- + +whole + ``parts['whole']`` contains the entire formatted document. + + +Parts Provided By the HTML Writer +--------------------------------- + +body + ``parts['body']`` is equivalent to ``parts['fragment']``. + +docinfo + ``parts['docinfo']`` contains the document bibliographic data. + +footer + ``parts['footer']`` contains the document footer content, meant to + appear at the bottom of a web page, or repeated at the bottom of + every printed page. + +fragment + ``parts['fragment']`` contains the document body (*not* the HTML + ````). In other words, it contains the entire document, + less the document title, subtitle, docinfo, header, and footer. + +header + ``parts['header']`` contains the document header content, meant to + appear at the top of a web page, or repeated at the top of every + printed page. + +html_body + ``parts['html_body']`` contains the HTML ```` content, less + the ```` and ```` tags themselves. + +html_subtitle + ``parts['html_subtitle']`` contains the document subtitle, + including the enclosing ``

`` & ``

`` + tags. + +html_title + ``parts['html_title']`` contains the document title, including the + enclosing ``

`` & ``

`` tags. + +meta + ``parts['meta']`` contains all ```` tags. + +stylesheet + ``parts['stylesheet']`` contains the document stylesheet link. + +subtitle + ``parts['subtitle']`` contains the document subtitle text and any + inline markup. It does not include the enclosing ``

`` & + ``

`` tags. + +title + ``parts['title']`` contains the document title text and any inline + markup. It does not include the enclosing ``

`` & ``

`` + tags. -- cgit v1.2.1 From df86c29341bb830c87ee468323c1e3afa9d32a03 Mon Sep 17 00:00:00 2001 From: goodger Date: Tue, 26 Apr 2005 03:57:00 +0000 Subject: Added ``html_prolog`` & ``html_head`` to HTML writer parts dictionary exposed by ``docutils.core.publish_parts``; updated tests & docs. At the request of Marcelo Huerta. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3257 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/publisher.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/api') diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt index 5d793f003..55883f1ae 100644 --- a/docs/api/publisher.txt +++ b/docs/api/publisher.txt @@ -129,6 +129,15 @@ html_body ``parts['html_body']`` contains the HTML ```` content, less the ```` and ```` tags themselves. +html_head + ``parts['html_head']`` contains the HTML ```` content, less + the stylesheet link and the ```` and ```` tags + themselves. + +html_prolog + ``parts['html_prolog]`` contains the XML declaration and the + doctype declaration. + html_subtitle ``parts['html_subtitle']`` contains the document subtitle, including the enclosing ``

`` & ``

`` -- cgit v1.2.1 From ce727c88d8d89f9f86275c0d3fca3ae2be392cec Mon Sep 17 00:00:00 2001 From: goodger Date: Wed, 27 Apr 2005 21:04:03 +0000 Subject: fixed encoding/charset values in "html_prolog" & "html_head" parts, which should not have been interpolated git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3268 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/publisher.txt | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) (limited to 'docs/api') diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt index 55883f1ae..66aaa06fb 100644 --- a/docs/api/publisher.txt +++ b/docs/api/publisher.txt @@ -132,11 +132,21 @@ html_body html_head ``parts['html_head']`` contains the HTML ```` content, less the stylesheet link and the ```` and ```` tags - themselves. + themselves. The "Content-Type" meta tag's "charset" value is left + unresolved, as "%s":: + + + + The interpolation should be done by client code. html_prolog ``parts['html_prolog]`` contains the XML declaration and the - doctype declaration. + doctype declaration. The XML declaration's "encoding" attribute's + value is left unresolved, as "%s":: + + + + The interpolation should be done by client code. html_subtitle ``parts['html_subtitle']`` contains the document subtitle, -- cgit v1.2.1 From abecd9557393b8a49965f04edad866b950feb338 Mon Sep 17 00:00:00 2001 From: wiemann Date: Mon, 2 May 2005 14:59:57 +0000 Subject: added motivation for unresolved charset git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3283 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/publisher.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/api') diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt index 66aaa06fb..79bac6202 100644 --- a/docs/api/publisher.txt +++ b/docs/api/publisher.txt @@ -132,8 +132,9 @@ html_body html_head ``parts['html_head']`` contains the HTML ```` content, less the stylesheet link and the ```` and ```` tags - themselves. The "Content-Type" meta tag's "charset" value is left - unresolved, as "%s":: + themselves. Since ``publish_parts`` returns Unicode strings and + does not know about the output encoding, the "Content-Type" meta + tag's "charset" value is left unresolved, as "%s":: -- cgit v1.2.1 From b7b2f9f3ecf1b3877314db63d09242dfe71b41fc Mon Sep 17 00:00:00 2001 From: wiemann Date: Sat, 28 May 2005 00:30:02 +0000 Subject: replaced references to the mailing lists with references to the new "mailing-lists" document git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3396 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/runtime-settings.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/api') diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt index d6b8997cd..0da1ae6d9 100644 --- a/docs/api/runtime-settings.txt +++ b/docs/api/runtime-settings.txt @@ -176,7 +176,7 @@ application calls one of ``publish_file``, ``publish_string``, or 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`_). +Docutils-develop_ mailing list). ``publish_programmatically`` accepts the same `convenience function parameters`_ as ``publish_cmdline``. Where things differ is that @@ -189,4 +189,4 @@ up the runtime settings. .. copy & modify the list from command-line tools? -.. _Docutils-Develop mailing list: docutils-develop@lists.sf.net +.. _Docutils-develop: ../users/mailing-lists.html#docutils-develop -- cgit v1.2.1 From 470195b45aa54c6f651cb107c038218090b05653 Mon Sep 17 00:00:00 2001 From: wiemann Date: Sat, 28 May 2005 01:22:12 +0000 Subject: fixed links git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3398 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/runtime-settings.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api') diff --git a/docs/api/runtime-settings.txt b/docs/api/runtime-settings.txt index 0da1ae6d9..2d60aa3e1 100644 --- a/docs/api/runtime-settings.txt +++ b/docs/api/runtime-settings.txt @@ -189,4 +189,4 @@ up the runtime settings. .. copy & modify the list from command-line tools? -.. _Docutils-develop: ../users/mailing-lists.html#docutils-develop +.. _Docutils-develop: ../user/mailing-lists.html#docutils-develop -- cgit v1.2.1 From d6649c9ccd1a002ab28b59c11d12bbaf96a5d2a9 Mon Sep 17 00:00:00 2001 From: wiemann Date: Mon, 27 Jun 2005 11:10:08 +0000 Subject: added link targets; note to self: need to document publish_(from_)doctree git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3597 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/publisher.txt | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) (limited to 'docs/api') diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt index 79bac6202..98d84235f 100644 --- a/docs/api/publisher.txt +++ b/docs/api/publisher.txt @@ -97,39 +97,39 @@ the "whole" part. Parts Provided By All Writers ----------------------------- -whole +_`whole` ``parts['whole']`` contains the entire formatted document. Parts Provided By the HTML Writer --------------------------------- -body +_`body` ``parts['body']`` is equivalent to ``parts['fragment']``. -docinfo +_`docinfo` ``parts['docinfo']`` contains the document bibliographic data. -footer +_`footer` ``parts['footer']`` contains the document footer content, meant to appear at the bottom of a web page, or repeated at the bottom of every printed page. -fragment +_`fragment` ``parts['fragment']`` contains the document body (*not* the HTML ````). In other words, it contains the entire document, less the document title, subtitle, docinfo, header, and footer. -header +_`header` ``parts['header']`` contains the document header content, meant to appear at the top of a web page, or repeated at the top of every printed page. -html_body +_`html_body` ``parts['html_body']`` contains the HTML ```` content, less the ```` and ```` tags themselves. -html_head +_`html_head` ``parts['html_head']`` contains the HTML ```` content, less the stylesheet link and the ```` and ```` tags themselves. Since ``publish_parts`` returns Unicode strings and @@ -140,7 +140,7 @@ html_head The interpolation should be done by client code. -html_prolog +_`html_prolog` ``parts['html_prolog]`` contains the XML declaration and the doctype declaration. The XML declaration's "encoding" attribute's value is left unresolved, as "%s":: @@ -149,27 +149,27 @@ html_prolog The interpolation should be done by client code. -html_subtitle +_`html_subtitle` ``parts['html_subtitle']`` contains the document subtitle, including the enclosing ``

`` & ``

`` tags. -html_title +_`html_title` ``parts['html_title']`` contains the document title, including the enclosing ``

`` & ``

`` tags. -meta +_`meta` ``parts['meta']`` contains all ```` tags. -stylesheet +_`stylesheet` ``parts['stylesheet']`` contains the document stylesheet link. -subtitle +_`subtitle` ``parts['subtitle']`` contains the document subtitle text and any inline markup. It does not include the enclosing ``

`` & ``

`` tags. -title +_`title` ``parts['title']`` contains the document title text and any inline markup. It does not include the enclosing ``

`` & ``

`` tags. -- cgit v1.2.1 From 9d1a45f051d1fea540749eab04bd0b549bdd0fc4 Mon Sep 17 00:00:00 2001 From: wiemann Date: Mon, 27 Jun 2005 11:25:47 +0000 Subject: added more links; added note about body != html_body git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk/docutils@3599 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docs/api/publisher.txt | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs/api') diff --git a/docs/api/publisher.txt b/docs/api/publisher.txt index 98d84235f..73cfc0ef2 100644 --- a/docs/api/publisher.txt +++ b/docs/api/publisher.txt @@ -19,19 +19,19 @@ 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 +:_`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. @@ -39,7 +39,7 @@ handles everything else. There are five convenience functions in the There are usage examples in the `docutils/examples.py`_ module. -* ``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,7 +105,8 @@ Parts Provided By the HTML Writer --------------------------------- _`body` - ``parts['body']`` is equivalent to ``parts['fragment']``. + ``parts['body']`` is equivalent to parts['fragment_']. It is + *not* equivalent to parts['html_body_']. _`docinfo` ``parts['docinfo']`` contains the document bibliographic data. -- cgit v1.2.1