diff options
Diffstat (limited to 'docutils/docs/user/tools.txt')
| -rw-r--r-- | docutils/docs/user/tools.txt | 389 |
1 files changed, 0 insertions, 389 deletions
diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt deleted file mode 100644 index 20f5a3b2f..000000000 --- a/docutils/docs/user/tools.txt +++ /dev/null @@ -1,389 +0,0 @@ -========================== - Docutils Front-End Tools -========================== - -:Author: David Goodger -:Contact: goodger@python.org -: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 rstpep2html.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. - -.. _Docutils-users: mailing-lists.html#docutils-users - - ------------ - The Tools ------------ - -HTML-Generating 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 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 that support cascading stylesheets (CSS). A stylesheet is -required for proper rendering; a simple but complete stylesheet is -installed and used by default (see Stylesheets_ below). - -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 project, add some options:: - - rst2html.py -stg test.txt test.html - - -Stylesheets -``````````` - -``rst2html.py`` inserts into the generated HTML a cascading stylesheet -(or a link to a stylesheet, when passing the "``--link-stylesheet``" -option). A stylesheet is required for proper rendering. The default -stylesheet (``docutils/writers/html4css1/html4css1.css``, located in -the installation directory) is provided for basic use. To use a -different stylesheet, you must specify the stylesheet's location with -a "``--stylesheet``" (for a URL) or "``--stylesheet-path``" (for a -local file) command-line option, or with `configuration file`_ -settings (e.g. ``./docutils.conf`` or ``~/.docutils``). To experiment -with styles, please see the `guide to writing HTML (CSS) stylesheets -for Docutils`__. - -__ ../howto/html-stylesheets.html - - -rstpep2html.py --------------- - -:Reader: PEP -:Parser: reStructuredText -:Writer: PEP/HTML - -``rstpep2html.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 the "``pep.css``" stylesheet (both in the -``docutils/writers/pep_html/`` directory), but these can be overridden -by command-line options or configuration files. - -For example, to process a PEP into HTML:: - - cd <path-to-docutils>/docs/peps - rstpep2html.py pep-0287.txt pep-0287.html - - -rst2s5.py ---------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: S5/HTML - -The ``rst2s5.py`` front end reads standalone reStructuredText source -files and produces (X)HTML output compatible with S5_, the "Simple -Standards-based Slide Show System" by Eric Meyer. A theme is required -for proper rendering; several are distributed with Docutils and others -are available; see Themes_ below. - -For example, to process a reStructuredText file "``slides.txt``" into -S5/HTML:: - - rst2s5.py slides.txt slides.html - -Now open the "``slides.html``" file in your favorite browser, switch -to full-screen mode, and enjoy the results. - -.. _S5: http://meyerweb.com/eric/tools/s5/ - - -Themes -`````` - -Each S5 theme consists of a directory containing several files: -stylesheets, JavaScript, and graphics. These are copied into a -``ui/<theme>`` directory beside the generated HTML. A theme is chosen -using the "``--theme``" option (for themes that come with Docutils) or -the "``--theme-url``" option (for themes anywhere). For example, the -"medium-black" theme can be specified as follows:: - - rst2s5.py --theme medium-black slides.txt slides.html - -The theme will be copied to the ``ui/medium-black`` directory. - -Several themes are included with Docutils: - -``default`` - This is a simplified version of S5's default theme. - - :Main content: black serif text on a white background - :Text capacity: about 13 lines - :Headers: light blue, bold sans-serif text on a dark blue - background; titles are limited to one line - :Footers: small, gray, bold sans-serif text on a dark blue - background - -``small-white`` - (Small text on a white background.) - - :Main content: black serif text on a white background - :Text capacity: about 15 lines - :Headers: black, bold sans-serif text on a white background; - titles wrap - :Footers: small, dark gray, bold sans-serif text on a white - background - -``small-black`` - :Main content: white serif text on a black background - :Text capacity: about 15 lines - :Headers: white, bold sans-serif text on a black background; - titles wrap - :Footers: small, light gray, bold sans-serif text on a black - background - -``medium-white`` - :Main content: black serif text on a white background - :Text capacity: about 9 lines - :Headers: black, bold sans-serif text on a white background; - titles wrap - :Footers: small, dark gray, bold sans-serif text on a white - background - -``medium-black`` - :Main content: white serif text on a black background - :Text capacity: about 9 lines - :Headers: white, bold sans-serif text on a black background; - titles wrap - :Footers: small, light gray, bold sans-serif text on a black - background - -``big-white`` - :Main content: black, bold sans-serif text on a white background - :Text capacity: about 5 lines - :Headers: black, bold sans-serif text on a white background; - titles wrap - :Footers: not displayed - -``big-black`` - :Main content: white, bold sans-serif text on a black background - :Text capacity: about 5 lines - :Headers: white, bold sans-serif text on a black background; - titles wrap - :Footers: not displayed - -If a theme directory contains a file named ``__base__``, the name of -the theme's base theme will be read from it. Files are accumulated -from the named theme, any base themes, and the "default" theme (which -is the implicit base of all themes). - -For details, please see `Easy Slide Shows With reStructuredText & -S5 <slide-shows.html>`_. - - -LaTeX-Generating Tools -====================== - -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`_. - - -XML-Generating Tools -==================== - -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. - - -Testing/Debugging Tools -======================= - -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: |