==========================
 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 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
=========

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/support/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/support/`` 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


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:
