FAQ.txt

   1 =====================================
   2  Docutils Frequently Asked Questions
   3 =====================================
   4
   5 :Date: $Date$
   6 :Web site: http://docutils.sourceforge.net/
   7
   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.
  12
  13
  14 .. contents::
  15 .. sectnum::
  16
  17
  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
  21 file directly.
  22
  23 __ mailto:docutils-users@lists.sourceforge.net
  24 __ http://lists.sourceforge.net/lists/listinfo/docutils-users
  25
  26
  27 Docutils
  28 ========
  29
  30 What is Docutils?
  31 -----------------
  32
  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
  38 discovered.
  39
  40 For an overview of the Docutils project implementation, see `PEP
  41 258`_, "Docutils Design Specification".
  42
  43 Docutils is implemented in Python_.
  44
  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/
  50
  51
  52 Why is it called "Docutils"?
  53 ----------------------------
  54
  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
  58 library.
  59
  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.
  67
  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.
  72
  73 For more history of reStructuredText and the Docutils project, see `An
  74 Introduction to reStructuredText`_.
  75
  76 Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils"
  77 or any other variation.
  78
  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
  84
  85
  86 reStructuredText
  87 ================
  88
  89 What is reStructuredText?
  90 -------------------------
  91
  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
  96 markup systems.
  97
  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.
 101
 102 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 103 .. _StructuredText:
 104    http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
 105 .. _Setext: mirror/setext.html
 106 __ FAQ.txt
 107
 108
 109 Why is it called "reStructuredText"?
 110 ------------------------------------
 111
 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`_.
 117
 118
 119 What's the standard abbreviation for "reStructuredText"?
 120 --------------------------------------------------------
 121
 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".
 125
 126 The abbreviations "reSTX" and "rSTX"/"rstx" should **not** be used;
 127 they overemphasize reStructuredText's precedessor, Zope's
 128 StructuredText.
 129
 130 __ http://www.xml.com/pub/a/2002/02/06/rest.html
 131
 132
 133 What's the standard filename extension for a reStructuredText file?
 134 -------------------------------------------------------------------
 135
 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.
 142
 143
 144 How can I indicate the document title?  Subtitle?
 145 -------------------------------------------------
 146
 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::
 151
 152     This is the Document Title
 153     ==========================
 154
 155     This is the Document Subtitle
 156     -----------------------------
 157
 158     Here's an ordinary paragraph.
 159
 160 Counterexample::
 161
 162     Here's an ordinary paragraph.
 163
 164     This is *not* a Document Title
 165     ==============================
 166
 167     The "ordinary paragraph" above the section title
 168     prevents it from becoming the document title.
 169
 170
 171 HTML Writer
 172 ===========
 173
 174 What is the status of the HTML Writer?
 175 --------------------------------------
 176
 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.
 182
 183
 184 What kind of HTML does it produce?
 185 ----------------------------------
 186
 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
 191 browser.
 192
 193 .. _HTML 4.01: http://www.w3.org/TR/html4/
 194 .. _XHTML 1.0: http://www.w3.org/TR/xhtml1/
 195
 196
 197 What browsers are supported?
 198 ----------------------------
 199
 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.
 206
 207
 208 Unexpected results from tools/html.py: H1, H1 instead of H1, H2.  Why?
 209 ----------------------------------------------------------------------
 210
 211 Here's the question in full:
 212
 213     I have this text::
 214
 215         Heading 1
 216         =========
 217
 218         All my life, I wanted to be H1.
 219
 220         Heading 1.1
 221         -----------
 222
 223         But along came H1, and so shouldn't I be H2?
 224         No!  I'm H1!
 225
 226         Heading 1.1.1
 227         *************
 228
 229         Yeah, imagine me, I'm stuck at H3!  No?!?
 230
 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,
 233     H2::
 234
 235         ...
 236         <html lang="en">
 237         <head>
 238         ...
 239         <title>Heading 1</title>
 240         <link rel="stylesheet" href="default.css" type="text/css" />
 241         </head>
 242         <body>
 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>
 252         ...
 253
 254     What gives?
 255
 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
 260 subtitle.
 261
 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.
 270
 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
 274 own.
 275
 276 (Thanks to Mark McEahern for the question and much of the answer.)
 277
 278
 279 Why do enumerated lists only use numbers (no letters or roman numerals)?
 280 ------------------------------------------------------------------------
 281
 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
 286 MSIE).