1 =====================================
2 Docutils Frequently Asked Questions
3 =====================================
6 :Web site: http://docutils.sourceforge.net/
8 .. Please note that until there's a Q&A-specific construct available,
9 this FAQ will use section titles for questions. Therefore
10 questions must fit on one line. The title may be a summary of the
11 question, with the full question in the section body.
18 This is a work in progress. Please feel free to ask questions and/or
19 provide answers; `send email`__ to the `Docutils-Users mailing
20 list`__. Project members should feel free to edit the source text
23 __ mailto:docutils-users@lists.sourceforge.net
24 __ http://lists.sourceforge.net/lists/listinfo/docutils-users
33 Docutils_ is a system for processing plaintext documentation into
34 useful formats, such as HTML, XML, and TeX. It supports multiple
35 types of input, such as standalone files (implemented), inline
36 documentation from Python modules and packages (under development),
37 `PEPs (Python Enhancement Proposals)`_ (implemented), and others as
40 For an overview of the Docutils project implementation, see `PEP
41 258`_, "Docutils Design Specification".
43 Docutils is implemented in Python_.
45 .. _Docutils: http://docutils.sourceforge.net/
46 .. _PEPs (Python Enhancement Proposals):
47 http://www.python.org/peps/pep-0012.html
48 .. _PEP 258: spec/pep-0258.html
49 .. _Python: http://www.python.org/
52 Why is it called "Docutils"?
53 ----------------------------
55 Docutils is short for "Python Documentation Utilities". The name
56 "Docutils" was inspired by "Distutils", the Python Distribution
57 Utilities architected by Greg Ward, a component of Python's standard
60 The earliest known use of the term "docutils" in a Python context was
61 a `fleeting reference`__ in a message by Fred Drake on 1999-12-02 in
62 the Python Doc-SIG mailing list. It was suggested `as a project
63 name`__ on 2000-11-27 on Doc-SIG, again by Fred Drake, in response to
64 a question from Tony "Tibs" Ibbs: "What do we want to *call* this
65 thing?". This was shortly after David Goodger first `announced
66 reStructuredText`__ on Doc-SIG.
68 Tibs used the name "Docutils" for `his effort`__ "to document what the
69 Python docutils package should support, with a particular emphasis on
70 documentation strings". Tibs joined the current project (and its
71 predecessors) and graciously donated the name.
73 For more history of reStructuredText and the Docutils project, see `An
74 Introduction to reStructuredText`_.
76 Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils"
77 or any other variation.
79 .. _An Introduction to reStructuredText: spec/rst/introduction.html
80 __ http://mail.python.org/pipermail/doc-sig/1999-December/000878.html
81 __ http://mail.python.org/pipermail/doc-sig/2000-November/001252.html
82 __ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html
83 __ http://homepage.ntlworld.com/tibsnjoan/docutils/STpy.html
89 What is reStructuredText?
90 -------------------------
92 reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get
93 plaintext markup syntax and parser system. The reStructuredText
94 parser is a component of Docutils_. reStructuredText is a revision
95 and reinterpretation of the StructuredText_ and Setext_ lightweight
98 If you are reading this on the web, you can see for yourself. `The
99 source for this FAQ`__ is written in reStructuredText; open it in
100 another window and compare them side by side.
102 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
104 http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
105 .. _Setext: mirror/setext.html
109 Why is it called "reStructuredText"?
110 ------------------------------------
112 The name came from a combination of "StructuredText", one of
113 reStructuredText's predecessors, with "re" (as in the ``re.py``
114 regular expression module), "revised", "reworked", and
115 "reinterpreted". For a detailed history of reStructuredText and the
116 Docutils project, see `An Introduction to reStructuredText`_.
119 What's the standard abbreviation for "reStructuredText"?
120 --------------------------------------------------------
122 "RST" and "ReST" (or "reST") are both acceptable. Care should be
123 taken with capitalization, to avoid confusion with "REST__", an
124 acronym for "Representational State Transfer".
126 The abbreviations "reSTX" and "rSTX"/"rstx" should **not** be used;
127 they overemphasize reStructuredText's precedessor, Zope's
130 __ http://www.xml.com/pub/a/2002/02/06/rest.html
133 What's the standard filename extension for a reStructuredText file?
134 -------------------------------------------------------------------
136 It's ".txt". Some people would like to use ".rest" or ".rst" or
137 ".restx", but why bother? ReStructuredText source files are meant to
138 be readable as plaintext, and most operating systems already associate
139 ".txt" with text files. Using a specialized filename extension would
140 require that users alter their OS settings, which is something that
141 many users will not be willing or able to do.
144 How can I indicate the document title? Subtitle?
145 -------------------------------------------------
147 A uniquely-adorned section title at the beginning of a document is
148 treated specially, as the document title. Similarly, a
149 uniquely-adorned section title immediately after the document title
150 becomes the document subtitle. For example::
152 This is the Document Title
153 ==========================
155 This is the Document Subtitle
156 -----------------------------
158 Here's an ordinary paragraph.
162 Here's an ordinary paragraph.
164 This is *not* a Document Title
165 ==============================
167 The "ordinary paragraph" above the section title
168 prevents it from becoming the document title.
174 What is the status of the HTML Writer?
175 --------------------------------------
177 The HTML Writer module, ``docutils/writers/html4css1.py``, is a
178 proof-of-concept reference implementation. While it is a complete
179 implementation, some aspects of the HTML it produces may be
180 incompatible with older browsers or specialized applications (such as
181 web templating). Alternate implementations are welcome.
184 What kind of HTML does it produce?
185 ----------------------------------
187 It produces XHTML compatible with the `HTML 4.01`_ and `XHTML 1.0`_
188 specifications. A cascading style sheet ("default.css" by default) is
189 required for proper viewing with a modern graphical browser. Correct
190 rendering of the HTML produced depends on the CSS support of the
193 .. _HTML 4.01: http://www.w3.org/TR/html4/
194 .. _XHTML 1.0: http://www.w3.org/TR/xhtml1/
197 What browsers are supported?
198 ----------------------------
200 No specific browser is targeted; all modern graphical browsers should
201 work. Some older browsers, text-only browsers, and browsers without
202 full CSS support are known to produce inferior results. Mozilla
203 (version 1.0 and up) and MS Internet Explorer (version 5.0 and up) are
204 known to give good results. Reports of experiences with other
205 browsers are welcome.
208 Unexpected results from tools/html.py: H1, H1 instead of H1, H2. Why?
209 ----------------------------------------------------------------------
211 Here's the question in full:
218 All my life, I wanted to be H1.
223 But along came H1, and so shouldn't I be H2?
229 Yeah, imagine me, I'm stuck at H3! No?!?
231 When I run it through tools/html.py, I get unexpected results
232 (below). I was expecting H1, H2, then H3; instead, I get H1, H1,
239 <title>Heading 1</title>
240 <link rel="stylesheet" href="default.css" type="text/css" />
243 <div class="document" id="heading-1">
244 <h1 class="title">Heading 1</h1> <-- first H1
245 <p>All my life, I wanted to be H1.</p>
246 <div class="section" id="heading-1-1">
247 <h1><a name="heading-1-1">Heading 1.1</a></h1> <-- H1
248 <p>But along came H1, and so now I must be H2.</p>
249 <div class="section" id="heading-1-1-1">
250 <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
251 <p>Yeah, imagine me, I'm stuck at H3!</p>
256 Check the "class" attribute on the H1 tags, and you will see a
257 difference. The first H1 is actually ``<h1 class="title">``; this is
258 the document title, and the default stylesheet renders it centered.
259 There can also be an ``<h2 class="subtitle">`` for the document
262 If there's only one highest-level section title at the beginning of a
263 document, it is treated specially, as the document title. (Similarly,
264 a lone second-highest-level section title may become the document
265 subtitle.) Rather than use a plain H1 for that, we use ``<h1
266 class="title">`` so that we can use H1 again within the document. Why
267 do we do this? HTML only has H1-H6, so by making H1 do double duty,
268 we effectively reserve these tags to provide 6 levels of heading
269 beyond the single document title.
271 HTML is being used for dumb formatting for nothing but final display.
272 A stylesheet *is required*, and one is provided:
273 tools/stylesheets/default.css. Of course, you're welcome to roll your
276 (Thanks to Mark McEahern for the question and much of the answer.)
279 Why do enumerated lists only use numbers (no letters or roman numerals)?
280 ------------------------------------------------------------------------
282 The rendering of enumerators (the numbers or letters acting as list
283 markers) is completely governed by the stylesheet, so either the
284 browser can't find the stylesheet (try using the "--embed-stylesheet"
285 option), or the browser can't understand it (try a recent Mozilla or