1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510
|
==========================
Docutils Front-End Tools
==========================
:Author: David Goodger
:Contact: docutils-develop@lists.sourceforge.net
:Revision: $Revision: 8012 $
:Date: $Date: 2017-01-04 00:08:19 +0100 (Mi, 04 Jan 2017) $
: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.
In Debian these tools are installed in the normal system path, without the
``.py`` extension, according to Debian policy.
buildhtml.py_ is installed as rst-buildhtml.
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_
In Debian this tool is installed under the name rst-buildhtml.
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::
rst-buildhtml [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_
In Debian this front end is installed as rst2html.
`rst2html.py` is the front-end for the default Docutils HTML writer.
The default writer may change with the development of HTML, browsers,
Docutils, and the web. Currently, it is html4css1_.
* Use `rst2html.py`, if you want the output to be up-to-date automatically.
* Use a specific front end, if you depend on stability of the
generated HTML code, e.g. because you use a custom style sheet or
post-processing that may break otherwise.
rst2html4.py
------------
:Reader: Standalone
:Parser: reStructuredText
:Writer: html4css1_
In Debian this front end is installed as rst2html4.
The ``rst2html4.py`` front end reads standalone reStructuredText source
files and produces `XHTML 1.0 Transitional`_ output.
A CSS 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 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 -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
different stylesheet(s), specify the stylesheets' location(s)
as comma-separated list with the "``--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
.. _html4css1: html.html#html4css1
.. _html: html.html#html
rst2html5.py
------------
:Reader: Standalone
:Parser: reStructuredText
:Writer: html5 (html5_polyglot_)
In Debian this front end is installed as rst2html5.
The ``rst2html5.py`` front end reads standalone reStructuredText source
files and produces `HTMLÂ 5`_ output.
Correct rendering of elements not directly supported by HTML depends on a
CSS style sheet. The provided style sheets ``minimal.css`` and ``plain.css``
define required and optional styling rules respectively.
.. _html5_polyglot: html.html#html5-polyglot
rstpep2html.py
--------------
:Reader: PEP
:Parser: reStructuredText
:Writer: pep_html_
In Debian this front end is installed as rstpep2html.
``rstpep2html.py`` reads a new-style PEP (marked up with reStructuredText)
and produces `XHTML 1.0 Transitional`_. 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 pep-0287.txt pep-0287.html
.. _pep_html: html.html#pep-html
rst2s5.py
---------
:Reader: Standalone
:Parser: reStructuredText
:Writer: s5_html_
In Debian this is installed as rst2s5.
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 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/
.. _s5_html: html.html#s5-html
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 --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>`_.
.. _HTML 5: http://www.w3.org/TR/html5/
.. _HTML 4.1: http://www.w3.org/TR/html401/
.. _XHTML 1.0 Transitional: http://www.w3.org/TR/xhtml1/
.. _XHTML 1.1: http://www.w3.org/TR/xhtml1/
LaTeX-Generating Tools
======================
rst2latex.py
------------
:Reader: Standalone
:Parser: reStructuredText
:Writer: latex2e
In Debian this is installed as rst2latex.
The ``rst2latex.py`` front end reads standalone reStructuredText
source files and produces LaTeX_ output. For example, to process a
reStructuredText file "``test.txt``" into LaTeX::
rst2latex test.txt test.tex
The output file "``test.tex``" should then be processed with ``latex``
or ``pdflatex`` to get a document in DVI, PostScript or PDF format for
printing or on-screen viewing.
For details see `Generating LaTeX with Docutils`_.
rst2xetex.py
------------
:Reader: Standalone
:Parser: reStructuredText
:Writer: xetex
On Debian this front end is installed as rst2xetex.
The ``rst2xetex.py`` front end reads standalone reStructuredText source
files and produces `LaTeX` output for processing with unicode-aware
TeX engines (`LuaTeX`_ or `XeTeX`_). For example, to process a
reStructuredText file "``test.txt``" into LaTeX::
rst2xetex.py test.txt test.tex
The output file "``test.tex``" should then be processed with ``xelatex`` or
``lualatex`` to get a document in PDF format for printing or on-screen
viewing.
For details see `Generating LaTeX with Docutils`_.
.. _LaTeX: https://en.wikipedia.org/wiki/LaTeX
.. _XeTeX: https://en.wikipedia.org/wiki/XeTeX
.. _LuaTeX: https://en.wikipedia.org/wiki/LuaTeX
XML-Generating Tools
====================
rst2xml.py
----------
:Reader: Standalone
:Parser: reStructuredText
:Writer: XML (Docutils native)
In Debian this is installed as rst2xml.
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. An example is the xml2rst_ processor
in the Docutils sandbox.
.. _xml2rst: ../../../sandbox/xml2rst
ODF/OpenOffice-Generating Tools
===============================
rst2odt.py
----------
:Reader: Standalone
:Parser: reStructuredText
:Writer: ODF/.odt
In Debian this front end is installed as rst2odt.
The ``rst2odt.py`` front end reads standalone reStructuredText
source files and produces ODF/.odt files that can be read, edited,
printed, etc with OpenOffice ``oowriter``
(http://www.openoffice.org/). A stylesheet file is required. A
stylesheet file is an OpenOffice .odt file containing definitions
of the styles required for ``rst2odt.py``. You can learn more
about how to use ``rst2odt.py``, the styles used ``rst2odt.py``,
etc from `Odt Writer for Docutils <odt.html>`_.
reStructuredText-Generating Tools
=================================
Currently, there is no reStructuredText writer in Docutils and therefore
an ``rst2rst.py`` tool is still missing.
To generate reStructuredText documents with Docutils, you can use
the XML (Docutils native) writer and the xml2rst_ processor.
Testing/Debugging Tools
=======================
rst2pseudoxml.py
----------------
:Reader: Standalone
:Parser: reStructuredText
:Writer: Pseudo-XML
In Debian this is installed as rst2pseudoxml.
``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
This tool is not currently installed by the Debian package;
``apt-get source python-docutils`` if you need it.
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:
|