re-added docutils-0.3.9 tag one level deeper (without web/ and sandboxes/)docutils-0.3.9

git-svn-id: http://svn.code.sf.net/p/docutils/code/tags/docutils-0.3.9@3815 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 0 insertions, 316 deletions

diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt
deleted file mode 100644
index ab31e0917..000000000
--- a/docutils/docs/user/tools.txt
+++ /dev/null
@@ -1,316 +0,0 @@
-==========================
- Docutils Front-End Tools
-==========================
-
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:Revision: $Revision$
-:Date: $Date$
-:Copyright: This document has been placed in the public domain.
-
-.. contents::
-
-
-Introduction
-============
-
-Once the Docutils package is unpacked, you will discover a "``tools``"
-directory containing several front ends for common Docutils
-processing.  Rather than a single all-purpose program, Docutils has
-many small front ends, each specialized for a specific "Reader" (which
-knows how to interpret a file in context), a "Parser" (which
-understands the syntax of the text), and a "Writer" (which knows how
-to generate a specific data format).  
-
-Most front ends have common options and the same command-line usage
-pattern::
-
-    toolname [options] [<source> [<destination]]
-
-(The exceptions are buildhtml.py_ and pep2html.py_.)  See rst2html.py_
-for concrete examples.  Each tool has a "``--help``" option which
-lists the `command-line options`_ and arguments it supports.
-Processing can also be customized with `configuration files`_.
-
-The two arguments, "source" and "destination", are optional.  If only
-one argument (source) is specified, the standard output (stdout) is
-used for the destination.  If no arguments are specified, the standard
-input (stdin) is used for the source as well.
-
-
-Getting Help
-------------
-
-First, try the "``--help``" option each front-end tool has.
-
-Users who have questions or need assistance with Docutils or
-reStructuredText should `post a message`_ to the `Docutils-Users
-mailing list`_.  The `Docutils project web site`_ has more
-information.
-
-.. _post a message: mailto:docutils-users@lists.sourceforge.net
-.. _Docutils-Users mailing list:
-   http://lists.sourceforge.net/lists/listinfo/docutils-users
-.. _Docutils project web site: http://docutils.sourceforge.net/
-
-
-The Tools
-=========
-
-buildhtml.py
-------------
-
-:Readers: Standalone, PEP
-:Parser: reStructuredText
-:Writers: HTML, PEP/HTML
-
-Use ``buildhtml.py`` to generate .html from all the .txt files
-(including PEPs) in each <directory> given, and their subdirectories
-too.  (Use the ``--local`` option to skip subdirectories.)
-
-Usage::
-
-    buildhtml.py [options] [<directory> ...]
-
-After unpacking the Docutils package, the following shell commands
-will generate HTML for all included documentation::
-
-    cd docutils/tools
-    buildhtml.py ..
-
-For official releases, the directory may be called "docutils-X.Y",
-where "X.Y" is the release version.  Alternatively::
-
-    cd docutils
-    tools/buildhtml.py --config=tools/docutils.conf
-
-The current directory (and all subdirectories) is chosen by default if
-no directory is named.  Some files may generate system messages
-(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: