1
========================
3
========================
6
:Contact: goodger@python.org
7
:Date: $Date: 2005-06-27 13:25:47 +0200 (Mon, 27 Jun 2005) $
8
:Revision: $Revision: 3599 $
9
:Copyright: This document has been placed in the public domain.
14
Publisher Convenience Functions
15
===============================
17
Each of these functions set up a ``docutils.core.Publisher`` object,
18
then call its ``publish`` method. ``docutils.core.Publisher.publish``
19
handles everything else. There are five convenience functions in the
20
``docutils.core`` module:
22
:_`publish_cmdline`: for command-line front-end tools, like
23
``rst2html.py``. There are several examples in the ``tools/``
24
directory. A detailed analysis of one such tool is in `Inside A
25
Docutils Command-Line Front-End Tool`_
27
:_`publish_file`: for programmatic use with file-like I/O. In
28
addition to writing the encoded output to a file, also returns the
29
encoded output as a string.
31
:_`publish_string`: for programmatic use with string I/O. Returns
32
the encoded output as a string.
34
:_`publish_parts`: for programmatic use with string input; returns a
35
dictionary of document parts. Dictionary keys are the names of
36
parts, and values are Unicode strings; encoding is up to the client.
37
Useful when only portions of the processed document are desired.
38
See `publish_parts Details`_ below.
40
There are usage examples in the `docutils/examples.py`_ module.
42
:_`publish_programmatically`: for custom programmatic use. This
43
function implements common code and is used by ``publish_file``,
44
``publish_string``, and ``publish_parts``. It returns a 2-tuple:
45
the encoded string output and the Publisher object.
47
.. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html
48
.. _docutils/examples.py: ../../docutils/examples.py
54
To pass application-specific setting defaults to the Publisher
55
convenience functions, use the ``settings_overrides`` parameter. Pass
56
a dictionary of setting names & values, like this::
58
overrides = {'input_encoding': 'ascii',
59
'output_encoding': 'latin-1'}
60
output = publish_string(..., settings_overrides=overrides)
62
Settings from command-line options override configuration file
63
settings, and they override application defaults. For details, see
64
`Docutils Runtime Settings`_. See `Docutils Configuration Files`_ for
65
details about individual settings.
67
.. _Docutils Runtime Settings: ./runtime-settings.html
68
.. _Docutils Configuration Files: ../user/tools.html
74
The default output encoding of Docutils is UTF-8. If you have any
75
non-ASCII in your input text, you may have to do a bit more setup.
76
Docutils may introduce some non-ASCII text if you use
77
`auto-symbol footnotes`_ or the `"contents" directive`_.
79
.. _auto-symbol footnotes:
80
../ref/rst/restructuredtext.html#auto-symbol-footnotes
81
.. _"contents" directive:
82
../ref/rst/directives.html#table-of-contents
85
``publish_parts`` Details
86
=========================
88
The ``docutils.core.publish_parts`` convenience function returns a
89
dictionary of document parts. Dictionary keys are the names of parts,
90
and values are Unicode strings.
92
Each Writer component may publish a different set of document parts,
93
described below. Currently only the HTML Writer implements more than
97
Parts Provided By All Writers
98
-----------------------------
101
``parts['whole']`` contains the entire formatted document.
104
Parts Provided By the HTML Writer
105
---------------------------------
108
``parts['body']`` is equivalent to parts['fragment_']. It is
109
*not* equivalent to parts['html_body_'].
112
``parts['docinfo']`` contains the document bibliographic data.
115
``parts['footer']`` contains the document footer content, meant to
116
appear at the bottom of a web page, or repeated at the bottom of
120
``parts['fragment']`` contains the document body (*not* the HTML
121
``<body>``). In other words, it contains the entire document,
122
less the document title, subtitle, docinfo, header, and footer.
125
``parts['header']`` contains the document header content, meant to
126
appear at the top of a web page, or repeated at the top of every
130
``parts['html_body']`` contains the HTML ``<body>`` content, less
131
the ``<body>`` and ``</body>`` tags themselves.
134
``parts['html_head']`` contains the HTML ``<head>`` content, less
135
the stylesheet link and the ``<head>`` and ``</head>`` tags
136
themselves. Since ``publish_parts`` returns Unicode strings and
137
does not know about the output encoding, the "Content-Type" meta
138
tag's "charset" value is left unresolved, as "%s"::
140
<meta http-equiv="Content-Type" content="text/html; charset=%s" />
142
The interpolation should be done by client code.
145
``parts['html_prolog]`` contains the XML declaration and the
146
doctype declaration. The XML declaration's "encoding" attribute's
147
value is left unresolved, as "%s"::
149
<?xml version="1.0" encoding="%s" ?>
151
The interpolation should be done by client code.
154
``parts['html_subtitle']`` contains the document subtitle,
155
including the enclosing ``<h2 class="subtitle">`` & ``</h2>``
159
``parts['html_title']`` contains the document title, including the
160
enclosing ``<h1 class="title">`` & ``</h1>`` tags.
163
``parts['meta']`` contains all ``<meta ... />`` tags.
166
``parts['stylesheet']`` contains the document stylesheet link.
169
``parts['subtitle']`` contains the document subtitle text and any
170
inline markup. It does not include the enclosing ``<h2>`` &
174
``parts['title']`` contains the document title text and any inline
175
markup. It does not include the enclosing ``<h1>`` & ``</h1>``
added
removed
docs/api/publisher.txt
