[Zope-Checkins] CVS: Zope/lib/python/third_party/docutils/docs/user
- config.txt:1.1.2.1 latex.txt:1.1.2.1 tools.txt:1.1.2.1
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:
moved
=== 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: 1.1.2.1 $
: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
priority.
-------------------------
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
comments.
.. 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
underscores.
For on/off switch settings (booleans), the following values are
recognized:
* 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
file.
Some knowledge of Python_ is assumed for some attributes.
.. _ConfigParser.py:
http://www.python.org/doc/current/lib/module-ConfigParser.html
.. _Python: http://www.python.org/
.. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt
.. _Docutils application: tools.html
[general]
=========
Settings in the "[general]" section are always applied.
_`datestamp`
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,
--no-datestamp``.
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:
datestamp:
__ http://www.python.org/doc/current/lib/module-time.html
_`debug`
Report debug-level system messages.
Default: don't (None). Options: ``--debug, --no-debug``.
_`dump_internals`
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).
_`dump_pseudo_xml`
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).
_`dump_settings`
At the end of processing, write all Docutils settings to stderr.
Default: don't (None). Options: ``--dump-settings`` (hidden, for
development use only).
_`dump_transforms`
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).
_`error_encoding`
The text encoding for error output.
Default: "ascii". Options: ``--error-encoding, -e``.
_`error_encoding_error_handler`
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``.
_`exit_status_level`
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``.
_`expose_internals`
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).
_`footnote_backlinks`
Enable or disable backlinks from footnotes and citations to their
references.
Default: enabled (1). Options: ``--footnote-backlinks,
--no-footnote-backlinks``.
_`generator`
Include a "Generated by Docutils" credit and link in the document
footer.
Default: off (None). Options: ``--generator, -g,
--no-generator``.
_`halt_level`
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``.
_`input_encoding`
The text encoding for input.
Default: auto-detect (None). Options: ``--input-encoding, -i``.
_`language_code`
`ISO 639`_ 2-letter language code (3-letter codes used only if no
2-letter code exists).
Default: English ("en"). Options: ``--language, -l``.
_`output_encoding`
The text encoding for output.
Default: "UTF-8". Options: ``--output-encoding, -o``.
_`output_encoding_error_handler`
The error handler for unencodable characters in the output.
Acceptable values include:
strict
Raise an exception in case of an encoding error.
replace
Replace malformed data with a suitable replacement marker,
such as "?".
ignore
Ignore malformed data and continue without further notice.
xmlcharrefreplace
Replace with the appropriate XML character reference, such as
"``†``".
backslashreplace
(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``.
_`report_level`
Verbosity threshold at or above which system messages are
reported.
Default: warning (2). Options: ``--report, -r, --verbose, -v,
--quiet, -q``.
_`sectnum_xform`
Enable or disable the section numbering transform
(docutils.transforms.parts.SectNum).
Default: enabled (1). Options: ``--no-section-numbering``.
_`source_link`
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,
--no-source-link``.
_`source_url`
An explicit URL for a "View document source" link, used verbatim.
Default: compute if source_link (None). Options: ``--source-url,
--no-source-link``.
_`toc_backlinks`
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``.
_`traceback`
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,
--no-traceback``.
_`warning_stream`
Path to a file for the output of system messages (warnings)
[#pwd]_.
Default: stderr (None). Options: ``--warnings``.
[parsers]
---------
Docutils currently supports only one parser, for reStructuredText.
[restructuredtext parser]
`````````````````````````
_`pep_references`
Recognize and link to standalone PEP references (like "PEP 258").
Default: disabled (None); enabled (1) in PEP Reader. Options:
``--pep-references``.
_`pep_base_url`
Base URL for PEP references.
Default: "http://www.python.org/peps/". Option:
``--pep-base-url``.
_`rfc_references`
Recognize and link to standalone RFC references (like "RFC 822").
Default: disabled (None); enabled (1) in PEP Reader. Options:
``--rfc-references``.
_`rfc_base_url`
Base URL for RFC references.
Default: "http://www.faqs.org/rfcs/". Option: ``--rfc-base-url``.
_`tab_width`
Number of spaces for hard tab expansion.
Default: 8. Options: ``--tab-width``.
_`trim_footnote_reference_space`
Remove spaces before footnote references.
Default: don't (None). Options:
``--trim-footnote-reference-space``.
[readers]
---------
[standalone reader]
```````````````````
_`docinfo_xform`
Enable or disable the bibliographic field list transform
(docutils.transforms.frontmatter.DocInfo).
Default: enabled (1). Options: ``--no-doc-info``.
_`doctitle_xform`
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.
[writers]
---------
[docutils_xml writer]
`````````````````````
_`doctype_declaration`
Generate XML with a DOCTYPE declaration.
Default: do (1). Options: ``--no-doctype``.
_`indents`
Generate XML with indents and newlines.
Default: don't (None). Options: ``--indents``.
_`newlines`
Generate XML with newlines before and after tags.
Default: don't (None). Options: ``--newlines``.
.. _xml_declaration [docutils_xml writer]:
xml_declaration
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]:
attribution
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]`_
_`compact_lists`
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,
--no-compact-lists``.
_`embed_stylesheet`
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,
--link-stylesheet``.
.. _footnote_references [html4css1 writer]:
footnote_references
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``.
__ `footnote_references [latex2e writer]`_
_`initial_header_level`
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]:
stylesheet
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::
stylesheet-path=
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]:
stylesheet_path
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]:
xml_declaration
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]".
_`no_random`
Workaround for platforms which core-dump on "``import random``".
Default: random enabled (None). Options: ``--no-random``
(hidden).
_`pep_home`
Home URL prefix for PEPs.
Default: current directory ("."). Options: ``--pep-home``.
_`template`
Path to PEP template file [#pwd]_.
Default: "pep-html-template" (in current directory). Options:
``--template``.
_`python_home`
Python's home URL.
Default: parent directory (".."). Options: ``--python-home``.
[latex2e writer]
````````````````
_`use_latex_toc`
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`
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``.
_`hyperlink_color`
Color of any hyperlinks embedded in text. Use "0" to disable
coloring of links.
Default: "blue", use "0" to disable. Option:
``--hyperlink-color``.
_`documentclass`
Specify latex documentclass, *but* beaware that books have chapters
articles not.
Default: "article". Option: ``--documentclass``.
_`documentoptions`
Specify document options. Multiple options can be given, separated by
commas.
Default is "10pt". Option: ``--documentoptions``.
.. _stylesheet [latex2e writer]:
stylesheet
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]:
stylesheet_path
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]:
footnote_references
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]:
attribution
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
Writer`__.
Default: "dash". Option: ``--attribution``.
__ `attribution [html4css1 writer]`_
_`compound_enumerators`
Enable or disable compound enumerators for nested enumerated lists
(e.g. "1.2.a.ii").
Default: disabled (None). Options: ``--compound-enumerators``,
``--no-compound-enumerators``.
_`section_prefix_for_enumerators`
Enable or disable section ("." subsection ...) prefixes for
compound enumerators. This has no effect unless
`compound_enumerators`_ are enabled.
Default: disabled (None). Options:
``--section-prefix-for-enumerators``,
``--no-section-prefix-for-enumerators``.
_`section_enumerator_separator`
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``.
table_style
Specify the drawing of separation lines.
- "standard" lines around and between cells.
- "booktabs" a line above and below the table and one after the
head.
- "nolines".
[pseudoxml writer]
``````````````````
No settings are defined for this Writer.
[applications]
--------------
[buildhtml application]
```````````````````````
_`prune`
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``.
_`recurse`
Recursively scan subdirectories, or ignore subdirectories.
Default: recurse (1). Options: ``--recurse, --local``.
_`silent`
Work silently (no progress messages). Independent of
"report_level".
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.
_`config`
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``.
_`_directories`
(``buildhtml.py`` front end.) List of paths to source
directories, set from positional arguments.
Default: current working directory (None). No command-line
options.
_`_disable_config`
Prevent standard configuration files from being read. For
internal use only.
Default: config files enabled (None). No command-line options.
_`_destination`
Path to output destination, set from positional arguments.
Default: stdout (None). No command-line options.
_`_source`
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
launch.
------------------------------
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: 1.1.2.1 $
:Date: $Date: 2004/10/29 18:24:48 $
:Copyright: This document has been placed in the public domain.
.. contents::
Introduction
============
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".
Options
=======
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,
legalpaper
* landscape, portrait, twoside.
and a ton of other option setting margins.
An example::
\geometry{a5paper,landscape}
--------------------- ------------------------------------------------
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
paragraphs.::
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}
--------------------- ------------------------------------------------
admonitionwidth The width for admonitions.
Default: 0.9*textwidth, this can be changed
e.g.::
\setlength{\admonitionwidth}{0.7\textwidth}
--------------------- ------------------------------------------------
docinfowidth The width for the docinfo table.
Default: 0.9*textwidth, changed to e.g.::
\setlength{\docinfowidth}{0.7\textwidth}
--------------------- ------------------------------------------------
rubric style The header contains the definition of a new
LaTeX command rubric. Inserting::
\renewcommand{\rubric}[1]{\subsection*{
~\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 ::
\usepackage{setspace}
\doublespacing
Another way ::
\linespread{1.55}
And yet another, add ``doublesp`` to the
documentoptions and e.g. ::
\setstretch{1.7}
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::
\usepackage{mathptmx}
\usepackage[scaled=.90]{helvet}
\usepackage{courier}
Unicode
-------
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::
\usepackage{ucs}
\usepackage[utf8]{inputenc}
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
\listoffigures
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
\makeatletter
\def\@seccntformat#1{}
\makeatother
% no numbers in toc
\renewcommand{\numberline}[1]{}
images
------
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
\newpage
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::
|begincolorbox|
Nobody expects the spanish inquisition.
|endcolorbox|
.. |begincolorbox| raw:: LaTeX
\\begin{center}
\\colorbox{bg}{
\\parbox{0.985\\linewidth}{
.. |endcolorbox| raw:: LaTeX
}}
\\end{center}
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::
\renewcommand{\maketitle}{
\begin{titlepage}
\begin{center}
\textsf{TITLE \@title} \\
Date: \today
\end{center}
\end{titlepage}
}
``\@title`` contains the title.
Problems
========
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
foot.
* Use LaTeX footnotes and citations for printing or more complex layout.
* Footnotes and citations done with figures might excell in hyperlink
support.
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.
Tables
------
: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
missing.
Notes
~~~~~
* table-style booktabs: booktabs.sty 1.00 does not work with longtable.
Miscellaneous
-------------
* 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
http://roundup.sf.net/doc-0.5/features.pdf
* 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: 1.1.2.1 $
:Date: $Date: 2004/10/29 18:24:48 $
: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 at 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:
More information about the Zope-Checkins
mailing list