1
==========================
2
Docutils Front-End Tools
3
==========================
6
:Contact: goodger@users.sourceforge.net
7
:Revision: $Revision: 1.42 $
8
:Date: $Date: 2004/04/16 15:11:41 $
9
:Copyright: This document has been placed in the public domain.
17
Once the Docutils package is unpacked, you will discover a "``tools``"
18
directory containing several front ends for common Docutils
19
processing. Rather than a single all-purpose program, Docutils has
20
many small front ends, each specialized for a specific "Reader" (which
21
knows how to interpret a file in context), a "Parser" (which
22
understands the syntax of the text), and a "Writer" (which knows how
23
to generate a specific data format).
25
Most front ends have common options and the same command-line usage
28
toolname [options] [<source> [<destination]]
30
(The exceptions are buildhtml.py_ and pep2html.py_.) See rst2html.py_
31
for concrete examples. Each tool has a "``--help``" option which
32
lists the `command-line options`_ and arguments it supports.
33
Processing can also be customized with `configuration files`_.
35
The two arguments, "source" and "destination", are optional. If only
36
one argument (source) is specified, the standard output (stdout) is
37
used for the destination. If no arguments are specified, the standard
38
input (stdin) is used for the source as well.
44
First, try the "``--help``" option each front-end tool has.
46
Users who have questions or need assistance with Docutils or
47
reStructuredText should `post a message`_ to the `Docutils-Users
48
mailing list`_. The `Docutils project web site`_ has more
51
.. _post a message: mailto:docutils-users@lists.sourceforge.net
52
.. _Docutils-Users mailing list:
53
http://lists.sourceforge.net/lists/listinfo/docutils-users
54
.. _Docutils project web site: http://docutils.sourceforge.net/
63
:Readers: Standalone, PEP
64
:Parser: reStructuredText
65
:Writers: HTML, PEP/HTML
67
Use ``buildhtml.py`` to generate .html from all the .txt files
68
(including PEPs) in each <directory> given, and their subdirectories
69
too. (Use the ``--local`` option to skip subdirectories.)
73
buildhtml.py [options] [<directory> ...]
75
After unpacking the Docutils package, the following shell commands
76
will generate HTML for all included documentation::
81
For official releases, the directory may be called "docutils-X.Y",
82
where "X.Y" is the release version. Alternatively::
85
tools/buildhtml.py --config=tools/docutils.conf
87
The current directory (and all subdirectories) is chosen by default if
88
no directory is named. Some files may generate system messages
89
(tools/test.txt contains intentional errors); use the ``--quiet``
90
option to suppress all warnings. The ``--config`` option ensures that
91
the correct stylesheets, templates, and settings are in place (a
92
``docutils.conf`` configuration file in the current directory is
93
picked up automatically). Command-line options may be used to
94
override config file settings or replace them altogether.
101
:Parser: reStructuredText
104
The ``rst2html.py`` front end reads standalone reStructuredText source
105
files and produces HTML 4 (XHTML 1) output compatible with modern
106
browsers. For example, to process a reStructuredText file
107
"``test.txt``" into HTML::
109
rst2html.py test.txt test.html
111
In fact, there *is* a "``test.txt``" file in the "``tools``"
112
directory. It contains "at least one example of each reStructuredText
113
construct", including several intentional errors (to test the error
114
reporting system). Use it to put the system through its paces and
115
compare input to output.
117
Now open the "``test.html``" file in your favorite browser to see the
118
results. To get a footer with a link to the source file, date & time
119
of processing, and links to the Docutils projects, add some options::
121
rst2html.py -stg test.txt test.html
127
``rst2html.py`` inserts into the generated HTML a link to a cascading
128
stylesheet, defaulting to "``default.css``" (override with a
129
"``--stylesheet``" or "``--stylesheet-path``" command-line option or
130
with configuration file settings). The
131
"``tools/stylesheets/default.css``" stylesheet is provided for basic
132
use. To experiment with styles, rather than editing the default
133
stylesheet (which will be updated as the project evolves), it is
134
recommended to use an "``@import``" statement to create a "wrapper"
135
stylesheet. For example, a "``my.css``" stylesheet could contain the
138
@import url(default.css);
140
h1, h2, h3, h4, h5, h6, p.topic-title {
141
font-family: sans-serif }
143
Generate HTML with the following command::
145
rst2html.py -stg --stylesheet my.css test.txt test.html
147
When viewed in a browser, the new "wrapper" stylesheet will change the
148
typeface family of titles to "sans serif", typically Helvetica or
149
Arial. Other styles will not be affected. Styles in wrapper
150
stylesheets override styles in imported stylesheets, enabling
151
incremental experimentation.
158
:Parser: reStructuredText
161
``pep.py`` reads a new-style PEP (marked up with reStructuredText) and
162
produces HTML. It requires a template file and a stylesheet. By
163
default, it makes use of a "``pep-html-template``" file and a
164
"``default.css``" stylesheet in the current directory, but these can
165
be overridden by command-line options or configuration files. The
166
"``tools/stylesheets/pep.css``" stylesheet is intended specifically
169
The "``docutils.conf``" `configuration file`_ in the "``spec``"
170
directory of Docutils contains a default setup for use in processing
171
the PEP files there (``spec/pep-*.txt``) into HTML. It specifies a
172
default template (``tools/pep-html-template``) and a default
173
stylesheet (``tools/stylesheets/pep.css``). See Stylesheets_ above
174
for more information.
181
:Parser: reStructuredText
184
``pep2html.py`` is a modified version of the original script by
185
Fredrik Lundh, with support for Docutils added. It reads the
186
beginning of a PEP text file to determine the format (old-style
187
indented or new-style reStructuredText) and processes accordingly.
188
Since it does not use the Docutils front end mechanism (the common
189
command-line options are not supported), it can only be configured
190
using `configuration files`_. The template and stylesheet
191
requirements of ``pep2html.py`` are the same as those of `pep.py`_
194
Arguments to ``pep2html.py`` may be a list of PEP numbers or .txt
195
files. If no arguments are given, all files of the form
196
"``pep-*.txt``" are processed.
203
:Parser: reStructuredText
206
The ``rst2latex.py`` front end reads standalone reStructuredText
207
source files and produces LaTeX2e output. For example, to process a
208
reStructuredText file "``test.txt``" into LaTeX::
210
rst2latex.py test.txt test.tex
212
The output file "``test.tex``" should then be processed with ``latex``
213
or ``pdflatex`` to get a typeset document.
215
Some limitations and difference apply:
217
- GIF, JPG and PNG images are not handled, when processed with
218
``latex``; use ``pdflatex`` instead.
219
- Only the Latin-1 output encoding has been tested up to now (Latin-1
220
has been made the default output encoding for LaTeX).
221
- The generated file includes a file ``style.tex``, which allows the
222
inclusion of special packages or changes to settings made in the
224
- Not all constructs are possible (e.g. row/column spans in tables are
232
:Parser: reStructuredText
233
:Writer: XML (Docutils native)
235
The ``docutils-xml.py`` front end produces Docutils-native XML output.
236
This can be transformed with standard XML tools such as XSLT
237
processors into arbitrary final forms.
244
:Parser: reStructuredText
247
``publish.py`` is used for debugging the Docutils "Reader to Transform
248
to Writer" pipeline. It produces a compact pretty-printed
249
"pseudo-XML", where nesting is indicated by indentation (no end-tags).
250
External attributes for all elements are output, and internal
251
attributes for any leftover "pending" elements are also given.
258
:Parser: reStructuredText
261
The ``quicktest.py`` tool is used for testing the reStructuredText
262
parser. It does not use a Docutils Reader or Writer or the standard
263
Docutils command-line options. Rather, it does its own I/O and calls
264
the parser directly. No transforms are applied to the parsed
265
document. Various forms output are possible:
267
- Pretty-printed pseudo-XML (default)
268
- Test data (Python list of input and pseudo-XML output strings;
269
useful for creating new test cases)
270
- Pretty-printed native XML
271
- Raw native XML (with or without a stylesheet reference)
281
Each front-end tool supports command-line options for one-off
282
customization. For persistent customization, use `configuration
283
files`_. Command-line options take priority over configuration file
286
Use the "--help" option on each of the front ends to list the
287
command-line options it supports. Command-line options and their
288
corresponding configuration file entry names are listed in the
289
`Docutils Configuration Files`_ document.
292
.. _configuration file:
297
Configuration files are used for persistent customization; they can be
298
set once and take effect every time you use a front-end tool.
300
For details, see `Docutils Configuration Files`_.
302
.. _Docutils Configuration Files: config.html
308
indent-tabs-mode: nil
309
sentence-end-double-space: t
added
removed
docs/tools.txt
