FAQ.txt 44 KB

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