File: tools.txt

package info (click to toggle)
python-docutils 0.12+dfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 8,108 kB
  • ctags: 7,367
  • sloc: python: 41,778; lisp: 8,644; sh: 164; makefile: 148; xml: 34
file content (438 lines) | stat: -rw-r--r-- 13,519 bytes parent folder | download
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
==========================
 Docutils Front-End Tools
==========================

:Author: David Goodger
:Contact: docutils-develop@lists.sourceforge.net
:Revision: $Revision: 7677 $
:Date: $Date: 2013-07-03 11:39:52 +0200 (Mit, 03. Jul 2013) $
: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 as well.

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.

The ``rst2html.py`` front end reads standalone reStructuredText source
files and produces HTML 4 (XHTML 1) output compatible with modern
browsers that support cascading stylesheets (CSS).  A 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 a
different stylesheet, you must specify the stylesheet's location with
a "``--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


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 HTML.  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


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/


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>`_.


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 LaTeX2e 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`_.


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: