diff options
Diffstat (limited to 'docs/user/tools.txt')
| -rw-r--r-- | docs/user/tools.txt | 389 |
1 files changed, 389 insertions, 0 deletions
diff --git a/docs/user/tools.txt b/docs/user/tools.txt new file mode 100644 index 000000000..20f5a3b2f --- /dev/null +++ b/docs/user/tools.txt @@ -0,0 +1,389 @@ +========================== + Docutils Front-End Tools +========================== + +:Author: David Goodger +:Contact: goodger@python.org +: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 rstpep2html.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. + +.. _Docutils-users: mailing-lists.html#docutils-users + + +----------- + The Tools +----------- + +HTML-Generating 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 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 that support cascading stylesheets (CSS). A stylesheet is +required for proper rendering; a simple but complete stylesheet is +installed and used by default (see Stylesheets_ below). + +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 project, add some options:: + + rst2html.py -stg test.txt test.html + + +Stylesheets +``````````` + +``rst2html.py`` inserts into the generated HTML a cascading stylesheet +(or a link to a stylesheet, when passing the "``--link-stylesheet``" +option). A stylesheet is required for proper rendering. The default +stylesheet (``docutils/writers/html4css1/html4css1.css``, located in +the installation directory) is provided for basic use. To use a +different stylesheet, you must specify the stylesheet's location with +a "``--stylesheet``" (for a URL) or "``--stylesheet-path``" (for a +local file) command-line option, or with `configuration file`_ +settings (e.g. ``./docutils.conf`` or ``~/.docutils``). To experiment +with styles, please see the `guide to writing HTML (CSS) stylesheets +for Docutils`__. + +__ ../howto/html-stylesheets.html + + +rstpep2html.py +-------------- + +:Reader: PEP +:Parser: reStructuredText +:Writer: PEP/HTML + +``rstpep2html.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 the "``pep.css``" stylesheet (both in the +``docutils/writers/pep_html/`` directory), but these can be overridden +by command-line options or configuration files. + +For example, to process a PEP into HTML:: + + cd <path-to-docutils>/docs/peps + rstpep2html.py pep-0287.txt pep-0287.html + + +rst2s5.py +--------- + +:Reader: Standalone +:Parser: reStructuredText +:Writer: S5/HTML + +The ``rst2s5.py`` front end reads standalone reStructuredText source +files and produces (X)HTML output compatible with S5_, the "Simple +Standards-based Slide Show System" by Eric Meyer. A theme is required +for proper rendering; several are distributed with Docutils and others +are available; see Themes_ below. + +For example, to process a reStructuredText file "``slides.txt``" into +S5/HTML:: + + rst2s5.py slides.txt slides.html + +Now open the "``slides.html``" file in your favorite browser, switch +to full-screen mode, and enjoy the results. + +.. _S5: http://meyerweb.com/eric/tools/s5/ + + +Themes +`````` + +Each S5 theme consists of a directory containing several files: +stylesheets, JavaScript, and graphics. These are copied into a +``ui/<theme>`` directory beside the generated HTML. A theme is chosen +using the "``--theme``" option (for themes that come with Docutils) or +the "``--theme-url``" option (for themes anywhere). For example, the +"medium-black" theme can be specified as follows:: + + rst2s5.py --theme medium-black slides.txt slides.html + +The theme will be copied to the ``ui/medium-black`` directory. + +Several themes are included with Docutils: + +``default`` + This is a simplified version of S5's default theme. + + :Main content: black serif text on a white background + :Text capacity: about 13 lines + :Headers: light blue, bold sans-serif text on a dark blue + background; titles are limited to one line + :Footers: small, gray, bold sans-serif text on a dark blue + background + +``small-white`` + (Small text on a white background.) + + :Main content: black serif text on a white background + :Text capacity: about 15 lines + :Headers: black, bold sans-serif text on a white background; + titles wrap + :Footers: small, dark gray, bold sans-serif text on a white + background + +``small-black`` + :Main content: white serif text on a black background + :Text capacity: about 15 lines + :Headers: white, bold sans-serif text on a black background; + titles wrap + :Footers: small, light gray, bold sans-serif text on a black + background + +``medium-white`` + :Main content: black serif text on a white background + :Text capacity: about 9 lines + :Headers: black, bold sans-serif text on a white background; + titles wrap + :Footers: small, dark gray, bold sans-serif text on a white + background + +``medium-black`` + :Main content: white serif text on a black background + :Text capacity: about 9 lines + :Headers: white, bold sans-serif text on a black background; + titles wrap + :Footers: small, light gray, bold sans-serif text on a black + background + +``big-white`` + :Main content: black, bold sans-serif text on a white background + :Text capacity: about 5 lines + :Headers: black, bold sans-serif text on a white background; + titles wrap + :Footers: not displayed + +``big-black`` + :Main content: white, bold sans-serif text on a black background + :Text capacity: about 5 lines + :Headers: white, bold sans-serif text on a black background; + titles wrap + :Footers: not displayed + +If a theme directory contains a file named ``__base__``, the name of +the theme's base theme will be read from it. Files are accumulated +from the named theme, any base themes, and the "default" theme (which +is the implicit base of all themes). + +For details, please see `Easy Slide Shows With reStructuredText & +S5 <slide-shows.html>`_. + + +LaTeX-Generating Tools +====================== + +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`_. + + +XML-Generating Tools +==================== + +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. + + +Testing/Debugging Tools +======================= + +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: |