FAQ.txt

   1 =====================================
   2  Docutils Frequently Asked Questions
   3 =====================================
   4
   5 :Date: $Date$
   6 :Web site: http://docutils.sourceforge.net/
   7 :Copyright: This document has been placed in the public domain.
   8
   9 .. Please note that until there's a Q&A-specific construct available,
  10    this FAQ will use section titles for questions.  Therefore
  11    questions must fit on one line.  The title may be a summary of the
  12    question, with the full question in the section body.
  13
  14
  15 .. contents::
  16 .. sectnum::
  17
  18
  19 This is a work in progress.  Please feel free to ask questions and/or
  20 provide answers; `send email`__ to the `Docutils-Users mailing list`__
  21 [1]_.  Project members should feel free to edit the source text file
  22 directly.
  23
  24 .. [1] Due to overwhelming amounts of spam, the
  25    docutils-users@lists.sourceforge.net mailing list has been set up
  26    for subscriber posting only.  Non-subscribers who post to
  27    docutils-users will receive a message with "Subject: Your message
  28    to Docutils-users awaits moderator approval".  Legitimate messages
  29    are accepted and posted as soon as possible (a list administrator
  30    must verify the message manually).  If you'd like to subscribe to
  31    docutils-users, please visit
  32    <http://lists.sourceforge.net/lists/listinfo/docutils-users>.
  33
  34 .. _let us know:
  35 __ mailto:docutils-users@lists.sourceforge.net
  36 __ http://lists.sourceforge.net/lists/listinfo/docutils-users
  37
  38
  39 Docutils
  40 ========
  41
  42 What is Docutils?
  43 -----------------
  44
  45 Docutils_ is a system for processing plaintext documentation into
  46 useful formats, such as HTML, XML, and TeX.  It supports multiple
  47 types of input, such as standalone files (implemented), inline
  48 documentation from Python modules and packages (under development),
  49 `PEPs (Python Enhancement Proposals)`_ (implemented), and others as
  50 discovered.
  51
  52 For an overview of the Docutils project implementation, see `PEP
  53 258`_, "Docutils Design Specification".
  54
  55 Docutils is implemented in Python_.
  56
  57 .. _Docutils: http://docutils.sourceforge.net/
  58 .. _PEPs (Python Enhancement Proposals):
  59    http://www.python.org/peps/pep-0012.html
  60 .. _PEP 258: docs/peps/pep-0258.html
  61 .. _Python: http://www.python.org/
  62
  63
  64 Why is it called "Docutils"?
  65 ----------------------------
  66
  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
  70 library.
  71
  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.
  79
  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.
  84
  85 For more history of reStructuredText and the Docutils project, see `An
  86 Introduction to reStructuredText`_.
  87
  88 Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils"
  89 or any other variation.
  90
  91 .. _An Introduction to reStructuredText: ref/rst/introduction.html
  92 __ http://mail.python.org/pipermail/doc-sig/1999-December/000878.html
  93 __ http://mail.python.org/pipermail/doc-sig/2000-November/001252.html
  94 __ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html
  95 __ http://homepage.ntlworld.com/tibsnjoan/docutils/STpy.html
  96
  97
  98 Is there a GUI authoring environment for Docutils?
  99 --------------------------------------------------
 100
 101 DocFactory_ is under development.  It uses wxPython and looks very
 102 promising.
 103
 104 .. _DocFactory:
 105    http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
 106
 107
 108 What is the status of the Docutils project?
 109 -------------------------------------------
 110
 111 Although useful and relatively stable, Docutils is experimental code,
 112 with APIs and architecture subject to change.
 113
 114 Our highest priority is to fix bugs as they are reported.  So the
 115 latest code from CVS (or `development snapshots`_) is almost always
 116 the most stable (bug-free) as well as the most featureful.
 117
 118
 119 What is the Docutils project release policy?
 120 --------------------------------------------
 121
 122 It ought to be "release early & often", but official releases are a
 123 significant effort and aren't done that often.  We have
 124 automatically-generated `development snapshots`_ which always contain
 125 the latest code from CVS.  As the project matures, we may formalize on
 126 a stable/development-branch scheme, but we're not using anything like
 127 that yet.
 128
 129 If anyone would like to volunteer as a release coordinator, please
 130 `contact the project coordinator`_.
 131
 132 .. _development snapshots:
 133    http://docutils.sf.net/#development-snapshots
 134
 135 .. _contact the project coordinator:
 136    mailto:goodger@python.org
 137
 138
 139 reStructuredText
 140 ================
 141
 142 What is reStructuredText?
 143 -------------------------
 144
 145 reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get
 146 plaintext markup syntax and parser system.  The reStructuredText
 147 parser is a component of Docutils_.  reStructuredText is a revision
 148 and reinterpretation of the StructuredText_ and Setext_ lightweight
 149 markup systems.
 150
 151 If you are reading this on the web, you can see for yourself.  `The
 152 source for this FAQ <FAQ.txt>`_ is written in reStructuredText; open
 153 it in another window and compare them side by side.
 154
 155 `A ReStructuredText Primer <docs/user/rst/quickstart.html>`_ and the
 156 `Quick reStructuredText <docs/user/rst/quickref.html>`_ user reference
 157 are a good place to start.  The `reStructuredText Markup Specification
 158 <docs/ref/rst/restructuredtext.html>`_ is a detailed technical
 159 specification.
 160
 161 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 162 .. _StructuredText:
 163    http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
 164 .. _Setext: mirror/setext.html
 165
 166
 167 Why is it called "reStructuredText"?
 168 ------------------------------------
 169
 170 The name came from a combination of "StructuredText", one of
 171 reStructuredText's predecessors, with "re": "revised", "reworked", and
 172 "reinterpreted", and as in the ``re.py`` regular expression module.
 173 For a detailed history of reStructuredText and the Docutils project,
 174 see `An Introduction to reStructuredText`_.
 175
 176
 177 What's the standard abbreviation for "reStructuredText"?
 178 --------------------------------------------------------
 179
 180 "RST" and "ReST" (or "reST") are both acceptable.  Care should be
 181 taken with capitalization, to avoid confusion with "REST__", an
 182 acronym for "Representational State Transfer".
 183
 184 The abbreviations "reSTX" and "rSTX"/"rstx" should **not** be used;
 185 they overemphasize reStructuredText's precedessor, Zope's
 186 StructuredText.
 187
 188 __ http://www.xml.com/pub/a/2002/02/06/rest.html
 189
 190
 191 What's the standard filename extension for a reStructuredText file?
 192 -------------------------------------------------------------------
 193
 194 It's ".txt".  Some people would like to use ".rest" or ".rst" or
 195 ".restx", but why bother?  ReStructuredText source files are meant to
 196 be readable as plaintext, and most operating systems already associate
 197 ".txt" with text files.  Using a specialized filename extension would
 198 require that users alter their OS settings, which is something that
 199 many users will not be willing or able to do.
 200
 201
 202 Are there any reStructuredText editor extensions?
 203 -------------------------------------------------
 204
 205 See `Editor Support for reStructuredText`__.
 206
 207 __ http://docutils.sf.net/tools/editors/README.html
 208
 209
 210 How can I indicate the document title?  Subtitle?
 211 -------------------------------------------------
 212
 213 A uniquely-adorned section title at the beginning of a document is
 214 treated specially, as the document title.  Similarly, a
 215 uniquely-adorned section title immediately after the document title
 216 becomes the document subtitle.  For example::
 217
 218     This is the Document Title
 219     ==========================
 220
 221     This is the Document Subtitle
 222     -----------------------------
 223
 224     Here's an ordinary paragraph.
 225
 226 Counterexample::
 227
 228     Here's an ordinary paragraph.
 229
 230     This is *not* a Document Title
 231     ==============================
 232
 233     The "ordinary paragraph" above the section title
 234     prevents it from becoming the document title.
 235
 236 Another counterexample::
 237
 238     This is not the Document Title,  because...
 239     ===========================================
 240
 241     Here's an ordinary paragraph.
 242
 243     ... the title adornment is not unique
 244     =====================================
 245
 246     Another ordinary paragraph.
 247
 248
 249 How can I represent esoteric characters (e.g. character entities) in a document?
 250 --------------------------------------------------------------------------------
 251
 252 For example, say you want an em-dash (XML character entity &mdash;,
 253 Unicode character ``\u2014``) in your document: use a real em-dash.
 254 Insert concrete characters (e.g. type a *real* em-dash) into your
 255 input file, using whatever encoding suits your application, and tell
 256 Docutils the input encoding.  Docutils uses Unicode internally, so the
 257 em-dash character is a real em-dash internally.
 258
 259 ReStructuredText has no character entity subsystem; it doesn't know
 260 anything about XML charents.  To Docutils, "&mdash;" in input text is
 261 7 discrete characters; no interpretation happens.  When writing HTML,
 262 the "&" is converted to "&amp;", so in the raw output you'd see
 263 "&amp;mdash;".  There's no difference in interpretation for text
 264 inside or outside inline literals or literal blocks -- there's no
 265 character entity interpretation in either case.
 266
 267 If you can't use a Unicode-compatible encoding and must rely on 7-bit
 268 ASCII, there is a workaround.  Files containing character entity set
 269 substitution definitions using the "unicode" directive `are available
 270 <tmp/charents/>`__ (`tarball <tmp/charents.tgz>`__).  A description
 271 and instructions for use `are here <tmp/charents/README.html>`__.
 272 Thanks to David Priest for the original idea.  Incorporating these
 273 files into Docutils is on the `to-do list
 274 <docs/dev/todo.html>`_.
 275
 276 If you insist on using XML-style charents, you'll have to implement a
 277 pre-processing system to convert to UTF-8 or something.  That
 278 introduces complications though; you can no longer *write* about
 279 charents naturally; instead of writing "&mdash;" you'd have to write
 280 "&amp;mdash;".
 281
 282
 283 How can I generate backticks using a Scandinavian keyboard?
 284 -----------------------------------------------------------
 285
 286 The use of backticks in reStructuredText is a bit awkward with
 287 Scandinavian keyboards, where the backtick is a "dead" key.  To get
 288 one ` character one must press SHIFT-` + SPACE.
 289
 290 Unfortunately, with all the variations out there, there's no way to
 291 please everyone.  For Scandinavian programmers and technical writers,
 292 this is not limited to reStructuredText but affects many languages and
 293 environments.
 294
 295 Possible solutions include
 296
 297 * If you have to input a lot of backticks, simply type one in the
 298   normal/awkward way, select it, copy and then paste the rest (CTRL-V
 299   is a lot faster than SHIFT-` + SPACE).
 300
 301 * Use keyboard macros.
 302
 303 * Remap the keyboard.  The Scandinavian keyboard layout is awkward for
 304   other programming/technical characters too; for example, []{}
 305   etc. are a bit awkward compared to US keyboards.
 306
 307   According to Axel Kollmorgen,
 308
 309       Under Windows, you can use the `Microsoft Keyboard Layout Creator
 310       <http://www.microsoft.com/globaldev/tools/msklc.mspx>`__ to easily
 311       map the backtick key to a real backtick (no dead key). took me
 312       five minutes to load my default (german) keyboard layout, untick
 313       "Dead Key?" from the backtick key properties ("in all shift
 314       states"), "build dll and setup package", install the generated
 315       .msi, and add my custom keyboard layout via Control Panel >
 316       Regional and Language Options > Languages > Details > Add
 317       Keyboard layout (and setting it as default "when you start your
 318       computer").
 319
 320 If anyone knows of other/better solutions, please `let us know`_.
 321
 322
 323 Are there any tools for HTML/XML-to-reStructuredText?  (Round-tripping)
 324 -----------------------------------------------------------------------
 325
 326 People have tossed the idea around, but little if any actual work has
 327 ever been done.  There's no reason why reStructuredText should not be
 328 round-trippable to/from XML; any technicalities which prevent
 329 round-tripping would be considered bugs.  Whitespace would not be
 330 identical, but paragraphs shouldn't suffer.  The tricky parts would be
 331 the smaller details, like links and IDs and other bookkeeping.
 332
 333 For HTML, true round-tripping may not be possible.  Even adding lots
 334 of extra "class" attributes may not be enough.  A "simple HTML" to RST
 335 filter is possible -- for some definition of "simple HTML" -- but HTML
 336 is used as dumb formatting so much that such a filter may not be
 337 particularly useful.  No general-purpose filter exists.  An 80/20
 338 approach should work though: build a tool that does 80% of the work
 339 automatically, leaving the other 20% for manual tweaks.
 340
 341
 342 Are there any Wikis that use reStructuredText syntax?
 343 -----------------------------------------------------
 344
 345 There are several, with various degrees of completeness.  With no
 346 implied endorsement or recommendation, and in no particular order:
 347
 348 * `Ian Bicking's experimental code <sandbox/ianb/wiki/WikiPage.py>`__
 349 * `MoinMoin <http://moin.sf.net>`__ has some support; `here's a sample
 350   <http://twistedmatrix.com/users/jh.twistd/moin/moin.cgi/RestSample>`__
 351 * Zope-based `Zwiki <http://zwiki.org/>`__
 352 * Zope3-based Zwiki (in the Zope 3 source tree as ``zope.products.zwiki``)
 353 * `StikiWiki <http://mithrandr.moria.org/code/stikiwiki/>`__
 354 * `Trac <http://projects.edgewall.com/trac/>`__ `supports using reStructuredText
 355   <http://projects.edgewall.com/trac/wiki/WikiRestructuredText>`__ as an
 356   alternative to wiki markup. This includes support for `TracLinks
 357   <http://projects.edgewall.com/trac/wiki/TracLinks>`__ from within RST
 358   text via a custom RST reference-directive or, even easier, an interpreted text
 359   role 'trac'
 360
 361 Please `let us know`_ of any other reStructuredText Wikis.
 362
 363 The example application for the `Web Framework Shootout
 364 <http://colorstudy.com/docs/shootout.html>`__ article is a Wiki using
 365 reStructuredText.
 366
 367
 368 Are there any Weblog (Blog) projects that use reStructuredText syntax?
 369 ----------------------------------------------------------------------
 370
 371 With no implied endorsement or recommendation, and in no particular
 372 order:
 373
 374 * `Python Desktop Server <http://pyds.muensterland.org/>`__
 375 * `PyBloxsom <http://roughingit.subtlehints.net/pyblosxom>`__
 376 * `rst2ht <http://www.rutherfurd.net/articles/rst-ht2html.html>`__
 377 * `htmlnav <http://docutils.sourceforge.net/sandbox/gschwant/htmlnav/>`__
 378 * `restblog <http://docutils.sourceforge.net/sandbox/mly/restblog/>`__
 379 * `ReSTWeb <http://wingide.com/opensource/restweb>`__
 380 * `Lino WebMan <http://lino.sourceforge.net/webman.html>`__
 381
 382 Please `let us know`_ of any other reStructuredText Blogs.
 383
 384
 385 Can lists be indented without generating block quotes?
 386 ------------------------------------------------------
 387
 388 Some people like to write lists with indentation, without intending a
 389 block quote context, like this::
 390
 391     paragraph
 392
 393       * list item 1
 394       * list item 2
 395
 396 There has been a lot of discussion about this, but there are some
 397 issues that would need to be resolved before it could be implemented.
 398 There is a summary of the issues and pointers to the discussions in
 399 `the to-do list <docs/dev/todo.html#indented-lists>`__.
 400
 401
 402 Could the requirement for blank lines around lists be relaxed?
 403 --------------------------------------------------------------
 404
 405 Short answer: no.
 406
 407 In reStructuredText, it would be impossible to unambigously mark up
 408 and parse lists without blank lines before and after.  Deeply nested
 409 lists may look ugly with so many blank lines, but it's a price we pay
 410 for unambiguous markup.  Some other plaintext markup systems do not
 411 require blank lines in nested lists, but they have to compromise
 412 somehow, either accepting ambiguity or requiring extra complexity.
 413 For example, `Epytext <http://epydoc.sf.net/epytext.html#list>`__ does
 414 not require blank lines around lists, but it does require that lists
 415 be indented and that ambiguous cases be escaped.
 416
 417
 418 How can I include mathematical equations in documents?
 419 ------------------------------------------------------
 420
 421 There is no elegant built-in way, yet.  There are several ideas, but
 422 no obvious winner.  This issue requires a champion to solve the
 423 technical and aesthetic issues and implement a generic solution.
 424 Here's the `to-do list entry <docs/dev/todo.html#math-markup>`__.
 425
 426 There are several quick & dirty ways to include equations in
 427 documents:
 428
 429 * For HTML there is MathML but its rendering is still quite broken (or
 430   absent) on most browsers.  An example of raw MathML is `here
 431   <http://sf.net/mailarchive/message.php?msg_id=2177102>`__.
 432
 433 * If you use LaTeX output only, a simple way is to use the "raw"
 434   directive; examples are `here
 435   <http://article.gmane.org/gmane.text.docutils.devel/521>`__.
 436
 437 * Images of the equations can be used, typically generated by TeX.
 438   Beni Cherniavsky has written some `preprocessing scripts`__ for
 439   making inline TeX (for LaTeX and other [HTML etc.] output) math much
 440   easier; `instructions here`__.
 441
 442   __ http://docutils.sourceforge.net/sandbox/cben/rolehack/
 443   __ http://docutils.sourceforge.net/sandbox/cben/rolehack/README.html
 444
 445 * Here is an example of potential `itex math markup
 446   <http://article.gmane.org/gmane.text.docutils.user/118>`__.
 447
 448
 449 Is nested inline markup possible?
 450 ---------------------------------
 451
 452 Not currently, no.  It's on the `to-do list`__ (`details here`__), and
 453 hopefully will be part of the reStructuredText parser soon.  At that
 454 time, markup like this will become possible::
 455
 456     Here is some *emphasized text containing a `hyperlink`_ and
 457     ``inline literals``*.
 458
 459 __ http://docutils.sf.net/docs/dev/todo.html#nested-inline-markup
 460 __ http://docutils.sf.net/docs/dev/rst/alternatives.html#nested-inline-markup
 461
 462 There are workarounds, but they are either convoluted or ugly or both.
 463 They are not recommended.
 464
 465 * Inline markup can be combined with hyperlinks using `substitution
 466   definitions`__ and references__ with the `"replace" directive`__.
 467   For example::
 468
 469       Here is an |emphasized hyperlink|_.
 470
 471       .. |emphasized hyperlink| replace:: *emphasized hyperlink*
 472       .. _emphasized hyperlink: http://example.org
 473
 474   It is not possible for just a portion of the replacement text to be
 475   a hyperlink; it's the entire replacement text or nothing.
 476
 477   __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#substitution-definitions
 478   __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#substitution-references
 479   __ http://docutils.sf.net/docs/ref/rst/directives.html#replace
 480
 481 * The `"raw" directive`__ can be used to insert raw HTML into HTML
 482   output::
 483
 484       Here is some |stuff|.
 485
 486       .. |stuff| raw:: html
 487
 488          <em>emphasized text containing a
 489          <a href="http://example.org">hyperlink</a> and
 490          <tt>inline literals</tt></em>
 491
 492   Raw LaTeX is supported for LaTeX output, etc.
 493
 494   __ http://docutils.sf.net/docs/ref/rst/directives.html#raw
 495
 496
 497 How to indicate a line break or a significant newline?
 498 ------------------------------------------------------
 499
 500 The `"line-block" directive`__ is designed for address blocks, verse,
 501 and other cases where line breaks are significant and must be
 502 preserved.  Unlike literal blocks, the typeface is not changed, and
 503 inline markup is recognized.  For example::
 504
 505     .. line-block::
 506
 507        A one, two, a one two three four
 508
 509        Half a bee, philosophically,
 510            must, *ipso facto*, half not be.
 511        But half the bee has got to be,
 512            *vis a vis* its entity.  D'you see?
 513
 514        But can a bee be said to be
 515            or not to be an entire bee,
 516                when half the bee is not a bee,
 517                    due to some ancient injury?
 518
 519        Singing...
 520
 521 __ http://docutils.sf.net/docs/ref/rst/directives.html#line-block
 522
 523 In the near future, we will be implementing `new syntax for line
 524 blocks`__, like this::
 525
 526     | Lend us a couple of bob till Thursday.
 527     | I'm absolutely skint.
 528     | But I'm expecting a postal order and I can pay you back
 529       as soon as it comes.
 530     | Love, Ewan.
 531
 532 __ http://docutils.sf.net/docs/dev/rst/alternatives.html#syntax-for-line-blocks
 533
 534 Here's a workaround for manually inserting explicit line breaks in
 535 HTML output::
 536
 537     .. |br| raw:: html
 538
 539        <br />
 540
 541     I want to break this line here: |br| this is after the break.
 542
 543     If the extra whitespace bothers you, |br|\ backslash-escape it.
 544
 545
 546 HTML Writer
 547 ===========
 548
 549 What is the status of the HTML Writer?
 550 --------------------------------------
 551
 552 The HTML Writer module, ``docutils/writers/html4css1.py``, is a
 553 proof-of-concept reference implementation.  While it is a complete
 554 implementation, some aspects of the HTML it produces may be
 555 incompatible with older browsers or specialized applications (such as
 556 web templating).  Alternate implementations are welcome.
 557
 558
 559 What kind of HTML does it produce?
 560 ----------------------------------
 561
 562 It produces XHTML compatible with the `HTML 4.01`_ and `XHTML 1.0`_
 563 specifications.  A cascading style sheet ("default.css" by default) is
 564 required for proper viewing with a modern graphical browser.  Correct
 565 rendering of the HTML produced depends on the CSS support of the
 566 browser.
 567
 568 .. _HTML 4.01: http://www.w3.org/TR/html4/
 569 .. _XHTML 1.0: http://www.w3.org/TR/xhtml1/
 570
 571
 572 What browsers are supported?
 573 ----------------------------
 574
 575 No specific browser is targeted; all modern graphical browsers should
 576 work.  Some older browsers, text-only browsers, and browsers without
 577 full CSS support are known to produce inferior results.  Mozilla
 578 (version 1.0 and up) and MS Internet Explorer (version 5.0 and up) are
 579 known to give good results.  Reports of experiences with other
 580 browsers are welcome.
 581
 582
 583 Unexpected results from tools/html.py: H1, H1 instead of H1, H2.  Why?
 584 ----------------------------------------------------------------------
 585
 586 Here's the question in full:
 587
 588     I have this text::
 589
 590         Heading 1
 591         =========
 592
 593         All my life, I wanted to be H1.
 594
 595         Heading 1.1
 596         -----------
 597
 598         But along came H1, and so shouldn't I be H2?
 599         No!  I'm H1!
 600
 601         Heading 1.1.1
 602         *************
 603
 604         Yeah, imagine me, I'm stuck at H3!  No?!?
 605
 606     When I run it through tools/html.py, I get unexpected results
 607     (below).  I was expecting H1, H2, then H3; instead, I get H1, H1,
 608     H2::
 609
 610         ...
 611         <html lang="en">
 612         <head>
 613         ...
 614         <title>Heading 1</title>
 615         <link rel="stylesheet" href="default.css" type="text/css" />
 616         </head>
 617         <body>
 618         <div class="document" id="heading-1">
 619         <h1 class="title">Heading 1</h1>                <-- first H1
 620         <p>All my life, I wanted to be H1.</p>
 621         <div class="section" id="heading-1-1">
 622         <h1><a name="heading-1-1">Heading 1.1</a></h1>        <-- H1
 623         <p>But along came H1, and so now I must be H2.</p>
 624         <div class="section" id="heading-1-1-1">
 625         <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
 626         <p>Yeah, imagine me, I'm stuck at H3!</p>
 627         ...
 628
 629     What gives?
 630
 631 Check the "class" attribute on the H1 tags, and you will see a
 632 difference.  The first H1 is actually ``<h1 class="title">``; this is
 633 the document title, and the default stylesheet renders it centered.
 634 There can also be an ``<h2 class="subtitle">`` for the document
 635 subtitle.
 636
 637 If there's only one highest-level section title at the beginning of a
 638 document, it is treated specially, as the document title.  (Similarly, a
 639 lone second-highest-level section title may become the document
 640 subtitle.)  See `How can I indicate the document title?  Subtitle?`_ for
 641 details.  Rather than use a plain H1 for the document title, we use ``<h1
 642 class="title">`` so that we can use H1 again within the document.  Why
 643 do we do this?  HTML only has H1-H6, so by making H1 do double duty, we
 644 effectively reserve these tags to provide 6 levels of heading beyond the
 645 single document title.
 646
 647 HTML is being used for dumb formatting for nothing but final display.
 648 A stylesheet *is required*, and one is provided:
 649 tools/stylesheets/default.css.  Of course, you're welcome to roll your
 650 own.  The default stylesheet provides rules to format ``<h1
 651 class="title">`` and ``<h2 class="subtitle">`` differently from
 652 ordinary ``<h1>`` and ``<h2>``::
 653
 654     h1.title {
 655       text-align: center }
 656
 657     h2.subtitle {
 658       text-align: center }
 659
 660 If you don't want the top section heading to be interpreted as a
 661 title at all, disable the `doctitle_xform`_ setting
 662 (``--no-doc-title`` option).  This will interpret your document
 663 differently from the standard settings, which might not be a good
 664 idea.  If you don't like the reuse of the H1 in the HTML output, you
 665 can tweak the `initial_header_level`_ setting
 666 (``--initial-header-level`` option) -- but unless you match its value
 667 to your specific document, you might end up with bad HTML (e.g. H3
 668 without H2).
 669
 670 .. _doctitle_xform: docs/user/config.html#doctitle-xform
 671 .. _initial_header_level: docs/user/config.html#initial-header-level
 672
 673 (Thanks to Mark McEahern for the question and much of the answer.)
 674
 675
 676 Why do enumerated lists only use numbers (no letters or roman numerals)?
 677 ------------------------------------------------------------------------
 678
 679 The rendering of enumerators (the numbers or letters acting as list
 680 markers) is completely governed by the stylesheet, so either the
 681 browser can't find the stylesheet (try using the "--embed-stylesheet"
 682 option), or the browser can't understand it (try a recent Mozilla or
 683 MSIE).
 684
 685
 686 Python Source Reader
 687 ====================
 688
 689 Can I use Docutils for Python auto-documentation?
 690 -------------------------------------------------
 691
 692 Yes, in conjunction with other projects.
 693
 694 Docstring extraction functionality from within Docutils is still under
 695 development.  There is most of a source code parsing module in
 696 docutils/readers/python/moduleparser.py.  We do plan to finish it
 697 eventually.  Ian Bicking wrote an initial front end for the
 698 moduleparser.py module, in sandbox/ianb/extractor/extractor.py.  Ian
 699 also did some work on the Python Source Reader
 700 (docutils.readers.python) component at PyCon DC 2004.
 701
 702 Version 2.0 of Ed Loper's `Epydoc <http://epydoc.sourceforge.net/>`_
 703 supports reStructuredText-format docstrings for HTML output.  Docutils
 704 0.3 or newer is required.  Development of a Docutils-specific
 705 auto-documentation tool will continue.  Epydoc works by importing
 706 Python modules to be documented, whereas the Docutils-specific tool,
 707 described above, will parse modules without importing them (as with
 708 `HappyDoc <http://happydoc.sourceforge.net/>`_, which doesn't support
 709 reStructuredText).
 710
 711 The advantages of parsing over importing are security and flexibility;
 712 the disadvantage is complexity/difficulty.
 713
 714 * Security: untrusted code that shouldn't be executed can be parsed;
 715   importing a module executes its top-level code.
 716 * Flexibility: comments and unofficial docstrings (those not supported
 717   by Python syntax) can only be processed by parsing.
 718 * Complexity/difficulty: it's a lot harder to parse and analyze a
 719   module than it is to ``import`` and analyze one.
 720
 721 For more details, please see "Docstring Extraction Rules" in `PEP
 722 258`_, item 3 ("How").
 723
 724
 725 Miscellaneous
 726 =============
 727
 728 Is the Docutils document model based on any existing XML models?
 729 ----------------------------------------------------------------
 730
 731 Not directly, no.  It borrows bits from DocBook, HTML, and others.  I
 732 (David Goodger) have designed several document models over the years,
 733 and have my own biases.  The Docutils document model is designed for
 734 simplicity and extensibility, and has been influenced by the needs of
 735 the reStructuredText markup.