5
5
:Author: David Goodger
6
6
:Contact: goodger@python.org
7
:Date: $Date: 2004/06/27 21:18:22 $
8
:Revision: $Revision: 1.6 $
7
:Date: $Date: 2005-02-25 03:36:17 +0100 (Fri, 25 Feb 2005) $
8
:Revision: $Revision: 2982 $
9
9
:Copyright: This document has been placed in the public domain.
37
37
(described in the ``docutils.core.publish_programmatically`` function
40
* ``settings``, if present, is assumed to be complete and no further
41
runtime settings processing is done.
40
* The ``settings`` parameter is a runtime settings
41
(``docutils.frontend.Values``) object which, if present, is assumed
42
to be complete (it must include all runtime settings). Also, if the
43
``settings`` parameter is present, no further runtime settings
44
processing is done. In other words, the other parameters, described
45
below, will have no effect.
43
* ``settings_spec`` is treated as a fourth component (after the
44
Parser, Reader, and Writer).
47
* ``settings_spec``, a `docutils.SettingsSpec` subclass or object, is
48
treated like a fourth component (after the Parser, Reader, and
49
Writer). In other words, it's the settings specification for the
46
52
* ``settings_overrides`` is a dictionary which will override the
47
defaults of the components.
53
defaults of the components (from their settings specs).
49
* ``config_section`` sets or overrides an application-specific
55
* ``config_section`` specifies the name of an application-specific
50
56
configuration file section.
58
64
Following along with the actual code is recommended. The
59
65
``docutils/__init__.py``, ``docutils/core.py``, and
60
``docutils.frontend`` modules are described.
66
``docutils.frontend.py`` modules are described.
62
68
1. A command-line front-end tool imports and calls
63
69
``docutils.core.publish_cmdline``. The relevant `convenience
163
169
Runtime Settings Processing From Applications
164
170
=============================================
166
Applications process runtime settings in a significantly different way
167
than `command-line tools`_ do. Instead of calling
168
``publish_cmdline``, the application calls one of ``publish_file``,
169
``publish_string``, or ``publish_parts``. These in turn call
170
``publish_programmatically``, which implements a generic programmatic
171
interface. Although an application may also call
172
``publish_programmatically`` directly, it is not recommended (if it
173
does seem to be necessary, please write to the `Docutils-Develop
172
Applications process runtime settings in a different way than
173
`command-line tools`_ do. Instead of calling ``publish_cmdline``, the
174
application calls one of ``publish_file``, ``publish_string``, or
175
``publish_parts``. These in turn call ``publish_programmatically``,
176
which implements a generic programmatic interface. Although an
177
application may also call ``publish_programmatically`` directly, it is
178
not recommended (if it does seem to be necessary, please write to the
179
`Docutils-Develop mailing list`_).
176
181
``publish_programmatically`` accepts the same `convenience function
177
182
parameters`_ as ``publish_cmdline``. Where things differ is that
178
programmatic use does not
183
programmatic use does no command-line processing. Instead of calling
184
``docutils.Publisher.process_command_line`` (as ``publish_cmdline``
185
does, via ``docutils.Publisher.publish``),
186
``docutils.Publisher.process_programmatic_settings`` is called to set
187
up the runtime settings.
182
189
.. copy & modify the list from command-line tools?
added
removed
docs/api/runtime-settings.txt
