docs/user/tools.txt

   1 ==========================
   2  Docutils Front-End Tools
   3 ==========================
   4
   5 :Author: David Goodger
   6 :Contact: docutils-develop@lists.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 --------------
  15  Introduction
  16 --------------
  17
  18 Once the Docutils package is unpacked, you will discover a "``tools``"
  19 directory containing several front ends for common Docutils
  20 processing.  Rather than a single all-purpose program, Docutils has
  21 many small front ends, each specialized for a specific "Reader" (which
  22 knows how to interpret a file in context), a "Parser" (which
  23 understands the syntax of the text), and a "Writer" (which knows how
  24 to generate a specific data format).
  25
  26 Most front ends have common options and the same command-line usage
  27 pattern::
  28
  29     toolname [options] [<source> [<destination]]
  30
  31 (The exceptions are buildhtml.py_ and rstpep2html.py_.)  See
  32 rst2html.py_ for concrete examples.  Each tool has a "``--help``"
  33 option which lists the `command-line options`_ and arguments it
  34 supports.  Processing can also be customized with `configuration
  35 files`_.
  36
  37 The two arguments, "source" and "destination", are optional.  If only
  38 one argument (source) is specified, the standard output (stdout) is
  39 used for the destination.  If no arguments are specified, the standard
  40 input (stdin) is used for the source as well.
  41
  42
  43 Getting Help
  44 ============
  45
  46 First, try the "``--help``" option each front-end tool has.
  47
  48 Users who have questions or need assistance with Docutils or
  49 reStructuredText should post a message to the Docutils-users_ mailing
  50 list.
  51
  52 .. _Docutils-users: mailing-lists.html#docutils-users
  53
  54
  55 -----------
  56  The Tools
  57 -----------
  58
  59 HTML-Generating Tools
  60 =====================
  61
  62 buildhtml.py
  63 ------------
  64
  65 :Readers: Standalone, PEP
  66 :Parser: reStructuredText
  67 :Writers: HTML, PEP/HTML
  68
  69 Use ``buildhtml.py`` to generate .html from all the .txt files
  70 (including PEPs) in each <directory> given, and their subdirectories
  71 too.  (Use the ``--local`` option to skip subdirectories.)
  72
  73 Usage::
  74
  75     buildhtml.py [options] [<directory> ...]
  76
  77 After unpacking the Docutils package, the following shell commands
  78 will generate HTML for all included documentation::
  79
  80     cd docutils/tools
  81     buildhtml.py ..
  82
  83 For official releases, the directory may be called "docutils-X.Y",
  84 where "X.Y" is the release version.  Alternatively::
  85
  86     cd docutils
  87     tools/buildhtml.py --config=tools/docutils.conf
  88
  89 The current directory (and all subdirectories) is chosen by default if
  90 no directory is named.  Some files may generate system messages
  91 (docs/user/rst/demo.txt contains intentional errors); use the
  92 ``--quiet`` option to suppress all warnings.  The ``--config`` option
  93 ensures that the correct settings are in place (a ``docutils.conf``
  94 `configuration file`_ in the current directory is picked up
  95 automatically).  Command-line options may be used to override config
  96 file settings or replace them altogether.
  97
  98
  99 rst2html.py
 100 -----------
 101
 102 :Reader: Standalone
 103 :Parser: reStructuredText
 104 :Writer: HTML
 105
 106 The ``rst2html.py`` front end reads standalone reStructuredText source
 107 files and produces HTML 4 (XHTML 1) output compatible with modern
 108 browsers that support cascading stylesheets (CSS).  A stylesheet is
 109 required for proper rendering; a simple but complete stylesheet is
 110 installed and used by default (see Stylesheets_ below).
 111
 112 For example, to process a reStructuredText file "``test.txt``" into
 113 HTML::
 114
 115     rst2html.py test.txt test.html
 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 project, 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 cascading stylesheet
 128 (or a link to a stylesheet, when passing the "``--link-stylesheet``"
 129 option).  A stylesheet is required for proper rendering.  The default
 130 stylesheet (``docutils/writers/html4css1/html4css1.css``, located in
 131 the installation directory) is provided for basic use.  To use a
 132 different stylesheet, you must specify the stylesheet's location with
 133 a "``--stylesheet``" (for a URL) or "``--stylesheet-path``" (for a
 134 local file) command-line option, or with `configuration file`_
 135 settings (e.g. ``./docutils.conf`` or ``~/.docutils``).  To experiment
 136 with styles, please see the `guide to writing HTML (CSS) stylesheets
 137 for Docutils`__.
 138
 139 __ ../howto/html-stylesheets.html
 140
 141
 142 rstpep2html.py
 143 --------------
 144
 145 :Reader: PEP
 146 :Parser: reStructuredText
 147 :Writer: PEP/HTML
 148
 149 ``rstpep2html.py`` reads a new-style PEP (marked up with
 150 reStructuredText) and produces HTML.  It requires a template file and
 151 a stylesheet.  By default, it makes use of a "``pep-html-template``"
 152 file and the "``pep.css``" stylesheet (both in the
 153 ``docutils/writers/pep_html/`` directory), but these can be overridden
 154 by command-line options or configuration files.
 155
 156 For example, to process a PEP into HTML::
 157
 158     cd <path-to-docutils>/docs/peps
 159     rstpep2html.py pep-0287.txt pep-0287.html
 160
 161
 162 rst2s5.py
 163 ---------
 164
 165 :Reader: Standalone
 166 :Parser: reStructuredText
 167 :Writer: S5/HTML
 168
 169 The ``rst2s5.py`` front end reads standalone reStructuredText source
 170 files and produces (X)HTML output compatible with S5_, the "Simple
 171 Standards-based Slide Show System" by Eric Meyer.  A theme is required
 172 for proper rendering; several are distributed with Docutils and others
 173 are available; see Themes_ below.
 174
 175 For example, to process a reStructuredText file "``slides.txt``" into
 176 S5/HTML::
 177
 178     rst2s5.py slides.txt slides.html
 179
 180 Now open the "``slides.html``" file in your favorite browser, switch
 181 to full-screen mode, and enjoy the results.
 182
 183 .. _S5: http://meyerweb.com/eric/tools/s5/
 184
 185
 186 Themes
 187 ``````
 188
 189 Each S5 theme consists of a directory containing several files:
 190 stylesheets, JavaScript, and graphics.  These are copied into a
 191 ``ui/<theme>`` directory beside the generated HTML.  A theme is chosen
 192 using the "``--theme``" option (for themes that come with Docutils) or
 193 the "``--theme-url``" option (for themes anywhere).  For example, the
 194 "medium-black" theme can be specified as follows::
 195
 196     rst2s5.py --theme medium-black slides.txt slides.html
 197
 198 The theme will be copied to the ``ui/medium-black`` directory.
 199
 200 Several themes are included with Docutils:
 201
 202 ``default``
 203     This is a simplified version of S5's default theme.
 204
 205     :Main content: black serif text on a white background
 206     :Text capacity: about 13 lines
 207     :Headers: light blue, bold sans-serif text on a dark blue
 208               background; titles are limited to one line
 209     :Footers: small, gray, bold sans-serif text on a dark blue
 210               background
 211
 212 ``small-white``
 213     (Small text on a white background.)
 214
 215     :Main content: black serif text on a white background
 216     :Text capacity: about 15 lines
 217     :Headers: black, bold sans-serif text on a white background;
 218               titles wrap
 219     :Footers: small, dark gray, bold sans-serif text on a white
 220               background
 221
 222 ``small-black``
 223     :Main content: white serif text on a black background
 224     :Text capacity: about 15 lines
 225     :Headers: white, bold sans-serif text on a black background;
 226               titles wrap
 227     :Footers: small, light gray, bold sans-serif text on a black
 228               background
 229
 230 ``medium-white``
 231     :Main content: black serif text on a white background
 232     :Text capacity: about 9 lines
 233     :Headers: black, bold sans-serif text on a white background;
 234               titles wrap
 235     :Footers: small, dark gray, bold sans-serif text on a white
 236               background
 237
 238 ``medium-black``
 239     :Main content: white serif text on a black background
 240     :Text capacity: about 9 lines
 241     :Headers: white, bold sans-serif text on a black background;
 242               titles wrap
 243     :Footers: small, light gray, bold sans-serif text on a black
 244               background
 245
 246 ``big-white``
 247     :Main content: black, bold sans-serif text on a white background
 248     :Text capacity: about 5 lines
 249     :Headers: black, bold sans-serif text on a white background;
 250               titles wrap
 251     :Footers: not displayed
 252
 253 ``big-black``
 254     :Main content: white, bold sans-serif text on a black background
 255     :Text capacity: about 5 lines
 256     :Headers: white, bold sans-serif text on a black background;
 257               titles wrap
 258     :Footers: not displayed
 259
 260 If a theme directory contains a file named ``__base__``, the name of
 261 the theme's base theme will be read from it.  Files are accumulated
 262 from the named theme, any base themes, and the "default" theme (which
 263 is the implicit base of all themes).
 264
 265 For details, please see `Easy Slide Shows With reStructuredText &
 266 S5 <slide-shows.html>`_.
 267
 268
 269 LaTeX-Generating Tools
 270 ======================
 271
 272 rst2latex.py
 273 ------------
 274
 275 :Reader: Standalone
 276 :Parser: reStructuredText
 277 :Writer: LaTeX2e
 278
 279 The ``rst2latex.py`` front end reads standalone reStructuredText
 280 source files and produces LaTeX2e output. For example, to process a
 281 reStructuredText file "``test.txt``" into LaTeX::
 282
 283     rst2latex.py test.txt test.tex
 284
 285 The output file "``test.tex``" should then be processed with ``latex``
 286 or ``pdflatex`` to get a document in DVI, PostScript or PDF format for
 287 printing or on-screen viewing.
 288
 289 For details see `Generating LaTeX with Docutils`_.
 290
 291
 292 XML-Generating Tools
 293 ====================
 294
 295 rst2xml.py
 296 ----------
 297
 298 :Reader: Standalone
 299 :Parser: reStructuredText
 300 :Writer: XML (Docutils native)
 301
 302 The ``rst2xml.py`` front end produces Docutils-native XML output.
 303 This can be transformed with standard XML tools such as XSLT
 304 processors into arbitrary final forms. An example is the xml2rst_ processor
 305 in the Docutils sandbox.
 306
 307 .. _xml2rst: ../../../sandbox/xml2rst
 308
 309
 310 ODF/OpenOffice-Generating Tools
 311 ===============================
 312
 313 rst2odt.py
 314 ----------
 315
 316 :Reader: Standalone
 317 :Parser: reStructuredText
 318 :Writer: ODF/.odt
 319
 320 The ``rst2odt.py`` front end reads standalone reStructuredText
 321 source files and produces ODF/.odt files that can be read, edited,
 322 printed, etc with OpenOffice ``oowriter``
 323 (http://www.openoffice.org/).  A stylesheet file is required.  A
 324 stylesheet file is an OpenOffice .odt file containing definitions
 325 of the styles required for ``rst2odt.py``.  You can learn more
 326 about how to use ``rst2odt.py``, the styles used ``rst2odt.py``,
 327 etc from `Odt Writer for Docutils <odt.html>`_.
 328
 329
 330 reStructuredText-Generating Tools
 331 =================================
 332
 333 Currently, there is no reStructuredText writer in Docutils and therefore
 334 an ``rst2rst.py`` tool is still missing.
 335
 336 To generate reStructuredText documents with Docutils, you can use
 337 the XML (Docutils native) writer and the xml2rst_ processor.
 338
 339
 340 Testing/Debugging Tools
 341 =======================
 342
 343 rst2pseudoxml.py
 344 ----------------
 345
 346 :Reader: Standalone
 347 :Parser: reStructuredText
 348 :Writer: Pseudo-XML
 349
 350 ``rst2pseudoxml.py`` is used for debugging the Docutils "Reader to
 351 Transform to Writer" pipeline.  It produces a compact pretty-printed
 352 "pseudo-XML", where nesting is indicated by indentation (no end-tags).
 353 External attributes for all elements are output, and internal
 354 attributes for any leftover "pending" elements are also given.
 355
 356
 357 quicktest.py
 358 ------------
 359
 360 :Reader: N/A
 361 :Parser: reStructuredText
 362 :Writer: N/A
 363
 364 The ``quicktest.py`` tool is used for testing the reStructuredText
 365 parser.  It does not use a Docutils Reader or Writer or the standard
 366 Docutils command-line options.  Rather, it does its own I/O and calls
 367 the parser directly.  No transforms are applied to the parsed
 368 document.  Various forms output are possible:
 369
 370 - Pretty-printed pseudo-XML (default)
 371 - Test data (Python list of input and pseudo-XML output strings;
 372   useful for creating new test cases)
 373 - Pretty-printed native XML
 374 - Raw native XML (with or without a stylesheet reference)
 375
 376
 377
 378 ---------------
 379  Customization
 380 ---------------
 381
 382 Command-Line Options
 383 ====================
 384
 385 Each front-end tool supports command-line options for one-off
 386 customization.  For persistent customization, use `configuration
 387 files`_.  Command-line options take priority over configuration file
 388 settings.
 389
 390 Use the "--help" option on each of the front ends to list the
 391 command-line options it supports.  Command-line options and their
 392 corresponding configuration file entry names are listed in the
 393 `Docutils Configuration Files`_ document.
 394
 395
 396 .. _configuration file:
 397
 398 Configuration Files
 399 ===================
 400
 401 Configuration files are used for persistent customization; they can be
 402 set once and take effect every time you use a front-end tool.
 403
 404 For details, see `Docutils Configuration Files`_.
 405
 406 .. _Docutils Configuration Files: config.html
 407 .. _Generating LaTeX with Docutils: latex.html
 408 \f
 409 ..
 410    Local Variables:
 411    mode: indented-text
 412    indent-tabs-mode: nil
 413    sentence-end-double-space: t
 414    fill-column: 70
 415    End: