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

:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Revision: $Revision: 1.42 $
:Date: $Date: 2004/04/16 15:11:41 $
: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
(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.


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

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


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 "``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.


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 generated file includes a file ``style.tex``, which allows the
  inclusion of special packages or changes to settings made in the
  header.
- Not all constructs are possible (e.g. row/column spans in tables are
  not).


docutils-xml.py
---------------

: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.


publish.py
----------

: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.


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


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End:
