diff options
Diffstat (limited to 'docutils/docs/user/tools.txt')
| -rw-r--r-- | docutils/docs/user/tools.txt | 316 |
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: |