| Server IP : 127.0.0.2 / Your IP : 13.59.234.246 Web Server : Apache/2.4.18 (Ubuntu) System : User : www-data ( ) PHP Version : 7.0.33-0ubuntu0.16.04.16 Disable Function : disk_free_space,disk_total_space,diskfreespace,dl,exec,fpaththru,getmyuid,getmypid,highlight_file,ignore_user_abord,leak,listen,link,opcache_get_configuration,opcache_get_status,passthru,pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,php_uname,phpinfo,posix_ctermid,posix_getcwd,posix_getegid,posix_geteuid,posix_getgid,posix_getgrgid,posix_getgrnam,posix_getgroups,posix_getlogin,posix_getpgid,posix_getpgrp,posix_getpid,posix,_getppid,posix_getpwnam,posix_getpwuid,posix_getrlimit,posix_getsid,posix_getuid,posix_isatty,posix_kill,posix_mkfifo,posix_setegid,posix_seteuid,posix_setgid,posix_setpgid,posix_setsid,posix_setuid,posix_times,posix_ttyname,posix_uname,pclose,popen,proc_open,proc_close,proc_get_status,proc_nice,proc_terminate,shell_exec,source,show_source,system,virtual MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /usr/share/doc/python-docutils/ |
Upload File : |
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
<title>Docutils FAQ (Frequently Asked Questions)</title>
<meta name="date" content="2013-07-03" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="css/html4css1.css" type="text/css" />
</head>
<body>
<div class="document" id="docutils-faq-frequently-asked-questions">
<h1 class="title">Docutils FAQ (Frequently Asked Questions)</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Date:</th>
<td>2013-07-03</td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>7677</td></tr>
<tr class="field"><th class="docinfo-name">Web site:</th><td class="field-body"><a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a></td>
</tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<!-- -*- coding: utf-8 -*- -->
<!-- NOTE TO MAINTAINERS: Please add new questions to the end of their
sections, so section/question numbers remain stable. -->
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#docutils" id="id21">1 Docutils</a><ul class="auto-toc">
<li><a class="reference internal" href="#what-is-docutils" id="id22">1.1 What is Docutils?</a></li>
<li><a class="reference internal" href="#why-is-it-called-docutils" id="id23">1.2 Why is it called "Docutils"?</a></li>
<li><a class="reference internal" href="#is-there-a-gui-authoring-environment-for-docutils" id="id24">1.3 Is there a GUI authoring environment for Docutils?</a></li>
<li><a class="reference internal" href="#what-is-the-status-of-the-docutils-project" id="id25">1.4 What is the status of the Docutils project?</a></li>
<li><a class="reference internal" href="#what-is-the-docutils-project-release-policy" id="id26">1.5 What is the Docutils project release policy?</a></li>
</ul>
</li>
<li><a class="reference internal" href="#restructuredtext" id="id27">2 reStructuredText</a><ul class="auto-toc">
<li><a class="reference internal" href="#what-is-restructuredtext" id="id28">2.1 What is reStructuredText?</a></li>
<li><a class="reference internal" href="#why-is-it-called-restructuredtext" id="id29">2.2 Why is it called "reStructuredText"?</a></li>
<li><a class="reference internal" href="#what-s-the-standard-abbreviation-for-restructuredtext" id="id30">2.3 What's the standard abbreviation for "reStructuredText"?</a></li>
<li><a class="reference internal" href="#what-s-the-standard-filename-extension-for-a-restructuredtext-file" id="id31">2.4 What's the standard filename extension for a reStructuredText file?</a></li>
<li><a class="reference internal" href="#are-there-any-restructuredtext-editor-extensions" id="id32">2.5 Are there any reStructuredText editor extensions?</a></li>
<li><a class="reference internal" href="#how-can-i-indicate-the-document-title-subtitle" id="id33">2.6 How can I indicate the document title? Subtitle?</a></li>
<li><a class="reference internal" href="#how-can-i-represent-esoteric-characters-e-g-character-entities-in-a-document" id="id34">2.7 How can I represent esoteric characters (e.g. character entities) in a document?</a></li>
<li><a class="reference internal" href="#how-can-i-generate-backticks-using-a-scandinavian-keyboard" id="id35">2.8 How can I generate backticks using a Scandinavian keyboard?</a></li>
<li><a class="reference internal" href="#are-there-any-tools-for-html-xml-to-restructuredtext-round-tripping" id="id36">2.9 Are there any tools for HTML/XML-to-reStructuredText? (Round-tripping)</a></li>
<li><a class="reference internal" href="#are-there-any-wikis-that-use-restructuredtext-syntax" id="id37">2.10 Are there any Wikis that use reStructuredText syntax?</a></li>
<li><a class="reference internal" href="#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax" id="id38">2.11 Are there any Weblog (Blog) projects that use reStructuredText syntax?</a></li>
<li><a class="reference internal" href="#how-should-i-mark-up-lists" id="id39">2.12 How should I mark up lists?</a></li>
<li><a class="reference internal" href="#could-lists-be-indented-without-generating-block-quotes" id="id40">2.13 Could lists be indented without generating block quotes?</a></li>
<li><a class="reference internal" href="#could-the-requirement-for-blank-lines-around-lists-be-relaxed" id="id41">2.14 Could the requirement for blank lines around lists be relaxed?</a></li>
<li><a class="reference internal" href="#how-can-i-include-mathematical-equations-in-documents" id="id42">2.15 How can I include mathematical equations in documents?</a></li>
<li><a class="reference internal" href="#is-nested-inline-markup-possible" id="id43">2.16 Is nested inline markup possible?</a></li>
<li><a class="reference internal" href="#how-to-indicate-a-line-break-or-a-significant-newline" id="id44">2.17 How to indicate a line break or a significant newline?</a></li>
<li><a class="reference internal" href="#a-url-containing-asterisks-doesn-t-work-what-to-do" id="id45">2.18 A URL containing asterisks doesn't work. What to do?</a></li>
<li><a class="reference internal" href="#how-can-i-make-a-literal-block-with-some-formatting" id="id46">2.19 How can I make a literal block with <em>some</em> formatting?</a></li>
<li><a class="reference internal" href="#can-restructuredtext-be-used-for-web-or-generic-templating" id="id47">2.20 Can reStructuredText be used for web or generic templating?</a></li>
<li><a class="reference internal" href="#how-can-i-mark-up-a-faq-or-other-list-of-questions-answers" id="id48">2.21 How can I mark up a FAQ or other list of questions & answers?</a></li>
<li><a class="reference internal" href="#can-i-produce-documents-in-right-to-left-languages" id="id49">2.22 Can I produce documents in right-to-left languages?</a></li>
<li><a class="reference internal" href="#what-s-the-official-mime-type-for-restructuredtext-data" id="id50">2.23 What's the official MIME type for reStructuredText data?</a></li>
</ul>
</li>
<li><a class="reference internal" href="#html-writer" id="id51">3 HTML Writer</a><ul class="auto-toc">
<li><a class="reference internal" href="#what-is-the-status-of-the-html-writer" id="id52">3.1 What is the status of the HTML Writer?</a></li>
<li><a class="reference internal" href="#what-kind-of-html-does-it-produce" id="id53">3.2 What kind of HTML does it produce?</a></li>
<li><a class="reference internal" href="#what-browsers-are-supported" id="id54">3.3 What browsers are supported?</a></li>
<li><a class="reference internal" href="#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why" id="id55">3.4 Unexpected results from tools/rst2html.py: H1, H1 instead of H1, H2. Why?</a></li>
<li><a class="reference internal" href="#how-are-lists-formatted-in-html" id="id56">3.5 How are lists formatted in HTML?</a></li>
<li><a class="reference internal" href="#why-do-enumerated-lists-only-use-numbers-no-letters-or-roman-numerals" id="id57">3.6 Why do enumerated lists only use numbers (no letters or roman numerals)?</a></li>
<li><a class="reference internal" href="#there-appear-to-be-garbage-characters-in-the-html-what-s-up" id="id58">3.7 There appear to be garbage characters in the HTML. What's up?</a></li>
<li><a class="reference internal" href="#how-can-i-retrieve-the-body-of-the-html-document" id="id59">3.8 How can I retrieve the body of the HTML document?</a></li>
<li><a class="reference internal" href="#why-is-the-docutils-xhtml-served-as-content-type-text-html" id="id60">3.9 Why is the Docutils XHTML served as "Content-type: text/html"?</a></li>
</ul>
</li>
<li><a class="reference internal" href="#python-source-reader" id="id61">4 Python Source Reader</a><ul class="auto-toc">
<li><a class="reference internal" href="#can-i-use-docutils-for-python-auto-documentation" id="id62">4.1 Can I use Docutils for Python auto-documentation?</a></li>
</ul>
</li>
<li><a class="reference internal" href="#miscellaneous" id="id63">5 Miscellaneous</a><ul class="auto-toc">
<li><a class="reference internal" href="#is-the-docutils-document-model-based-on-any-existing-xml-models" id="id64">5.1 Is the Docutils document model based on any existing XML models?</a></li>
</ul>
</li>
</ul>
</div>
<p>This is a work in progress. If you are reading a local copy, the
<a class="reference external" href="http://docutils.sourceforge.net/FAQ.html">master copy</a> might be newer. This document uses are relative links;
if they don't work, please use the <a class="reference external" href="http://docutils.sourceforge.net/FAQ.html">master copy</a>.</p>
<p>Please feel free to ask questions and/or provide answers; send email
to the <a class="reference external" href="docs/user/mailing-lists.html#docutils-users">Docutils-users</a> mailing list. Project members should feel
free to edit the source text file directly.</p>
<div class="section" id="docutils">
<h1><a class="toc-backref" href="#id21">1 Docutils</a></h1>
<div class="section" id="what-is-docutils">
<h2><a class="toc-backref" href="#id22">1.1 What is Docutils?</a></h2>
<p><a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> is a system for processing plaintext documentation into
useful formats, such as HTML, XML, and LaTeX. It supports multiple
types of input, such as standalone files (implemented), inline
documentation from Python modules and packages (under development),
<a class="reference external" href="http://www.python.org/peps/pep-0012.html">PEPs (Python Enhancement Proposals)</a> (implemented), and others as
discovered.</p>
<p>The Docutils distribution consists of:</p>
<ul class="simple">
<li>a library (the "docutils" package), which <a class="reference external" href="docs/api/publisher.html">can be used by client
code</a>;</li>
<li>several <a class="reference external" href="docs/user/tools.html">front-end tools</a> (such as <tt class="docutils literal">rst2html.py</tt>, which converts
reStructuredText input into HTML output);</li>
<li>a <a class="reference external" href="docs/dev/testing.html">test suite</a>; and</li>
<li>extensive <a class="reference external" href="docs/index.html">documentation</a>.</li>
</ul>
<p>For an overview of the Docutils project implementation, see <a class="reference external" href="http://www.python.org/peps/pep-0258.html">PEP
258</a>, "Docutils Design Specification".</p>
<p>Docutils is implemented in <a class="reference external" href="http://www.python.org/">Python</a>.</p>
</div>
<div class="section" id="why-is-it-called-docutils">
<h2><a class="toc-backref" href="#id23">1.2 Why is it called "Docutils"?</a></h2>
<p>Docutils is short for "Python Documentation Utilities". The name
"Docutils" was inspired by "Distutils", the Python Distribution
Utilities architected by Greg Ward, a component of Python's standard
library.</p>
<p>The earliest known use of the term "docutils" in a Python context was
a <a class="reference external" href="http://mail.python.org/pipermail/doc-sig/1999-December/000878.html">fleeting reference</a> in a message by Fred Drake on 1999-12-02 in
the Python Doc-SIG mailing list. It was suggested <a class="reference external" href="http://mail.python.org/pipermail/doc-sig/2000-November/001252.html">as a project
name</a> on 2000-11-27 on Doc-SIG, again by Fred Drake, in response to
a question from Tony "Tibs" Ibbs: "What do we want to <em>call</em> this
thing?". This was shortly after David Goodger first <a class="reference external" href="http://mail.python.org/pipermail/doc-sig/2000-November/001239.html">announced
reStructuredText</a> on Doc-SIG.</p>
<p>Tibs used the name "Docutils" for <a class="reference external" href="http://homepage.ntlworld.com/tibsnjoan/docutils/STpy.html">his effort</a> "to document what the
Python docutils package should support, with a particular emphasis on
documentation strings". Tibs joined the current project (and its
predecessors) and graciously donated the name.</p>
<p>For more history of reStructuredText and the Docutils project, see <a class="reference external" href="docs/ref/rst/introduction.html">An
Introduction to reStructuredText</a>.</p>
<p>Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils"
or any other variation. It is pronounced as in "DOCumentation
UTILitieS", with emphasis on the first syllable.</p>
</div>
<div class="section" id="is-there-a-gui-authoring-environment-for-docutils">
<h2><a class="toc-backref" href="#id24">1.3 Is there a GUI authoring environment for Docutils?</a></h2>
<p><a class="reference external" href="http://docutils.sf.net/sandbox/gschwant/docfactory/doc/">DocFactory</a> is under development. It uses wxPython and looks very
promising.</p>
</div>
<div class="section" id="what-is-the-status-of-the-docutils-project">
<h2><a class="toc-backref" href="#id25">1.4 What is the status of the Docutils project?</a></h2>
<p>Although useful and relatively stable, Docutils is experimental code,
with APIs and architecture subject to change.</p>
<p>Our highest priority is to fix bugs as they are reported. So the
latest code from the <a class="reference external" href="docs/dev/repository.html">repository</a> (or the <a class="reference external" href="http://docutils.sourceforge.net/#download">snapshots</a>) is almost always
the most stable (bug-free) as well as the most featureful.</p>
</div>
<div class="section" id="what-is-the-docutils-project-release-policy">
<h2><a class="toc-backref" href="#id26">1.5 What is the Docutils project release policy?</a></h2>
<p>It's "release early & often". We also have automatically-generated
<a class="reference external" href="http://docutils.sourceforge.net/#download">snapshots</a> which always contain the latest code from the <a class="reference external" href="docs/dev/repository.html">repository</a>.
As the project matures, we may formalize on a
stable/development-branch scheme, but we're not using anything like
that yet.</p>
</div>
</div>
<div class="section" id="restructuredtext">
<h1><a class="toc-backref" href="#id27">2 reStructuredText</a></h1>
<div class="section" id="what-is-restructuredtext">
<h2><a class="toc-backref" href="#id28">2.1 What is reStructuredText?</a></h2>
<p><a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> is an easy-to-read, what-you-see-is-what-you-get
plaintext markup syntax and parser system. The reStructuredText
parser is a component of <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a>. reStructuredText is a revision
and reinterpretation of the <a class="reference external" href="http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/">StructuredText</a> and <a class="reference external" href="http://docutils.sourceforge.net/mirror/setext.html">Setext</a> lightweight
markup systems.</p>
<p>If you are reading this on the web, you can see for yourself. <a class="reference external" href="FAQ.txt">The
source for this FAQ</a> is written in reStructuredText; open
it in another window and compare them side by side.</p>
<p><a class="reference external" href="docs/user/rst/quickstart.html">A ReStructuredText Primer</a> and the <a class="reference external" href="docs/user/rst/quickref.html">Quick reStructuredText</a> user
reference are a good place to start. The <a class="reference external" href="docs/ref/rst/restructuredtext.html">reStructuredText Markup
Specification</a> is a detailed technical specification.</p>
</div>
<div class="section" id="why-is-it-called-restructuredtext">
<h2><a class="toc-backref" href="#id29">2.2 Why is it called "reStructuredText"?</a></h2>
<p>The name came from a combination of "StructuredText", one of
reStructuredText's predecessors, with "re": "revised", "reworked", and
"reinterpreted", and as in the <tt class="docutils literal">re.py</tt> regular expression module.
For a detailed history of reStructuredText and the Docutils project,
see <a class="reference external" href="docs/ref/rst/introduction.html">An Introduction to reStructuredText</a>.</p>
<p>"reStructuredText" is <strong>ONE</strong> word, <em>not two!</em></p>
</div>
<div class="section" id="what-s-the-standard-abbreviation-for-restructuredtext">
<h2><a class="toc-backref" href="#id30">2.3 What's the standard abbreviation for "reStructuredText"?</a></h2>
<p>"RST" and "ReST" (or "reST") are both acceptable. Care should be
taken with capitalization, to avoid confusion with "<a class="reference external" href="http://en.wikipedia.org/wiki/Representational_State_Transfer">REST</a>", an
acronym for "Representational State Transfer".</p>
<p>The abbreviations "reSTX" and "rSTX"/"rstx" should <strong>not</strong> be used;
they overemphasize reStructuredText's precedessor, Zope's
StructuredText.</p>
</div>
<div class="section" id="what-s-the-standard-filename-extension-for-a-restructuredtext-file">
<h2><a class="toc-backref" href="#id31">2.4 What's the standard filename extension for a reStructuredText file?</a></h2>
<p>It's ".txt". Some people would like to use ".rest" or ".rst" or
".restx", but why bother? ReStructuredText source files are meant to
be readable as plaintext, and most operating systems already associate
".txt" with text files. Using a specialized filename extension would
require that users alter their OS settings, which is something that
many users will not be willing or able to do.</p>
<p>Also see <a class="reference internal" href="#what-s-the-official-mime-type-for-restructuredtext-data">What's the official MIME type for reStructuredText data?</a></p>
</div>
<div class="section" id="are-there-any-restructuredtext-editor-extensions">
<h2><a class="toc-backref" href="#id32">2.5 Are there any reStructuredText editor extensions?</a></h2>
<p>See <a class="reference external" href="tools/editors/README.html">Editor Support for reStructuredText</a>.</p>
</div>
<div class="section" id="how-can-i-indicate-the-document-title-subtitle">
<h2><a class="toc-backref" href="#id33">2.6 How can I indicate the document title? Subtitle?</a></h2>
<p>A uniquely-adorned section title at the beginning of a document is
treated specially, as the document title. Similarly, a
uniquely-adorned section title immediately after the document title
becomes the document subtitle. For example:</p>
<pre class="literal-block">
This is the Document Title
==========================
This is the Document Subtitle
-----------------------------
Here's an ordinary paragraph.
</pre>
<p>Counterexample:</p>
<pre class="literal-block">
Here's an ordinary paragraph.
This is *not* a Document Title
==============================
The "ordinary paragraph" above the section title
prevents it from becoming the document title.
</pre>
<p>Another counterexample:</p>
<pre class="literal-block">
This is not the Document Title, because...
===========================================
Here's an ordinary paragraph.
... the title adornment is not unique
=====================================
Another ordinary paragraph.
</pre>
</div>
<div class="section" id="how-can-i-represent-esoteric-characters-e-g-character-entities-in-a-document">
<h2><a class="toc-backref" href="#id34">2.7 How can I represent esoteric characters (e.g. character entities) in a document?</a></h2>
<p>For example, say you want an em-dash (XML character entity &mdash;,
Unicode character U+2014) in your document: use a real em-dash.
Insert concrete characters (e.g. type a <em>real</em> em-dash) into your
input file, using whatever encoding suits your application, and tell
Docutils the input encoding. Docutils uses Unicode internally, so the
em-dash character is a real em-dash internally.</p>
<p>Emacs users should refer to the <a class="reference external" href="tools/editors/emacs/README.html">Emacs Support for reStructuredText</a>
document. Tips for other editors are welcome.</p>
<p>ReStructuredText has no character entity subsystem; it doesn't know
anything about XML charents. To Docutils, "&mdash;" in input text is
7 discrete characters; no interpretation happens. When writing HTML,
the "&" is converted to "&amp;", so in the raw output you'd see
"&amp;mdash;". There's no difference in interpretation for text
inside or outside inline literals or literal blocks -- there's no
character entity interpretation in either case.</p>
<p>If you can't use a Unicode-compatible encoding and must rely on 7-bit
ASCII, there is a workaround. New in Docutils 0.3.10 is a set of
<a class="reference external" href="docs/ref/rst/substitutions.html">Standard Substitution Definition Sets</a>, which provide equivalents of
XML & HTML character entity sets as substitution definitions. For
example, the Japanese yen currency symbol can be used as follows:</p>
<pre class="literal-block">
.. include:: <xhtml1-lat1.txt>
|yen| 600 for a complete meal? That's cheap!
</pre>
<p>For earlier versions of Docutils, equivalent files containing
character entity set substitution definitions using the "<a class="reference external" href="docs/ref/rst/directives.html#unicode-character-codes">unicode</a>"
directive <a class="reference external" href="http://docutils.sourceforge.net/tmp/charents/">are available</a>. Please read the <a class="reference external" href="http://docutils.sourceforge.net/tmp/charents/README.html">description and
instructions</a> for use. Thanks to David Priest for the original idea.</p>
<p>If you insist on using XML-style charents, you'll have to implement a
pre-processing system to convert to UTF-8 or something. That
introduces complications though; you can no longer <em>write</em> about
charents naturally; instead of writing "&mdash;" you'd have to write
"&amp;mdash;".</p>
<p>For the common case of long dashes, you might also want to insert the
following substitution definitons into your document (both of them are
using the "<a class="reference external" href="docs/ref/rst/directives.html#unicode-character-codes">unicode</a>" directive):</p>
<pre class="literal-block">
.. |--| unicode:: U+2013 .. en dash
.. |---| unicode:: U+2014 .. em dash, trimming surrounding whitespace
:trim:
</pre>
<p>Now you can write dashes using pure ASCII: "<tt class="docutils literal">foo <span class="pre">|--|</span> bar; foo <span class="pre">|---|</span>
bar</tt>", rendered as "foo – bar; foo—bar". (Note that Mozilla
and Firefox may render this incorrectly.) The <tt class="docutils literal">:trim:</tt> option for
the em dash is necessary because you cannot write "<tt class="docutils literal"><span class="pre">foo|---|bar</span></tt>";
thus you need to add spaces ("<tt class="docutils literal">foo <span class="pre">|---|</span> bar</tt>") and advise the
reStructuredText parser to trim the spaces.</p>
</div>
<div class="section" id="how-can-i-generate-backticks-using-a-scandinavian-keyboard">
<h2><a class="toc-backref" href="#id35">2.8 How can I generate backticks using a Scandinavian keyboard?</a></h2>
<p>The use of backticks in reStructuredText is a bit awkward with
Scandinavian keyboards, where the backtick is a "dead" key. To get
one ` character one must press SHIFT-` + SPACE.</p>
<p>Unfortunately, with all the variations out there, there's no way to
please everyone. For Scandinavian programmers and technical writers,
this is not limited to reStructuredText but affects many languages and
environments.</p>
<p>Possible solutions include</p>
<ul>
<li><p class="first">If you have to input a lot of backticks, simply type one in the
normal/awkward way, select it, copy and then paste the rest (CTRL-V
is a lot faster than SHIFT-` + SPACE).</p>
</li>
<li><p class="first">Use keyboard macros.</p>
</li>
<li><p class="first">Remap the keyboard. The Scandinavian keyboard layout is awkward for
other programming/technical characters too; for example, []{}
etc. are a bit awkward compared to US keyboards.</p>
<p>According to Axel Kollmorgen,</p>
<blockquote>
<p>Under Windows, you can use the <a class="reference external" href="http://www.microsoft.com/globaldev/tools/msklc.mspx">Microsoft Keyboard Layout Creator</a> to easily
map the backtick key to a real backtick (no dead key). took me
five minutes to load my default (german) keyboard layout, untick
"Dead Key?" from the backtick key properties ("in all shift
states"), "build dll and setup package", install the generated
.msi, and add my custom keyboard layout via Control Panel >
Regional and Language Options > Languages > Details > Add
Keyboard layout (and setting it as default "when you start your
computer").</p>
</blockquote>
</li>
<li><p class="first">Use a virtual/screen keyboard or character palette, such as:</p>
<ul class="simple">
<li><a class="reference external" href="http://keyboard.lab.co.il/">Web-based keyboards</a> (IE only
unfortunately).</li>
<li>Windows: <a class="reference external" href="http://www.lakefolks.org/cnt/">Click-N-Type</a>.</li>
<li>Mac OS X: the Character Palette can store a set of favorite
characters for easy input. Open System Preferences,
International, Input Menu tab, enable "Show input menu in menu
bar", and be sure that Character Palette is enabled in the list.</li>
</ul>
</li>
</ul>
<p>If anyone knows of other/better solutions, please <a class="reference external" href="docs/user/mailing-lists.html#docutils-users">let us know</a>.</p>
</div>
<div class="section" id="are-there-any-tools-for-html-xml-to-restructuredtext-round-tripping">
<h2><a class="toc-backref" href="#id36">2.9 Are there any tools for HTML/XML-to-reStructuredText? (Round-tripping)</a></h2>
<p>People have tossed the idea around, and some implementations of
reStructuredText-generating tools can be found in the <a class="reference external" href="docs/user/links.html">Docutils Link
List</a>.</p>
<p>There's no reason why reStructuredText should not be round-trippable
to/from XML; any technicalities which prevent round-tripping would be
considered bugs. Whitespace would not be identical, but paragraphs
shouldn't suffer. The tricky parts would be the smaller details, like
links and IDs and other bookkeeping.</p>
<p>For HTML, true round-tripping may not be possible. Even adding lots
of extra "class" attributes may not be enough. A "simple HTML" to RST
filter is possible -- for some definition of "simple HTML" -- but HTML
is used as dumb formatting so much that such a filter may not be
particularly useful. An 80/20 approach should work though: build a
tool that does 80% of the work automatically, leaving the other 20%
for manual tweaks.</p>
</div>
<div class="section" id="are-there-any-wikis-that-use-restructuredtext-syntax">
<h2><a class="toc-backref" href="#id37">2.10 Are there any Wikis that use reStructuredText syntax?</a></h2>
<p>There are several, with various degrees of completeness. With no
implied endorsement or recommendation, and in no particular order:</p>
<ul class="simple">
<li><a class="reference external" href="http://wiki.webwareforpython.org/thiswiki.html">Webware for Python wiki</a></li>
<li><a class="reference external" href="http://docutils.sf.net/sandbox/ianb/wiki/Wiki.py">Ian Bicking's experimental code</a></li>
<li><a class="reference external" href="http://moinmoin.wikiwikiweb.de/">MoinMoin</a> has some support;
<a class="reference external" href="http://moinmoin.wikiwikiweb.de/RestSample">here's a sample</a></li>
<li>Zope-based <a class="reference external" href="http://zwiki.org/">Zwiki</a></li>
<li>Zope3-based Zwiki (in the Zope 3 source tree as
<tt class="docutils literal">zope.products.zwiki</tt>)</li>
<li><a class="reference external" href="http://mithrandr.moria.org/code/stikiwiki/">StikiWiki</a></li>
<li><a class="reference external" href="http://trac.edgewall.com//">Trac</a> <a class="reference external" href="http://trac.edgewall.com//wiki/WikiRestructuredText">supports using
reStructuredText</a> as
an alternative to wiki markup. This includes support for <a class="reference external" href="http://trac.edgewall.com//wiki/TracLinks">TracLinks</a> from within
RST text via a custom RST reference-directive or, even easier, an
interpreted text role 'trac'</li>
</ul>
<p>Please <a class="reference external" href="docs/user/mailing-lists.html#docutils-users">let us know</a> of any other reStructuredText Wikis.</p>
<p>The example application for the <a class="reference external" href="http://colorstudy.com/docs/shootout.html">Web Framework Shootout</a> article is a Wiki using
reStructuredText.</p>
</div>
<div class="section" id="are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax">
<h2><a class="toc-backref" href="#id38">2.11 Are there any Weblog (Blog) projects that use reStructuredText syntax?</a></h2>
<p>With no implied endorsement or recommendation, and in no particular
order:</p>
<ul class="simple">
<li><a class="reference external" href="http://www.voidspace.org.uk/python/firedrop2/">Firedrop</a></li>
<li><a class="reference external" href="http://pyblosxom.sourceforge.net/">PyBloxsom</a></li>
<li><a class="reference external" href="http://lino.sourceforge.net/webman.html">Lino WebMan</a></li>
<li><a class="reference external" href="http://blog.getpelican.com/">Pelican</a>
(also listed <a class="reference external" href="http://pypi.python.org/pypi/pelican">on PyPi</a>)</li>
</ul>
<p>Please <a class="reference external" href="docs/user/mailing-lists.html#docutils-users">let us know</a> of any other reStructuredText Blogs.</p>
</div>
<div class="section" id="how-should-i-mark-up-lists">
<span id="can-lists-be-indented-without-generating-block-quotes"></span><h2><a class="toc-backref" href="#id39">2.12 How should I mark up lists?</a></h2>
<p><a class="reference external" href="docs/ref/rst/restructuredtext.html#bullet-lists">Bullet</a> & <a class="reference external" href="docs/ref/rst/restructuredtext.html#enumerated-lists">enumerated</a> list markup is very intuitive but there are 2
points that must be noted:</p>
<ol class="arabic">
<li><p class="first">Lists should <strong>not</strong> be indented. This is correct:</p>
<pre class="literal-block">
paragraph
* list item 1
* nested item 1.1
* nested item 1.2
* list item 2
</pre>
<p>while this is probably incorrect:</p>
<pre class="literal-block">
paragraph
* list item 1
* nested item 1.1
* nested item 1.2
* list item 2
</pre>
<p>The extra indentation (of the list containing items 1.1 and 1.2) is
recognized as a block quote. This is usually not what you mean and
it causes the list in the output to be indented too much.</p>
</li>
<li><p class="first">There <strong>must</strong> be blank lines around list items, except between
items of the same level, where blank lines are optional. The
example above shows this.</p>
</li>
</ol>
<p>Note that formatting of the <em>output</em> is independent of the input, and
is decided by the writer and the stylesheet. For instance, lists
<em>are</em> indented in HTML output by default. See <a class="reference internal" href="#how-are-lists-formatted-in-html">How are lists
formatted in HTML?</a> for details.</p>
</div>
<div class="section" id="could-lists-be-indented-without-generating-block-quotes">
<h2><a class="toc-backref" href="#id40">2.13 Could lists be indented without generating block quotes?</a></h2>
<p>Some people like to write lists with indentation but don't intend a
blockquote context. There has been a lot of discussion about allowing
this in reStructuredText, but there are some issues that would need to
be resolved before it could be implemented. There is a summary of the
issues and pointers to the discussions in <a class="reference external" href="docs/dev/todo.html#indented-lists">the to-do list</a>.</p>
</div>
<div class="section" id="could-the-requirement-for-blank-lines-around-lists-be-relaxed">
<h2><a class="toc-backref" href="#id41">2.14 Could the requirement for blank lines around lists be relaxed?</a></h2>
<p>Short answer: no.</p>
<p>In reStructuredText, it would be impossible to unambigously mark up
and parse lists without blank lines before and after. Deeply nested
lists may look ugly with so many blank lines, but it's a price we pay
for unambiguous markup. Some other plaintext markup systems do not
require blank lines in nested lists, but they have to compromise
somehow, either accepting ambiguity or requiring extra complexity.
For example, <a class="reference external" href="http://epydoc.sf.net/epytext.html#list">Epytext</a> does
not require blank lines around lists, but it does require that lists
be indented and that ambiguous cases be escaped.</p>
</div>
<div class="section" id="how-can-i-include-mathematical-equations-in-documents">
<h2><a class="toc-backref" href="#id42">2.15 How can I include mathematical equations in documents?</a></h2>
<p>Use the <a class="reference external" href="docs/ref/rst/directives.html#math">math directive</a> and <a class="reference external" href="docs/ref/rst/roles.html#math">math role</a>, available since Docutils 0.8.</p>
</div>
<div class="section" id="is-nested-inline-markup-possible">
<h2><a class="toc-backref" href="#id43">2.16 Is nested inline markup possible?</a></h2>
<p>Not currently, no. It's on the <a class="reference external" href="docs/dev/todo.html#nested-inline-markup">to-do list</a> (<a class="reference external" href="docs/dev/rst/alternatives.html#nested-inline-markup">details here</a>), and
hopefully will be part of the reStructuredText parser soon. At that
time, markup like this will become possible:</p>
<pre class="literal-block">
Here is some *emphasized text containing a `hyperlink`_ and
``inline literals``*.
</pre>
<p>There are workarounds, but they are either convoluted or ugly or both.
They are not recommended.</p>
<ul>
<li><p class="first">Inline markup can be combined with hyperlinks using <a class="reference external" href="docs/ref/rst/restructuredtext.html#substitution-definitions">substitution
definitions</a> and <a class="reference external" href="docs/ref/rst/restructuredtext.html#substitution-references">references</a> with the <a class="reference external" href="docs/ref/rst/directives.html#replace">"replace" directive</a>.
For example:</p>
<pre class="literal-block">
Here is an |emphasized hyperlink|_.
.. |emphasized hyperlink| replace:: *emphasized hyperlink*
.. _emphasized hyperlink: http://example.org
</pre>
<p>It is not possible for just a portion of the replacement text to be
a hyperlink; it's the entire replacement text or nothing.</p>
</li>
<li><p class="first">The <a class="reference external" href="docs/ref/rst/directives.html#raw">"raw" directive</a> can be used to insert raw HTML into HTML
output:</p>
<pre class="literal-block">
Here is some |stuff|.
.. |stuff| raw:: html
<em>emphasized text containing a
<a href="http://example.org">hyperlink</a> and
<tt>inline literals</tt></em>
</pre>
<p>Raw LaTeX is supported for LaTeX output, etc.</p>
</li>
</ul>
</div>
<div class="section" id="how-to-indicate-a-line-break-or-a-significant-newline">
<h2><a class="toc-backref" href="#id44">2.17 How to indicate a line break or a significant newline?</a></h2>
<p><a class="reference external" href="docs/ref/rst/restructuredtext.html#line-blocks">Line blocks</a> are designed for address blocks, verse, and other
cases where line breaks are significant and must be preserved. Unlike
literal blocks, the typeface is not changed, and inline markup is
recognized. For example:</p>
<pre class="literal-block">
| A one, two, a one two three four
|
| Half a bee, philosophically,
| must, *ipso facto*, half not be.
| But half the bee has got to be,
| *vis a vis* its entity. D'you see?
|
| But can a bee be said to be
| or not to be an entire bee,
| when half the bee is not a bee,
| due to some ancient injury?
|
| Singing...
</pre>
<p>Here's a workaround for manually inserting explicit line breaks in
HTML output:</p>
<pre class="literal-block">
.. |br| raw:: html
<br />
I want to break this line here: |br| this is after the break.
If the extra whitespace bothers you, |br|\ backslash-escape it.
</pre>
</div>
<div class="section" id="a-url-containing-asterisks-doesn-t-work-what-to-do">
<h2><a class="toc-backref" href="#id45">2.18 A URL containing asterisks doesn't work. What to do?</a></h2>
<p>Asterisks are valid URL characters (see <a class="reference external" href="http://www.faqs.org/rfcs/rfc2396.html">RFC 2396</a>), sometimes used
in URLs. For example:</p>
<pre class="literal-block">
http://cvs.example.org/viewcvs.py/*checkout*/module/file
</pre>
<p>Unfortunately, the parser thinks the asterisks are indicating
emphasis. The slashes serve as delineating punctuation, allowing the
asterisks to be recognized as markup. The example above is separated
by the parser into a truncated URL, an emphasized word, and some
regular text:</p>
<pre class="literal-block">
http://cvs.example.org/viewcvs.py/
*checkout*
/module/file
</pre>
<p>To turn off markup recognition, use a backslash to escape at least the
first asterisk, like this:</p>
<pre class="literal-block">
http://cvs.example.org/viewcvs.py/\*checkout*/module/file
</pre>
<p>Escaping the second asterisk doesn't hurt, but it isn't necessary.</p>
</div>
<div class="section" id="how-can-i-make-a-literal-block-with-some-formatting">
<h2><a class="toc-backref" href="#id46">2.19 How can I make a literal block with <em>some</em> formatting?</a></h2>
<p>Use the <a class="reference external" href="docs/ref/rst/directives.html#parsed-literal">parsed-literal</a> directive.</p>
<p>Scenario: a document contains some source code, which calls for a
literal block to preserve linebreaks and whitespace. But part of the
source code should be formatted, for example as emphasis or as a
hyperlink. This calls for a <em>parsed</em> literal block:</p>
<pre class="literal-block">
.. parsed-literal::
print "Hello world!" # *tricky* code [1]_
</pre>
<p>The emphasis (<tt class="docutils literal">*tricky*</tt>) and footnote reference (<tt class="docutils literal">[1]_</tt>) will be
parsed.</p>
</div>
<div class="section" id="can-restructuredtext-be-used-for-web-or-generic-templating">
<h2><a class="toc-backref" href="#id47">2.20 Can reStructuredText be used for web or generic templating?</a></h2>
<p>Docutils and reStructuredText can be used with or as a component of a
templating system, but they do not themselves include templating
functionality. Templating should simply be left to dedicated
templating systems. Users can choose a templating system to apply to
their reStructuredText documents as best serves their interests.</p>
<p>There are many good templating systems for Python (<a class="reference external" href="http://ht2html.sourceforge.net/">ht2html</a>, <a class="reference external" href="http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52305">YAPTU</a>,
<a class="reference external" href="http://www.mems-exchange.org/software/quixote/">Quixote</a>'s PTL, <a class="reference external" href="http://www.cheetahtemplate.org/">Cheetah</a>, etc.; see this non-exhaustive list of <a class="reference external" href="http://webware.sourceforge.net/Papers/Templates/">some
other templating systems</a>), and many more for other languages, each
with different approaches. We invite you to try several and find one
you like. If you adapt it to use Docutils/reStructuredText, please
consider contributing the code to Docutils or <a class="reference external" href="docs/user/mailing-lists.html#docutils-users">let us know</a> and we'll
keep a list here.</p>
<p>One reST-specific web templating system is <a class="reference external" href="http://www.voidspace.org.uk/python/rest2web">rest2web</a>, a tool for
automatically building websites, or parts of websites.</p>
</div>
<div class="section" id="how-can-i-mark-up-a-faq-or-other-list-of-questions-answers">
<h2><a class="toc-backref" href="#id48">2.21 How can I mark up a FAQ or other list of questions & answers?</a></h2>
<p>There is no specific syntax for FAQs and Q&A lists. Here are two
options:</p>
<ol class="arabic">
<li><p class="first">For a FAQ (Frequently Asked Questions, usually with answers), a
convenient way to mark up the questions is as section titles, with
the answer(s) as section content. This document is marked up in
this way.</p>
<p>The advantages of using section titles for questions are: sections
can be numbered automatically, and a table of contents can be
generated automatically. One limitation of this format is that
questions must fit on one line (section titles may not wrap, in the
source text). For very long questions, the title may be a summary
of the question, with the full question in the section body.</p>
</li>
<li><p class="first">Field lists work well as Q&A lists:</p>
<pre class="literal-block">
:Q: What kind of questions can we
put here?
:A: Any kind we like!
</pre>
<p>In order to separate questions, lists can be used:</p>
<blockquote>
<ol class="arabic">
<li><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Q:</th><td class="field-body">What kind of question can we
put here?</td>
</tr>
<tr class="field"><th class="field-name">A:</th><td class="field-body">Any kind we like!</td>
</tr>
</tbody>
</table>
</li>
<li><table class="first docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Q:</th><td class="field-body"><p class="first">How many answers can a question have?</p>
</td>
</tr>
<tr class="field"><th class="field-name">A:</th><td class="field-body"><p class="first">It can have one,</p>
</td>
</tr>
<tr class="field"><th class="field-name">A:</th><td class="field-body"><p class="first">or more.</p>
</td>
</tr>
<tr class="field"><th class="field-name">A3:</th><td class="field-body"><p class="first">Answers can be numbered like this.</p>
</td>
</tr>
<tr class="field"><th class="field-name">A:</th><td class="field-body"><ol class="first last arabic simple">
<li>Or like this.</li>
<li>We're flexible!</li>
</ol>
</td>
</tr>
</tbody>
</table>
</li>
</ol>
</blockquote>
<p>If you don't want to number or otherwise mark questions, you can
use an empty comment between individual field lists to separate
them:</p>
<pre class="literal-block">
:Q: First question?
:A: Answer.
..
:Q: Second question?
:A: Answer.
</pre>
</li>
</ol>
</div>
<div class="section" id="can-i-produce-documents-in-right-to-left-languages">
<span id="bidi"></span><h2><a class="toc-backref" href="#id49">2.22 Can I produce documents in right-to-left languages?</a></h2>
<p>Languages written from right to left, such as Arabic and Hebrew, must
be reordered according to the <a class="reference external" href="http://www.unicode.org/reports/tr9/">Unicode Bidi Algorithm</a>. This
requires support from the editor and special markup in the output
format.</p>
<p>The source format of reStructuredText is relatively bidi-friendly:
most constructs are denoted by punctuation without intrusion of
English and when you must write in English, it's usually on a separate
line. So any editor that auto-detects direction per-line (like gedit
or <a class="reference external" href="http://www.typo.co.il/~mooffie/geresh/">geresh</a>) will suffice.</p>
<p>Moreover, it's possible to <a class="reference external" href="docs/howto/i18n.html">translate</a> all reStructuredText keywords.
This was not yet done for any RTL language, but when it is, it will be
possible to write an RTL document with vitually no English. This will
allow reasonable use of editors limited to a single base direction for
the whole document (like Notepad, Vim and text boxes in Firefox).</p>
<p>The second problem is bidi markup of the output. There is an almost
transparent implicit solution for HTML:</p>
<ul class="simple">
<li>Grab <a class="reference external" href="http://cben-hacks.sourceforge.net/bidi/hibidi.py">http://cben-hacks.sourceforge.net/bidi/hibidi.py</a> and
<a class="reference external" href="http://cben-hacks.sourceforge.net/bidi/rst2html_hibidi.py">http://cben-hacks.sourceforge.net/bidi/rst2html_hibidi.py</a>.
Put them both in the same directory and make them executable.</li>
<li>Use <tt class="docutils literal">rst2html_hibidi.py</tt> instead of <tt class="docutils literal">rst2html.py</tt>.</li>
<li>It infers dir attributes in the HTML from the text. It does it
hierachically, giving much better results than usual. You can still
use LRM/RLM and LRE/RLE/PDF control codes to help it.<ul>
<li>If you want the gory details: See the full <a class="reference external" href="http://cben-hacks.sf.net/bidi/hibidi.html">theory</a>, and note the
incomplete <a class="reference external" href="http://cben-hacks.sf.net/bidi/hibidi.html#practice">practice</a> (this is still a partial implementation - but
sufficient for most needs).</li>
</ul>
</li>
</ul>
<p>There is also an explicit way to set directions through CSS and
classes in the HTML:</p>
<ul>
<li><p class="first">Copy <tt class="docutils literal">default.css</tt> to a new file and add relevant parts of the
following:</p>
<pre class="literal-block">
/* Use these two if the main document direction is RTL */
body { direction: rtl; }
div.sidebar { float: left !important; }
/* The next 3 rules are very useful in documents containing pieces
of code in english */
/* Use this if you all your literal blocks (::) are LTR */
pre {direction: ltr; unicode-bidi: embed; }
/* Use this if you all your inline literals (``) are LTR */
tt {direction: ltr; unicode-bidi: embed; }
/* Use this if you all your interpretted text (`) is LTR */
cite {direction: ltr; unicode-bidi: embed; }
/* Allow manual direction override by class directive and roles */
.rtl { direction: rtl; }
.ltr { direction: ltr; }
</pre>
</li>
<li><p class="first">Select this new stylesheet with <tt class="docutils literal"><span class="pre">--stylesheet=<file></span></tt> or the
<a class="reference external" href="docs/user/config.html#stylesheet">stylesheet</a> setting.</p>
</li>
<li><p class="first">Now if you need to override the direction of some element (from a
paragraph to a whole section), write:</p>
<pre class="literal-block">
.. class:: rtl
</pre>
<p>or:</p>
<pre class="literal-block">
.. class:: ltr
</pre>
<p>before it (see the <a class="reference external" href="docs/ref/rst/directives.txt#class">class</a> directive for details).</p>
</li>
<li><p class="first">To change the direction of some inline text fragment, you can use
RLE/LRE/PDF control characters, or write <tt class="docutils literal"><span class="pre">:rtl:`RTL</span> text`</tt> /
<tt class="docutils literal"><span class="pre">:ltr:`RTL</span> text`</tt>. To use the latter syntax, you must write this
once at the beginning of your document:</p>
<pre class="literal-block">
.. role:: ltr
.. role:: rtl
</pre>
</li>
</ul>
<p>LaTeX is quite hard to implement (it doesn't support the bidi
algorithm, so all direction changes - even numbers in RTL text - must
be explicitly marked). Other formats are more-or-less easy.</p>
<p>If you have any questions/problems/bugs related to bidi with docutils,
ask <a class="reference external" href="mailto:cben@users.sf.net">Beni Cherniavsky</a> directly or the <a class="reference external" href="docs/user/mailing-lists.html#docutils-users">Docutils-users</a> mailing
list.</p>
</div>
<div class="section" id="what-s-the-official-mime-type-for-restructuredtext-data">
<h2><a class="toc-backref" href="#id50">2.23 What's the official MIME type for reStructuredText data?</a></h2>
<p>While there is no registered MIME type for reStructuredText, the
"official unofficial" standard MIME type is "text/x-rst". This was
invented for the build system for PEPs (Python Enhancement Proposals),
and it's used by the python.org web site build system.</p>
<p>(The "x-" prefix means it's an unregistered MIME type.)</p>
<p>Also see <a class="reference internal" href="#what-s-the-standard-filename-extension-for-a-restructuredtext-file">What's the standard filename extension for a
reStructuredText file?</a></p>
</div>
</div>
<div class="section" id="html-writer">
<h1><a class="toc-backref" href="#id51">3 HTML Writer</a></h1>
<div class="section" id="what-is-the-status-of-the-html-writer">
<h2><a class="toc-backref" href="#id52">3.1 What is the status of the HTML Writer?</a></h2>
<p>The HTML Writer module, <tt class="docutils literal">docutils/writers/html4css1.py</tt>, is a
proof-of-concept reference implementation. While it is a complete
implementation, some aspects of the HTML it produces may be incompatible
with older browsers or specialized applications (such as web templating).
The sandbox has some alternative HTML writers, contributions are welcome.</p>
</div>
<div class="section" id="what-kind-of-html-does-it-produce">
<h2><a class="toc-backref" href="#id53">3.2 What kind of HTML does it produce?</a></h2>
<p>It produces XHTML compatible with the <a class="reference external" href="http://www.w3.org/TR/xhtml1/">XHTML 1.0</a> specification. A
cascading stylesheet is required for proper viewing with a modern
graphical browser. Correct rendering of the HTML produced depends on
the CSS support of the browser. A general-purpose stylesheet,
<tt class="docutils literal">html4css1.css</tt> is provided with the code, and is embedded by
default. It is installed in the "writers/html4css1/" subdirectory
within the Docutils package. Use the <tt class="docutils literal"><span class="pre">--help</span></tt> command-line option
to see the specific location on your machine.</p>
</div>
<div class="section" id="what-browsers-are-supported">
<h2><a class="toc-backref" href="#id54">3.3 What browsers are supported?</a></h2>
<p>No specific browser is targeted; all modern graphical browsers should
work. Some older browsers, text-only browsers, and browsers without
full CSS support are known to produce inferior results. Firefox,
Safari, Mozilla (version 1.0 and up), Opera, and MS Internet Explorer
(version 5.0 and up) are known to give good results. Reports of
experiences with other browsers are welcome.</p>
</div>
<div class="section" id="unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why">
<h2><a class="toc-backref" href="#id55">3.4 Unexpected results from tools/rst2html.py: H1, H1 instead of H1, H2. Why?</a></h2>
<p>Here's the question in full:</p>
<blockquote>
<p>I have this text:</p>
<pre class="literal-block">
Heading 1
=========
All my life, I wanted to be H1.
Heading 1.1
-----------
But along came H1, and so shouldn't I be H2?
No! I'm H1!
Heading 1.1.1
*************
Yeah, imagine me, I'm stuck at H3! No?!?
</pre>
<p>When I run it through tools/rst2html.py, I get unexpected results
(below). I was expecting H1, H2, then H3; instead, I get H1, H1,
H2:</p>
<pre class="literal-block">
...
<html lang="en">
<head>
...
<title>Heading 1</title>
</head>
<body>
<div class="document" id="heading-1">
<h1 class="title">Heading 1</h1> <-- first H1
<p>All my life, I wanted to be H1.</p>
<div class="section" id="heading-1-1">
<h1><a name="heading-1-1">Heading 1.1</a></h1> <-- H1
<p>But along came H1, and so now I must be H2.</p>
<div class="section" id="heading-1-1-1">
<h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
<p>Yeah, imagine me, I'm stuck at H3!</p>
...
</pre>
<p>What gives?</p>
</blockquote>
<p>Check the "class" attribute on the H1 tags, and you will see a
difference. The first H1 is actually <tt class="docutils literal"><h1 <span class="pre">class="title"></span></tt>; this is
the document title, and the default stylesheet renders it centered.
There can also be an <tt class="docutils literal"><h2 <span class="pre">class="subtitle"></span></tt> for the document
subtitle.</p>
<p>If there's only one highest-level section title at the beginning of a
document, it is treated specially, as the document title. (Similarly, a
lone second-highest-level section title may become the document
subtitle.) See <a class="reference internal" href="#how-can-i-indicate-the-document-title-subtitle">How can I indicate the document title? Subtitle?</a> for
details. Rather than use a plain H1 for the document title, we use <tt class="docutils literal"><h1
<span class="pre">class="title"></span></tt> so that we can use H1 again within the document. Why
do we do this? HTML only has H1-H6, so by making H1 do double duty, we
effectively reserve these tags to provide 6 levels of heading beyond the
single document title.</p>
<p>HTML is being used for dumb formatting for nothing but final display.
A stylesheet <em>is required</em>, and one is provided; see <a class="reference internal" href="#what-kind-of-html-does-it-produce">What kind of
HTML does it produce?</a> above. Of course, you're welcome to roll your
own. The default stylesheet provides rules to format <tt class="docutils literal"><h1
<span class="pre">class="title"></span></tt> and <tt class="docutils literal"><h2 <span class="pre">class="subtitle"></span></tt> differently from
ordinary <tt class="docutils literal"><h1></tt> and <tt class="docutils literal"><h2></tt>:</p>
<pre class="literal-block">
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
</pre>
<p>If you don't want the top section heading to be interpreted as a
title at all, disable the <a class="reference external" href="docs/user/config.html#doctitle-xform">doctitle_xform</a> setting
(<tt class="docutils literal"><span class="pre">--no-doc-title</span></tt> option). This will interpret your document
differently from the standard settings, which might not be a good
idea. If you don't like the reuse of the H1 in the HTML output, you
can tweak the <a class="reference external" href="docs/user/config.html#initial-header-level">initial_header_level</a> setting
(<tt class="docutils literal"><span class="pre">--initial-header-level</span></tt> option) -- but unless you match its value
to your specific document, you might end up with bad HTML (e.g. H3
without H2).</p>
<p>(Thanks to Mark McEahern for the question and much of the answer.)</p>
</div>
<div class="section" id="how-are-lists-formatted-in-html">
<h2><a class="toc-backref" href="#id56">3.5 How are lists formatted in HTML?</a></h2>
<p>If list formatting looks strange, first check that you understand
<a class="reference internal" href="#how-should-i-mark-up-lists">list markup</a>.</p>
<ul>
<li><p class="first">By default, HTML browsers indent lists relative to their context.
This follows a long tradition in browsers (but isn't so established
in print). If you don't like it, you should change the stylesheet.</p>
<p>This is different from how lists look in reStructuredText source.
Extra indentation in the source indicates a blockquote, resulting in
too much indentation in the browser.</p>
</li>
<li><p class="first">A list item can contain multiple paragraphs etc. In complex cases
list items are separated by vertical space. By default this spacing
is omitted in "simple" lists. A list is simple if every item
contains a simple paragraph and/or a "simple" nested list. For
example:</p>
<blockquote>
<ul>
<li><p class="first">text</p>
<ul class="simple">
<li>simple<ul>
<li>simple</li>
<li>simple</li>
</ul>
</li>
<li>simple</li>
</ul>
<p>text after a nested list</p>
</li>
<li><p class="first">multiple</p>
<p>paragraphs</p>
</li>
</ul>
</blockquote>
<p>In this example the nested lists are simple (and should appear
compacted) but the outer list is not.</p>
<p>If you want all lists to have equal spacing, disable the
<a class="reference external" href="docs/user/config.html#compact-lists">compact_lists</a> setting (<tt class="docutils literal"><span class="pre">--no-compact-lists</span></tt> option). The
precise spacing can be controlled in the stylesheet.</p>
<p>Note again that this is not exactly WYSIWYG: it partially resembles
the rules about blank lines being optional between list items in
reStructuredText -- but adding/removing optional blank lines does
not affect spacing in the output! It's a feature, not a bug: you
write it as you like but the output is styled consistently.</p>
</li>
</ul>
</div>
<div class="section" id="why-do-enumerated-lists-only-use-numbers-no-letters-or-roman-numerals">
<h2><a class="toc-backref" href="#id57">3.6 Why do enumerated lists only use numbers (no letters or roman numerals)?</a></h2>
<p>The rendering of enumerators (the numbers or letters acting as list
markers) is completely governed by the stylesheet, so either the
browser can't find the stylesheet (try enabling the
<a class="reference external" href="docs/user/config.html#embed-stylesheet">embed_stylesheet</a> setting [<tt class="docutils literal"><span class="pre">--embed-stylesheet</span></tt> option]), or the
browser can't understand it (try a recent Firefox, Mozilla, Konqueror,
Opera, Safari, or even MSIE).</p>
</div>
<div class="section" id="there-appear-to-be-garbage-characters-in-the-html-what-s-up">
<h2><a class="toc-backref" href="#id58">3.7 There appear to be garbage characters in the HTML. What's up?</a></h2>
<p>What you're seeing is most probably not garbage, but the result of a
mismatch between the actual encoding of the HTML output and the
encoding your browser is expecting. Your browser is misinterpreting
the HTML data, which is encoded text. A discussion of text encodings
is beyond the scope of this FAQ; see one or more of these documents
for more info:</p>
<ul class="simple">
<li><a class="reference external" href="http://www.cl.cam.ac.uk/~mgk25/unicode.html">UTF-8 and Unicode FAQ for Unix/Linux</a></li>
<li>Chapters 3 and 4 of <a class="reference external" href="http://www.debian.org/doc/manuals/intro-i18n/">Introduction to i18n [Internationalization]</a></li>
<li><a class="reference external" href="http://www.reportlab.com/i18n/python_unicode_tutorial.html">Python Unicode Tutorial</a></li>
<li><a class="reference external" href="http://effbot.org/zone/unicode-objects.htm">Python Unicode Objects: Some Observations on Working With Non-ASCII
Character Sets</a></li>
</ul>
<p>The common case is with the default output encoding (UTF-8), when
either numbered sections are used (via the "<a class="reference external" href="docs/ref/rst/directives.html#sectnum">sectnum</a>" directive) or
symbol-footnotes. 3 non-breaking spaces are inserted in each numbered
section title, between the generated number and the title text. Most
footnote symbols are not available in ASCII, nor are non-breaking
spaces. When encoded with UTF-8 and viewed with ordinary ASCII tools,
these characters will appear to be multi-character garbage.</p>
<p>You may have an decoding problem in your browser (or editor, etc.).
The encoding of the output is set to "utf-8", but your browswer isn't
recognizing that. You can either try to fix your browser (enable
"UTF-8 character set", sometimes called "Unicode"), or choose a
different encoding for the HTML output. You can also try
<tt class="docutils literal"><span class="pre">--output-encoding=ascii:xmlcharrefreplace</span></tt> for HTML or XML, but not
applicable to non-XMLish outputs (if using runtime
settings/configuration files, use <tt class="docutils literal">output_encoding=ascii</tt> and
<tt class="docutils literal">output_encoding_error_handler=xmlcharrefreplace</tt>).</p>
<p>If you're generating document fragments, the "Content-Type" metadata
(between the HTML <tt class="docutils literal"><head></tt> and <tt class="docutils literal"></head></tt> tags) must agree with the
encoding of the rest of the document. For UTF-8, it should be:</p>
<pre class="literal-block">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</pre>
<p>Also, Docutils normally generates an XML declaration as the first line
of the output. It must also match the document encoding. For UTF-8:</p>
<pre class="literal-block">
<?xml version="1.0" encoding="utf-8" ?>
</pre>
</div>
<div class="section" id="how-can-i-retrieve-the-body-of-the-html-document">
<h2><a class="toc-backref" href="#id59">3.8 How can I retrieve the body of the HTML document?</a></h2>
<p>(This is usually needed when using Docutils in conjunction with a
templating system.)</p>
<p>You can use the <a class="reference external" href="docs/api/publisher.html#publish-parts">docutils.core.publish_parts()</a> function, which
returns a dictionary containing an '<a class="reference external" href="docs/api/publisher.html#html-body">html_body</a>' entry.</p>
</div>
<div class="section" id="why-is-the-docutils-xhtml-served-as-content-type-text-html">
<h2><a class="toc-backref" href="#id60">3.9 Why is the Docutils XHTML served as "Content-type: text/html"?</a></h2>
<p>Full question:</p>
<blockquote>
<p>Docutils' HTML output looks like XHTML and is advertised as such:</p>
<pre class="literal-block">
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xht ml1/DTD/xhtml1-transitional.dtd">
</pre>
<p>But this is followed by:</p>
<pre class="literal-block">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</pre>
<p>Shouldn't this be "application/xhtml+xml" instead of "text/html"?</p>
</blockquote>
<p>In a perfect web, the Docutils XHTML output would be 100% strict
XHTML. But it's not a perfect web, and a major source of imperfection
is Internet Explorer. Despite it's drawbacks, IE still represents the
majority of web browsers, and cannot be ignored.</p>
<p>Short answer: if we didn't serve XHTML as "text/html" (which is a
perfectly valid thing to do), it couldn't be viewed in Internet
Explorer.</p>
<p>Long answer: see the <a class="reference external" href="http://en.wikipedia.org/wiki/Criticisms_of_Internet_Explorer#XHTML">"Criticisms of Internet Explorer" Wikipedia
entry</a>.</p>
<p>However, there's also <a class="reference external" href="http://hixie.ch/advocacy/xhtml">Sending XHTML as text/html Considered
Harmful</a>. What to do, what to do? We're damned no matter what we
do. So we'll continue to do the practical instead of the pure:
support the browsers that are actually out there, and not fight for
strict standards compliance.</p>
<p>(Thanks to Martin F. Krafft, Robert Kern, Michael Foord, and Alan
G. Isaac.)</p>
</div>
</div>
<div class="section" id="python-source-reader">
<h1><a class="toc-backref" href="#id61">4 Python Source Reader</a></h1>
<div class="section" id="can-i-use-docutils-for-python-auto-documentation">
<h2><a class="toc-backref" href="#id62">4.1 Can I use Docutils for Python auto-documentation?</a></h2>
<p>Yes, in conjunction with other projects.</p>
<p>The <a class="reference external" href="http://sphinx.pocoo.org/index.html">Sphinx</a> documentation generator includes an autodoc module.</p>
<p>Version 2.0 of Ed Loper's <a class="reference external" href="http://epydoc.sourceforge.net/">Epydoc</a>
supports reStructuredText-format docstrings for HTML output. Docutils
0.3 or newer is required. Development of a Docutils-specific
auto-documentation tool will continue. Epydoc works by importing
Python modules to be documented, whereas the Docutils-specific tool,
described above, will parse modules without importing them (as with
<a class="reference external" href="http://happydoc.sourceforge.net/">HappyDoc</a>, which doesn't support
reStructuredText).</p>
<p>The advantages of parsing over importing are security and flexibility;
the disadvantage is complexity/difficulty.</p>
<ul class="simple">
<li>Security: untrusted code that shouldn't be executed can be parsed;
importing a module executes its top-level code.</li>
<li>Flexibility: comments and unofficial docstrings (those not supported
by Python syntax) can only be processed by parsing.</li>
<li>Complexity/difficulty: it's a lot harder to parse and analyze a
module than it is to <tt class="docutils literal">import</tt> and analyze one.</li>
</ul>
<p>For more details, please see "Docstring Extraction Rules" in <a class="reference external" href="http://www.python.org/peps/pep-0258.html">PEP
258</a>, item 3 ("How").</p>
</div>
</div>
<div class="section" id="miscellaneous">
<h1><a class="toc-backref" href="#id63">5 Miscellaneous</a></h1>
<div class="section" id="is-the-docutils-document-model-based-on-any-existing-xml-models">
<h2><a class="toc-backref" href="#id64">5.1 Is the Docutils document model based on any existing XML models?</a></h2>
<p>Not directly, no. It borrows bits from DocBook, HTML, and others. I
(David Goodger) have designed several document models over the years,
and have my own biases. The Docutils document model is designed for
simplicity and extensibility, and has been influenced by the needs of
the reStructuredText markup.</p>
<!-- Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: -->
<!-- Here's a code css to make a table colourful::
/* Table: */
th {
background-color: #ede;
}
/* alternating colors in table rows */
table.docutils tr:nth-child(even) {
background-color: #F3F3FF;
}
table.docutils tr:nth-child(odd) {
background-color: #FFFFEE;
}
table.docutils tr {
border-style: solid none solid none;
border-width: 1px 0 1px 0;
border-color: #AAAAAA;
} -->
</div>
</div>
</div>
</body>
</html>