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 know use of the term "docutils" in a Python context was a
  61 `fleeting reference`__ in a message by Fred Drake on 1999-12-02 in the
  62 Python Doc-SIG mailing list.  It was suggested `as a project name`__
  63 on 2000-11-27 on Doc-SIG, again by Fred Drake, in response to a
  64 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 If there's only one highest-level section title at the beginning of a
 148 document, it is treated specially, as the document title.  Similarly,
 149 a lone second-highest-level section title may become the document
 150 subtitle if it immediately follows the document title.
 151
 152 For example::
 153
 154     This is the Document Title
 155     ==========================
 156
 157     This is the Document Subtitle
 158     -----------------------------
 159
 160     Here's an ordinary paragraph.
 161
 162 Counterexample::
 163
 164     Here's an ordinary paragraph.
 165
 166     This is *not* a Document Title
 167     ==============================
 168
 169     The "ordinary paragraph" above the section title
 170     prevents it from becoming the document title.
 171
 172
 173 HTML Writer
 174 ===========
 175
 176 Unexpected results from tools/html.py: H1, H1 instead of H1, H2.  Why?
 177 ----------------------------------------------------------------------
 178
 179 Here's the question in full:
 180
 181     I have this text::
 182
 183         Heading 1
 184         =========
 185
 186         All my life, I wanted to be H1.
 187
 188         Heading 1.1
 189         -----------
 190
 191         But along came H1, and so shouldn't I be H2?
 192         No!  I'm H1!
 193
 194         Heading 1.1.1
 195         *************
 196
 197         Yeah, imagine me, I'm stuck at H3!  No?!?
 198
 199     When I run it through tools/html.py, I get unexpected results
 200     (below).  I was expecting H1, H2, then H3; instead, I get H1, H1,
 201     H2::
 202
 203         ...
 204         <html lang="en">
 205         <head>
 206         ...
 207         <title>Heading 1</title>
 208         <link rel="stylesheet" href="default.css" type="text/css" />
 209         </head>
 210         <body>
 211         <div class="document" id="heading-1">
 212         <h1 class="title">Heading 1</h1>                <-- first H1
 213         <p>All my life, I wanted to be H1.</p>
 214         <div class="section" id="heading-1-1">
 215         <h1><a name="heading-1-1">Heading 1.1</a></h1>        <-- H1
 216         <p>But along came H1, and so now I must be H2.</p>
 217         <div class="section" id="heading-1-1-1">
 218         <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
 219         <p>Yeah, imagine me, I'm stuck at H3!</p>
 220         ...
 221
 222     What gives?
 223
 224 Check the "class" attribute on the H1 tags, and you will see a
 225 difference.  The first H1 is actually ``<h1 class="title">``; this is
 226 the document title, and the default stylesheet renders it centered.
 227 There can also be an ``<h2 class="subtitle">`` for the document
 228 subtitle.
 229
 230 If there's only one highest-level section title at the beginning of a
 231 document, it is treated specially, as the document title.  (Similarly,
 232 a lone second-highest-level section title may become the document
 233 subtitle.)  Rather than use a plain H1 for that, we use ``<h1
 234 class="title">`` so that we can use H1 again within the document.  Why
 235 we do this?  HTML only has H1-H6, so by making H1 do double duty, we
 236 effectively reserve these tags to provide 6 levels of heading beyond
 237 the single document title.
 238
 239 HTML is being used for dumb formatting for nothing but final display.
 240 A stylesheet *is* required, and you're welcome to roll your own.
 241
 242 (Thanks to Mark McEahern for the question and much of the answer.)