[Zope-Checkins] CVS: Zope/lib/python/third_party/docutils/docs/user - config.txt: latex.txt: tools.txt:

Andreas Jung andreas at andreas-jung.com
Fri Oct 29 14:24:49 EDT 2004

Update of /cvs-repository/Zope/lib/python/third_party/docutils/docs/user
In directory cvs.zope.org:/tmp/cvs-serv11767/docutils/docs/user

Added Files:
      Tag: ajung-docutils-cleanup-branch
	config.txt latex.txt tools.txt 
Log Message:

=== Added File Zope/lib/python/third_party/docutils/docs/user/config.txt ===
 Docutils Configuration Files

:Author: David Goodger
:Contact: goodger at python.org
:Revision: $Revision: $
:Date: $Date: 2004/10/29 18:24:48 $
:Copyright: This document has been placed in the public domain.

.. contents::

.. Cross-reference command-line options with configuration file
   settings?  Make alphabetical indexes of both.

Configuration files are used for persistent customization; they can be
set once and take effect every time you use a front-end tool.
Configuration file settings override the built-in defaults, and
command-line options override all.

By default, Docutils checks the following places for configuration
files, in the following order:

1. ``/etc/docutils.conf``: This is a system-wide configuration file,
   applicable to all Docutils processing on the system.

2. ``./docutils.conf``: This is a project-specific configuration file,
   located in the current directory.  The Docutils front end has to be
   executed from the directory containing this configuration file for
   it to take effect (note that this may have nothing to do with the
   location of the source files).  Settings in the project-specific
   configuration file will override corresponding settings in the
   system-wide file.

3. ``~/.docutils``: This is a user-specific configuration file,
   located in the user's home directory.  Settings in this file will
   override corresponding settings in both the system-wide and
   project-specific configuration files.

If more than one configuration file is found, all will be read but
later entries will override earlier ones.  For example, a "stylesheet"
entry in a user-specific configuration file will override a
"stylesheet" entry in the system-wide file.

The default implicit config file paths can be overridden by the
``DOCUTILSCONFIG`` environment variable.  ``DOCUTILSCONFIG`` should
contain a colon-separated (semicolon-separated on Windows) sequence of
config file paths to search for; leave it empty to disable implicit
config files altogether.  Tilde-expansion is performed on paths.
Paths are interpreted relative to the current working directory.
Empty path items are ignored.

In addition, a configuration file may be explicitly specified with the
"--config" command-line option.  This configuration file is read after
the three implicit ones listed above (or the ones defined by the
``DOCUTILSCONFIG`` environment variable), and its entries will have

Configuration File Syntax

Configuration files use the standard ConfigParser.py_ Python_ module.
>From its documentation:

    The configuration file consists of sections, lead by a "[section]"
    header and followed by "name: value" entries, with continuations
    in the style of `RFC 822`_; "name=value" is also accepted.  Note
    that leading whitespace is removed from values.  ...  Lines
    beginning with "#" or ";" are ignored and may be used to provide

.. Note:: No format string interpolation is done.

Configuration file entry names correspond to internal runtime
settings.  Underscores ("_") and hyphens ("-") can be used
interchangably in entry names; hyphens are automatically converted to

For on/off switch settings (booleans), the following values are

* On: "true", "yes", "on", "1"
* Off: "false", "no", "off", "0", "" (no value)

Configuration File Sections & Entries

Below are the Docutils runtime settings, listed by config file
section.  Any setting may be specified in any section, but only
settings from active sections will be used.  Sections correspond to
Docutils components (module name or alias; section names are always in
lowercase letters).  Each `Docutils application`_ uses a specific set
of components; corresponding configuration file sections are applied
when the application is used.  Configuration sections are applied in
general-to-specific order, as follows:

1. `[general]`_

2. `[parsers]`_, parser dependencies, and the section specific to the
   Parser used ("[... parser]").  Currently, only `[restructuredtext
   parser]`_ is applicable.

3. `[readers]`_, reader dependencies, and the section specific to the
   Reader used ("[... reader]").  For example, `[pep reader]`_ depends
   on `[standalone reader]`_.

4. `[writers]`_, writer dependencies, and the section specific to the
   Writer used ("[... writer]").  For example, `[pep_html writer]`_
   depends on `[html4css1 writer]`_.

5. `[applications]`_, application dependencies, and the section
    specific to the Application (front-end tool) in use
    ("[... application]").

Since any setting may be specified in any section, this ordering
allows component- or application-specific overrides of earlier
settings.  For example, there may be Reader-specific overrides of
general settings; Writer-specific overrides of Parser settings;
Application-specific overrides of Writer settings; and so on.

If multiple configuration files are applicable, the process is
completed (all sections are applied in the order given) for each one
before going on to the next.  For example, a "[pep_html writer]
stylesheet" setting in an earlier configuration file would be
overridden by an "[html4css1 writer] stylesheet" setting in a later

Some knowledge of Python_ is assumed for some attributes.

.. _ConfigParser.py:
.. _Python: http://www.python.org/
.. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt
.. _Docutils application: tools.html


Settings in the "[general]" section are always applied.

    Include a time/datestamp in the document footer.  Contains a
    format string for Python's ``time.strftime``.  See the `time
    module documentation`__.

    Default: None.  Options: ``--date, -d, --time, -t,

    Configuration file entry examples::

        # Equivalent to --date command-line option, results in
        # ISO 8601 extended format datestamp, e.g. "2001-12-21":
        datestamp: %Y-%m-%d

        # Equivalent to --time command-line option, results in
        # date/timestamp like "2001-12-21 18:43 UTC":
        datestamp: %Y-%m-%d %H:%M UTC

        # Disables datestamp; equivalent to --no-datestamp:

    __ http://www.python.org/doc/current/lib/module-time.html

    Report debug-level system messages.

    Default: don't (None).  Options: ``--debug, --no-debug``.

    At the end of processing, write all internal attributes of the
    document (``document.__dict__``) to stderr.

    Default: don't (None).  Options: ``--dump-internals`` (hidden, for
    development use only).

    At the end of processing, write the pseudo-XML representation of
    the document to stderr.

    Default: don't (None).  Options: ``--dump-pseudo-xml`` (hidden,
    for development use only).

    At the end of processing, write all Docutils settings to stderr.

    Default: don't (None).  Options: ``--dump-settings`` (hidden, for
    development use only).

    At the end of processing, write a list of all transforms applied
    to the document to stderr.

    Default: don't (None).  Options: ``--dump-transforms`` (hidden,
    for development use only).

    The text encoding for error output.

    Default: "ascii".  Options: ``--error-encoding, -e``.

    The error handler for unencodable characters in error output.  See
    output_encoding_error_handler_ for acceptable values.

    Default: "backslashreplace" for Python 2.3 and later; "replace"
    otherwise.  Options: ``--error-encoding-error-handler,
    --error-encoding, -e``.

    A system message level threshold; non-halting system messages at
    or above this level will produce a non-zero exit status at normal
    exit.  Exit status is the maximum system message level plus 10 (11
    for INFO, etc.).

    Default: disabled (5).  Options: ``--exit-status``.

    List of internal attribues to expose as external attributes (with
    "internal:" namespace prefix).  To specify multiple attributes in
    configuration files, use colons to separate names; on the command
    line, the option may be used more than once.

    Default: don't (None).  Options: ``--expose-internal-attribute``
    (hidden, for development use only).

    Enable or disable backlinks from footnotes and citations to their

    Default: enabled (1).  Options: ``--footnote-backlinks,

    Include a "Generated by Docutils" credit and link in the document

    Default: off (None).  Options: ``--generator, -g,

    The threshold at or above which system messages are converted to
    exceptions, halting execution immediately.  If `traceback`_ is
    set, the exception will propagate; otherwise, Docutils will exit.

    Default: severe (4).  Options: ``--halt, --strict``.

    The text encoding for input.

    Default: auto-detect (None).  Options: ``--input-encoding, -i``.

    `ISO 639`_ 2-letter language code (3-letter codes used only if no
    2-letter code exists).

    Default: English ("en").  Options: ``--language, -l``.

    The text encoding for output.

    Default: "UTF-8".  Options: ``--output-encoding, -o``.

    The error handler for unencodable characters in the output.
    Acceptable values include:

        Raise an exception in case of an encoding error.
        Replace malformed data with a suitable replacement marker,
        such as "?".
        Ignore malformed data and continue without further notice.
        Replace with the appropriate XML character reference, such as
        (Python 2.3+)  Replace with backslashed escape sequences, such
        as "``\u2020``".

    Acceptable values are the same as for the "error" parameter of
    Python's ``encode`` string method; other values may be defined in
    applications or in future versions of Python.

    Default: "strict".  Options: ``--output-encoding-error-handler,
    --output-encoding, -o``.

    Verbosity threshold at or above which system messages are

    Default: warning (2).  Options: ``--report, -r, --verbose, -v,
    --quiet, -q``.

    Enable or disable the section numbering transform

    Default: enabled (1).  Options: ``--no-section-numbering``.

    Include a "View document source" link in the document footer.  URL
    will be relative to the destination.

    Default: don't (None).  Options: ``--source-link, -s,

    An explicit URL for a "View document source" link, used verbatim.

    Default: compute if source_link (None).  Options: ``--source-url,

    Enable backlinks from section titles to table of contents entries
    ("entry"), to the top of the TOC ("top"), or disable ("none").

    Default: "entry".  Options: ``--toc-entry-backlinks,
    --toc-top-backlinks, --no-toc-backlinks``.

    Enable Python tracebacks when halt-level system messages and other
    exceptions occur.  Useful for debugging, and essential for issue
    reports.  Exceptions are allowed to propagate, instead of being
    caught and reported (in a user-friendly way) by Docutils.

    Default: disabled (None).  Options: ``--traceback,

    Path to a file for the output of system messages (warnings)

    Default: stderr (None).  Options: ``--warnings``.


Docutils currently supports only one parser, for reStructuredText.

[restructuredtext parser]

    Recognize and link to standalone PEP references (like "PEP 258").

    Default: disabled (None); enabled (1) in PEP Reader.  Options:

    Base URL for PEP references.  

    Default: "http://www.python.org/peps/".  Option:

    Recognize and link to standalone RFC references (like "RFC 822").

    Default: disabled (None); enabled (1) in PEP Reader.  Options:

    Base URL for RFC references.  

    Default: "http://www.faqs.org/rfcs/".  Option: ``--rfc-base-url``.

    Number of spaces for hard tab expansion.

    Default: 8.  Options: ``--tab-width``.

    Remove spaces before footnote references.

    Default: don't (None).  Options:


[standalone reader]

    Enable or disable the bibliographic field list transform

    Default: enabled (1).  Options: ``--no-doc-info``.

    Enable or disable the promotion of a lone top-level section title
    to document title (and subsequent section title to document
    subtitle promotion; docutils.transforms.frontmatter.DocTitle).

    Default: enabled (1).  Options: ``--no-doc-title``.

[pep reader]

The `pep_references`_ and `rfc_references`_ options
(`[restructuredtext parser]`_) are set on by default.

[python reader]

Under construction.


[docutils_xml writer]

    Generate XML with a DOCTYPE declaration.

    Default: do (1).  Options: ``--no-doctype``.

    Generate XML with indents and newlines.

    Default: don't (None).  Options: ``--indents``.

    Generate XML with newlines before and after tags.

    Default: don't (None).  Options: ``--newlines``.

.. _xml_declaration [docutils_xml writer]:

    Generate XML with an XML declaration.  Also defined for the
    `HTML Writer`__.

    .. Caution:: The XML declaration carries text encoding
       information, without which standard tools may be unable to read
       the generated XML.

    Default: do (1).  Options: ``--no-xml-declaration``.

    __ `xml_declaration [html4css1 writer]`_

[html4css1 writer]

.. _attribution [html4css1 writer]:

    Format for block quote attributions: one of "dash" (em-dash
    prefix), "parentheses"/"parens", or "none".  Also defined for the
    `LaTeX Writer`__.

    Default: "dash".  Options: ``--attribution``.

    __ `attribution [latex2e writer]`_

    Remove extra vertical whitespace between items of bullet lists and
    enumerated lists, when list items are "simple" (i.e., all items
    each contain one paragraph and/or one "simple" sublist only).

    Default: enabled (1).  Options: ``--compact-lists,

    Embed the stylesheet in the output HTML file.  The stylesheet file
    must be accessible during processing.

    Default: link, don't embed (None).  Options: ``--embed-stylesheet,

.. _footnote_references [html4css1 writer]:

    Format for footnote references, one of "superscript" or
    "brackets".  Also defined for the `LaTeX Writer`__.

    Default: "superscript"; "brackets" in PEP/HTML Writer.  Options:

    __ `footnote_references [latex2e writer]`_

    The initial level for header elements.  This does not affect the
    document title & subtitle; see doctitle_xform_.

    Default: 1 (for "<h1>").  Option: ``--initial-header-level``.

.. _stylesheet [html4css1 writer]:

    CSS stylesheet URL, used verbatim.  Overridden by the
    "stylesheet_path" setting (``--stylesheet-path``).  However, an
    earlier file's "stylesheet-path" setting can be overriden by a
    later config file's "stylesheet" by nullifying "stylesheet-path"
    in the later file::


    On the command line, use ``--stylesheet-path=''``.

    Default: "default.css".  Options: ``--stylesheet``.

    (Setting also defined for the `LaTeX Writer`__.)

    __ `stylesheet [latex2e writer]`_

.. _stylesheet_path [html4css1 writer]:

    Path to CSS stylesheet [#pwd]_.  Overrides "stylesheet" URL
    setting (``--stylesheet``).  Path is adjusted relative to the
    output HTML file.  Also defined for the `LaTeX Writer`__.

    Default: None.  Options: ``--stylesheet-path``.

    __ `stylesheet_path [latex2e writer]`_

.. _xml_declaration [html4css1 writer]:

    Generate XML with an XML declaration.  Also defined for the
    `Docutils XML Writer`__.

    .. Caution:: The XML declaration carries text encoding
       information, without which standard tools may be unable to read
       the generated XML.

    Default: do (1).  Options: ``--no-xml-declaration``.

    __ `xml_declaration [docutils_xml writer]`_

[pep_html writer]

The PEP/HTML Writer derives from the standard HTML Writer, and shares
all settings defined in the `[html4css1 writer]`_ section.  The
"[html4css1 writer]" section is processed before "[pep_html writer]".

    Workaround for platforms which core-dump on "``import random``".

    Default: random enabled (None).  Options: ``--no-random``

    Home URL prefix for PEPs.

    Default: current directory (".").  Options: ``--pep-home``.

    Path to PEP template file [#pwd]_.

    Default: "pep-html-template" (in current directory).  Options:

    Python's home URL.

    Default: parent directory ("..").  Options: ``--python-home``.

[latex2e writer]

    To get pagenumbers in the table of contents the table of contents
    must be generated by latex. Usually latex must be run twice to get
    numbers correct.

    *Note:* LaTeX will number the sections, which might be a bug in
    this case.

    Default: off.  Option: ``--use-latex-toc``.

.. XXX Missing: use_latex_docinfo

    Use LaTeX-footnotes not a figure simulation. This might give no
    Hyperrefs on /to footnotes, but should be able to handle an
    unlimited number of footnotes.

    Default: off.  Option: ``--use-latex-footnotes``.

    Color of any hyperlinks embedded in text. Use "0" to disable
    coloring of links.

    Default: "blue", use "0" to disable.  Option:

    Specify latex documentclass, *but* beaware that books have chapters
    articles not.

    Default: "article".  Option: ``--documentclass``.

    Specify document options.  Multiple options can be given, separated by

    Default is "10pt".  Option: ``--documentoptions``.

.. _stylesheet [latex2e writer]:

    Specify a stylesheet file. The file will be ``input`` by latex in
    the document header. If this is set to "" disables generation of
    input latex command.  Also defined for the `HTML Writer`__.

    Default: no stylesheet ("").  Option: ``--stylesheet``.

    __ `stylesheet [html4css1 writer]`_

.. _stylesheet_path [latex2e writer]:

    Path to stylesheet [#pwd]_.  Overrides "stylesheet" setting
    (``--stylesheet``).  XXX LaTeX semantics?  Also defined for the
    `HTML Writer`__.

    Default: None.  Option: ``--stylesheet-path``.

    __ `stylesheet_path [html4css1 writer]`_

.. XXX Missing: embed_stylesheet

.. _footnote_references [latex2e writer]:

    Format for footnote references: one of "superscript" or
    "brackets".  Also defined for the `HTML Writer`__.

    Default is "brackets".  Option: ``--footnote-references``.

    __ `footnote_references [html4css1 writer]`_

.. _attribution [latex2e writer]:

    Format for block quote attributions, the same as for the
    html-writer: one of "dash" (em-dash prefix),
    "parentheses"/"parens" or "none".  Also defined for the `HTML

    Default: "dash".  Option: ``--attribution``.

    __ `attribution [html4css1 writer]`_

    Enable or disable compound enumerators for nested enumerated lists
    (e.g. "1.2.a.ii").

    Default: disabled (None).  Options: ``--compound-enumerators``,

    Enable or disable section ("." subsection ...) prefixes for
    compound enumerators.  This has no effect unless
    `compound_enumerators`_ are enabled.
    Default: disabled (None).  Options:

    The separator between section number prefix and enumerator for
    compound enumerated lists (see `compound_enumerators`_).

    Generally it isn't recommended to use both sub-sections and nested
    enumerated lists with compound enumerators.  This setting avoids
    ambiguity in the situation where a section "1" has a list item
    enumerated "1.1", and subsection "1.1" has list item "1".  With a
    separator of ".", these both would translate into a final compound
    enumerator of "1.1.1".  With a separator of "-", we get the
    unambiguous "1-1.1" and "1.1-1".

    Default: "-".  Option: ``--section-enumerator-separator``.

    Specify the drawing of separation lines.

    - "standard" lines around and between cells.
    - "booktabs" a line above and below the table and one after the
    - "nolines".

[pseudoxml writer]

No settings are defined for this Writer.


[buildhtml application]

    List of directories not to process.  To specify multiple
    directories in configuration files, use colon-separated paths; on
    the command line, the option may be used more than once.

    Default: none ([]).  Options: ``--prune``.

    Recursively scan subdirectories, or ignore subdirectories.

    Default: recurse (1).  Options: ``--recurse, --local``.

    Work silently (no progress messages).  Independent of

    Default: show progress (None).  Options: ``--silent``.

[docfactory application]

(To be completed.)

Other Settings

These settings are only effective as command-line options, positional
arguments, or for internal use; setting them in configuration files
has no effect.

    Path to a configuration file to read (if it exists) [#pwd]_.
    Settings may override defaults and earlier settings.  The config
    file is processed immediately.  Multiple ``--config`` options may
    be specified; each will be processed in turn.

    Filesystem path settings contained within the config file will be
    interpreted relative to the config file's location (*not* relative
    to the current working directory).

    Default: None.  Options: ``--config``.

    (``buildhtml.py`` front end.)  List of paths to source
    directories, set from positional arguments.

    Default: current working directory (None).  No command-line

    Prevent standard configuration files from being read.  For
    internal use only.

    Default: config files enabled (None).  No command-line options.

    Path to output destination, set from positional arguments.

    Default: stdout (None).  No command-line options.

    Path to input source, set from positional arguments.

    Default: stdin (None).  No command-line options.

.. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html

.. [#pwd] Path relative to the working directory of the process at

Old-Format Configuration Files

Formerly, Docutils configuration files contained a single "[options]"
section only.  This was found to be inflexible, and in August 2003
Docutils adopted the current component-based configuration file
sections as described above.  Docutils will still recognize the old
"[options]" section, but complains with a deprecation warning.

To convert existing config files, the easiest way is to change the
section title: change "[options]" to "[general]".  Most settings
haven't changed.  The only ones to watch out for are these:

=====================  =====================================
Old-Format Setting     New Section & Setting
=====================  =====================================
pep_stylesheet         [pep_html writer] stylesheet
pep_stylesheet_path    [pep_html writer] stylesheet_path
pep_template           [pep_html writer] template
=====================  =====================================

=== Added File Zope/lib/python/third_party/docutils/docs/user/latex.txt ===
 Generating LaTeX with Docutils

:Author: Engelbert Gruber
:Contact: grubert at users.sourceforge.net
:Revision: $Revision: $
:Date: $Date: 2004/10/29 18:24:48 $
:Copyright: This document has been placed in the public domain.

.. contents::


Producing LaTeX code from reST input could be done in at least two ways:

a. Transform the internal markup into corresponding LaTeX markup e.g.
   a section title would be written as ```\section{this section ...}``.
b. Using LaTeX as a typesetting system to produce desired paperwork
   without caring about loosing document structure information.

The former might be preferable, but limits to LaTeXs capabilities, so 
in reality it is a mix. The reality is that LaTeX has a titlepage with
title, author and date, by default only title is used. Author and date
are shown in the docutils docinfo table and set to blank for LaTeX.
To get author and date set by LaTeX specify option "use-LaTeX-docinfo".


Configuration can be done in two ways (again):

1. Options to the docutils tool: e.g. language selection.
2. Options to LaTeX via the stylesheet file.

The generated LaTeX documents should be kept processable by a standard
LaTeX installation (if such a thing exists), therefore the document
contains default settings. To allow *overwriting defaults* the stylesheet
is included at last.

Run ``rst2latex.py --help`` to see the command-line options, or have look in
config documentytion.

=====================  ================================================
Configuration Issue    Description
=====================  ================================================
papersize              Default: a4paper. Paper geometry can be changed  
                       using ``\geometry{xxx}`` entries.

                       Some possibilities:

                       * a4paper, b3paper, letterpaper, executivepaper,
                       * landscape, portrait, twoside.

                       and a ton of other option setting margins.

                       An example::

---------------------  ------------------------------------------------
paragraph indent       By default LaTeX indents the forst line in a
                       paragraph. The following lines set indentation 
                       to zero but add a vertical space between 

                         \setlength{\parskip}{6pt plus 2pt minus 1pt}
---------------------  ------------------------------------------------
admonitionwidth        The width for admonitions.
                       Default: 0.9*textwidth, this can be changed 

---------------------  ------------------------------------------------
docinfowidth           The width for the docinfo table.
                       Default: 0.9*textwidth, changed to e.g.::

---------------------  ------------------------------------------------
rubric style           The header contains the definition of a new
                       LaTeX command rubric. Inserting::

                           ~\hfill {\color{red} #1} \hfill ~}}

                       sets rubric to subsection style in red.

                       Default: subsection style italic.
---------------------  ------------------------------------------------
line spacing           Is done with package *setspace*, which gives
                       singlespace, onehalfspace and doublespace 
                       commands. To get documentwide double spacing, 
                       add this to your stylesheet ::


                       Another way ::


                       And yet another, add ``doublesp`` to the
                       documentoptions and e.g. ::


                       for bigger linespacing.
---------------------  ------------------------------------------------
font selection         see below
=====================  ================================================

Font selection

When generating pdf-files from LaTeX, use the pdflatex command, the files
are a lot smaller if postscript fonts are used. This *was* fixed by putting 
``\usepackage{times}`` into the stylesheet. 

It is said that the typewriter font in computer modern font, the default
LaTeX font package, is too heavy compared to the others. There is a package
or some commands too fix this, which i currently cannot find.

Some people diagnose a similar unbalance for the postscript fonts, the
package to fix this is ``\usepackage{pslatex}``.
pslatex in contrast to the standard LaTeX fonts has a bold typewriter font.

As ``times`` does not use the appropriate mathematical fonts and ``pslatex``
does not work with T1 encodings one should use::



The generated LaTeX documents are in latin1 encoding per default, if unicode
characters are required one must set ``--output-encoding=utf-8`` install
`LaTeX unicode`_ support and add::


to the stylesheet.

.. _LaTeX unicode: http://www.unruh.de/DniQ/latex/unicode/

Table of figures

A table of figures can be generated by a command directly to LaTeX::

  .. raw:: LaTeX


LaTeX also has a command ``\listoftables``.

Section numbering

If section numbering and LaTeX table of contents is used LaTeX and 
docutils will number sections. To switch off displaying of LaTeX's
numbers one has to add following lines to the stylesheet ::

  % no section number display
  % no numbers in toc


Images are included in LaTeX by the graphicx package. The supported
image formats depend on the used driver (dvi, dvips, pdftex, ...).

pdf-image inclusion in pdf files fails, specify ``--graphicx-option=pdftex``
or ``--graphicx-option=auto``.

Commands directly to LaTeX

By means of the reST-raw directive one can give commands directly to 
LaTeX, e.g. forcing a page break::

  .. raw:: LaTeX


Or setting formulas in LaTeX::

  .. raw:: LaTeX

     $$x^3 + 3x^2a + 3xa^2 + a^3,$$

Or making a colorbox: If someone wants to get a red background for a textblock,
she/he can put \definecolor{bg}{rgb}{.9,0,0} into style.tex and in
reStructuredText do something like this::

  Nobody expects the spanish inquisition.

  .. |begincolorbox| raw:: LaTeX


  .. |endcolorbox| raw:: LaTeX


Custom title page

Currently maketitle only shows the title and subtitle, date and author are shown 
in the docinfo table.

To change the titlepage layout, e.g. see fancyhdr, one must redefine the
maketitle command in the stylesheet::

      \textsf{TITLE \@title} \\
      Date: \today

``\@title`` contains the title.


Open to be fixed or open to discussion.

footnotes and citations

Initially both were implemented using figures, because hyperlinking back
and forth seemed to be impossible. Later images were put into figures.

This results in footnotes images and figures possibly being mixed at page 

* Use LaTeX footnotes and citations for printing or more complex layout.
* Footnotes and citations done with figures might excell in hyperlink

If ``use-latex-citations`` is used a bibliography is inserted right at
the end of the document. *This should be customizable*.

Tilde in italian

Does not work, or only in verbatim or verb. Could be fixed by using T1, but
the hyphen in literal environments is different:

* Inline or in verbatim it is lower than it should.
  If package courier is used acroread 5 puts it too high, xpdf
  shows it at the same height as the horizontal line of ``+``.
* In a block with markup two hyphens become one (endashed ?).
  and ``<<``, ``>>`` become separate characters too.


:Tablewidth: reST-documents line length is assumed to be 80 characters. The
             tablewidth is set relative to this value. If someone produces
             documents with line length of 132 this will fail.

             Table width is tried to fit in page even if it is wider than
             the assumed linewidth, still assumed linewidth is a hook. 

* In tools.txt the option tables right column, there should be some more spacing
  between the description and the next paragraph "Default:".

  Paragraph separation in tables is hairy. 
  see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab

  - The strut solution did not work.
  - setting extrarowheight added ad top of row not between paragraphs in
    a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
  - baselineskip/stretch does not help.
* Should there be two hlines after table head and on table end ?
* Table: multicol cells are always {l}.
* The contents of a rowspan cell do not influence table height.
  (Maybe if we put a tabular inside ?)
* Table heads and footer for longtable (firstpage lastpage ..).
* Table cells with multirow and multicolumn
* literal-blocks in table cells: 

  - If verbatim or flushleft is used one gets vertical space above and below.
  - This is bad for the topmost paragraph in a cell, therefore the writer
    uses raggedright. 
  - Ragged right fails on followup paragraphs as the vertical space would be


* table-style booktabs: booktabs.sty 1.00 does not work with longtable.


* Selection of LaTeX fontsize configurable.
* Assumed reST linelength for table width setting configurable.
* literal-block indentation configurable.
* The underscore ``_`` does not work in literal-blocks, has different width.
  I tried

  - Underline a blank ``\underline{ }`` to low, and does not fit the font.
    But on many systems underscore is an underlined blank.
  - Escape it ``{\_}`` to narrow
  - Subscript a hyphen ``$_{\tt-}$`` too wide and thin
  - ``$_{-}$`` the same.

* recongize LaTeX and replace by ``\LaTeX``.
* Support embed-stylesheet.
* the ^-sign is problematic: using mathmode wedge is usually the wrong font.
* Sidebar handling.
* Maybe add end of line after term in definition list. see
* Pdfbookmark level 4 (and greater) does not work (might be settable but OTOH).
* center subsection{Abstract} gives a LaTeX error here.
  ``! LaTeX Error: Something's wrong--perhaps a missing \item.``
  Committed a HACK: centering by hfill.
* Document errors are also too silent.
* Use optionlist for docinfo, the table does only work for single page.
* Consider peter funk's hooks for TeXpert:
  * Define his own document preamble (including the choice to
    choose his own documentclass.  That would make the ``--documentclass``
    option superfluous).  I suggest to call this option ``--preamble``
  * Use two additional hooks to put additional stuff just behind the 
    ``\begin{document}`` and just before the ``\end{document}`` macros.
    Typical uses would be ``\tableofcontents``, ``\listoffigures`` and
    ``\appendix``, ``\makeindex``, ``\makeglossary`` and some such 
    for larger documents.

* Hyphens: co-developers should be co--developers?
* The indentional problematic error in docs/user/rst/demo.txt is not
  referring anywhere.
* Footnotes are not all on the same page (as in
  docs/user/rst/demo.txt) and do not link back and forth.
* No link to system errors.	
* Hyperlinks are not hyphenated; this leads to bad spacing. See
  docs/user/rst/demo.txt 2.14 directives.
* Meta keywords into pdf ?
* Pagestyle headings does not work, when sections are starred.
* For additional docinfo items: the field_body is inserted as text, i.e. no
  markup is done.
* Multiple author entries in docinfo (same thing as in html).
* pslatex has not textbackslash in bold ?
* make use (but test against pslatex) ::

    \textbackslash      \backslash \
    \textbar            \mid       |
    \textless           <          <
    \textgreater        >          >
    \textasciicircum    \hat       ^
    \textasciitilde     \tilde     ~
    \textbullet         \bullet    gefüllter Kreis auf halber Höhe
    \textperiodcentered \cdot      ·
    \textvisiblespace   (n.v.)     sichtbares Leerzeichen
* keep literal-blocks together on a page, avoid pagebreaks.

  failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before
  the block.

=== Added File Zope/lib/python/third_party/docutils/docs/user/tools.txt ===
 Docutils Front-End Tools

:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:Revision: $Revision: $
:Date: $Date: 2004/10/29 18:24:48 $
:Copyright: This document has been placed in the public domain.

.. contents::


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

    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

.. _post a message: mailto:docutils-users at lists.sourceforge.net
.. _Docutils-Users mailing list:
.. _Docutils project web site: http://docutils.sourceforge.net/

The Tools


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


    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.


: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


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

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


: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


: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`_

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.


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


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


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


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


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

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

More information about the Zope-Checkins mailing list