docutils/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.
  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 (html4css1)
 105
 106 The ``rst2html.py`` front end reads standalone reStructuredText source
 107 files and produces HTML 4 (XHTML 1) "transitional" output compatible with
 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 rst2xhtml11.py
 143 --------------
 144
 145 :Reader: Standalone
 146 :Parser: reStructuredText
 147 :Writer: xhtml11
 148
 149 The ``rst2xhtml11.py`` front end reads standalone reStructuredText source
 150 files and produces clean XHTML 1.1 output. A stylesheet is required for
 151 proper rendering; a complete stylesheet is installed and used by default.
 152
 153 rst2html5.py
 154 ------------
 155
 156 :Reader: Standalone
 157 :Parser: reStructuredText
 158 :Writer: html5
 159
 160 The ``rst2html5.py`` front end reads standalone reStructuredText source
 161 files and produces simple HTML 5 output. A stylesheet is required for
 162 proper rendering; a complete stylesheet is installed and used by default.
 163
 164 rstpep2html.py
 165 --------------
 166
 167 :Reader: PEP
 168 :Parser: reStructuredText
 169 :Writer: PEP/HTML
 170
 171 ``rstpep2html.py`` reads a new-style PEP (marked up with
 172 reStructuredText) and produces HTML.  It requires a template file and
 173 a stylesheet.  By default, it makes use of a "``pep-html-template``"
 174 file and the "``pep.css``" stylesheet (both in the
 175 ``docutils/writers/pep_html/`` directory), but these can be overridden
 176 by command-line options or configuration files.
 177
 178 For example, to process a PEP into HTML::
 179
 180     cd <path-to-docutils>/docs/peps
 181     rstpep2html.py pep-0287.txt pep-0287.html
 182
 183
 184 rst2s5.py
 185 ---------
 186
 187 :Reader: Standalone
 188 :Parser: reStructuredText
 189 :Writer: S5/HTML
 190
 191 The ``rst2s5.py`` front end reads standalone reStructuredText source
 192 files and produces (X)HTML output compatible with S5_, the "Simple
 193 Standards-based Slide Show System" by Eric Meyer.  A theme is required
 194 for proper rendering; several are distributed with Docutils and others
 195 are available; see Themes_ below.
 196
 197 For example, to process a reStructuredText file "``slides.txt``" into
 198 S5/HTML::
 199
 200     rst2s5.py slides.txt slides.html
 201
 202 Now open the "``slides.html``" file in your favorite browser, switch
 203 to full-screen mode, and enjoy the results.
 204
 205 .. _S5: http://meyerweb.com/eric/tools/s5/
 206
 207
 208 Themes
 209 ``````
 210
 211 Each S5 theme consists of a directory containing several files:
 212 stylesheets, JavaScript, and graphics.  These are copied into a
 213 ``ui/<theme>`` directory beside the generated HTML.  A theme is chosen
 214 using the "``--theme``" option (for themes that come with Docutils) or
 215 the "``--theme-url``" option (for themes anywhere).  For example, the
 216 "medium-black" theme can be specified as follows::
 217
 218     rst2s5.py --theme medium-black slides.txt slides.html
 219
 220 The theme will be copied to the ``ui/medium-black`` directory.
 221
 222 Several themes are included with Docutils:
 223
 224 ``default``
 225     This is a simplified version of S5's default theme.
 226
 227     :Main content: black serif text on a white background
 228     :Text capacity: about 13 lines
 229     :Headers: light blue, bold sans-serif text on a dark blue
 230               background; titles are limited to one line
 231     :Footers: small, gray, bold sans-serif text on a dark blue
 232               background
 233
 234 ``small-white``
 235     (Small text on a white background.)
 236
 237     :Main content: black serif text on a white background
 238     :Text capacity: about 15 lines
 239     :Headers: black, bold sans-serif text on a white background;
 240               titles wrap
 241     :Footers: small, dark gray, bold sans-serif text on a white
 242               background
 243
 244 ``small-black``
 245     :Main content: white serif text on a black background
 246     :Text capacity: about 15 lines
 247     :Headers: white, bold sans-serif text on a black background;
 248               titles wrap
 249     :Footers: small, light gray, bold sans-serif text on a black
 250               background
 251
 252 ``medium-white``
 253     :Main content: black serif text on a white background
 254     :Text capacity: about 9 lines
 255     :Headers: black, bold sans-serif text on a white background;
 256               titles wrap
 257     :Footers: small, dark gray, bold sans-serif text on a white
 258               background
 259
 260 ``medium-black``
 261     :Main content: white serif text on a black background
 262     :Text capacity: about 9 lines
 263     :Headers: white, bold sans-serif text on a black background;
 264               titles wrap
 265     :Footers: small, light gray, bold sans-serif text on a black
 266               background
 267
 268 ``big-white``
 269     :Main content: black, bold sans-serif text on a white background
 270     :Text capacity: about 5 lines
 271     :Headers: black, bold sans-serif text on a white background;
 272               titles wrap
 273     :Footers: not displayed
 274
 275 ``big-black``
 276     :Main content: white, bold sans-serif text on a black background
 277     :Text capacity: about 5 lines
 278     :Headers: white, bold sans-serif text on a black background;
 279               titles wrap
 280     :Footers: not displayed
 281
 282 If a theme directory contains a file named ``__base__``, the name of
 283 the theme's base theme will be read from it.  Files are accumulated
 284 from the named theme, any base themes, and the "default" theme (which
 285 is the implicit base of all themes).
 286
 287 For details, please see `Easy Slide Shows With reStructuredText &
 288 S5 <slide-shows.html>`_.
 289
 290
 291 LaTeX-Generating Tools
 292 ======================
 293
 294 rst2latex.py
 295 ------------
 296
 297 :Reader: Standalone
 298 :Parser: reStructuredText
 299 :Writer: LaTeX2e
 300
 301 The ``rst2latex.py`` front end reads standalone reStructuredText
 302 source files and produces LaTeX2e output. For example, to process a
 303 reStructuredText file "``test.txt``" into LaTeX::
 304
 305     rst2latex.py test.txt test.tex
 306
 307 The output file "``test.tex``" should then be processed with ``latex``
 308 or ``pdflatex`` to get a document in DVI, PostScript or PDF format for
 309 printing or on-screen viewing.
 310
 311 For details see `Generating LaTeX with Docutils`_.
 312
 313
 314 XML-Generating Tools
 315 ====================
 316
 317 rst2xml.py
 318 ----------
 319
 320 :Reader: Standalone
 321 :Parser: reStructuredText
 322 :Writer: XML (Docutils native)
 323
 324 The ``rst2xml.py`` front end produces Docutils-native XML output.
 325 This can be transformed with standard XML tools such as XSLT
 326 processors into arbitrary final forms. An example is the xml2rst_ processor
 327 in the Docutils sandbox.
 328
 329 .. _xml2rst: ../../../sandbox/xml2rst
 330
 331
 332 ODF/OpenOffice-Generating Tools
 333 ===============================
 334
 335 rst2odt.py
 336 ----------
 337
 338 :Reader: Standalone
 339 :Parser: reStructuredText
 340 :Writer: ODF/.odt
 341
 342 The ``rst2odt.py`` front end reads standalone reStructuredText
 343 source files and produces ODF/.odt files that can be read, edited,
 344 printed, etc with OpenOffice ``oowriter``
 345 (http://www.openoffice.org/).  A stylesheet file is required.  A
 346 stylesheet file is an OpenOffice .odt file containing definitions
 347 of the styles required for ``rst2odt.py``.  You can learn more
 348 about how to use ``rst2odt.py``, the styles used ``rst2odt.py``,
 349 etc from `Odt Writer for Docutils <odt.html>`_.
 350
 351
 352 reStructuredText-Generating Tools
 353 =================================
 354
 355 Currently, there is no reStructuredText writer in Docutils and therefore
 356 an ``rst2rst.py`` tool is still missing.
 357
 358 To generate reStructuredText documents with Docutils, you can use
 359 the XML (Docutils native) writer and the xml2rst_ processor.
 360
 361
 362 Testing/Debugging Tools
 363 =======================
 364
 365 rst2pseudoxml.py
 366 ----------------
 367
 368 :Reader: Standalone
 369 :Parser: reStructuredText
 370 :Writer: Pseudo-XML
 371
 372 ``rst2pseudoxml.py`` is used for debugging the Docutils "Reader to
 373 Transform to Writer" pipeline.  It produces a compact pretty-printed
 374 "pseudo-XML", where nesting is indicated by indentation (no end-tags).
 375 External attributes for all elements are output, and internal
 376 attributes for any leftover "pending" elements are also given.
 377
 378
 379 quicktest.py
 380 ------------
 381
 382 :Reader: N/A
 383 :Parser: reStructuredText
 384 :Writer: N/A
 385
 386 The ``quicktest.py`` tool is used for testing the reStructuredText
 387 parser.  It does not use a Docutils Reader or Writer or the standard
 388 Docutils command-line options.  Rather, it does its own I/O and calls
 389 the parser directly.  No transforms are applied to the parsed
 390 document.  Various forms output are possible:
 391
 392 - Pretty-printed pseudo-XML (default)
 393 - Test data (Python list of input and pseudo-XML output strings;
 394   useful for creating new test cases)
 395 - Pretty-printed native XML
 396 - Raw native XML (with or without a stylesheet reference)
 397
 398
 399
 400 ---------------
 401  Customization
 402 ---------------
 403
 404 Command-Line Options
 405 ====================
 406
 407 Each front-end tool supports command-line options for one-off
 408 customization.  For persistent customization, use `configuration
 409 files`_.  Command-line options take priority over configuration file
 410 settings.
 411
 412 Use the "--help" option on each of the front ends to list the
 413 command-line options it supports.  Command-line options and their
 414 corresponding configuration file entry names are listed in the
 415 `Docutils Configuration Files`_ document.
 416
 417
 418 .. _configuration file:
 419
 420 Configuration Files
 421 ===================
 422
 423 Configuration files are used for persistent customization; they can be
 424 set once and take effect every time you use a front-end tool.
 425
 426 For details, see `Docutils Configuration Files`_.
 427
 428 .. _Docutils Configuration Files: config.html
 429 .. _Generating LaTeX with Docutils: latex.html
 430 \f
 431 ..
 432    Local Variables:
 433    mode: indented-text
 434    indent-tabs-mode: nil
 435    sentence-end-double-space: t
 436    fill-column: 70
 437    End: