1 ==========================
2 Docutils Front-End Tools
3 ==========================
6 :Contact: docutils-develop@lists.sourceforge.net
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.
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
104 :Writer: HTML (html4css1)
106 The ``rst2html.py`` front end reads standalone reStructuredText source
107 files and produces HTML 4 (XHTML 1) "transitional" output compatible with
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 The ``rst2xhtml11.py`` front end reads standalone reStructuredText source
150 files and produces clean XHTML 1.1 output. A stylesheet is required for
151 proper rendering; a complete stylesheet is installed and used by default.
157 :Parser: reStructuredText
160 The ``rst2html5.py`` front end reads standalone reStructuredText source
161 files and produces simple HTML 5 output. A stylesheet is required for
162 proper rendering; a complete stylesheet is installed and used by default.
168 :Parser: reStructuredText
171 ``rstpep2html.py`` reads a new-style PEP (marked up with
172 reStructuredText) and produces HTML. It requires a template file and
173 a stylesheet. By default, it makes use of a "``pep-html-template``"
174 file and the "``pep.css``" stylesheet (both in the
175 ``docutils/writers/pep_html/`` directory), but these can be overridden
176 by command-line options or configuration files.
178 For example, to process a PEP into HTML::
180 cd <path-to-docutils>/docs/peps
181 rstpep2html.py pep-0287.txt pep-0287.html
188 :Parser: reStructuredText
191 The ``rst2s5.py`` front end reads standalone reStructuredText source
192 files and produces (X)HTML output compatible with S5_, the "Simple
193 Standards-based Slide Show System" by Eric Meyer. A theme is required
194 for proper rendering; several are distributed with Docutils and others
195 are available; see Themes_ below.
197 For example, to process a reStructuredText file "``slides.txt``" into
200 rst2s5.py slides.txt slides.html
202 Now open the "``slides.html``" file in your favorite browser, switch
203 to full-screen mode, and enjoy the results.
205 .. _S5: http://meyerweb.com/eric/tools/s5/
211 Each S5 theme consists of a directory containing several files:
212 stylesheets, JavaScript, and graphics. These are copied into a
213 ``ui/<theme>`` directory beside the generated HTML. A theme is chosen
214 using the "``--theme``" option (for themes that come with Docutils) or
215 the "``--theme-url``" option (for themes anywhere). For example, the
216 "medium-black" theme can be specified as follows::
218 rst2s5.py --theme medium-black slides.txt slides.html
220 The theme will be copied to the ``ui/medium-black`` directory.
222 Several themes are included with Docutils:
225 This is a simplified version of S5's default theme.
227 :Main content: black serif text on a white background
228 :Text capacity: about 13 lines
229 :Headers: light blue, bold sans-serif text on a dark blue
230 background; titles are limited to one line
231 :Footers: small, gray, bold sans-serif text on a dark blue
235 (Small text on a white background.)
237 :Main content: black serif text on a white background
238 :Text capacity: about 15 lines
239 :Headers: black, bold sans-serif text on a white background;
241 :Footers: small, dark gray, bold sans-serif text on a white
245 :Main content: white serif text on a black background
246 :Text capacity: about 15 lines
247 :Headers: white, bold sans-serif text on a black background;
249 :Footers: small, light gray, bold sans-serif text on a black
253 :Main content: black serif text on a white background
254 :Text capacity: about 9 lines
255 :Headers: black, bold sans-serif text on a white background;
257 :Footers: small, dark gray, bold sans-serif text on a white
261 :Main content: white serif text on a black background
262 :Text capacity: about 9 lines
263 :Headers: white, bold sans-serif text on a black background;
265 :Footers: small, light gray, bold sans-serif text on a black
269 :Main content: black, bold sans-serif text on a white background
270 :Text capacity: about 5 lines
271 :Headers: black, bold sans-serif text on a white background;
273 :Footers: not displayed
276 :Main content: white, bold sans-serif text on a black background
277 :Text capacity: about 5 lines
278 :Headers: white, bold sans-serif text on a black background;
280 :Footers: not displayed
282 If a theme directory contains a file named ``__base__``, the name of
283 the theme's base theme will be read from it. Files are accumulated
284 from the named theme, any base themes, and the "default" theme (which
285 is the implicit base of all themes).
287 For details, please see `Easy Slide Shows With reStructuredText &
288 S5 <slide-shows.html>`_.
291 LaTeX-Generating Tools
292 ======================
298 :Parser: reStructuredText
301 The ``rst2latex.py`` front end reads standalone reStructuredText
302 source files and produces LaTeX2e output. For example, to process a
303 reStructuredText file "``test.txt``" into LaTeX::
305 rst2latex.py test.txt test.tex
307 The output file "``test.tex``" should then be processed with ``latex``
308 or ``pdflatex`` to get a document in DVI, PostScript or PDF format for
309 printing or on-screen viewing.
311 For details see `Generating LaTeX with Docutils`_.
321 :Parser: reStructuredText
322 :Writer: XML (Docutils native)
324 The ``rst2xml.py`` front end produces Docutils-native XML output.
325 This can be transformed with standard XML tools such as XSLT
326 processors into arbitrary final forms. An example is the xml2rst_ processor
327 in the Docutils sandbox.
329 .. _xml2rst: ../../../sandbox/xml2rst
332 ODF/OpenOffice-Generating Tools
333 ===============================
339 :Parser: reStructuredText
342 The ``rst2odt.py`` front end reads standalone reStructuredText
343 source files and produces ODF/.odt files that can be read, edited,
344 printed, etc with OpenOffice ``oowriter``
345 (http://www.openoffice.org/). A stylesheet file is required. A
346 stylesheet file is an OpenOffice .odt file containing definitions
347 of the styles required for ``rst2odt.py``. You can learn more
348 about how to use ``rst2odt.py``, the styles used ``rst2odt.py``,
349 etc from `Odt Writer for Docutils <odt.html>`_.
352 reStructuredText-Generating Tools
353 =================================
355 Currently, there is no reStructuredText writer in Docutils and therefore
356 an ``rst2rst.py`` tool is still missing.
358 To generate reStructuredText documents with Docutils, you can use
359 the XML (Docutils native) writer and the xml2rst_ processor.
362 Testing/Debugging Tools
363 =======================
369 :Parser: reStructuredText
372 ``rst2pseudoxml.py`` is used for debugging the Docutils "Reader to
373 Transform to Writer" pipeline. It produces a compact pretty-printed
374 "pseudo-XML", where nesting is indicated by indentation (no end-tags).
375 External attributes for all elements are output, and internal
376 attributes for any leftover "pending" elements are also given.
383 :Parser: reStructuredText
386 The ``quicktest.py`` tool is used for testing the reStructuredText
387 parser. It does not use a Docutils Reader or Writer or the standard
388 Docutils command-line options. Rather, it does its own I/O and calls
389 the parser directly. No transforms are applied to the parsed
390 document. Various forms output are possible:
392 - Pretty-printed pseudo-XML (default)
393 - Test data (Python list of input and pseudo-XML output strings;
394 useful for creating new test cases)
395 - Pretty-printed native XML
396 - Raw native XML (with or without a stylesheet reference)
407 Each front-end tool supports command-line options for one-off
408 customization. For persistent customization, use `configuration
409 files`_. Command-line options take priority over configuration file
412 Use the "--help" option on each of the front ends to list the
413 command-line options it supports. Command-line options and their
414 corresponding configuration file entry names are listed in the
415 `Docutils Configuration Files`_ document.
418 .. _configuration file:
423 Configuration files are used for persistent customization; they can be
424 set once and take effect every time you use a front-end tool.
426 For details, see `Docutils Configuration Files`_.
428 .. _Docutils Configuration Files: config.html
429 .. _Generating LaTeX with Docutils: latex.html
434 indent-tabs-mode: nil
435 sentence-end-double-space: t