Author: | David Goodger |
---|---|
Contact: | goodger@users.sourceforge.net |
Revision: | 1.42 |
Date: | 2004-04-16 |
Copyright: | This document has been placed in the public domain. |
Once the Docutils package is unpacked, you will discover a "tools" directory containing several front ends for common Docutils processing. Rather than a single all-purpose program, Docutils has many small front ends, each specialized for a specific "Reader" (which knows how to interpret a file in context), a "Parser" (which understands the syntax of the text), and a "Writer" (which knows how to generate a specific data format).
Most front ends have common options and the same command-line usage pattern:
toolname [options] [<source> [<destination]]
(The exceptions are buildhtml.py and pep2html.py.) See rst2html.py for concrete examples. Each tool has a "--help" option which lists the command-line options and arguments it supports. Processing can also be customized with configuration files.
The two arguments, "source" and "destination", are optional. If only one argument (source) is specified, the standard output (stdout) is used for the destination. If no arguments are specified, the standard input (stdin) is used for the source as well.
First, try the "--help" option each front-end tool has.
Users who have questions or need assistance with Docutils or reStructuredText should post a message to the Docutils-Users mailing list. The Docutils project web site has more information.
Readers: | Standalone, PEP |
---|---|
Parser: | reStructuredText |
Writers: | HTML, PEP/HTML |
Use buildhtml.py to generate .html from all the .txt files (including PEPs) in each <directory> given, and their subdirectories too. (Use the --local option to skip subdirectories.)
Usage:
buildhtml.py [options] [<directory> ...]
After unpacking the Docutils package, the following shell commands will generate HTML for all included documentation:
cd docutils/tools buildhtml.py ..
For official releases, the directory may be called "docutils-X.Y", where "X.Y" is the release version. Alternatively:
cd docutils tools/buildhtml.py --config=tools/docutils.conf
The current directory (and all subdirectories) is chosen by default if no directory is named. Some files may generate system messages (tools/test.txt contains intentional errors); use the --quiet option to suppress all warnings. The --config option ensures that the correct stylesheets, templates, and settings are in place (a docutils.conf configuration file in the current directory is picked up automatically). Command-line options may be used to override config file settings or replace them altogether.
Reader: | Standalone |
---|---|
Parser: | reStructuredText |
Writer: | HTML |
The rst2html.py front end reads standalone reStructuredText source files and produces HTML 4 (XHTML 1) output compatible with modern browsers. For example, to process a reStructuredText file "test.txt" into HTML:
rst2html.py test.txt test.html
In fact, there is a "test.txt" file in the "tools" directory. It contains "at least one example of each reStructuredText construct", including several intentional errors (to test the error reporting system). Use it to put the system through its paces and compare input to output.
Now open the "test.html" file in your favorite browser to see the results. To get a footer with a link to the source file, date & time of processing, and links to the Docutils projects, add some options:
rst2html.py -stg test.txt test.html
rst2html.py inserts into the generated HTML a link to a cascading stylesheet, defaulting to "default.css" (override with a "--stylesheet" or "--stylesheet-path" command-line option or with configuration file settings). The "tools/stylesheets/default.css" stylesheet is provided for basic use. To experiment with styles, rather than editing the default stylesheet (which will be updated as the project evolves), it is recommended to use an "@import" statement to create a "wrapper" stylesheet. For example, a "my.css" stylesheet could contain the following:
@import url(default.css); h1, h2, h3, h4, h5, h6, p.topic-title { font-family: sans-serif }
Generate HTML with the following command:
rst2html.py -stg --stylesheet my.css test.txt test.html
When viewed in a browser, the new "wrapper" stylesheet will change the typeface family of titles to "sans serif", typically Helvetica or Arial. Other styles will not be affected. Styles in wrapper stylesheets override styles in imported stylesheets, enabling incremental experimentation.
Reader: | PEP |
---|---|
Parser: | reStructuredText |
Writer: | PEP/HTML |
pep.py reads a new-style PEP (marked up with reStructuredText) and produces HTML. It requires a template file and a stylesheet. By default, it makes use of a "pep-html-template" file and a "default.css" stylesheet in the current directory, but these can be overridden by command-line options or configuration files. The "tools/stylesheets/pep.css" stylesheet is intended specifically for PEP use.
The "docutils.conf" configuration file in the "spec" directory of Docutils contains a default setup for use in processing the PEP files there (spec/pep-*.txt) into HTML. It specifies a default template (tools/pep-html-template) and a default stylesheet (tools/stylesheets/pep.css). See Stylesheets above for more information.
Reader: | PEP |
---|---|
Parser: | reStructuredText |
Writer: | PEP/HTML |
pep2html.py is a modified version of the original script by Fredrik Lundh, with support for Docutils added. It reads the beginning of a PEP text file to determine the format (old-style indented or new-style reStructuredText) and processes accordingly. Since it does not use the Docutils front end mechanism (the common command-line options are not supported), it can only be configured using configuration files. The template and stylesheet requirements of pep2html.py are the same as those of pep.py above.
Arguments to pep2html.py may be a list of PEP numbers or .txt files. If no arguments are given, all files of the form "pep-*.txt" are processed.
Reader: | Standalone |
---|---|
Parser: | reStructuredText |
Writer: | LaTeX2e |
The rst2latex.py front end reads standalone reStructuredText source files and produces LaTeX2e output. For example, to process a reStructuredText file "test.txt" into LaTeX:
rst2latex.py test.txt test.tex
The output file "test.tex" should then be processed with latex or pdflatex to get a typeset document.
Some limitations and difference apply:
Reader: | Standalone |
---|---|
Parser: | reStructuredText |
Writer: | XML (Docutils native) |
The docutils-xml.py front end produces Docutils-native XML output. This can be transformed with standard XML tools such as XSLT processors into arbitrary final forms.
Reader: | Standalone |
---|---|
Parser: | reStructuredText |
Writer: | Pseudo-XML |
publish.py is used for debugging the Docutils "Reader to Transform to Writer" pipeline. It produces a compact pretty-printed "pseudo-XML", where nesting is indicated by indentation (no end-tags). External attributes for all elements are output, and internal attributes for any leftover "pending" elements are also given.
Reader: | N/A |
---|---|
Parser: | reStructuredText |
Writer: | N/A |
The quicktest.py tool is used for testing the reStructuredText parser. It does not use a Docutils Reader or Writer or the standard Docutils command-line options. Rather, it does its own I/O and calls the parser directly. No transforms are applied to the parsed document. Various forms output are possible:
Each front-end tool supports command-line options for one-off customization. For persistent customization, use configuration files. Command-line options take priority over configuration file settings.
Use the "--help" option on each of the front ends to list the command-line options it supports. Command-line options and their corresponding configuration file entry names are listed in the Docutils Configuration Files document.
Configuration files are used for persistent customization; they can be set once and take effect every time you use a front-end tool.
For details, see Docutils Configuration Files.