diff options
Diffstat (limited to 'docs/user/tools.txt')
| -rw-r--r-- | docs/user/tools.txt | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/docs/user/tools.txt b/docs/user/tools.txt new file mode 100644 index 000000000..ab31e0917 --- /dev/null +++ b/docs/user/tools.txt @@ -0,0 +1,316 @@ +========================== + Docutils Front-End Tools +========================== + +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:Revision: $Revision$ +:Date: $Date$ +:Copyright: This document has been placed in the public domain. + +.. contents:: + + +Introduction +============ + +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. + + +Getting Help +------------ + +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. + +.. _post a message: mailto:docutils-users@lists.sourceforge.net +.. _Docutils-Users mailing list: + http://lists.sourceforge.net/lists/listinfo/docutils-users +.. _Docutils project web site: http://docutils.sourceforge.net/ + + +The Tools +========= + +buildhtml.py +------------ + +: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 +(docs/user/rst/demo.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. + + +rst2html.py +----------- + +: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 + +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 + + +Stylesheets +``````````` + +``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. + + +pep.py +------ + +: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 "``tools``" +directory of Docutils contains a default setup for use in processing +the PEP files (``docs/peps/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. + +``pep.py`` can be run from the ``tools`` directory or from the +``docs/peps/`` directory, by adjusting the settings. These two sets +of commands are equivalent:: + + cd <path-to-docutils>/tools + # This will pick up the "docutils.conf" file automatically: + pep.py ../docs/peps/pep-0287.txt ../docs/peps/pep-0287.html + + cd <path-to-docutils>/docs/peps + # Must tell the tool where to find the config file: + ../../tools/pep.py --config ../../tools/docutils.conf \ + pep-0287.txt pep-0287.html + + +pep2html.py +----------- + +: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. + + +rst2latex.py +------------ + +: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: + +- GIF, JPG and PNG images are not handled, when processed with + ``latex``; use ``pdflatex`` instead. +- Only the Latin-1 output encoding has been tested up to now (Latin-1 + has been made the default output encoding for LaTeX). +- The optional stylesheet file allows the inclusion of special packages + or overwriting default settings for LaTeX. +- Not all constructs are possible, see `Generating LaTeX with Docutils`_. + + +rst2xml.py +---------- + +:Reader: Standalone +:Parser: reStructuredText +:Writer: XML (Docutils native) + +The ``rst2xml.py`` front end produces Docutils-native XML output. +This can be transformed with standard XML tools such as XSLT +processors into arbitrary final forms. + + +rst2pseudoxml.py +---------------- + +:Reader: Standalone +:Parser: reStructuredText +:Writer: Pseudo-XML + +``rst2pseudoxml.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. + + +quicktest.py +------------ + +: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: + +- Pretty-printed pseudo-XML (default) +- Test data (Python list of input and pseudo-XML output strings; + useful for creating new test cases) +- Pretty-printed native XML +- Raw native XML (with or without a stylesheet reference) + + + +Customization +============= + +Command-Line Options +-------------------- + +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 file: + +Configuration Files +------------------- + +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`_. + +.. _Docutils Configuration Files: config.html +.. _Generating LaTeX with Docutils: latex.html + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + End: |