1 .. -*- coding: utf-8 -*-
3 ===========================================
4 Docutils FAQ (Frequently Asked Questions)
5 ===========================================
9 :Web site: http://docutils.sourceforge.net/
10 :Copyright: This document has been placed in the public domain.
16 This is a work in progress. Please feel free to ask questions and/or
17 provide answers; send email to the `Docutils-users`_ mailing list.
18 Project members should feel free to edit the source text file
22 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
31 Docutils_ is a system for processing plaintext documentation into
32 useful formats, such as HTML, XML, and LaTeX. It supports multiple
33 types of input, such as standalone files (implemented), inline
34 documentation from Python modules and packages (under development),
35 `PEPs (Python Enhancement Proposals)`_ (implemented), and others as
38 The Docutils distribution consists of:
40 * a library (the "docutils" package), which `can be used by client
42 * several `front-end tools`_ (such as ``rst2html.py``, which converts
43 reStructuredText input into HTML output);
44 * a `test suite`_; and
45 * extensive documentation_.
47 For an overview of the Docutils project implementation, see `PEP
48 258`_, "Docutils Design Specification".
50 Docutils is implemented in Python_.
52 .. _Docutils: http://docutils.sourceforge.net/
53 .. _PEPs (Python Enhancement Proposals):
54 http://www.python.org/peps/pep-0012.html
55 .. _can be used by client code:
56 http://docutils.sourceforge.net/docs/api/publisher.html
57 .. _front-end tools: http://docutils.sourceforge.net/docs/user/tools.html
58 .. _test suite: http://docutils.sourceforge.net/docs/dev/testing.html
59 .. _documentation: http://docutils.sourceforge.net/docs/
60 .. _PEP 258: http://www.python.org/peps/pep-0258.html
61 .. _Python: http://www.python.org/
64 Why is it called "Docutils"?
65 ----------------------------
67 Docutils is short for "Python Documentation Utilities". The name
68 "Docutils" was inspired by "Distutils", the Python Distribution
69 Utilities architected by Greg Ward, a component of Python's standard
72 The earliest known use of the term "docutils" in a Python context was
73 a `fleeting reference`__ in a message by Fred Drake on 1999-12-02 in
74 the Python Doc-SIG mailing list. It was suggested `as a project
75 name`__ on 2000-11-27 on Doc-SIG, again by Fred Drake, in response to
76 a question from Tony "Tibs" Ibbs: "What do we want to *call* this
77 thing?". This was shortly after David Goodger first `announced
78 reStructuredText`__ on Doc-SIG.
80 Tibs used the name "Docutils" for `his effort`__ "to document what the
81 Python docutils package should support, with a particular emphasis on
82 documentation strings". Tibs joined the current project (and its
83 predecessors) and graciously donated the name.
85 For more history of reStructuredText and the Docutils project, see `An
86 Introduction to reStructuredText`_.
88 Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils"
89 or any other variation. It is pronounced as in "DOCumentation
90 UTILitieS", with emphasis on the first syllable.
92 .. _An Introduction to reStructuredText:
93 http://docutils.sourceforge.net/docs/ref/rst/introduction.html
94 __ http://mail.python.org/pipermail/doc-sig/1999-December/000878.html
95 __ http://mail.python.org/pipermail/doc-sig/2000-November/001252.html
96 __ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html
97 __ http://homepage.ntlworld.com/tibsnjoan/docutils/STpy.html
100 Is there a GUI authoring environment for Docutils?
101 --------------------------------------------------
103 DocFactory_ is under development. It uses wxPython and looks very
107 http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
110 What is the status of the Docutils project?
111 -------------------------------------------
113 Although useful and relatively stable, Docutils is experimental code,
114 with APIs and architecture subject to change.
116 Our highest priority is to fix bugs as they are reported. So the
117 latest code from the repository_ (or the snapshots_) is almost always
118 the most stable (bug-free) as well as the most featureful.
121 What is the Docutils project release policy?
122 --------------------------------------------
124 It's "release early & often". We also have automatically-generated
125 snapshots_ which always contain the latest code from the repository_.
126 As the project matures, we may formalize on a
127 stable/development-branch scheme, but we're not using anything like
130 .. _repository: docs/dev/repository.html
131 .. _snapshots: http://docutils.sourceforge.net/#download
137 What is reStructuredText?
138 -------------------------
140 reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get
141 plaintext markup syntax and parser system. The reStructuredText
142 parser is a component of Docutils_. reStructuredText is a revision
143 and reinterpretation of the StructuredText_ and Setext_ lightweight
146 If you are reading this on the web, you can see for yourself. `The
147 source for this FAQ <FAQ.txt>`_ is written in reStructuredText; open
148 it in another window and compare them side by side.
150 `A ReStructuredText Primer`_ and the `Quick reStructuredText`_ user
151 reference are a good place to start. The `reStructuredText Markup
152 Specification`_ is a detailed technical specification.
154 .. _A ReStructuredText Primer:
155 http://docutils.sourceforge.net/docs/user/rst/quickstart.html
156 .. _Quick reStructuredText:
157 http://docutils.sourceforge.net/docs/user/rst/quickref.html
158 .. _reStructuredText Markup Specification:
159 http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
160 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
162 http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
163 .. _Setext: http://docutils.sourceforge.net/mirror/setext.html
166 Why is it called "reStructuredText"?
167 ------------------------------------
169 The name came from a combination of "StructuredText", one of
170 reStructuredText's predecessors, with "re": "revised", "reworked", and
171 "reinterpreted", and as in the ``re.py`` regular expression module.
172 For a detailed history of reStructuredText and the Docutils project,
173 see `An Introduction to reStructuredText`_.
176 What's the standard abbreviation for "reStructuredText"?
177 --------------------------------------------------------
179 "RST" and "ReST" (or "reST") are both acceptable. Care should be
180 taken with capitalization, to avoid confusion with "REST__", an
181 acronym for "Representational State Transfer".
183 The abbreviations "reSTX" and "rSTX"/"rstx" should **not** be used;
184 they overemphasize reStructuredText's precedessor, Zope's
187 __ http://en.wikipedia.org/wiki/Representational_State_Transfer
190 What's the standard filename extension for a reStructuredText file?
191 -------------------------------------------------------------------
193 It's ".txt". Some people would like to use ".rest" or ".rst" or
194 ".restx", but why bother? ReStructuredText source files are meant to
195 be readable as plaintext, and most operating systems already associate
196 ".txt" with text files. Using a specialized filename extension would
197 require that users alter their OS settings, which is something that
198 many users will not be willing or able to do.
201 Are there any reStructuredText editor extensions?
202 -------------------------------------------------
204 See `Editor Support for reStructuredText`__.
206 __ http://docutils.sf.net/tools/editors/README.html
209 How can I indicate the document title? Subtitle?
210 -------------------------------------------------
212 A uniquely-adorned section title at the beginning of a document is
213 treated specially, as the document title. Similarly, a
214 uniquely-adorned section title immediately after the document title
215 becomes the document subtitle. For example::
217 This is the Document Title
218 ==========================
220 This is the Document Subtitle
221 -----------------------------
223 Here's an ordinary paragraph.
227 Here's an ordinary paragraph.
229 This is *not* a Document Title
230 ==============================
232 The "ordinary paragraph" above the section title
233 prevents it from becoming the document title.
235 Another counterexample::
237 This is not the Document Title, because...
238 ===========================================
240 Here's an ordinary paragraph.
242 ... the title adornment is not unique
243 =====================================
245 Another ordinary paragraph.
248 How can I represent esoteric characters (e.g. character entities) in a document?
249 --------------------------------------------------------------------------------
251 For example, say you want an em-dash (XML character entity —,
252 Unicode character U+2014) in your document: use a real em-dash.
253 Insert concrete characters (e.g. type a *real* em-dash) into your
254 input file, using whatever encoding suits your application, and tell
255 Docutils the input encoding. Docutils uses Unicode internally, so the
256 em-dash character is a real em-dash internally.
258 Emacs users should refer to the `Emacs Support for reStructuredText`__
259 document. Tips for other editors are welcome.
261 __ http://docutils.sourceforge.net/tools/editors/emacs/README.html
263 ReStructuredText has no character entity subsystem; it doesn't know
264 anything about XML charents. To Docutils, "—" in input text is
265 7 discrete characters; no interpretation happens. When writing HTML,
266 the "&" is converted to "&", so in the raw output you'd see
267 "&mdash;". There's no difference in interpretation for text
268 inside or outside inline literals or literal blocks -- there's no
269 character entity interpretation in either case.
271 If you can't use a Unicode-compatible encoding and must rely on 7-bit
272 ASCII, there is a workaround. New in Docutils 0.3.10 is a set of
273 `Standard Substitution Definition Sets`_, which provide equivalents of
274 XML & HTML character entity sets as substitution definitions. For
275 example, the Japanese yen currency symbol can be used as follows::
277 .. include:: <xhtml1-lat1.txt>
279 |yen| 600 for a complete meal? That's cheap!
281 For earlier versions of Docutils, equivalent files containing
282 character entity set substitution definitions using the "unicode_"
283 directive `are available`_. Please read the `description and
284 instructions`_ for use. Thanks to David Priest for the original idea.
286 If you insist on using XML-style charents, you'll have to implement a
287 pre-processing system to convert to UTF-8 or something. That
288 introduces complications though; you can no longer *write* about
289 charents naturally; instead of writing "—" you'd have to write
292 For the common case of long dashes, you might also want to insert the
293 following substitution definitons into your document (both of them are
294 using the "unicode_" directive)::
296 .. |--| unicode:: U+2013 .. en dash
297 .. |---| unicode:: U+2014 .. em dash, trimming surrounding whitespace
300 .. |--| unicode:: U+2013 .. en dash
301 .. |---| unicode:: U+2014 .. em dash, trimming surrounding whitespace
304 Now you can write dashes using pure ASCII: "``foo |--| bar; foo |---|
305 bar``", rendered as "foo |--| bar; foo |---| bar". (Note that Mozilla
306 and Firefox may render this incorrectly.) The ``:trim:`` option for
307 the em dash is necessary because you cannot write "``foo|---|bar``";
308 thus you need to add spaces ("``foo |---| bar``") and advise the
309 reStructuredText parser to trim the spaces.
311 .. _Standard Substitution Definition Sets:
312 http://docutils.sf.net/docs/ref/rst/substitutions.html
314 http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
315 .. _are available: http://docutils.sourceforge.net/tmp/charents/
316 .. _tarball: http://docutils.sourceforge.net/tmp/charents.tgz
317 .. _description and instructions:
318 http://docutils.sourceforge.net/tmp/charents/README.html
319 .. _to-do list: http://docutils.sourceforge.net/docs/dev/todo.html
322 How can I generate backticks using a Scandinavian keyboard?
323 -----------------------------------------------------------
325 The use of backticks in reStructuredText is a bit awkward with
326 Scandinavian keyboards, where the backtick is a "dead" key. To get
327 one ` character one must press SHIFT-` + SPACE.
329 Unfortunately, with all the variations out there, there's no way to
330 please everyone. For Scandinavian programmers and technical writers,
331 this is not limited to reStructuredText but affects many languages and
334 Possible solutions include
336 * If you have to input a lot of backticks, simply type one in the
337 normal/awkward way, select it, copy and then paste the rest (CTRL-V
338 is a lot faster than SHIFT-` + SPACE).
340 * Use keyboard macros.
342 * Remap the keyboard. The Scandinavian keyboard layout is awkward for
343 other programming/technical characters too; for example, []{}
344 etc. are a bit awkward compared to US keyboards.
346 According to Axel Kollmorgen,
348 Under Windows, you can use the `Microsoft Keyboard Layout Creator
349 <http://www.microsoft.com/globaldev/tools/msklc.mspx>`__ to easily
350 map the backtick key to a real backtick (no dead key). took me
351 five minutes to load my default (german) keyboard layout, untick
352 "Dead Key?" from the backtick key properties ("in all shift
353 states"), "build dll and setup package", install the generated
354 .msi, and add my custom keyboard layout via Control Panel >
355 Regional and Language Options > Languages > Details > Add
356 Keyboard layout (and setting it as default "when you start your
359 * Use a virtual/screen keyboard or character palette, such as:
361 - `Web-based keyboards <http://keyboard.lab.co.il/>`__ (IE only
363 - Windows: `Click-N-Type <http://www.lakefolks.org/cnt/>`__.
364 - Mac OS X: the Character Palette can store a set of favorite
365 characters for easy input. Open System Preferences,
366 International, Input Menu tab, enable "Show input menu in menu
367 bar", and be sure that Character Palette is enabled in the list.
369 If anyone knows of other/better solutions, please `let us know`_.
372 Are there any tools for HTML/XML-to-reStructuredText? (Round-tripping)
373 -----------------------------------------------------------------------
375 People have tossed the idea around, and some implementations of
376 reStructuredText-generating tools can be found in the `Docutils Link
379 There's no reason why reStructuredText should not be round-trippable
380 to/from XML; any technicalities which prevent round-tripping would be
381 considered bugs. Whitespace would not be identical, but paragraphs
382 shouldn't suffer. The tricky parts would be the smaller details, like
383 links and IDs and other bookkeeping.
385 For HTML, true round-tripping may not be possible. Even adding lots
386 of extra "class" attributes may not be enough. A "simple HTML" to RST
387 filter is possible -- for some definition of "simple HTML" -- but HTML
388 is used as dumb formatting so much that such a filter may not be
389 particularly useful. An 80/20 approach should work though: build a
390 tool that does 80% of the work automatically, leaving the other 20%
393 .. _Docutils Link List: docs/user/links.html
396 Are there any Wikis that use reStructuredText syntax?
397 -----------------------------------------------------
399 There are several, with various degrees of completeness. With no
400 implied endorsement or recommendation, and in no particular order:
402 * `Webware for Python wiki
403 <http://wiki.webwareforpython.org/thiswiki.html>`__
404 * `Ian Bicking's experimental code
405 <http://docutils.sf.net/sandbox/ianb/wiki/Wiki.py>`__
406 * `MoinMoin <http://moinmoin.wikiwikiweb.de/>`__ has some support;
407 `here's a sample <http://moinmoin.wikiwikiweb.de/RestSample>`__
408 * Zope-based `Zwiki <http://zwiki.org/>`__
409 * Zope3-based Zwiki (in the Zope 3 source tree as ``zope.products.zwiki``)
410 * `StikiWiki <http://mithrandr.moria.org/code/stikiwiki/>`__
411 * `Trac <http://projects.edgewall.com/trac/>`__ `supports using reStructuredText
412 <http://projects.edgewall.com/trac/wiki/WikiRestructuredText>`__ as an
413 alternative to wiki markup. This includes support for `TracLinks
414 <http://projects.edgewall.com/trac/wiki/TracLinks>`__ from within RST
415 text via a custom RST reference-directive or, even easier, an interpreted text
417 * `Vogontia <http://www.ososo.de/vogontia/>`__, a Wiki-like FAQ system
419 Please `let us know`_ of any other reStructuredText Wikis.
421 The example application for the `Web Framework Shootout
422 <http://colorstudy.com/docs/shootout.html>`__ article is a Wiki using
426 Are there any Weblog (Blog) projects that use reStructuredText syntax?
427 ----------------------------------------------------------------------
429 With no implied endorsement or recommendation, and in no particular
432 * `Firedrop <http://www.voidspace.org.uk/python/firedrop2/>`__
433 * `Python Desktop Server <http://pyds.muensterland.org/>`__
434 * `PyBloxsom <http://pyblosxom.sourceforge.net/>`__
435 * `Lino WebMan <http://lino.sourceforge.net/webman.html>`__
437 Please `let us know`_ of any other reStructuredText Blogs.
440 Can lists be indented without generating block quotes?
441 ------------------------------------------------------
443 Some people like to write lists with indentation, without intending a
444 block quote context, like this::
451 There has been a lot of discussion about this, but there are some
452 issues that would need to be resolved before it could be implemented.
453 There is a summary of the issues and pointers to the discussions in
456 __ http://docutils.sourceforge.net/docs/dev/todo.html#indented-lists
459 Could the requirement for blank lines around lists be relaxed?
460 --------------------------------------------------------------
464 In reStructuredText, it would be impossible to unambigously mark up
465 and parse lists without blank lines before and after. Deeply nested
466 lists may look ugly with so many blank lines, but it's a price we pay
467 for unambiguous markup. Some other plaintext markup systems do not
468 require blank lines in nested lists, but they have to compromise
469 somehow, either accepting ambiguity or requiring extra complexity.
470 For example, `Epytext <http://epydoc.sf.net/epytext.html#list>`__ does
471 not require blank lines around lists, but it does require that lists
472 be indented and that ambiguous cases be escaped.
475 How can I include mathematical equations in documents?
476 ------------------------------------------------------
478 There is no elegant built-in way, yet. There are several ideas, but
479 no obvious winner. This issue requires a champion to solve the
480 technical and aesthetic issues and implement a generic solution.
481 Here's the `to-do list entry`__.
483 __ http://docutils.sourceforge.net/docs/dev/todo.html#math-markup
485 There are several quick & dirty ways to include equations in documents.
486 They all presently use LaTeX syntax or dialects of it.
488 * For LaTeX output, nothing beats raw LaTeX math. A simple way is to
489 use the `raw directive`_::
493 \[ x^3 + 3x^2a + 3xa^2 + a^3, \]
495 For inline math you could use substitutions of the raw directive but
496 the recently added `raw role`_ is more convenient. You must define a
497 custom role based on it once in your document::
499 .. role:: raw-latex(raw)
502 and then you can just use the new role in your text::
504 the binomial expansion of :raw-latex:`$(x+a)^3$` is
506 .. _raw directive: http://docutils.sourceforge.net/docs/ref/rst/
507 directives.html#raw-data-pass-through
508 .. _raw role: http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw
510 * Jens Jørgen Mortensen has implemented a "latex-math" role and
511 directive, available from `his sandbox`__.
513 __ http://docutils.sourceforge.net/sandbox/jensj/latex_math/
515 * For HTML the "Right" w3c-standard way to include math is MathML_.
516 Unfortunately its rendering is still quite broken (or absent) on many
517 browsers but it's getting better. Another bad problem is that typing
518 or reading raw MathML by humans is *really* painful, so embedding it
519 in a reST document with the raw directive would defy the goals of
520 readability and editability of reST (see an `example of raw MathML
521 <http://sf.net/mailarchive/message.php?msg_id=2177102>`__).
523 A much less painful way to generate HTML+MathML is to use itex2mml_ to
524 convert a dialect of LaTeX syntax to presentation MathML. Here is an
525 example of potential `itex math markup
526 <http://article.gmane.org/gmane.text.docutils.user/118>`__. The
527 simplest way to use it is to add ``html`` to the format lists for the
528 raw directive/role and postprocess the resulting document with
529 itex2mml. This way you can *generate LaTeX and HTML+MathML from the
530 same source*, but you must limit yourself to the intersection of LaTeX
531 and itex markups for this to work. Alan G. Isaac wrote a detailed
532 HOWTO_ for this approach.
534 .. _MathML: http://www.w3.org/Math/
535 .. _itex2mml: http://pear.math.pitt.edu/mathzilla/itex2mml.html
536 .. _HOWTO: http://www.american.edu/econ/itex2mml/mathhack.rst
538 * The other way to add math to HTML is to use images of the equations,
539 typically generated by TeX. This is inferior to MathML in the long
540 term but is perhaps more accessible nowdays.
542 Of course, doing it by hand is too much work. Beni Cherniavsky has
543 written some `preprocessing scripts`__ for converting the
544 ``texmath`` role/directive into images for HTML output and raw
545 directives/subsitution for LaTeX output. This way you can *generate
546 LaTeX and HTML+images from the same source*. `Instructions here`__.
548 __ http://docutils.sourceforge.net/sandbox/cben/rolehack/
549 __ http://docutils.sourceforge.net/sandbox/cben/rolehack/README.html
552 Is nested inline markup possible?
553 ---------------------------------
555 Not currently, no. It's on the `to-do list`__ (`details here`__), and
556 hopefully will be part of the reStructuredText parser soon. At that
557 time, markup like this will become possible::
559 Here is some *emphasized text containing a `hyperlink`_ and
560 ``inline literals``*.
562 __ http://docutils.sf.net/docs/dev/todo.html#nested-inline-markup
563 __ http://docutils.sf.net/docs/dev/rst/alternatives.html#nested-inline-markup
565 There are workarounds, but they are either convoluted or ugly or both.
566 They are not recommended.
568 * Inline markup can be combined with hyperlinks using `substitution
569 definitions`__ and references__ with the `"replace" directive`__.
572 Here is an |emphasized hyperlink|_.
574 .. |emphasized hyperlink| replace:: *emphasized hyperlink*
575 .. _emphasized hyperlink: http://example.org
577 It is not possible for just a portion of the replacement text to be
578 a hyperlink; it's the entire replacement text or nothing.
580 __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#substitution-definitions
581 __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#substitution-references
582 __ http://docutils.sf.net/docs/ref/rst/directives.html#replace
584 * The `"raw" directive`__ can be used to insert raw HTML into HTML
587 Here is some |stuff|.
589 .. |stuff| raw:: html
591 <em>emphasized text containing a
592 <a href="http://example.org">hyperlink</a> and
593 <tt>inline literals</tt></em>
595 Raw LaTeX is supported for LaTeX output, etc.
597 __ http://docutils.sf.net/docs/ref/rst/directives.html#raw
600 How to indicate a line break or a significant newline?
601 ------------------------------------------------------
603 `Line blocks`__ are designed for address blocks, verse, and other
604 cases where line breaks are significant and must be preserved. Unlike
605 literal blocks, the typeface is not changed, and inline markup is
606 recognized. For example::
608 | A one, two, a one two three four
610 | Half a bee, philosophically,
611 | must, *ipso facto*, half not be.
612 | But half the bee has got to be,
613 | *vis a vis* its entity. D'you see?
615 | But can a bee be said to be
616 | or not to be an entire bee,
617 | when half the bee is not a bee,
618 | due to some ancient injury?
622 __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#line-blocks
624 Here's a workaround for manually inserting explicit line breaks in
631 I want to break this line here: |br| this is after the break.
633 If the extra whitespace bothers you, |br|\ backslash-escape it.
636 A URL containing asterisks doesn't work. What to do?
637 -----------------------------------------------------
639 Asterisks are valid URL characters (see :RFC:`2396`), sometimes used
640 in URLs. For example::
642 http://cvs.example.org/viewcvs.py/*checkout*/module/file
644 Unfortunately, the parser thinks the asterisks are indicating
645 emphasis. The slashes serve as delineating punctuation, allowing the
646 asterisks to be recognized as markup. The example above is separated
647 by the parser into a truncated URL, an emphasized word, and some
650 http://cvs.example.org/viewcvs.py/
654 To turn off markup recognition, use a backslash to escape at least the
655 first asterisk, like this::
657 http://cvs.example.org/viewcvs.py/\*checkout*/module/file
659 Escaping the second asterisk doesn't hurt, but it isn't necessary.
662 How can I make a literal block with *some* formatting?
663 ------------------------------------------------------
665 Use the `parsed-literal`_ directive.
667 .. _parsed-literal: docs/ref/rst/directives.html#parsed-literal
669 Scenario: a document contains some source code, which calls for a
670 literal block to preserve linebreaks and whitespace. But part of the
671 source code should be formatted, for example as emphasis or as a
672 hyperlink. This calls for a *parsed* literal block::
676 print "Hello world!" # *tricky* code [1]_
678 The emphasis (``*tricky*``) and footnote reference (``[1]_``) will be
682 Can reStructuredText be used for web or generic templating?
683 -----------------------------------------------------------
685 Docutils and reStructuredText can be used with or as a component of a
686 templating system, but they do not themselves include templating
687 functionality. Templating should simply be left to dedicated
688 templating systems. Users can choose a templating system to apply to
689 their reStructuredText documents as best serves their interests.
691 There are many good templating systems for Python (ht2html_, YAPTU_,
692 Quixote_'s PTL, Cheetah_, etc.; see this non-exhaustive list of `some
693 other templating systems`_), and many more for other languages, each
694 with different approaches. We invite you to try several and find one
695 you like. If you adapt it to use Docutils/reStructuredText, please
696 consider contributing the code to Docutils or `let us know`_ and we'll
699 One reST-specific web templating system is `rest2web
700 <http://www.voidspace.org.uk/python/rest2web>`_, a tool for
701 automatically building websites, or parts of websites.
703 .. _ht2html: http://ht2html.sourceforge.net/
705 http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52305
706 .. _Quixote: http://www.mems-exchange.org/software/quixote/
707 .. _Cheetah: http://www.cheetahtemplate.org/
708 .. _some other templating systems:
709 http://webware.sourceforge.net/Papers/Templates/
712 How can I mark up a FAQ or other list of questions & answers?
713 -------------------------------------------------------------
715 There is no specific syntax for FAQs and Q&A lists. Here are two
718 1. For a FAQ (Frequently Asked Questions, usually with answers), a
719 convenient way to mark up the questions is as section titles, with
720 the answer(s) as section content. This document is marked up in
723 The advantages of using section titles for questions are: sections
724 can be numbered automatically, and a table of contents can be
725 generated automatically. One limitation of this format is that
726 questions must fit on one line (section titles may not wrap, in the
727 source text). For very long questions, the title may be a summary
728 of the question, with the full question in the section body.
730 2. Field lists work well as Q&A lists::
732 :Q: What kind of questions can we
735 :A: Any kind we like!
737 In order to separate questions, lists can be used:
739 1. :Q: What kind of question can we
741 :A: Any kind we like!
743 2. :Q: How many answers can a question have?
746 :A3: Answers can be numbered like this.
750 If you don't want to number or otherwise mark questions, you can
751 use an empty comment between individual field lists to separate
766 What is the status of the HTML Writer?
767 --------------------------------------
769 The HTML Writer module, ``docutils/writers/html4css1.py``, is a
770 proof-of-concept reference implementation. While it is a complete
771 implementation, some aspects of the HTML it produces may be
772 incompatible with older browsers or specialized applications (such as
773 web templating). Alternate implementations are welcome.
776 What kind of HTML does it produce?
777 ----------------------------------
779 It produces XHTML compatible with the `XHTML 1.0`_ specification. A
780 cascading stylesheet is required for proper viewing with a modern
781 graphical browser. Correct rendering of the HTML produced depends on
782 the CSS support of the browser. A general-purpose stylesheet,
783 ``html4css1.css`` is provided with the code, and is embedded by
784 default. It is installed in the "writers/html4css1/" subdirectory
785 within the Docutils package. Use the ``--help`` command-line option
786 to see the specific location on your machine.
788 .. _XHTML 1.0: http://www.w3.org/TR/xhtml1/
791 What browsers are supported?
792 ----------------------------
794 No specific browser is targeted; all modern graphical browsers should
795 work. Some older browsers, text-only browsers, and browsers without
796 full CSS support are known to produce inferior results. Firefox,
797 Safari, Mozilla (version 1.0 and up), and MS Internet Explorer
798 (version 5.0 and up) are known to give good results. Reports of
799 experiences with other browsers are welcome.
802 Unexpected results from tools/rst2html.py: H1, H1 instead of H1, H2. Why?
803 --------------------------------------------------------------------------
805 Here's the question in full:
812 All my life, I wanted to be H1.
817 But along came H1, and so shouldn't I be H2?
823 Yeah, imagine me, I'm stuck at H3! No?!?
825 When I run it through tools/rst2html.py, I get unexpected results
826 (below). I was expecting H1, H2, then H3; instead, I get H1, H1,
833 <title>Heading 1</title>
836 <div class="document" id="heading-1">
837 <h1 class="title">Heading 1</h1> <-- first H1
838 <p>All my life, I wanted to be H1.</p>
839 <div class="section" id="heading-1-1">
840 <h1><a name="heading-1-1">Heading 1.1</a></h1> <-- H1
841 <p>But along came H1, and so now I must be H2.</p>
842 <div class="section" id="heading-1-1-1">
843 <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
844 <p>Yeah, imagine me, I'm stuck at H3!</p>
849 Check the "class" attribute on the H1 tags, and you will see a
850 difference. The first H1 is actually ``<h1 class="title">``; this is
851 the document title, and the default stylesheet renders it centered.
852 There can also be an ``<h2 class="subtitle">`` for the document
855 If there's only one highest-level section title at the beginning of a
856 document, it is treated specially, as the document title. (Similarly, a
857 lone second-highest-level section title may become the document
858 subtitle.) See `How can I indicate the document title? Subtitle?`_ for
859 details. Rather than use a plain H1 for the document title, we use ``<h1
860 class="title">`` so that we can use H1 again within the document. Why
861 do we do this? HTML only has H1-H6, so by making H1 do double duty, we
862 effectively reserve these tags to provide 6 levels of heading beyond the
863 single document title.
865 HTML is being used for dumb formatting for nothing but final display.
866 A stylesheet *is required*, and one is provided; see `What kind of
867 HTML does it produce?`_ above. Of course, you're welcome to roll your
868 own. The default stylesheet provides rules to format ``<h1
869 class="title">`` and ``<h2 class="subtitle">`` differently from
870 ordinary ``<h1>`` and ``<h2>``::
878 If you don't want the top section heading to be interpreted as a
879 title at all, disable the `doctitle_xform`_ setting
880 (``--no-doc-title`` option). This will interpret your document
881 differently from the standard settings, which might not be a good
882 idea. If you don't like the reuse of the H1 in the HTML output, you
883 can tweak the `initial_header_level`_ setting
884 (``--initial-header-level`` option) -- but unless you match its value
885 to your specific document, you might end up with bad HTML (e.g. H3
889 http://docutils.sourceforge.net/docs/user/config.html#doctitle-xform
890 .. _initial_header_level:
891 http://docutils.sourceforge.net/docs/user/config.html#initial-header-level
893 (Thanks to Mark McEahern for the question and much of the answer.)
896 Why do enumerated lists only use numbers (no letters or roman numerals)?
897 ------------------------------------------------------------------------
899 The rendering of enumerators (the numbers or letters acting as list
900 markers) is completely governed by the stylesheet, so either the
901 browser can't find the stylesheet (try using the "--embed-stylesheet"
902 option), or the browser can't understand it (try a recent Firefox,
903 Mozilla, Konqueror, Opera, Safari, or even MSIE).
906 There appear to be garbage characters in the HTML. What's up?
907 --------------------------------------------------------------
909 What you're seeing is most probably not garbage, but the result of a
910 mismatch between the actual encoding of the HTML output and the
911 encoding your browser is expecting. Your browser is misinterpreting
912 the HTML data, which is encoded text. A discussion of text encodings
913 is beyond the scope of this FAQ; see one or more of these documents
916 * `UTF-8 and Unicode FAQ for Unix/Linux
917 <http://www.cl.cam.ac.uk/~mgk25/unicode.html>`_
919 * Chapters 3 and 4 of `Introduction to i18n [Internationalization]
920 <http://www.debian.org/doc/manuals/intro-i18n/>`_
922 * `Python Unicode Tutorial
923 <http://www.reportlab.com/i18n/python_unicode_tutorial.html>`_
925 * `Python Unicode Objects: Some Observations on Working With Non-ASCII
926 Character Sets <http://effbot.org/zone/unicode-objects.htm>`_
928 The common case is with the default output encoding (UTF-8), when
929 either numbered sections are used (via the "sectnum_" directive) or
930 symbol-footnotes. 3 non-breaking spaces are inserted in each numbered
931 section title, between the generated number and the title text. Most
932 footnote symbols are not available in ASCII, nor are non-breaking
933 spaces. When encoded with UTF-8 and viewed with ordinary ASCII tools,
934 these characters will appear to be multi-character garbage.
936 You may have an decoding problem in your browser (or editor, etc.).
937 The encoding of the output is set to "utf-8", but your browswer isn't
938 recognizing that. You can either try to fix your browser (enable
939 "UTF-8 character set", sometimes called "Unicode"), or choose a
940 different encoding for the HTML output. You can also try
941 ``--output-encoding=ascii:xmlcharrefreplace`` for HTML or XML, but not
942 applicable to non-XMLish outputs (if using runtime
943 settings/configuration files, use ``output_encoding=ascii`` and
944 ``output_encoding_error_handler=xmlcharrefreplace``).
946 If you're generating document fragments, the "Content-Type" metadata
947 (between the HTML ``<head>`` and ``</head>`` tags) must agree with the
948 encoding of the rest of the document. For UTF-8, it should be::
950 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
952 Also, Docutils normally generates an XML declaration as the first line
953 of the output. It must also match the document encoding. For UTF-8::
955 <?xml version="1.0" encoding="utf-8" ?>
958 http://docutils.sourceforge.net/docs/ref/rst/directives.html#sectnum
961 How can I retrieve the body of the HTML document?
962 -------------------------------------------------
964 (This is usually needed when using Docutils in conjunction with a
967 You can use the `docutils.core.publish_parts()`_ function, which
968 returns a dictionary containing an 'html_body_' entry.
970 .. _docutils.core.publish_parts():
971 docs/api/publisher.html#publish-parts
973 docs/api/publisher.html#html-body
976 Why is the Docutils XHTML served as "Content-type: text/html"?
977 --------------------------------------------------------------
981 Docutils' HTML output looks like XHTML and is advertised as such::
983 <?xml version="1.0" encoding="utf-8" ?>
984 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
985 "http://www.w3.org/TR/xht ml1/DTD/xhtml1-transitional.dtd">
987 But this is followed by::
989 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
991 Shouldn't this be "application/xhtml+xml" instead of "text/html"?
993 In a perfect web, the Docutils XHTML output would be 100% strict
994 XHTML. But it's not a perfect web, and a major source of imperfection
995 is Internet Explorer. Despite it's drawbacks, IE still represents the
996 majority of web browsers, and cannot be ignored.
998 Short answer: if we didn't serve XHTML as "text/html" (which is a
999 perfectly valid thing to do), it couldn't be viewed in Internet
1002 Long answer: see the `"Criticisms of Internet Explorer" Wikipedia
1003 entry <http://en.wikipedia.org/wiki/Criticisms_of_Internet_Explorer#XHTML>`__.
1005 However, there's also `Sending XHTML as text/html Considered
1006 Harmful`__. What to do, what to do? We're damned no matter what we
1007 do. So we'll continue to do the practical instead of the pure:
1008 support the browsers that are actually out there, and not fight for
1009 strict standards compliance.
1011 __ http://hixie.ch/advocacy/xhtml
1013 (Thanks to Martin F. Krafft, Robert Kern, Michael Foord, and Alan
1017 Python Source Reader
1018 ====================
1020 Can I use Docutils for Python auto-documentation?
1021 -------------------------------------------------
1023 Yes, in conjunction with other projects.
1025 Docstring extraction functionality from within Docutils is still under
1026 development. There is most of a source code parsing module in
1027 docutils/readers/python/moduleparser.py. We do plan to finish it
1028 eventually. Ian Bicking wrote an initial front end for the
1029 moduleparser.py module, in sandbox/ianb/extractor/extractor.py. Ian
1030 also did some work on the Python Source Reader
1031 (docutils.readers.python) component at PyCon DC 2004.
1033 Version 2.0 of Ed Loper's `Epydoc <http://epydoc.sourceforge.net/>`_
1034 supports reStructuredText-format docstrings for HTML output. Docutils
1035 0.3 or newer is required. Development of a Docutils-specific
1036 auto-documentation tool will continue. Epydoc works by importing
1037 Python modules to be documented, whereas the Docutils-specific tool,
1038 described above, will parse modules without importing them (as with
1039 `HappyDoc <http://happydoc.sourceforge.net/>`_, which doesn't support
1042 The advantages of parsing over importing are security and flexibility;
1043 the disadvantage is complexity/difficulty.
1045 * Security: untrusted code that shouldn't be executed can be parsed;
1046 importing a module executes its top-level code.
1047 * Flexibility: comments and unofficial docstrings (those not supported
1048 by Python syntax) can only be processed by parsing.
1049 * Complexity/difficulty: it's a lot harder to parse and analyze a
1050 module than it is to ``import`` and analyze one.
1052 For more details, please see "Docstring Extraction Rules" in `PEP
1053 258`_, item 3 ("How").
1059 Is the Docutils document model based on any existing XML models?
1060 ----------------------------------------------------------------
1062 Not directly, no. It borrows bits from DocBook, HTML, and others. I
1063 (David Goodger) have designed several document models over the years,
1064 and have my own biases. The Docutils document model is designed for
1065 simplicity and extensibility, and has been influenced by the needs of
1066 the reStructuredText markup.