Tools

[ x ]

Texto Original

blable

Sugira uma tradução melhor

Licença: PUBLIC

Link: None

Data: 15/05/2009

Status da tradução: 0.320512820513%

==========================

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.

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] [ [

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

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@lists.sourceforge.net

.. _Docutils-Users mailing list:

http://lists.sourceforge.net/lists/listinfo/docutils-users

.. _Docutils project web site: http://docutils.sourceforge.net/

:Readers: Standalone, PEP

:Parser: reStructuredText

:Writers: HTML, PEP/HTML

Use ``buildhtml.py`` to generate .html from all the .txt files

(including PEPs) in each given, and their subdirectories

too. (Use the ``--local`` option to skip subdirectories.)

buildhtml.py [options] [ ...]

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

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.

:Reader: Standalone

:Parser: reStructuredText

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

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

: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

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.

: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 generated file includes a file ``style.tex``, which allows the

inclusion of special packages or changes to settings made in the

- Not all constructs are possible (e.g. row/column spans in tables are

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.

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

:Parser: reStructuredText

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

Local Variables:

mode: indented-text

indent-tabs-mode: nil

sentence-end-double-space: t

fill-column: 70