docs/user/tools.txt

   1 ==========================
   2  Docutils Front-End Tools
   3 ==========================
   4
   5 :Author: David Goodger
   6 :Contact: goodger@users.sourceforge.net
   7 :Revision: $Revision$
   8 :Date: $Date$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 .. contents::
  12
  13
  14 Introduction
  15 ============
  16
  17 Once the Docutils package is unpacked, you will discover a "``tools``"
  18 directory containing several front ends for common Docutils
  19 processing.  Rather than a single all-purpose program, Docutils has
  20 many small front ends, each specialized for a specific "Reader" (which
  21 knows how to interpret a file in context), a "Parser" (which
  22 understands the syntax of the text), and a "Writer" (which knows how
  23 to generate a specific data format).
  24
  25 Most front ends have common options and the same command-line usage
  26 pattern::
  27
  28     toolname [options] [<source> [<destination]]
  29
  30 (The exceptions are buildhtml.py_ and pep2html.py_.)  See rst2html.py_
  31 for concrete examples.  Each tool has a "``--help``" option which
  32 lists the `command-line options`_ and arguments it supports.
  33 Processing can also be customized with `configuration files`_.
  34
  35 The two arguments, "source" and "destination", are optional.  If only
  36 one argument (source) is specified, the standard output (stdout) is
  37 used for the destination.  If no arguments are specified, the standard
  38 input (stdin) is used for the source as well.
  39
  40
  41 Getting Help
  42 ------------
  43
  44 First, try the "``--help``" option each front-end tool has.
  45
  46 Users who have questions or need assistance with Docutils or
  47 reStructuredText should `post a message`_ to the `Docutils-Users
  48 mailing list`_.  The `Docutils project web site`_ has more
  49 information.
  50
  51 .. _post a message: mailto:docutils-users@lists.sourceforge.net
  52 .. _Docutils-Users mailing list:
  53    http://lists.sourceforge.net/lists/listinfo/docutils-users
  54 .. _Docutils project web site: http://docutils.sourceforge.net/
  55
  56
  57 The Tools
  58 =========
  59
  60 buildhtml.py
  61 ------------
  62
  63 :Readers: Standalone, PEP
  64 :Parser: reStructuredText
  65 :Writers: HTML, PEP/HTML
  66
  67 Use ``buildhtml.py`` to generate .html from all the .txt files
  68 (including PEPs) in each <directory> given, and their subdirectories
  69 too.  (Use the ``--local`` option to skip subdirectories.)
  70
  71 Usage::
  72
  73     buildhtml.py [options] [<directory> ...]
  74
  75 After unpacking the Docutils package, the following shell commands
  76 will generate HTML for all included documentation::
  77
  78     cd docutils/tools
  79     buildhtml.py ..
  80
  81 For official releases, the directory may be called "docutils-X.Y",
  82 where "X.Y" is the release version.  Alternatively::
  83
  84     cd docutils
  85     tools/buildhtml.py --config=tools/docutils.conf
  86
  87 The current directory (and all subdirectories) is chosen by default if
  88 no directory is named.  Some files may generate system messages
  89 (tools/test.txt contains intentional errors); use the ``--quiet``
  90 option to suppress all warnings.  The ``--config`` option ensures that
  91 the correct stylesheets, templates, and settings are in place (a
  92 ``docutils.conf`` configuration file in the current directory is
  93 picked up automatically).  Command-line options may be used to
  94 override config file settings or replace them altogether.
  95
  96
  97 rst2html.py
  98 -----------
  99
 100 :Reader: Standalone
 101 :Parser: reStructuredText
 102 :Writer: HTML
 103
 104 The ``rst2html.py`` front end reads standalone reStructuredText source
 105 files and produces HTML 4 (XHTML 1) output compatible with modern
 106 browsers.  For example, to process a reStructuredText file
 107 "``test.txt``" into HTML::
 108
 109     rst2html.py test.txt test.html
 110
 111 In fact, there *is* a "``test.txt``" file in the "``tools``"
 112 directory.  It contains "at least one example of each reStructuredText
 113 construct", including several intentional errors (to test the error
 114 reporting system).  Use it to put the system through its paces and
 115 compare input to output.
 116
 117 Now open the "``test.html``" file in your favorite browser to see the
 118 results.  To get a footer with a link to the source file, date & time
 119 of processing, and links to the Docutils projects, add some options::
 120
 121     rst2html.py -stg test.txt test.html
 122
 123
 124 Stylesheets
 125 ```````````
 126
 127 ``rst2html.py`` inserts into the generated HTML a link to a cascading
 128 stylesheet, defaulting to "``default.css``" (override with a
 129 "``--stylesheet``" or "``--stylesheet-path``" command-line option or
 130 with configuration file settings).  The
 131 "``tools/stylesheets/default.css``" stylesheet is provided for basic
 132 use.  To experiment with styles, rather than editing the default
 133 stylesheet (which will be updated as the project evolves), it is
 134 recommended to use an "``@import``" statement to create a "wrapper"
 135 stylesheet.  For example, a "``my.css``" stylesheet could contain the
 136 following::
 137
 138     @import url(default.css);
 139
 140     h1, h2, h3, h4, h5, h6, p.topic-title {
 141       font-family: sans-serif }
 142
 143 Generate HTML with the following command::
 144
 145     rst2html.py -stg --stylesheet my.css test.txt test.html
 146
 147 When viewed in a browser, the new "wrapper" stylesheet will change the
 148 typeface family of titles to "sans serif", typically Helvetica or
 149 Arial.  Other styles will not be affected.  Styles in wrapper
 150 stylesheets override styles in imported stylesheets, enabling
 151 incremental experimentation.
 152
 153
 154 pep.py
 155 ------
 156
 157 :Reader: PEP
 158 :Parser: reStructuredText
 159 :Writer: PEP/HTML
 160
 161 ``pep.py`` reads a new-style PEP (marked up with reStructuredText) and
 162 produces HTML.  It requires a template file and a stylesheet.  By
 163 default, it makes use of a "``pep-html-template``" file and a
 164 "``default.css``" stylesheet in the current directory, but these can
 165 be overridden by command-line options or configuration files.  The
 166 "``tools/stylesheets/pep.css``" stylesheet is intended specifically
 167 for PEP use.
 168
 169 The "``docutils.conf``" `configuration file`_ in the "``spec``"
 170 directory of Docutils contains a default setup for use in processing
 171 the PEP files there (``spec/pep-*.txt``) into HTML.  It specifies a
 172 default template (``tools/pep-html-template``) and a default
 173 stylesheet (``tools/stylesheets/pep.css``).  See Stylesheets_ above
 174 for more information.
 175
 176
 177 pep2html.py
 178 -----------
 179
 180 :Reader: PEP
 181 :Parser: reStructuredText
 182 :Writer: PEP/HTML
 183
 184 ``pep2html.py`` is a modified version of the original script by
 185 Fredrik Lundh, with support for Docutils added.  It reads the
 186 beginning of a PEP text file to determine the format (old-style
 187 indented or new-style reStructuredText) and processes accordingly.
 188 Since it does not use the Docutils front end mechanism (the common
 189 command-line options are not supported), it can only be configured
 190 using `configuration files`_.  The template and stylesheet
 191 requirements of ``pep2html.py`` are the same as those of `pep.py`_
 192 above.
 193
 194 Arguments to ``pep2html.py`` may be a list of PEP numbers or .txt
 195 files.  If no arguments are given, all files of the form
 196 "``pep-*.txt``" are processed.
 197
 198
 199 rst2latex.py
 200 ------------
 201
 202 :Reader: Standalone
 203 :Parser: reStructuredText
 204 :Writer: LaTeX2e
 205
 206 The ``rst2latex.py`` front end reads standalone reStructuredText
 207 source files and produces LaTeX2e output. For example, to process a
 208 reStructuredText file "``test.txt``" into LaTeX::
 209
 210     rst2latex.py test.txt test.tex
 211
 212 The output file "``test.tex``" should then be processed with ``latex``
 213 or ``pdflatex`` to get a typeset document.
 214
 215 Some limitations and difference apply:
 216
 217 - GIF, JPG and PNG images are not handled, when processed with
 218   ``latex``; use ``pdflatex`` instead.
 219 - Only the Latin-1 output encoding has been tested up to now (Latin-1
 220   has been made the default output encoding for LaTeX).
 221 - The generated file includes a file ``style.tex``, which allows the
 222   inclusion of special packages or changes to settings made in the
 223   header.
 224 - Not all constructs are possible (e.g. row/column spans in tables are
 225   not).
 226
 227
 228 docutils-xml.py
 229 ---------------
 230
 231 :Reader: Standalone
 232 :Parser: reStructuredText
 233 :Writer: XML (Docutils native)
 234
 235 The ``docutils-xml.py`` front end produces Docutils-native XML output.
 236 This can be transformed with standard XML tools such as XSLT
 237 processors into arbitrary final forms.
 238
 239
 240 publish.py
 241 ----------
 242
 243 :Reader: Standalone
 244 :Parser: reStructuredText
 245 :Writer: Pseudo-XML
 246
 247 ``publish.py`` is used for debugging the Docutils "Reader to Transform
 248 to Writer" pipeline.  It produces a compact pretty-printed
 249 "pseudo-XML", where nesting is indicated by indentation (no end-tags).
 250 External attributes for all elements are output, and internal
 251 attributes for any leftover "pending" elements are also given.
 252
 253
 254 quicktest.py
 255 ------------
 256
 257 :Reader: N/A
 258 :Parser: reStructuredText
 259 :Writer: N/A
 260
 261 The ``quicktest.py`` tool is used for testing the reStructuredText
 262 parser.  It does not use a Docutils Reader or Writer or the standard
 263 Docutils command-line options.  Rather, it does its own I/O and calls
 264 the parser directly.  No transforms are applied to the parsed
 265 document.  Various forms output are possible:
 266
 267 - Pretty-printed pseudo-XML (default)
 268 - Test data (Python list of input and pseudo-XML output strings;
 269   useful for creating new test cases)
 270 - Pretty-printed native XML
 271 - Raw native XML (with or without a stylesheet reference)
 272
 273
 274
 275 Customization
 276 =============
 277
 278 Command-Line Options
 279 --------------------
 280
 281 Each front-end tool supports command-line options for one-off
 282 customization.  For persistent customization, use `configuration
 283 files`_.  Command-line options take priority over configuration file
 284 settings.
 285
 286 Use the "--help" option on each of the front ends to list the
 287 command-line options it supports.  Command-line options and their
 288 corresponding configuration file entry names are listed in the
 289 `Docutils Configuration Files`_ document.
 290
 291
 292 .. _configuration file:
 293
 294 Configuration Files
 295 -------------------
 296
 297 Configuration files are used for persistent customization; they can be
 298 set once and take effect every time you use a front-end tool.
 299
 300 For details, see `Docutils Configuration Files`_.
 301
 302 .. _Docutils Configuration Files: config.html
 303
 304 \f
 305 ..
 306    Local Variables:
 307    mode: indented-text
 308    indent-tabs-mode: nil
 309    sentence-end-double-space: t
 310    fill-column: 70
 311    End: