1.. -*- coding: utf-8 -*- 2 3 4.. NOTE TO MAINTAINERS: Please add new questions to the end of their 5 sections, so section/question numbers remain stable. 6 7 8=========================================== 9 Docutils FAQ (Frequently Asked Questions) 10=========================================== 11 12:Date: $Date: 2021-03-26 14:51:36 +0100 (Fr, 26. Mär 2021) $ 13:Revision: $Revision: 8644 $ 14:Web site: https://docutils.sourceforge.io/ 15:Copyright: This document has been placed in the public domain. 16 17.. contents:: 18.. sectnum:: 19 20 21This is a work in progress. If you are reading a local copy, the 22`master copy`_ might be newer. This document uses are relative links; 23if they don't work, please use the `master copy`_. 24 25Please feel free to ask questions and/or provide answers; send email 26to the `Docutils-users`_ mailing list. Project members should feel 27free to edit the source text file directly. 28 29.. _master copy: https://docutils.sourceforge.io/FAQ.html 30.. _let us know: 31.. _Docutils-users: docs/user/mailing-lists.html#docutils-users 32 33 34 35Docutils 36======== 37 38What is Docutils? 39----------------- 40 41Docutils_ is a system for processing plaintext documentation into 42useful formats, such as HTML, XML, and LaTeX. It supports multiple 43types of input, such as standalone files, `PEPs (Python Enhancement 44Proposals)`_, and string input. Client code may add other input types, 45e.g. Sphinx_ comes with an extension to extract inline documentation 46from Python modules and packages. 47 48The Docutils distribution consists of: 49 50* a library (the "docutils" package), which `can be used by client 51 code`_; 52* several `front-end tools`_ (such as ``rst2html.py``, which converts 53 reStructuredText input into HTML output); 54* a `test suite`_; and 55* documentation_. 56 57For an overview of the Docutils project implementation, see `PEP 58258`_, "Docutils Design Specification". 59 60Docutils is implemented in Python_. 61 62.. _Docutils: https://docutils.sourceforge.io/ 63.. _PEPs (Python Enhancement Proposals): 64 http://www.python.org/peps/pep-0012.html 65.. _can be used by client code: docs/api/publisher.html 66.. _front-end tools: docs/user/tools.html 67.. _test suite: docs/dev/testing.html 68.. _documentation: docs/index.html 69.. _PEP 258: http://www.python.org/peps/pep-0258.html 70.. _Python: http://www.python.org/ 71 72 73Why is it called "Docutils"? 74---------------------------- 75 76Docutils is short for "Python Documentation Utilities". The name 77"Docutils" was inspired by "Distutils", the Python Distribution 78Utilities architected by Greg Ward, a component of Python's standard 79library. 80 81The earliest known use of the term "docutils" in a Python context was 82a `fleeting reference`__ in a message by Fred Drake on 1999-12-02 in 83the Python Doc-SIG mailing list. It was suggested `as a project 84name`__ on 2000-11-27 on Doc-SIG, again by Fred Drake, in response to 85a question from Tony "Tibs" Ibbs: "What do we want to *call* this 86thing?". This was shortly after David Goodger first `announced 87reStructuredText`__ on Doc-SIG. 88 89Tibs used the name "Docutils" for `his effort`__ "to document what the 90Python docutils package should support, with a particular emphasis on 91documentation strings". Tibs joined the current project (and its 92predecessors) and graciously donated the name. 93 94For more history of reStructuredText and the Docutils project, see `An 95Introduction to reStructuredText`_. 96 97Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils" 98or any other variation. It is pronounced as in "DOCumentation 99UTILitieS", with emphasis on the first syllable. 100 101.. _An Introduction to reStructuredText: docs/ref/rst/introduction.html 102__ http://mail.python.org/pipermail/doc-sig/1999-December/000878.html 103__ http://mail.python.org/pipermail/doc-sig/2000-November/001252.html 104__ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html 105__ http://homepage.ntlworld.com/tibsnjoan/docutils/STpy.html 106 107 108Is there a GUI authoring environment for Docutils? 109-------------------------------------------------- 110 111DocFactory_ is under development. See also the links to editors_ 112supporting reStructuredText. 113 114.. _DocFactory: 115 http://docutils.sf.net/sandbox/gschwant/docfactory/doc/ 116.. _editors: docs/user/links.html#editors 117 118 119What is the status of the Docutils project? 120------------------------------------------- 121 122Docutils is mainly stable, with documented APIs and architecture 123subject to change after announcement and a transition period. 124 125We fix bugs as they are reported. So the latest code from the 126repository_ (or the snapshots_) are almost always the most stable 127as well as the most featureful. 128 129 130What is the Docutils project release policy? 131-------------------------------------------- 132 133Besides the regular releases_, we provide automatically-generated 134snapshots_ which always contain the latest code from the repository_. 135As the project matures, we may formalize on a 136stable/development-branch scheme, but we're not using anything like 137that yet. 138 139.. _releases: https://pypi.org/project/docutils/#history 140.. _snapshots: https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/ 141.. _repository: docs/dev/repository.html 142 143 144reStructuredText 145================ 146 147What is reStructuredText? 148------------------------- 149 150reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get 151plaintext markup syntax and parser system. The reStructuredText 152parser is a component of Docutils_. reStructuredText is a revision 153and reinterpretation of the StructuredText_ and Setext_ lightweight 154markup systems. 155 156If you are reading this on the web, you can see for yourself. `The 157source for this FAQ <FAQ.txt>`_ is written in reStructuredText; open 158it in another window and compare them side by side. 159 160`A ReStructuredText Primer`_ and the `Quick reStructuredText`_ user 161reference are a good place to start. The `reStructuredText Markup 162Specification`_ is a detailed technical specification. 163 164.. _A ReStructuredText Primer: docs/user/rst/quickstart.html 165.. _Quick reStructuredText: docs/user/rst/quickref.html 166.. _reStructuredText Markup Specification: 167 docs/ref/rst/restructuredtext.html 168.. _reStructuredText: https://docutils.sourceforge.io/rst.html 169.. _StructuredText: 170 http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/ 171.. _Setext: https://docutils.sourceforge.io/mirror/setext.html 172 173 174Why is it called "reStructuredText"? 175------------------------------------ 176 177The name came from a combination of "StructuredText", one of 178reStructuredText's predecessors, with "re": "revised", "reworked", and 179"reinterpreted", and as in the ``re.py`` regular expression module. 180For a detailed history of reStructuredText and the Docutils project, 181see `An Introduction to reStructuredText`_. 182 183"reStructuredText" is **ONE** word, *not two!* 184 185 186What's the standard abbreviation for "reStructuredText"? 187-------------------------------------------------------- 188 189"RST" and "ReST" (or "reST") are both acceptable. Care should be 190taken with capitalization, to avoid confusion with "REST__", an 191acronym for "Representational State Transfer". 192 193The abbreviations "reSTX" and "rSTX"/"rstx" should **not** be used; 194they overemphasize reStructuredText's precedessor, Zope's 195StructuredText. 196 197__ http://en.wikipedia.org/wiki/Representational_State_Transfer 198 199 200What's the standard filename extension for a reStructuredText file? 201------------------------------------------------------------------- 202 203It's ".txt". Some people would like to use ".rest" or ".rst" or 204".restx", but why bother? ReStructuredText source files are meant to 205be readable as plaintext, and most operating systems already associate 206".txt" with text files. Using a specialized filename extension would 207require that users alter their OS settings, which is something that 208many users will not be willing or able to do. 209 210Also see `What's the official MIME type for reStructuredText data?`_ 211 212 213Are there any reStructuredText editor extensions? 214------------------------------------------------- 215 216See the list of editors_ supporting reStructuredText. 217 218 219How can I indicate the document title? Subtitle? 220------------------------------------------------- 221 222A uniquely-adorned section title at the beginning of a document is 223treated specially, as the document title. Similarly, a 224uniquely-adorned section title immediately after the document title 225becomes the document subtitle. For example:: 226 227 This is the Document Title 228 ========================== 229 230 This is the Document Subtitle 231 ----------------------------- 232 233 Here's an ordinary paragraph. 234 235Counterexample:: 236 237 Here's an ordinary paragraph. 238 239 This is *not* a Document Title 240 ============================== 241 242 The "ordinary paragraph" above the section title 243 prevents it from becoming the document title. 244 245Another counterexample:: 246 247 This is not the Document Title, because... 248 =========================================== 249 250 Here's an ordinary paragraph. 251 252 ... the title adornment is not unique 253 ===================================== 254 255 Another ordinary paragraph. 256 257 258How can I represent esoteric characters (e.g. character entities) in a document? 259-------------------------------------------------------------------------------- 260 261For example, say you want an em-dash (XML character entity —, 262Unicode character U+2014) in your document: use a real em-dash. 263Insert concrete characters (e.g. type a *real* em-dash) into your 264input file, using whatever encoding suits your application, and tell 265Docutils the input encoding. Docutils uses Unicode internally, so the 266em-dash character is a real em-dash internally. 267 268Emacs users should refer to the `Emacs Support for reStructuredText`__ 269document. Tips for other editors are welcome. 270 271__ tools/editors/emacs/README.html 272 273ReStructuredText has no character entity subsystem; it doesn't know 274anything about XML charents. To Docutils, "—" in input text is 2757 discrete characters; no interpretation happens. When writing HTML, 276the "&" is converted to "&", so in the raw output you'd see 277"&mdash;". There's no difference in interpretation for text 278inside or outside inline literals or literal blocks -- there's no 279character entity interpretation in either case. 280 281If you can't use a Unicode-compatible encoding and must rely on 7-bit 282ASCII, there is a workaround. New in Docutils 0.3.10 is a set of 283`Standard Substitution Definition Sets`_, which provide equivalents of 284XML & HTML character entity sets as substitution definitions. For 285example, the Japanese yen currency symbol can be used as follows:: 286 287 .. include:: <xhtml1-lat1.txt> 288 289 |yen| 600 for a complete meal? That's cheap! 290 291Thanks to David Priest for the original idea. 292 293If you insist on using XML-style charents, you'll have to implement a 294pre-processing system to convert to UTF-8 or something. That 295introduces complications though; you can no longer *write* about 296charents naturally; instead of writing "—" you'd have to write 297"&mdash;". 298 299For the common case of long dashes, you might also want to insert the 300following substitution definitons into your document (both of them are 301using the "unicode_" directive):: 302 303 .. |--| unicode:: U+2013 .. en dash 304 .. |---| unicode:: U+2014 .. em dash, trimming surrounding whitespace 305 :trim: 306 307.. |--| unicode:: U+2013 .. en dash 308.. |---| unicode:: U+2014 .. em dash, trimming surrounding whitespace 309 :trim: 310 311Now you can write dashes using pure ASCII: "``foo |--| bar; foo |---| 312bar``", rendered as "foo |--| bar; foo |---| bar". 313The ``:trim:`` option for 314the em dash is necessary because you cannot write "``foo|---|bar``"; 315thus you need to add spaces ("``foo |---| bar``") and advise the 316reStructuredText parser to trim the spaces. 317 318.. _Standard Substitution Definition Sets: docs/ref/rst/definitions.html 319.. _unicode: docs/ref/rst/directives.html#unicode-character-codes 320.. _are available: https://docutils.sourceforge.io/tmp/charents/ 321.. _tarball: https://docutils.sourceforge.io/tmp/charents.tgz 322.. _description and instructions: 323 https://docutils.sourceforge.io/tmp/charents/README.html 324.. _to-do list: docs/dev/todo.html 325 326 327How can I generate backticks using a Scandinavian keyboard? 328----------------------------------------------------------- 329 330The use of backticks in reStructuredText is a bit awkward with 331Scandinavian keyboards, where the backtick is a "dead" key. To get 332one ` character one must press SHIFT-` + SPACE. 333 334Unfortunately, with all the variations out there, there's no way to 335please everyone. For Scandinavian programmers and technical writers, 336this is not limited to reStructuredText but affects many languages and 337environments. 338 339Possible solutions include 340 341* If you have to input a lot of backticks, simply type one in the 342 normal/awkward way, select it, copy and then paste the rest (CTRL-V 343 is a lot faster than SHIFT-` + SPACE). 344 345* Use keyboard macros. 346 347* Remap the keyboard. The Scandinavian keyboard layout is awkward for 348 other programming/technical characters too; for example, []{} 349 etc. are a bit awkward compared to US keyboards. 350 351 According to Axel Kollmorgen, 352 353 Under Windows, you can use the `Microsoft Keyboard Layout Creator 354 <http://www.microsoft.com/globaldev/tools/msklc.mspx>`__ to easily 355 map the backtick key to a real backtick (no dead key). took me 356 five minutes to load my default (german) keyboard layout, untick 357 "Dead Key?" from the backtick key properties ("in all shift 358 states"), "build dll and setup package", install the generated 359 .msi, and add my custom keyboard layout via Control Panel > 360 Regional and Language Options > Languages > Details > Add 361 Keyboard layout (and setting it as default "when you start your 362 computer"). 363 364* Use a virtual/screen keyboard or character palette, such as: 365 366 - `Web-based keyboards <http://keyboard.lab.co.il/>`__ (IE only 367 unfortunately). 368 - Windows: `Click-N-Type <http://www.lakefolks.org/cnt/>`__. 369 - Mac OS X: the Character Palette can store a set of favorite 370 characters for easy input. Open System Preferences, 371 International, Input Menu tab, enable "Show input menu in menu 372 bar", and be sure that Character Palette is enabled in the list. 373 374If anyone knows of other/better solutions, please `let us know`_. 375 376 377Are there any tools for HTML/XML-to-reStructuredText? (Round-tripping) 378----------------------------------------------------------------------- 379 380People have tossed the idea around, and some implementations of 381reStructuredText-generating tools can be found in the `Docutils Link 382List`_. 383 384There's no reason why reStructuredText should not be round-trippable 385to/from XML; any technicalities which prevent round-tripping would be 386considered bugs. Whitespace would not be identical, but paragraphs 387shouldn't suffer. The tricky parts would be the smaller details, like 388links and IDs and other bookkeeping. 389 390For HTML, true round-tripping may not be possible. Even adding lots 391of extra "class" attributes may not be enough. A "simple HTML" to RST 392filter is possible -- for some definition of "simple HTML" -- but HTML 393is used as dumb formatting so much that such a filter may not be 394particularly useful. An 80/20 approach should work though: build a 395tool that does 80% of the work automatically, leaving the other 20% 396for manual tweaks. 397 398.. _Docutils Link List: docs/user/links.html 399 400 401Are there any Wikis that use reStructuredText syntax? 402----------------------------------------------------- 403 404There are several, with various degrees of completeness. With no 405implied endorsement or recommendation, and in no particular order: 406 407* `Ian Bicking's experimental code 408 <http://docutils.sf.net/sandbox/ianb/wiki/Wiki.py>`__ 409 410* `MoinMoin <http://moinmoin.wikiwikiweb.de/>`__ has some support; 411 `here's a sample <http://moinmoin.wikiwikiweb.de/RestSample>`__ 412 413* Zope-based `Zwiki <http://zwiki.org/>`__ 414 415* Zope3-based Zwiki (in the Zope 3 source tree as 416 ``zope.products.zwiki``) 417 418* `StikiWiki <http://mithrandr.moria.org/code/stikiwiki/>`__ 419 420* `Trac <http://trac.edgewall.com//>`__ `supports using 421 reStructuredText 422 <http://trac.edgewall.com//wiki/WikiRestructuredText>`__ as 423 an alternative to wiki markup. This includes support for `TracLinks 424 <http://trac.edgewall.com//wiki/TracLinks>`__ from within 425 RST text via a custom RST reference-directive or, even easier, an 426 interpreted text role 'trac' 427 428Please `let us know`_ of any other reStructuredText Wikis. 429 430.. dead link 431.. The example application for the `Web Framework Shootout 432.. <http://colorstudy.com/docs/shootout.html>`__ article is a Wiki using 433.. reStructuredText. 434 435 436Are there any Weblog (Blog) projects that use reStructuredText syntax? 437---------------------------------------------------------------------- 438 439With no implied endorsement or recommendation, and in no particular 440order: 441 442* `Firedrop <http://www.voidspace.org.uk/python/firedrop2/>`__ 443* `PyBloxsom <http://pyblosxom.sourceforge.net/>`__ 444* `Lino WebMan <http://lino.sourceforge.net/webman.html>`__ 445* `Pelican <http://blog.getpelican.com/>`__ 446 (also listed `on PyPi <http://pypi.python.org/pypi/pelican>`__) 447 448Please `let us know`_ of any other reStructuredText Blogs. 449 450 451.. _Can lists be indented without generating block quotes?: 452 453How should I mark up lists? 454--------------------------- 455 456Bullet_ & enumerated_ list markup is very intuitive but there are 2 457points that must be noted: 458 459.. _bullet: docs/ref/rst/restructuredtext.html#bullet-lists 460.. _enumerated: docs/ref/rst/restructuredtext.html#enumerated-lists 461 4621. Lists should **not** be indented. This is correct:: 463 464 paragraph 465 466 * list item 1 467 468 * nested item 1.1 469 * nested item 1.2 470 471 * list item 2 472 473 while this is probably incorrect:: 474 475 paragraph 476 477 * list item 1 478 479 * nested item 1.1 480 * nested item 1.2 481 482 * list item 2 483 484 The extra indentation (of the list containing items 1.1 and 1.2) is 485 recognized as a block quote. This is usually not what you mean and 486 it causes the list in the output to be indented too much. 487 4882. There **must** be blank lines around list items, except between 489 items of the same level, where blank lines are optional. The 490 example above shows this. 491 492Note that formatting of the *output* is independent of the input, and 493is decided by the writer and the stylesheet. For instance, lists 494*are* indented in HTML output by default. See `How are lists 495formatted in HTML?`_ for details. 496 497 498Could lists be indented without generating block quotes? 499-------------------------------------------------------- 500 501Some people like to write lists with indentation but don't intend a 502blockquote context. There has been a lot of discussion about allowing 503this in reStructuredText, but there are some issues that would need to 504be resolved before it could be implemented. There is a summary of the 505issues and pointers to the discussions in `the to-do list`__. 506 507__ docs/dev/todo.html#indented-lists 508 509 510Could the requirement for blank lines around lists be relaxed? 511-------------------------------------------------------------- 512 513Short answer: no. 514 515In reStructuredText, it would be impossible to unambigously mark up 516and parse lists without blank lines before and after. Deeply nested 517lists may look ugly with so many blank lines, but it's a price we pay 518for unambiguous markup. Some other plaintext markup systems do not 519require blank lines in nested lists, but they have to compromise 520somehow, either accepting ambiguity or requiring extra complexity. 521For example, `Epytext <http://epydoc.sf.net/epytext.html#list>`__ does 522not require blank lines around lists, but it does require that lists 523be indented and that ambiguous cases be escaped. 524 525 526How can I include mathematical equations in documents? 527------------------------------------------------------ 528 529Use the `math directive`_ and `math role`_, available since Docutils 0.8. 530 531.. _math directive: docs/ref/rst/directives.html#math 532.. _math role: docs/ref/rst/roles.html#math 533 534 535Is nested inline markup possible? 536--------------------------------- 537 538Not currently, no. It's on the `to-do list`__ (`details here`__), and 539hopefully will be part of the reStructuredText parser soon. At that 540time, markup like this will become possible:: 541 542 Here is some *emphasized text containing a `hyperlink`_ and 543 ``inline literals``*. 544 545__ docs/dev/todo.html#nested-inline-markup 546__ docs/dev/rst/alternatives.html#nested-inline-markup 547 548There are workarounds, but they are either convoluted or ugly or both. 549They are not recommended. 550 551* Inline markup can be combined with hyperlinks using `substitution 552 definitions`__ and references__ with the `"replace" directive`__. 553 For example:: 554 555 Here is an |emphasized hyperlink|_. 556 557 .. |emphasized hyperlink| replace:: *emphasized hyperlink* 558 .. _emphasized hyperlink: http://example.org 559 560 It is not possible for just a portion of the replacement text to be 561 a hyperlink; it's the entire replacement text or nothing. 562 563 __ docs/ref/rst/restructuredtext.html#substitution-definitions 564 __ docs/ref/rst/restructuredtext.html#substitution-references 565 __ docs/ref/rst/directives.html#replace 566 567* The `"raw" directive`__ can be used to insert raw HTML into HTML 568 output:: 569 570 Here is some |stuff|. 571 572 .. |stuff| raw:: html 573 574 <em>emphasized text containing a 575 <a href="http://example.org">hyperlink</a> and 576 <tt>inline literals</tt></em> 577 578 Raw LaTeX is supported for LaTeX output, etc. 579 580 __ docs/ref/rst/directives.html#raw 581 582 583How to indicate a line break or a significant newline? 584------------------------------------------------------ 585 586`Line blocks`__ are designed for address blocks, verse, and other 587cases where line breaks are significant and must be preserved. Unlike 588literal blocks, the typeface is not changed, and inline markup is 589recognized. For example:: 590 591 | A one, two, a one two three four 592 | 593 | Half a bee, philosophically, 594 | must, *ipso facto*, half not be. 595 | But half the bee has got to be, 596 | *vis a vis* its entity. D'you see? 597 | 598 | But can a bee be said to be 599 | or not to be an entire bee, 600 | when half the bee is not a bee, 601 | due to some ancient injury? 602 | 603 | Singing... 604 605__ docs/ref/rst/restructuredtext.html#line-blocks 606 607Here's a workaround for manually inserting explicit line breaks in 608HTML output:: 609 610 .. |br| raw:: html 611 612 <br /> 613 614 I want to break this line here: |br| this is after the break. 615 616 If the extra whitespace bothers you, |br|\ backslash-escape it. 617 618 619A URL containing asterisks doesn't work. What to do? 620----------------------------------------------------- 621 622Asterisks are valid URL characters (see :RFC:`2396`), sometimes used 623in URLs. For example:: 624 625 http://cvs.example.org/viewcvs.py/*checkout*/module/file 626 627Unfortunately, the parser thinks the asterisks are indicating 628emphasis. The slashes serve as delineating punctuation, allowing the 629asterisks to be recognized as markup. The example above is separated 630by the parser into a truncated URL, an emphasized word, and some 631regular text:: 632 633 http://cvs.example.org/viewcvs.py/ 634 *checkout* 635 /module/file 636 637To turn off markup recognition, use a backslash to escape at least the 638first asterisk, like this:: 639 640 http://cvs.example.org/viewcvs.py/\*checkout*/module/file 641 642Escaping the second asterisk doesn't hurt, but it isn't necessary. 643 644 645How can I make a literal block with *some* formatting? 646------------------------------------------------------ 647 648Use the `parsed-literal`_ directive. 649 650.. _parsed-literal: docs/ref/rst/directives.html#parsed-literal 651 652Scenario: a document contains some source code, which calls for a 653literal block to preserve linebreaks and whitespace. But part of the 654source code should be formatted, for example as emphasis or as a 655hyperlink. This calls for a *parsed* literal block:: 656 657 .. parsed-literal:: 658 659 print "Hello world!" # *tricky* code [1]_ 660 661The emphasis (``*tricky*``) and footnote reference (``[1]_``) will be 662parsed. 663 664 665Can reStructuredText be used for web or generic templating? 666----------------------------------------------------------- 667 668Docutils and reStructuredText can be used with or as a component of a 669templating system, but they do not themselves include templating 670functionality. Templating should simply be left to dedicated 671templating systems. Users can choose a templating system to apply to 672their reStructuredText documents as best serves their interests. 673 674There are many good templating systems for Python (ht2html_, YAPTU_, 675Quixote_'s PTL, Cheetah_, etc.; see this non-exhaustive list of `some 676other templating systems`_), and many more for other languages, each 677with different approaches. We invite you to try several and find one 678you like. If you adapt it to use Docutils/reStructuredText, please 679consider contributing the code to Docutils or `let us know`_ and we'll 680keep a list here. 681 682One reST-specific web templating system is `rest2web 683<http://www.voidspace.org.uk/python/rest2web>`_, a tool for 684automatically building websites, or parts of websites. 685 686.. _ht2html: http://ht2html.sourceforge.net/ 687.. _YAPTU: 688 http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52305 689.. _Quixote: http://www.mems-exchange.org/software/quixote/ 690.. _Cheetah: http://www.cheetahtemplate.org/ 691.. _some other templating systems: 692 http://webware.sourceforge.net/Papers/Templates/ 693 694 695How can I mark up a FAQ or other list of questions & answers? 696------------------------------------------------------------- 697 698There is no specific syntax for FAQs and Q&A lists. Here are two 699options: 700 7011. For a FAQ (Frequently Asked Questions, usually with answers), a 702 convenient way to mark up the questions is as section titles, with 703 the answer(s) as section content. This document is marked up in 704 this way. 705 706 The advantages of using section titles for questions are: sections 707 can be numbered automatically, and a table of contents can be 708 generated automatically. One limitation of this format is that 709 questions must fit on one line (section titles may not wrap, in the 710 source text). For very long questions, the title may be a summary 711 of the question, with the full question in the section body. 712 7132. Field lists work well as Q&A lists:: 714 715 :Q: What kind of questions can we 716 put here? 717 718 :A: Any kind we like! 719 720 In order to separate questions, lists can be used: 721 722 1. :Q: What kind of question can we 723 put here? 724 :A: Any kind we like! 725 726 2. :Q: How many answers can a question have? 727 :A: It can have one, 728 :A: or more. 729 :A3: Answers can be numbered like this. 730 :A: 1. Or like this. 731 2. We're flexible! 732 733 If you don't want to number or otherwise mark questions, you can 734 use an empty comment between individual field lists to separate 735 them:: 736 737 :Q: First question? 738 :A: Answer. 739 740 .. 741 742 :Q: Second question? 743 :A: Answer. 744 745 746.. _bidi: 747 748Can I produce documents in right-to-left languages? 749--------------------------------------------------- 750 751Languages written from right to left, such as Arabic and Hebrew, must 752be reordered according to the `Unicode Bidi Algorithm`_. This 753requires support from the editor and special markup in the output 754format. 755 756The source format of reStructuredText is relatively bidi-friendly: 757most constructs are denoted by punctuation without intrusion of 758English and when you must write in English, it's usually on a separate 759line. So any editor that auto-detects direction per-line (like gedit 760or geresh_) will suffice. 761 762Moreover, it's possible to translate_ all reStructuredText keywords. 763Docutils 0.17 includes translations for Arab, Hebrew, and 764Persian/Farsi. This should allow reasonable use of editors limited to 765a single base direction for the whole document (like Notepad, Vim and 766text boxes in Firefox). 767 768.. _Unicode Bidi Algorithm: http://www.unicode.org/reports/tr9/ 769.. _geresh: http://www.typo.co.il/~mooffie/geresh/ 770.. _translate: docs/howto/i18n.html 771 772The second problem is bidi markup of the output. There is an almost 773transparent implicit solution for HTML: 774 775* Grab http://cben-hacks.sourceforge.net/bidi/hibidi.py and 776 http://cben-hacks.sourceforge.net/bidi/rst2html_hibidi.py. 777 Put them both in the same directory and make them executable. 778 779* Use ``rst2html_hibidi.py`` instead of ``rst2html.py``. 780 781* It infers dir attributes in the HTML from the text. It does it 782 hierachically, giving much better results than usual. You can still 783 use LRM/RLM and LRE/RLE/PDF control codes to help it. 784 785 * If you want the gory details: See the full theory_, and note the 786 incomplete practice_ (this is still a partial implementation - but 787 sufficient for most needs). 788 789 .. _theory: http://cben-hacks.sf.net/bidi/hibidi.html 790 .. _practice: http://cben-hacks.sf.net/bidi/hibidi.html#practice 791 792There is also an explicit way to set directions through CSS and 793classes in the HTML: 794 795* Copy ``default.css`` to a new file and add relevant parts of the 796 following:: 797 798 /* Use these two if the main document direction is RTL */ 799 body { direction: rtl; } 800 div.sidebar { float: left !important; } 801 802 /* The next 3 rules are very useful in documents containing pieces 803 of code in english */ 804 /* Use this if you all your literal blocks (::) are LTR */ 805 pre {direction: ltr; unicode-bidi: embed; } 806 /* Use this if you all your inline literals (``) are LTR */ 807 tt {direction: ltr; unicode-bidi: embed; } 808 /* Use this if you all your interpretted text (`) is LTR */ 809 cite {direction: ltr; unicode-bidi: embed; } 810 811 /* Allow manual direction override by class directive and roles */ 812 .rtl { direction: rtl; } 813 .ltr { direction: ltr; } 814 815* Select this new stylesheet with ``--stylesheet=<file>`` or the 816 stylesheet_ setting. 817 818* Now if you need to override the direction of some element (from a 819 paragraph to a whole section), write:: 820 821 .. class:: rtl 822 823 or:: 824 825 .. class:: ltr 826 827 before it (see the class_ directive for details). 828 829* To change the direction of some inline text fragment, you can use 830 RLE/LRE/PDF control characters, or write ``:rtl:`RTL text``` / 831 ``:ltr:`RTL text```. To use the latter syntax, you must write this 832 once at the beginning of your document:: 833 834 .. role:: ltr 835 .. role:: rtl 836 837.. _stylesheet: docs/user/config.html#stylesheet 838.. _class: docs/ref/rst/directives.txt#class 839 840LaTeX is quite hard to implement (it doesn't support the bidi 841algorithm, so all direction changes - even numbers in RTL text - must 842be explicitly marked). Other formats are more-or-less easy. 843 844If you have any questions/problems/bugs related to bidi with docutils, 845ask `Beni Cherniavsky`__ directly or the `Docutils-users`_ mailing 846list. 847 848__ mailto:cben@users.sf.net 849 850 851What's the official MIME type for reStructuredText data? 852-------------------------------------------------------- 853 854While there is no registered MIME type for reStructuredText, the 855"official unofficial" standard MIME type is "text/x-rst". [#]_ This was 856invented for the build system for PEPs (Python Enhancement Proposals), 857and it's used by the python.org web site build system. 858 859Also see `What's the standard filename extension for a 860reStructuredText file?`_ 861 862.. [#] The "x-" prefix means it's an unregistered MIME type. 863 864 865HTML Writer 866=========== 867 868What is the status of the HTML Writer? 869-------------------------------------- 870 871The default HTML Writer module, ``docutils/writers/html4css1.py``, is 872a proof-of-concept reference implementation. While it is a complete 873implementation, some aspects of the HTML it produces may be outdated or 874incompatible with older browsers or specialized applications (such as 875web templating). 876 877For the full selection see `Docutils HTML writers`_ 878 879.. _Docutils HTML writers: docs/user/html.html 880 881What browsers are supported? 882---------------------------- 883 884No specific browser is targeted; all modern graphical browsers should 885work. Some older browsers, text-only browsers, and browsers without 886full CSS support are known to produce inferior results. Firefox, 887Safari, Opera, Chrome, Edge, and MS Internet Explorer (version 5.0 and up) 888are known to give good results. Reports of experiences with other 889browsers are welcome. 890 891 892Unexpected results from tools/rst2html.py: H1, H1 instead of H1, H2. Why? 893-------------------------------------------------------------------------- 894 895Here's the question in full: 896 897 I have this text:: 898 899 Heading 1 900 ========= 901 902 All my life, I wanted to be H1. 903 904 Heading 1.1 905 ----------- 906 907 But along came H1, and so shouldn't I be H2? 908 No! I'm H1! 909 910 Heading 1.1.1 911 ************* 912 913 Yeah, imagine me, I'm stuck at H3! No?!? 914 915 When I run it through tools/rst2html.py, I get unexpected results 916 (below). I was expecting H1, H2, then H3; instead, I get H1, H1, 917 H2:: 918 919 ... 920 <html lang="en"> 921 <head> 922 ... 923 <title>Heading 1</title> 924 </head> 925 <body> 926 <div class="document" id="heading-1"> 927 <h1 class="title">Heading 1</h1> <-- first H1 928 <p>All my life, I wanted to be H1.</p> 929 <div class="section" id="heading-1-1"> 930 <h1><a name="heading-1-1">Heading 1.1</a></h1> <-- H1 931 <p>But along came H1, and so now I must be H2.</p> 932 <div class="section" id="heading-1-1-1"> 933 <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2> 934 <p>Yeah, imagine me, I'm stuck at H3!</p> 935 ... 936 937 What gives? 938 939Check the "class" attribute on the H1 tags, and you will see a 940difference. The first H1 is actually ``<h1 class="title">``; this is 941the document title, and the default stylesheet renders it centered. 942There can also be an ``<h2 class="subtitle">`` for the document 943subtitle. 944 945If there's only one highest-level section title at the beginning of a 946document, it is treated specially, as the document title. (Similarly, a 947lone second-highest-level section title may become the document 948subtitle.) See `How can I indicate the document title? Subtitle?`_ for 949details. Rather than use a plain H1 for the document title, we use ``<h1 950class="title">`` so that we can use H1 again within the document. Why 951do we do this? HTML only has H1-H6, so by making H1 do double duty, we 952effectively reserve these tags to provide 6 levels of heading beyond the 953single document title. 954 955With "html4css1", HTML is being used for dumb formatting for nothing 956but final display. A stylesheet *is required*, and one is provided; 957see `Docutils HTML writers`_. Of course, you're 958welcome to roll your own. The default stylesheet provides rules to 959format ``<h1 class="title">`` and ``<h2 class="subtitle">`` 960differently from ordinary ``<h1>`` and ``<h2>``:: 961 962 h1.title { 963 text-align: center } 964 965 h2.subtitle { 966 text-align: center } 967 968If you don't want the top section heading to be interpreted as a 969title at all, disable the `doctitle_xform`_ setting 970(``--no-doc-title`` option). This will interpret your document 971differently from the standard settings, which might not be a good 972idea. If you don't like the reuse of the H1 in the HTML output, you 973can tweak the `initial_header_level`_ setting 974(``--initial-header-level`` option) -- but unless you match its value 975to your specific document, you might end up with bad HTML (e.g. H3 976without H2). 977 978.. _doctitle_xform: docs/user/config.html#doctitle-xform 979.. _initial_header_level: docs/user/config.html#initial-header-level 980 981(Thanks to Mark McEahern for the question and much of the answer.) 982 983.. note:: For the html5 writer, `initial_header_level`_ defaults to 984 ``2`` because this is what the `HTML5 standard`__ expects as 985 start value for headings nested in <section> elements. 986 987 __ https://www.w3.org/TR/html53/sections.html#headings-and-sections 988 989 990How are lists formatted in HTML? 991-------------------------------- 992 993If list formatting looks strange, first check that you understand 994`list markup`__. 995 996__ `How should I mark up lists?`_ 997 998* By default, HTML browsers indent lists relative to their context. 999 This follows a long tradition in browsers (but isn't so established 1000 in print). If you don't like it, you should change the stylesheet. 1001 1002 This is different from how lists look in reStructuredText source. 1003 Extra indentation in the source indicates a blockquote, resulting in 1004 too much indentation in the browser. 1005 1006* A list item can contain multiple paragraphs etc. In complex cases 1007 list items are separated by vertical space. By default this spacing 1008 is omitted in "simple" lists. A list is simple if every item 1009 contains a simple paragraph and/or a "simple" nested list. For 1010 example: 1011 1012 * text 1013 1014 * simple 1015 1016 * simple 1017 * simple 1018 1019 * simple 1020 1021 text after a nested list 1022 1023 * multiple 1024 1025 paragraphs 1026 1027 In this example the nested lists are simple (and should appear 1028 compacted) but the outer list is not. 1029 1030 If you want all lists to have equal spacing, disable the 1031 `compact_lists`_ setting (``--no-compact-lists`` option). The 1032 precise spacing can be controlled in the stylesheet. 1033 1034 Note again that this is not exactly WYSIWYG: it partially resembles 1035 the rules about blank lines being optional between list items in 1036 reStructuredText -- but adding/removing optional blank lines does 1037 not affect spacing in the output! It's a feature, not a bug: you 1038 write it as you like but the output is styled consistently. 1039 1040 .. _compact_lists: docs/user/config.html#compact-lists 1041 1042 1043Why do enumerated lists only use numbers (no letters or roman numerals)? 1044------------------------------------------------------------------------ 1045 1046The rendering of enumerators (the numbers or letters acting as list 1047markers) is completely governed by the stylesheet, so either the 1048browser can't find the stylesheet (try enabling the 1049`embed_stylesheet`_ setting [``--embed-stylesheet`` option]), or the 1050browser can't understand it (try a not too old Firefox, Chrome, Opera, 1051Safari, Edge, or even MSIE). 1052 1053.. _embed_stylesheet: docs/user/config.html#embed-stylesheet 1054 1055 1056There appear to be garbage characters in the HTML. What's up? 1057-------------------------------------------------------------- 1058 1059What you're seeing is most probably not garbage, but the result of a 1060mismatch between the actual encoding of the HTML output and the 1061encoding your browser is expecting. Your browser is misinterpreting 1062the HTML data, which is encoded text. A discussion of text encodings 1063is beyond the scope of this FAQ; see one or more of these documents 1064for more info: 1065 1066* `UTF-8 and Unicode FAQ for Unix/Linux 1067 <http://www.cl.cam.ac.uk/~mgk25/unicode.html>`_ 1068 1069* Chapters 3 and 4 of `Introduction to i18n [Internationalization] 1070 <http://www.debian.org/doc/manuals/intro-i18n/>`_ 1071 1072* `Python Unicode Tutorial 1073 <http://www.reportlab.com/i18n/python_unicode_tutorial.html>`_ 1074 1075* `Python Unicode Objects: Some Observations on Working With Non-ASCII 1076 Character Sets <http://effbot.org/zone/unicode-objects.htm>`_ 1077 1078The common case is with the default output encoding (UTF-8), when 1079either numbered sections are used (via the "sectnum_" directive) or 1080symbol-footnotes. 3 non-breaking spaces are inserted in each numbered 1081section title, between the generated number and the title text. Most 1082footnote symbols are not available in ASCII, nor are non-breaking 1083spaces. When encoded with UTF-8 and viewed with ordinary ASCII tools, 1084these characters will appear to be multi-character garbage. 1085 1086You may have an decoding problem in your browser (or editor, etc.). 1087The encoding of the output is set to "utf-8", but your browswer isn't 1088recognizing that. You can either try to fix your browser (enable 1089"UTF-8 character set", sometimes called "Unicode"), or choose a 1090different encoding for the HTML output. You can also try 1091``--output-encoding=ascii:xmlcharrefreplace`` for HTML or XML, but not 1092applicable to non-XMLish outputs (if using runtime 1093settings/configuration files, use ``output_encoding=ascii`` and 1094``output_encoding_error_handler=xmlcharrefreplace``). 1095 1096If you're generating document fragments, the "Content-Type" metadata 1097(between the HTML ``<head>`` and ``</head>`` tags) must agree with the 1098encoding of the rest of the document. For UTF-8, it should be:: 1099 1100 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 1101 1102Also, Docutils normally generates an XML declaration as the first line 1103of the output. It must also match the document encoding. For UTF-8:: 1104 1105 <?xml version="1.0" encoding="utf-8" ?> 1106 1107.. _sectnum: docs/ref/rst/directives.html#sectnum 1108 1109 1110How can I retrieve the body of the HTML document? 1111------------------------------------------------- 1112 1113(This is usually needed when using Docutils in conjunction with a 1114templating system.) 1115 1116You can use the `docutils.core.publish_parts()`_ function, which 1117returns a dictionary containing an 'html_body_' entry. 1118 1119.. _docutils.core.publish_parts(): docs/api/publisher.html#publish-parts 1120.. _html_body: docs/api/publisher.html#html-body 1121 1122 1123Why is the Docutils XHTML served as "Content-type: text/html"? 1124-------------------------------------------------------------- 1125 1126Full question: 1127 1128 Docutils' HTML output looks like XHTML and is advertised as such:: 1129 1130 <?xml version="1.0" encoding="utf-8" ?> 1131 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 1132 "http://www.w3.org/TR/xht ml1/DTD/xhtml1-transitional.dtd"> 1133 1134 But this is followed by:: 1135 1136 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 1137 1138 Shouldn't this be "application/xhtml+xml" instead of "text/html"? 1139 1140Short answer: if we didn't serve XHTML as "text/html" (which is a 1141perfectly valid thing to do), it couldn't be viewed in Internet 1142Explorer. 1143 1144Long answer: In a perfect web, the Docutils XHTML output would be 100% 1145strict XHTML. But it's not a perfect web, and a major source of 1146imperfection is Internet Explorer. When the "html4css1" 1147writer was created, IE represented the overwhelming majority of web 1148browsers "in the wild". 1149The behaviour is kept for backwards compatibility while 1150modern, semantic HTML output is available with the "html5" writer. 1151 1152(Thanks to Martin F. Krafft, Robert Kern, Michael Foord, and Alan 1153G. Isaac.) 1154 1155 1156Python Source Reader 1157==================== 1158 1159Can I use Docutils for Python auto-documentation? 1160------------------------------------------------- 1161 1162Yes, in conjunction with other projects. 1163 1164The Sphinx_ documentation generator includes an autodoc module. 1165 1166.. _Sphinx: http://sphinx.pocoo.org/index.html 1167 1168Version 2.0 of Ed Loper's `Epydoc <http://epydoc.sourceforge.net/>`_ 1169supports reStructuredText-format docstrings for HTML output. Docutils 11700.3 or newer is required. Development of a Docutils-specific 1171auto-documentation tool will continue. Epydoc works by importing 1172Python modules to be documented, whereas the Docutils-specific tool, 1173described above, will parse modules without importing them (as with 1174`HappyDoc <http://happydoc.sourceforge.net/>`_, which doesn't support 1175reStructuredText). 1176 1177The advantages of parsing over importing are security and flexibility; 1178the disadvantage is complexity/difficulty. 1179 1180* Security: untrusted code that shouldn't be executed can be parsed; 1181 importing a module executes its top-level code. 1182* Flexibility: comments and unofficial docstrings (those not supported 1183 by Python syntax) can only be processed by parsing. 1184* Complexity/difficulty: it's a lot harder to parse and analyze a 1185 module than it is to ``import`` and analyze one. 1186 1187For more details, please see "Docstring Extraction Rules" in `PEP 1188258`_, item 3 ("How"). 1189 1190 1191Miscellaneous 1192============= 1193 1194Is the Docutils document model based on any existing XML models? 1195---------------------------------------------------------------- 1196 1197Not directly, no. It borrows bits from DocBook, HTML, and others. I 1198(David Goodger) have designed several document models over the years, 1199and have my own biases. The Docutils document model is designed for 1200simplicity and extensibility, and has been influenced by the needs of 1201the reStructuredText markup. 1202 1203 1204.. 1205 Local Variables: 1206 mode: indented-text 1207 indent-tabs-mode: nil 1208 sentence-end-double-space: t 1209 fill-column: 70 1210 End: 1211 1212.. Here's a code css to make a table colourful:: 1213 1214 /* Table: */ 1215 1216 th { 1217 background-color: #ede; 1218 } 1219 1220 /* alternating colors in table rows */ 1221 table.docutils tr:nth-child(even) { 1222 background-color: #F3F3FF; 1223 } 1224 table.docutils tr:nth-child(odd) { 1225 background-color: #FFFFEE; 1226 } 1227 1228 table.docutils tr { 1229 border-style: solid none solid none; 1230 border-width: 1px 0 1px 0; 1231 border-color: #AAAAAA; 1232 } 1233