1
==========================
2
Docutils Front-End Tools
3
==========================
6
:Contact: goodger@python.org
7
:Revision: $Revision: 4163 $
8
:Date: $Date: 2005-12-09 05:21:34 +0100 (Fri, 09 Dec 2005) $
9
:Copyright: This document has been placed in the public domain.
18
Once the Docutils package is unpacked, you will discover a "``tools``"
19
directory containing several front ends for common Docutils
20
processing. Rather than a single all-purpose program, Docutils has
21
many small front ends, each specialized for a specific "Reader" (which
22
knows how to interpret a file in context), a "Parser" (which
23
understands the syntax of the text), and a "Writer" (which knows how
24
to generate a specific data format).
26
Most front ends have common options and the same command-line usage
29
toolname [options] [<source> [<destination]]
31
(The exceptions are buildhtml.py_ and rstpep2html.py_.) See
32
rst2html.py_ for concrete examples. Each tool has a "``--help``"
33
option which lists the `command-line options`_ and arguments it
34
supports. Processing can also be customized with `configuration
37
The two arguments, "source" and "destination", are optional. If only
38
one argument (source) is specified, the standard output (stdout) is
39
used for the destination. If no arguments are specified, the standard
40
input (stdin) is used for the source as well.
46
First, try the "``--help``" option each front-end tool has.
48
Users who have questions or need assistance with Docutils or
49
reStructuredText should post a message to the Docutils-users_ mailing
52
.. _Docutils-users: mailing-lists.html#docutils-users
65
:Readers: Standalone, PEP
66
:Parser: reStructuredText
67
:Writers: HTML, PEP/HTML
69
Use ``buildhtml.py`` to generate .html from all the .txt files
70
(including PEPs) in each <directory> given, and their subdirectories
71
too. (Use the ``--local`` option to skip subdirectories.)
75
buildhtml.py [options] [<directory> ...]
77
After unpacking the Docutils package, the following shell commands
78
will generate HTML for all included documentation::
83
For official releases, the directory may be called "docutils-X.Y",
84
where "X.Y" is the release version. Alternatively::
87
tools/buildhtml.py --config=tools/docutils.conf
89
The current directory (and all subdirectories) is chosen by default if
90
no directory is named. Some files may generate system messages
91
(docs/user/rst/demo.txt contains intentional errors); use the
92
``--quiet`` option to suppress all warnings. The ``--config`` option
93
ensures that the correct settings are in place (a ``docutils.conf``
94
`configuration file`_ in the current directory is picked up
95
automatically). Command-line options may be used to override config
96
file settings or replace them altogether.
103
:Parser: reStructuredText
106
The ``rst2html.py`` front end reads standalone reStructuredText source
107
files and produces HTML 4 (XHTML 1) output compatible with modern
108
browsers that support cascading stylesheets (CSS). A stylesheet is
109
required for proper rendering; a simple but complete stylesheet is
110
installed and used by default (see Stylesheets_ below).
112
For example, to process a reStructuredText file "``test.txt``" into
115
rst2html.py test.txt test.html
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 project, add some options::
121
rst2html.py -stg test.txt test.html
127
``rst2html.py`` inserts into the generated HTML a cascading stylesheet
128
(or a link to a stylesheet, when passing the "``--link-stylesheet``"
129
option). A stylesheet is required for proper rendering. The default
130
stylesheet (``docutils/writers/html4css1/html4css1.css``, located in
131
the installation directory) is provided for basic use. To use a
132
different stylesheet, you must specify the stylesheet's location with
133
a "``--stylesheet``" (for a URL) or "``--stylesheet-path``" (for a
134
local file) command-line option, or with `configuration file`_
135
settings (e.g. ``./docutils.conf`` or ``~/.docutils``). To experiment
136
with styles, please see the `guide to writing HTML (CSS) stylesheets
139
__ ../howto/html-stylesheets.html
146
:Parser: reStructuredText
149
``rstpep2html.py`` reads a new-style PEP (marked up with
150
reStructuredText) and produces HTML. It requires a template file and
151
a stylesheet. By default, it makes use of a "``pep-html-template``"
152
file and the "``pep.css``" stylesheet (both in the
153
``docutils/writers/pep_html/`` directory), but these can be overridden
154
by command-line options or configuration files.
156
For example, to process a PEP into HTML::
158
cd <path-to-docutils>/docs/peps
159
rstpep2html.py pep-0287.txt pep-0287.html
166
:Parser: reStructuredText
169
The ``rst2s5.py`` front end reads standalone reStructuredText source
170
files and produces (X)HTML output compatible with S5_, the "Simple
171
Standards-based Slide Show System" by Eric Meyer. A theme is required
172
for proper rendering; several are distributed with Docutils and others
173
are available; see Themes_ below.
175
For example, to process a reStructuredText file "``slides.txt``" into
178
rst2s5.py slides.txt slides.html
180
Now open the "``slides.html``" file in your favorite browser, switch
181
to full-screen mode, and enjoy the results.
183
.. _S5: http://meyerweb.com/eric/tools/s5/
189
Each S5 theme consists of a directory containing several files:
190
stylesheets, JavaScript, and graphics. These are copied into a
191
``ui/<theme>`` directory beside the generated HTML. A theme is chosen
192
using the "``--theme``" option (for themes that come with Docutils) or
193
the "``--theme-url``" option (for themes anywhere). For example, the
194
"medium-black" theme can be specified as follows::
196
rst2s5.py --theme medium-black slides.txt slides.html
198
The theme will be copied to the ``ui/medium-black`` directory.
200
Several themes are included with Docutils:
203
This is a simplified version of S5's default theme.
205
:Main content: black serif text on a white background
206
:Text capacity: about 13 lines
207
:Headers: light blue, bold sans-serif text on a dark blue
208
background; titles are limited to one line
209
:Footers: small, gray, bold sans-serif text on a dark blue
213
(Small text on a white background.)
215
:Main content: black serif text on a white background
216
:Text capacity: about 15 lines
217
:Headers: black, bold sans-serif text on a white background;
219
:Footers: small, dark gray, bold sans-serif text on a white
223
:Main content: white serif text on a black background
224
:Text capacity: about 15 lines
225
:Headers: white, bold sans-serif text on a black background;
227
:Footers: small, light gray, bold sans-serif text on a black
231
:Main content: black serif text on a white background
232
:Text capacity: about 9 lines
233
:Headers: black, bold sans-serif text on a white background;
235
:Footers: small, dark gray, bold sans-serif text on a white
239
:Main content: white serif text on a black background
240
:Text capacity: about 9 lines
241
:Headers: white, bold sans-serif text on a black background;
243
:Footers: small, light gray, bold sans-serif text on a black
247
:Main content: black, bold sans-serif text on a white background
248
:Text capacity: about 5 lines
249
:Headers: black, bold sans-serif text on a white background;
251
:Footers: not displayed
254
:Main content: white, bold sans-serif text on a black background
255
:Text capacity: about 5 lines
256
:Headers: white, bold sans-serif text on a black background;
258
:Footers: not displayed
260
If a theme directory contains a file named ``__base__``, the name of
261
the theme's base theme will be read from it. Files are accumulated
262
from the named theme, any base themes, and the "default" theme (which
263
is the implicit base of all themes).
265
For details, please see `Easy Slide Shows With reStructuredText &
266
S5 <slide-shows.html>`_.
269
LaTeX-Generating Tools
270
======================
276
:Parser: reStructuredText
279
The ``rst2latex.py`` front end reads standalone reStructuredText
280
source files and produces LaTeX2e output. For example, to process a
281
reStructuredText file "``test.txt``" into LaTeX::
283
rst2latex.py test.txt test.tex
285
The output file "``test.tex``" should then be processed with ``latex``
286
or ``pdflatex`` to get a typeset document.
288
Some limitations and difference apply:
290
- GIF, JPG and PNG images are not handled, when processed with
291
``latex``; use ``pdflatex`` instead.
292
- Only the Latin-1 output encoding has been tested up to now (Latin-1
293
has been made the default output encoding for LaTeX).
294
- The optional stylesheet file allows the inclusion of special packages
295
or overwriting default settings for LaTeX.
296
- Not all constructs are possible, see `Generating LaTeX with Docutils`_.
306
:Parser: reStructuredText
307
:Writer: XML (Docutils native)
309
The ``rst2xml.py`` front end produces Docutils-native XML output.
310
This can be transformed with standard XML tools such as XSLT
311
processors into arbitrary final forms.
314
Testing/Debugging Tools
315
=======================
321
:Parser: reStructuredText
324
``rst2pseudoxml.py`` is used for debugging the Docutils "Reader to
325
Transform to Writer" pipeline. It produces a compact pretty-printed
326
"pseudo-XML", where nesting is indicated by indentation (no end-tags).
327
External attributes for all elements are output, and internal
328
attributes for any leftover "pending" elements are also given.
335
:Parser: reStructuredText
338
The ``quicktest.py`` tool is used for testing the reStructuredText
339
parser. It does not use a Docutils Reader or Writer or the standard
340
Docutils command-line options. Rather, it does its own I/O and calls
341
the parser directly. No transforms are applied to the parsed
342
document. Various forms output are possible:
344
- Pretty-printed pseudo-XML (default)
345
- Test data (Python list of input and pseudo-XML output strings;
346
useful for creating new test cases)
347
- Pretty-printed native XML
348
- Raw native XML (with or without a stylesheet reference)
359
Each front-end tool supports command-line options for one-off
360
customization. For persistent customization, use `configuration
361
files`_. Command-line options take priority over configuration file
364
Use the "--help" option on each of the front ends to list the
365
command-line options it supports. Command-line options and their
366
corresponding configuration file entry names are listed in the
367
`Docutils Configuration Files`_ document.
370
.. _configuration file:
375
Configuration files are used for persistent customization; they can be
376
set once and take effect every time you use a front-end tool.
378
For details, see `Docutils Configuration Files`_.
380
.. _Docutils Configuration Files: config.html
381
.. _Generating LaTeX with Docutils: latex.html
386
indent-tabs-mode: nil
387
sentence-end-double-space: t
added
removed
docs/user/tools.txt
