==========================
 Docutils Front-End Tools
==========================

:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Revision: $Revision: 1.46 $
:Date: $Date: 2004/07/27 16:36:24 $
: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: