|
From: <mi...@us...> - 2016-08-18 21:40:04
|
Revision: 7969
http://sourceforge.net/p/docutils/code/7969
Author: milde
Date: 2016-08-18 21:40:00 +0000 (Thu, 18 Aug 2016)
Log Message:
-----------
Rename html_plain writer to html5_polyglott.
Modified Paths:
--------------
trunk/docutils/docs/user/html.txt
trunk/docutils/docutils/writers/__init__.py
trunk/docutils/docutils/writers/html4css1/__init__.py
trunk/docutils/docutils/writers/html5_polyglot/__init__.py
trunk/docutils/setup.py
trunk/docutils/test/functional/input/data/math.css
trunk/docutils/test/functional/input/data/minimal.css
trunk/docutils/test/functional/input/data/plain.css
trunk/docutils/test/functional/tests/standalone_rst_html_plain.py
trunk/docutils/test/test_writers/test_html4css1_misc.py
Added Paths:
-----------
trunk/docutils/docutils/writers/html5_polyglot/
trunk/docutils/test/functional/expected/footnotes_html5_polyglot.html
trunk/docutils/test/functional/expected/standalone_rst_html5_polyglot.html
trunk/docutils/test/functional/input/standalone_rst_html5_polyglot.txt
trunk/docutils/test/functional/tests/footnotes_html5_polyglot.py
trunk/docutils/test/test_writers/test_html5_polyglot_misc.py
Removed Paths:
-------------
trunk/docutils/docutils/writers/html_plain/
trunk/docutils/test/functional/expected/footnotes_html_plain.html
trunk/docutils/test/functional/expected/standalone_rst_html_plain.html
trunk/docutils/test/functional/input/standalone_rst_html_plain.txt
trunk/docutils/test/functional/tests/footnotes_html_plain.py
trunk/docutils/test/test_writers/test_html_plain_misc.py
Modified: trunk/docutils/docs/user/html.txt
===================================================================
--- trunk/docutils/docs/user/html.txt 2016-08-18 21:21:58 UTC (rev 7968)
+++ trunk/docutils/docs/user/html.txt 2016-08-18 21:40:00 UTC (rev 7969)
@@ -12,17 +12,17 @@
* `Generic HTML writers`_
- =========== ============== ============== ================= ===========
- name alias(es) `front-end`_ HTML version CSS version
- =========== ============== ============== ================= ===========
- html4css1_ html4 rst2html4.py `XHTML 1 `CSS 1`_
+ =============== ========== ============== ================= ===========
+ name alias(es) `front-end`_ HTML version CSS version
+ =============== ========== ============== ================= ===========
+ html4css1_ html4 rst2html4.py `XHTML 1 `CSS 1`_
Transitional`_
- .. html_ rst2html.py `XHTML 1 `CSS 1`_
+ .. html_ rst2html.py `XHTML 1 `CSS 1`_
Transitional`_
- html_plain_ html5_ rst2html5.py `HTML5`_ `CSS 3`_
- =========== ============== ============== ================= ===========
+ html5_polyglot_ html5_ rst2html5.py `HTML5`_ `CSS 3`_
+ =============== ========== ============== ================= ===========
* `Special HTML writers`_
@@ -87,14 +87,14 @@
.. _html4css1.css: ../../docutils/writers/html4css1/html4css1.css
-html_plain
-~~~~~~~~~~
+html5_polyglot
+~~~~~~~~~~~~~~
:aliases: html5_
:front-end: rst2html5.py_
-:config: `[html-plain writer]`_
+:config: `[html-polyglot writer]`_
-The ``html_plain`` writer generates `polyglot HTML`_ output, valid XML that
+The ``html5_polyglot`` writer generates `polyglot HTML`_ output, valid XML that
is compatible with `HTML5`_.
New features and elements will only be used if they are widely supported to
make documents `viewable with any browser`_.
@@ -109,8 +109,8 @@
.. _rst2html5.py: tools.html#rst2html5-py
.. _[html-plain writer]: config.html#html-plain-writer
-.. _minimal.css: ../../docutils/writers/html_plain/minimal.css
-.. _plain.css: ../../docutils/writers/html_plain/plain.css
+.. _minimal.css: ../../docutils/writers/html5_polyglot/minimal.css
+.. _plain.css: ../../docutils/writers/html5_polyglot/plain.css
.. _custom style sheets: ../howto/html-stylesheets.html
.. _viewable with any browser: http://www.anybrowser.org/campaign
Modified: trunk/docutils/docutils/writers/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/__init__.py 2016-08-18 21:21:58 UTC (rev 7968)
+++ trunk/docutils/docutils/writers/__init__.py 2016-08-18 21:40:00 UTC (rev 7969)
@@ -122,15 +122,14 @@
_writer_aliases = {
'html': 'html4css1', # may change to html5 some day
'html4': 'html4css1',
- 'html5': 'html_plain', # may be replaced with a special HTML 5 writer
- 'html-plain': 'html_plain',
+ 'html5': 'html5_polyglot',
'latex': 'latex2e',
'pprint': 'pseudoxml',
'pformat': 'pseudoxml',
'pdf': 'rlpdf',
's5': 's5_html',
'xelatex': 'xetex',
- 'xhtml': 'html_plain',
+ 'xhtml': 'html5_polyglot',
'xhtml10': 'html4css1',
'xml': 'docutils_xml'}
Modified: trunk/docutils/docutils/writers/html4css1/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html4css1/__init__.py 2016-08-18 21:21:58 UTC (rev 7968)
+++ trunk/docutils/docutils/writers/html4css1/__init__.py 2016-08-18 21:40:00 UTC (rev 7969)
@@ -47,7 +47,7 @@
os.path.abspath(os.path.dirname(__file__)),
# for math.css
os.path.abspath(os.path.join(
- os.path.dirname(os.path.dirname(__file__)), 'html_plain'))
+ os.path.dirname(os.path.dirname(__file__)), 'html5_polyglot'))
]
default_template = 'template.txt'
Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html_plain/__init__.py 2016-08-18 21:21:58 UTC (rev 7968)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2016-08-18 21:40:00 UTC (rev 7969)
@@ -203,7 +203,7 @@
class HTMLTranslator(nodes.NodeVisitor):
"""
- This writer generates `polyglott markup`: HTML 5 that is also valid XML.
+ This writer generates `polyglot markup`: HTML 5 that is also valid XML.
"""
xml_declaration = '<?xml version="1.0" encoding="%s" ?>\n'
@@ -1255,7 +1255,7 @@
pass # never reached
# Meta tags: 'lang' attribute replaced by 'xml:lang' in XHTML 1.1
- # HTML5/polyglott recommends using both
+ # HTML5/polyglot recommends using both
def visit_meta(self, node):
if node.hasattr('lang'):
node['xml:lang'] = node['lang']
Modified: trunk/docutils/setup.py
===================================================================
--- trunk/docutils/setup.py 2016-08-18 21:21:58 UTC (rev 7968)
+++ trunk/docutils/setup.py 2016-08-18 21:40:00 UTC (rev 7969)
@@ -135,7 +135,7 @@
'docutils.utils.math',
'docutils.writers',
'docutils.writers.html4css1',
- 'docutils.writers.html_plain',
+ 'docutils.writers.html5_polyglot',
# 'docutils.writers.xhtml11', # moved to the sandbox
'docutils.writers.pep_html',
'docutils.writers.s5_html',
@@ -146,11 +146,11 @@
],
'data_files': ([('docutils/parsers/rst/include',
glob.glob('docutils/parsers/rst/include/*.txt')),
- ('docutils/writers/html_plain',
- ['docutils/writers/html_plain/minimal.css',
- 'docutils/writers/html_plain/plain.css',
- 'docutils/writers/html_plain/math.css',
- 'docutils/writers/html_plain/template.txt']),
+ ('docutils/writers/html5_polyglot',
+ ['docutils/writers/html5_polyglot/minimal.css',
+ 'docutils/writers/html5_polyglot/plain.css',
+ 'docutils/writers/html5_polyglot/math.css',
+ 'docutils/writers/html5_polyglot/template.txt']),
('docutils/writers/html4css1',
['docutils/writers/html4css1/html4css1.css',
'docutils/writers/html4css1/template.txt']),
Copied: trunk/docutils/test/functional/expected/footnotes_html5_polyglot.html (from rev 7968, trunk/docutils/test/functional/expected/footnotes_html_plain.html)
===================================================================
--- trunk/docutils/test/functional/expected/footnotes_html5_polyglot.html (rev 0)
+++ trunk/docutils/test/functional/expected/footnotes_html5_polyglot.html 2016-08-18 21:40:00 UTC (rev 7969)
@@ -0,0 +1,66 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="generator" content="Docutils 0.13: http://docutils.sourceforge.net/" />
+<title>Test footnote and citation rendering</title>
+<link rel="stylesheet" href="../input/data/minimal.css" type="text/css" />
+<link rel="stylesheet" href="../input/data/plain.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="test-footnote-and-citation-rendering">
+<h1 class="title">Test footnote and citation rendering</h1>
+
+<p>Paragraphs may contain footnote references (manually numbered<a class="footnote-reference superscript" href="#id7" id="id1">1</a>, anonymous auto-numbered<a class="footnote-reference superscript" href="#id11" id="id2">3</a>, labeled auto-numbered<a class="footnote-reference superscript" href="#label" id="id3">2</a>, or
+symbolic<a class="footnote-reference superscript" href="#id12" id="id4">*</a>) or citation references (<a class="citation-reference" href="#cit2002" id="id5">[CIT2002]</a>, <a class="citation-reference" href="#du2015" id="id6">[DU2015]</a>).</p>
+<dl class="footnote superscript">
+<dt class="label" id="id7"><span class="superscript">1</span><span class="fn-backref">(<a href="#id1">1</a>,<a href="#id8">2</a>)</span></dt>
+<dd><p>A footnote contains body elements, consistently indented by at
+least 3 spaces.</p>
+<p>This is the footnote's second paragraph.</p>
+</dd>
+<dt class="label" id="label"><span class="superscript">2</span><span class="fn-backref">(<a href="#id3">1</a>,<a href="#id9">2</a>)</span></dt>
+<dd><p>Footnotes may be numbered, either manually (as in<a class="footnote-reference superscript" href="#id7" id="id8">1</a>) or
+automatically using a "#"-prefixed label. This footnote has a
+label so it can be referred to from multiple places, both as a
+footnote reference (<a class="footnote-reference superscript" href="#label" id="id9">2</a>) and as a <a class="reference internal" href="#label">hyperlink reference</a>.</p>
+</dd>
+<dt class="label" id="id11"><span class="superscript"><a class="fn-backref" href="#id2">3</a></span></dt>
+<dd><p>This footnote is numbered automatically and anonymously using a
+label of "#" only.</p>
+<p>This is the second paragraph.</p>
+<p>And this is the third paragraph.</p>
+</dd>
+<dt class="label" id="id12"><span class="superscript"><a class="fn-backref" href="#id4">*</a></span></dt>
+<dd><p>Footnotes may also use symbols, specified with a "*" label.
+Here's a reference to the next footnote:<a class="footnote-reference superscript" href="#id14" id="id13">†</a>.</p>
+</dd>
+<dt class="label" id="id14"><span class="superscript"><a class="fn-backref" href="#id13">†</a></span></dt>
+<dd><p>This footnote shows the next symbol in the sequence.</p>
+</dd>
+<dt class="label" id="id15"><span class="superscript">4</span></dt>
+<dd><p>Here's an unreferenced footnote, with a reference to a
+nonexistent footnote:<a class="footnote-reference superscript" href="#id18" id="id16">5</a>.</p>
+</dd>
+</dl>
+<div class="section" id="citations">
+<h1>Citations</h1>
+<dl class="citation">
+<dt class="label" id="cit2002"><span class="brackets">CIT2002</span><span class="fn-backref">(<a href="#id5">1</a>,<a href="#id17">2</a>)</span></dt>
+<dd><p>Citations are text-labeled footnotes. They may be
+rendered separately and differently from footnotes.</p>
+</dd>
+<dt class="label" id="du2015"><span class="brackets"><a class="fn-backref" href="#id6">DU2015</a></span></dt>
+<dd><p><cite>Example document</cite>, Hometown: 2015.</p>
+</dd>
+</dl>
+<p>Here's a reference to the above, <a class="citation-reference" href="#cit2002" id="id17">[CIT2002]</a>.</p>
+<dl class="footnote superscript">
+<dt class="label" id="id18"><span class="superscript"><a class="fn-backref" href="#id16">5</a></span></dt>
+<dd><p>this footnote is missing in the standard example document.</p>
+</dd>
+</dl>
+</div>
+</div>
+</body>
+</html>
Deleted: trunk/docutils/test/functional/expected/footnotes_html_plain.html
===================================================================
--- trunk/docutils/test/functional/expected/footnotes_html_plain.html 2016-08-18 21:21:58 UTC (rev 7968)
+++ trunk/docutils/test/functional/expected/footnotes_html_plain.html 2016-08-18 21:40:00 UTC (rev 7969)
@@ -1,66 +0,0 @@
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-<meta charset="utf-8"/>
-<meta name="generator" content="Docutils 0.13: http://docutils.sourceforge.net/" />
-<title>Test footnote and citation rendering</title>
-<link rel="stylesheet" href="../input/data/minimal.css" type="text/css" />
-<link rel="stylesheet" href="../input/data/plain.css" type="text/css" />
-</head>
-<body>
-<div class="document" id="test-footnote-and-citation-rendering">
-<h1 class="title">Test footnote and citation rendering</h1>
-
-<p>Paragraphs may contain footnote references (manually numbered<a class="footnote-reference superscript" href="#id7" id="id1">1</a>, anonymous auto-numbered<a class="footnote-reference superscript" href="#id11" id="id2">3</a>, labeled auto-numbered<a class="footnote-reference superscript" href="#label" id="id3">2</a>, or
-symbolic<a class="footnote-reference superscript" href="#id12" id="id4">*</a>) or citation references (<a class="citation-reference" href="#cit2002" id="id5">[CIT2002]</a>, <a class="citation-reference" href="#du2015" id="id6">[DU2015]</a>).</p>
-<dl class="footnote superscript">
-<dt class="label" id="id7"><span class="superscript">1</span><span class="fn-backref">(<a href="#id1">1</a>,<a href="#id8">2</a>)</span></dt>
-<dd><p>A footnote contains body elements, consistently indented by at
-least 3 spaces.</p>
-<p>This is the footnote's second paragraph.</p>
-</dd>
-<dt class="label" id="label"><span class="superscript">2</span><span class="fn-backref">(<a href="#id3">1</a>,<a href="#id9">2</a>)</span></dt>
-<dd><p>Footnotes may be numbered, either manually (as in<a class="footnote-reference superscript" href="#id7" id="id8">1</a>) or
-automatically using a "#"-prefixed label. This footnote has a
-label so it can be referred to from multiple places, both as a
-footnote reference (<a class="footnote-reference superscript" href="#label" id="id9">2</a>) and as a <a class="reference internal" href="#label">hyperlink reference</a>.</p>
-</dd>
-<dt class="label" id="id11"><span class="superscript"><a class="fn-backref" href="#id2">3</a></span></dt>
-<dd><p>This footnote is numbered automatically and anonymously using a
-label of "#" only.</p>
-<p>This is the second paragraph.</p>
-<p>And this is the third paragraph.</p>
-</dd>
-<dt class="label" id="id12"><span class="superscript"><a class="fn-backref" href="#id4">*</a></span></dt>
-<dd><p>Footnotes may also use symbols, specified with a "*" label.
-Here's a reference to the next footnote:<a class="footnote-reference superscript" href="#id14" id="id13">†</a>.</p>
-</dd>
-<dt class="label" id="id14"><span class="superscript"><a class="fn-backref" href="#id13">†</a></span></dt>
-<dd><p>This footnote shows the next symbol in the sequence.</p>
-</dd>
-<dt class="label" id="id15"><span class="superscript">4</span></dt>
-<dd><p>Here's an unreferenced footnote, with a reference to a
-nonexistent footnote:<a class="footnote-reference superscript" href="#id18" id="id16">5</a>.</p>
-</dd>
-</dl>
-<div class="section" id="citations">
-<h1>Citations</h1>
-<dl class="citation">
-<dt class="label" id="cit2002"><span class="brackets">CIT2002</span><span class="fn-backref">(<a href="#id5">1</a>,<a href="#id17">2</a>)</span></dt>
-<dd><p>Citations are text-labeled footnotes. They may be
-rendered separately and differently from footnotes.</p>
-</dd>
-<dt class="label" id="du2015"><span class="brackets"><a class="fn-backref" href="#id6">DU2015</a></span></dt>
-<dd><p><cite>Example document</cite>, Hometown: 2015.</p>
-</dd>
-</dl>
-<p>Here's a reference to the above, <a class="citation-reference" href="#cit2002" id="id17">[CIT2002]</a>.</p>
-<dl class="footnote superscript">
-<dt class="label" id="id18"><span class="superscript"><a class="fn-backref" href="#id16">5</a></span></dt>
-<dd><p>this footnote is missing in the standard example document.</p>
-</dd>
-</dl>
-</div>
-</div>
-</body>
-</html>
Copied: trunk/docutils/test/functional/expected/standalone_rst_html5_polyglot.html (from rev 7968, trunk/docutils/test/functional/expected/standalone_rst_html_plain.html)
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_html5_polyglot.html (rev 0)
+++ trunk/docutils/test/functional/expected/standalone_rst_html5_polyglot.html 2016-08-18 21:40:00 UTC (rev 7969)
@@ -0,0 +1,1524 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="generator" content="Docutils 0.13: http://docutils.sourceforge.net/" />
+<title>reStructuredText Test Document</title>
+<meta name="author" content="David Goodger" />
+<meta content="reStructuredText, test, parser" name="keywords" />
+<meta content="A test document, containing at least one example of each reStructuredText construct." lang="en" name="description" xml:lang="en" />
+<link rel="stylesheet" href="../input/data/minimal.css" type="text/css" />
+<link rel="stylesheet" href="../input/data/plain.css" type="text/css" />
+<link rel="stylesheet" href="../input/data/math.css" type="text/css" />
+</head>
+<body>
+<div class="header">
+<p>Document header</p>
+
+<hr class="header"/>
+</div>
+<div class="document" id="restructuredtext-test-document">
+<span id="doctitle"></span>
+<h1 class="title">reStructuredText Test Document</h1>
+
+<p class="subtitle" id="examples-of-syntax-constructs"><span id="subtitle"></span>Examples of Syntax Constructs</p>
+<dl class="docinfo">
+<dt class="author">Author</dt>
+<dd class="author"><p>David Goodger</p></dd>
+<dt class="address">Address</dt>
+<dd class="address"><pre class="address">123 Example Street
+Example, EX Canada
+A1B 2C3
+</pre>
+</dd>
+<dt class="contact">Contact</dt>
+<dd class="contact"><a class="reference external" href="mailto:goodger@python.org">goodger@python.org</a></dd>
+<dt class="authors">Authors</dt>
+<dd class="authors"><p>Me</p>
+<p>Myself</p>
+<p>I</p>
+</dd>
+<dt class="organization">Organization</dt>
+<dd class="organization">humankind</dd>
+<dt class="date">Date</dt>
+<dd class="date">Now, or yesterday. Or maybe even <em>before</em> yesterday.</dd>
+<dt class="status">Status</dt>
+<dd class="status">This is a "work in progress"</dd>
+<dt class="revision">Revision</dt>
+<dd class="revision">is managed by a version control system.</dd>
+<dt class="version">Version</dt>
+<dd class="version">1</dd>
+<dt class="copyright">Copyright</dt>
+<dd class="copyright">This document has been placed in the public domain. You
+may do with it as you wish. You may copy, modify,
+redistribute, reattribute, sell, buy, rent, lease,
+destroy, or improve it, quote it at length, excerpt,
+incorporate, collate, fold, staple, or mutilate it, or do
+anything else to it that your or anyone else's heart
+desires.</dd>
+<dt class="field-name">field name</dt>
+<dd class="field-name"><p>This is a "generic bibliographic field".</p>
+</dd>
+<dt class="field-name-2">field name "2"</dt>
+<dd class="field-name-2"><p>Generic bibliographic fields may contain multiple body elements.</p>
+<p>Like this.</p>
+</dd>
+</dl>
+<div class="dedication topic">
+<p class="topic-title first">Dedication</p>
+<p>For Docutils users & co-developers.</p>
+</div>
+<div class="abstract topic">
+<p class="topic-title first">Abstract</p>
+<p>This is a test document, containing at least one example of each
+reStructuredText construct.</p>
+</div>
+<!-- This is a comment. Note how any initial comments are moved by
+transforms to after the document title, subtitle, and docinfo. -->
+<!-- Above is the document title, and below is the subtitle.
+They are transformed from section titles after parsing. -->
+<!-- bibliographic fields (which also require a transform): -->
+<div class="contents topic" id="table-of-contents">
+<p class="topic-title first">Table of Contents</p>
+<ul class="auto-toc simple">
+<li><p><a class="reference internal" href="#structural-elements" id="id38"><span class="sectnum">1</span> Structural Elements</a></p>
+<ul class="auto-toc">
+<li><p><a class="reference internal" href="#section-title" id="id39"><span class="sectnum">1.1</span> Section Title</a></p></li>
+<li><p><a class="reference internal" href="#empty-section" id="id40"><span class="sectnum">1.2</span> Empty Section</a></p></li>
+<li><p><a class="reference internal" href="#transitions" id="id41"><span class="sectnum">1.3</span> Transitions</a></p></li>
+</ul>
+</li>
+<li><p><a class="reference internal" href="#body-elements" id="id42"><span class="sectnum">2</span> Body Elements</a></p>
+<ul class="auto-toc">
+<li><p><a class="reference internal" href="#paragraphs" id="id43"><span class="sectnum">2.1</span> Paragraphs</a></p>
+<ul class="auto-toc">
+<li><p><a class="reference internal" href="#inline-markup" id="id44"><span class="sectnum">2.1.1</span> Inline Markup</a></p></li>
+</ul>
+</li>
+<li><p><a class="reference internal" href="#bullet-lists" id="id45"><span class="sectnum">2.2</span> Bullet Lists</a></p></li>
+<li><p><a class="reference internal" href="#enumerated-lists" id="id46"><span class="sectnum">2.3</span> Enumerated Lists</a></p></li>
+<li><p><a class="reference internal" href="#definition-lists" id="id47"><span class="sectnum">2.4</span> Definition Lists</a></p></li>
+<li><p><a class="reference internal" href="#field-lists" id="id48"><span class="sectnum">2.5</span> Field Lists</a></p></li>
+<li><p><a class="reference internal" href="#option-lists" id="id49"><span class="sectnum">2.6</span> Option Lists</a></p></li>
+<li><p><a class="reference internal" href="#literal-blocks" id="id50"><span class="sectnum">2.7</span> Literal Blocks</a></p></li>
+<li><p><a class="reference internal" href="#line-blocks" id="id51"><span class="sectnum">2.8</span> Line Blocks</a></p></li>
+<li><p><a class="reference internal" href="#block-quotes" id="id52"><span class="sectnum">2.9</span> Block Quotes</a></p></li>
+<li><p><a class="reference internal" href="#doctest-blocks" id="id53"><span class="sectnum">2.10</span> Doctest Blocks</a></p></li>
+<li><p><a class="reference internal" href="#footnotes" id="id54"><span class="sectnum">2.11</span> Footnotes</a></p></li>
+<li><p><a class="reference internal" href="#citations" id="id55"><span class="sectnum">2.12</span> Citations</a></p></li>
+<li><p><a class="reference internal" href="#targets" id="id56"><span class="sectnum">2.13</span> Targets</a></p>
+<ul class="auto-toc">
+<li><p><a class="reference internal" href="#duplicate-target-names" id="id57"><span class="sectnum">2.13.1</span> Duplicate Target Names</a></p></li>
+<li><p><a class="reference internal" href="#id21" id="id58"><span class="sectnum">2.13.2</span> Duplicate Target Names</a></p></li>
+</ul>
+</li>
+<li><p><a class="reference internal" href="#directives" id="id59"><span class="sectnum">2.14</span> Directives</a></p>
+<ul class="auto-toc">
+<li><p><a class="reference internal" href="#document-parts" id="id60"><span class="sectnum">2.14.1</span> Document Parts</a></p></li>
+<li><p><a class="reference internal" href="#images-and-figures" id="id61"><span class="sectnum">2.14.2</span> Images and Figures</a></p></li>
+<li><p><a class="reference internal" href="#admonitions" id="id62"><span class="sectnum">2.14.3</span> Admonitions</a></p></li>
+<li><p><a class="reference internal" href="#topics-sidebars-and-rubrics" id="id63"><span class="sectnum">2.14.4</span> Topics, Sidebars, and Rubrics</a></p></li>
+<li><p><a class="reference internal" href="#target-footnotes" id="id64"><span class="sectnum">2.14.5</span> Target Footnotes</a></p></li>
+<li><p><a class="reference internal" href="#replacement-text" id="id65"><span class="sectnum">2.14.6</span> Replacement Text</a></p></li>
+<li><p><a class="reference internal" href="#compound-paragraph" id="id66"><span class="sectnum">2.14.7</span> Compound Paragraph</a></p></li>
+<li><p><a class="reference internal" href="#parsed-literal-blocks" id="id67"><span class="sectnum">2.14.8</span> Parsed Literal Blocks</a></p></li>
+<li><p><a class="reference internal" href="#code" id="id68"><span class="sectnum">2.14.9</span> Code</a></p></li>
+</ul>
+</li>
+<li><p><a class="reference internal" href="#substitution-definitions" id="id69"><span class="sectnum">2.15</span> Substitution Definitions</a></p></li>
+<li><p><a class="reference internal" href="#comments" id="id70"><span class="sectnum">2.16</span> Comments</a></p></li>
+<li><p><a class="reference internal" href="#raw-text" id="id71"><span class="sectnum">2.17</span> Raw text</a></p></li>
+<li><p><a class="reference internal" href="#container" id="id72"><span class="sectnum">2.18</span> Container</a></p></li>
+<li><p><a class="reference internal" href="#colspanning-tables" id="id73"><span class="sectnum">2.19</span> Colspanning tables</a></p></li>
+<li><p><a class="reference internal" href="#rowspanning-tables" id="id74"><span class="sectnum">2.20</span> Rowspanning tables</a></p></li>
+<li><p><a class="reference internal" href="#complex-tables" id="id75"><span class="sectnum">2.21</span> Complex tables</a></p></li>
+<li><p><a class="reference internal" href="#list-tables" id="id76"><span class="sectnum">2.22</span> List Tables</a></p></li>
+<li><p><a class="reference internal" href="#custom-roles" id="id77"><span class="sectnum">2.23</span> Custom Roles</a></p></li>
+<li><p><a class="reference internal" href="#svg-images" id="id78"><span class="sectnum">2.24</span> SVG Images</a></p></li>
+<li><p><a class="reference internal" href="#swf-images" id="id79"><span class="sectnum">2.25</span> SWF Images</a></p></li>
+</ul>
+</li>
+<li><p><a class="reference internal" href="#changes-to-the-html4css1-writer" id="id80"><span class="sectnum">3</span> Changes to the html4css1 writer</a></p>
+<ul class="auto-toc">
+<li><p><a class="reference internal" href="#field-list-handling" id="id81"><span class="sectnum">3.1</span> Field list handling</a></p></li>
+<li><p><a class="reference internal" href="#styling-with-class-arguments" id="id82"><span class="sectnum">3.2</span> Styling with class arguments</a></p>
+<ul class="auto-toc">
+<li><p><a class="reference internal" href="#description-lists" id="id83"><span class="sectnum">3.2.1</span> Description lists</a></p></li>
+<li><p><a class="reference internal" href="#field-list-variants" id="id84"><span class="sectnum">3.2.2</span> Field list variants</a></p></li>
+<li><p><a class="reference internal" href="#table-variants" id="id85"><span class="sectnum">3.2.3</span> Table variants</a></p></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><p><a class="reference internal" href="#error-handling" id="id86"><span class="sectnum">4</span> Error Handling</a></p></li>
+</ul>
+</div>
+<div class="section" id="structural-elements">
+<h1><a class="toc-backref" href="#id38"><span class="sectnum">1</span> Structural Elements</a></h1>
+<div class="section" id="section-title">
+<h2 class="with-subtitle"><a class="toc-backref" href="#id39"><span class="sectnum">1.1</span> Section Title</a></h2>
+<p class="section-subtitle" id="section-subtitle">Section Subtitle</p>
+<p>Lone subsections are converted to a section subtitle by a transform
+activated with the <span class="docutils literal"><span class="pre">--section-subtitles</span></span> command line option or the
+<span class="docutils literal"><span class="pre">sectsubtitle-xform</span></span> configuration value.</p>
+</div>
+<div class="section" id="empty-section">
+<h2><a class="toc-backref" href="#id40"><span class="sectnum">1.2</span> Empty Section</a></h2>
+</div>
+<div class="section" id="transitions">
+<h2><a class="toc-backref" href="#id41"><span class="sectnum">1.3</span> Transitions</a></h2>
+<p>Here's a transition:</p>
+<hr class="docutils" />
+<p>It divides the section. Transitions may also occur between sections:</p>
+</div>
+</div>
+<hr class="docutils" />
+<div class="section" id="body-elements">
+<h1><a class="toc-backref" href="#id42"><span class="sectnum">2</span> Body Elements</a></h1>
+<div class="section" id="paragraphs">
+<h2><a class="toc-backref" href="#id43"><span class="sectnum">2.1</span> Paragraphs</a></h2>
+<p>A paragraph.</p>
+<div class="section" id="inline-markup">
+<h3><a class="toc-backref" href="#id44"><span class="sectnum">2.1.1</span> Inline Markup</a></h3>
+<p>Paragraphs contain text and may contain inline markup: <em>emphasis</em>,
+<strong>strong emphasis</strong>, <span class="docutils literal">inline literals</span>, standalone hyperlinks
+(<a class="reference external" href="http://www.python.org">http://www.python.org</a>), external hyperlinks (<a class="reference external" href="http://www.python.org/">Python</a> <a class="footnote-reference brackets" href="#id25" id="id26">5</a>), internal
+cross-references (<a class="reference internal" href="#example">example</a>), external hyperlinks with embedded URIs
+(<a class="reference external" href="http://www.python.org">Python web site</a>), <a class="reference external" href="http://www.python.org/">anonymous hyperlink
+references</a> <a class="footnote-reference brackets" href="#id25" id="id35">5</a> (<a class="reference external" href="http://docutils.sourceforge.net/">a second reference</a> <a class="footnote-reference brackets" href="#id36" id="id37">9</a>), footnote references (manually
+numbered <a class="footnote-reference brackets" href="#id8" id="id1">1</a>, anonymous auto-numbered <a class="footnote-reference brackets" href="#id12" id="id2">3</a>, labeled auto-numbered
+<a class="footnote-reference brackets" href="#label" id="id3">2</a>, or symbolic <a class="footnote-reference brackets" href="#id13" id="id4">*</a>), citation references (<a class="citation-reference" href="#cit2002" id="id5">[CIT2002]</a>),
+substitution references (<img alt="EXAMPLE" src="../../../docs/user/rst/images/biohazard.png" />), and <span class="target" id="inline-hyperlink-targets">inline hyperlink targets</span>
+(see <a class="reference internal" href="#targets">Targets</a> below for a reference back to here). Character-level
+inline markup is also possible (although exceedingly ugly!) in <em>re</em><span class="docutils literal">Structured</span><em>Text</em>. Problems are indicated by <a href="#id23"><span class="problematic" id="id24">|problematic|</span></a> text
+(generated by processing errors; this one is intentional). Here is a
+reference to the <a class="reference internal" href="#doctitle">doctitle</a> and the <a class="reference internal" href="#subtitle">subtitle</a>.</p>
+<p>The default role for interpreted text is <cite>Title Reference</cite>. Here are
+some explicit interpreted text roles: a PEP reference (<a class="reference external" href="http://www.python.org/dev/peps/pep-0287">PEP 287</a>); an
+RFC reference (<a class="reference external" href="http://tools.ietf.org/html/rfc2822.html">RFC 2822</a>); an abbreviation (<abbr>abb.</abbr>), an acronym
+(<abbr>reST</abbr>), code (<code>print "hello world"</code>); a <sub>subscript</sub>;
+a <sup>superscript</sup> and explicit roles for <cite>Docutils</cite>'
+<em>standard</em> <strong>inline</strong> <span class="docutils literal">markup</span>.</p>
+<!-- DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! -->
+<p>Let's test wrapping and whitespace significance in inline literals:
+<span class="docutils literal">This is an example of <span class="pre">--inline-literal</span> <span class="pre">--text,</span> <span class="pre">--including</span> <span class="pre">some--</span> <span class="pre">strangely--hyphenated-words.</span> <span class="pre">Adjust-the-width-of-your-browser-window</span> to see how the text is wrapped. <span class="pre">--</span> <span class="pre">----</span> <span class="pre">--------</span> Now note the spacing between the words of this sentence (words should be grouped in pairs).</span></p>
+<p>If the <span class="docutils literal"><span class="pre">--pep-references</span></span> option was supplied, there should be a
+live link to PEP 258 here.</p>
+</div>
+</div>
+<div class="section" id="bullet-lists">
+<h2><a class="toc-backref" href="#id45"><span class="sectnum">2.2</span> Bullet Lists</a></h2>
+<ul>
+<li><p>A bullet list</p>
+<ul class="simple">
+<li><p>Nested bullet list.</p></li>
+<li><p>Nested item 2.</p></li>
+</ul>
+</li>
+<li><p>Item 2.</p>
+<p>Paragraph 2 of item 2.</p>
+<ul class="simple">
+<li><p>Nested bullet list.</p></li>
+<li><p>Nested item 2.</p>
+<ul>
+<li><p>Third level.</p></li>
+<li><p>Item 2.</p></li>
+</ul>
+</li>
+<li><p>Nested item 3.</p></li>
+<li><p>This nested list should be compacted by the HTML writer.</p>
+<span class="target" id="target"></span><!-- Even if this item contains a target and a comment. -->
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="enumerated-lists">
+<h2><a class="toc-backref" href="#id46"><span class="sectnum">2.3</span> Enumerated Lists</a></h2>
+<ol class="arabic">
+<li><p>Arabic numerals.</p>
+<ol class="loweralpha simple">
+<li><p>lower alpha)</p>
+<ol class="lowerroman simple">
+<li><p>(lower roman)</p>
+<ol class="upperalpha simple">
+<li><p>upper alpha.</p>
+<ol class="upperroman simple">
+<li><p>upper roman)</p></li>
+</ol>
+</li>
+</ol>
+</li>
+</ol>
+</li>
+</ol>
+</li>
+<li><p>Lists that don't start at 1:</p>
+<ol class="arabic simple" start="3">
+<li><p>Three</p></li>
+<li><p>Four</p></li>
+</ol>
+<ol class="upperalpha simple" start="3">
+<li><p>C</p></li>
+<li><p>D</p></li>
+</ol>
+<ol class="lowerroman simple" start="3">
+<li><p>iii</p></li>
+<li><p>iv</p></li>
+</ol>
+</li>
+</ol>
+</div>
+<div class="section" id="definition-lists">
+<h2><a class="toc-backref" href="#id47"><span class="sectnum">2.4</span> Definition Lists</a></h2>
+<dl>
+<dt>Term</dt>
+<dd><p>Definition</p>
+</dd>
+<dt>Term<span class="classifier">classifier</span></dt>
+<dd><p>Definition paragraph 1.</p>
+<p>Definition paragraph 2.</p>
+</dd>
+<dt>Term</dt>
+<dd><p>Definition</p>
+</dd>
+<dt>Term<span class="classifier">classifier one</span><span class="classifier">classifier two</span></dt>
+<dd><p>Definition</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="field-lists">
+<h2><a class="toc-backref" href="#id48"><span class="sectnum">2.5</span> Field Lists</a></h2>
+<dl class="field-list">
+<dt>what</dt>
+<dd><p>Field lists map field names to field bodies, like database
+records. They are often part of an extension syntax. They are
+an unambiguous variant of RFC 2822 fields.</p>
+</dd>
+<dt>how arg1 arg2</dt>
+<dd><p>The field marker is a colon, the field name, and a colon.</p>
+<p>The field body may contain one or more body elements, indented
+relative to the field marker.</p>
+</dd>
+<dt>credits</dt>
+<dd><p class="credits">This paragraph has the <cite>credits</cite> class set. (This is actually not
+about credits but just for ensuring that the class attribute
+doesn't get stripped away.)</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="option-lists">
+<h2><a class="toc-backref" href="#id49"><span class="sectnum">2.6</span> Option Lists</a></h2>
+<p>For listing command-line options:</p>
+<dl class="option-list">
+<dt><kbd><span class="option">-a</span></kbd></dt>
+<dd><p>command-line option "a"</p>
+</dd>
+<dt><kbd><span class="option">-b <var>file</var></span></kbd></dt>
+<dd><p>options can have arguments
+and long descriptions</p>
+</dd>
+<dt><kbd><span class="option">--long</span></kbd></dt>
+<dd><p>options can be long also</p>
+</dd>
+<dt><kbd><span class="option">--input=<var>file</var></span></kbd></dt>
+<dd><p>long options can also have
+arguments</p>
+</dd>
+<dt><kbd><span class="option">--very-long-option</span></kbd></dt>
+<dd><p>The description can also start on the next line.</p>
+<p>The description may contain multiple body elements,
+regardless of where it starts.</p>
+</dd>
+<dt><kbd><span class="option">-x</span>, <span class="option">-y</span>, <span class="option">-z</span></kbd></dt>
+<dd><p>Multiple options are an "option group".</p>
+</dd>
+<dt><kbd><span class="option">-v</span>, <span class="option">--verbose</span></kbd></dt>
+<dd><p>Commonly-seen: short & long options.</p>
+</dd>
+<dt><kbd><span class="option">-1 <var>file</var></span>, <span class="option">--one=<var>file</var></span>, <span class="option">--two <var>file</var></span></kbd></dt>
+<dd><p>Multiple options with arguments.</p>
+</dd>
+<dt><kbd><span class="option">/V</span></kbd></dt>
+<dd><p>DOS/VMS-style options too</p>
+</dd>
+</dl>
+<p>There must be at least two spaces between the option and the
+description.</p>
+</div>
+<div class="section" id="literal-blocks">
+<h2><a class="toc-backref" href="#id50"><span class="sectnum">2.7</span> Literal Blocks</a></h2>
+<p>Literal blocks are indicated with a double-colon ("::") at the end of
+the preceding paragraph (over there <span class="docutils literal"><span class="pre">--></span></span>). They can be indented:</p>
+<pre class="literal-block">if literal_block:
+ text = 'is left as-is'
+ spaces_and_linebreaks = 'are preserved'
+ markup_processing = None</pre>
+<p>Or they can be quoted without indentation:</p>
+<pre class="literal-block">>> Great idea!
+>
+> Why didn't I think of that?</pre>
+</div>
+<div class="section" id="line-blocks">
+<h2><a class="toc-backref" href="#id51"><span class="sectnum">2.8</span> Line Blocks</a></h2>
+<p>This section tests line blocks. Line blocks are body elements which
+consist of lines and other line blocks. Nested line blocks cause
+indentation.</p>
+<div class="line-block">
+<div class="line">This is a line block. It ends with a blank line.</div>
+<div class="line-block">
+<div class="line">New lines begin with a vertical bar ("|").</div>
+<div class="line">Line breaks and initial indent are significant, and preserved.</div>
+<div class="line-block">
+<div class="line">Continuation lines are also possible. A long line that is intended
+to wrap should begin with a space in place of the vertical bar.</div>
+</div>
+<div class="line">The left edge of a continuation line need not be aligned with
+the left edge of the text above it.</div>
+</div>
+</div>
+<div class="line-block">
+<div class="line">This is a second line block.</div>
+<div class="line"><br /></div>
+<div class="line">Blank lines are permitted internally, but they must begin with a "|".</div>
+</div>
+<p>Another line block, surrounded by paragraphs:</p>
+<div class="line-block">
+<div class="line">And it's no good waiting by the window</div>
+<div class="line">It's no good waiting for the sun</div>
+<div class="line">Please believe me, the things you dream of</div>
+<div class="line">They don't fall in the lap of no-one</div>
+</div>
+<p>Take it away, Eric the Orchestra Leader!</p>
+<blockquote>
+<div class="line-block">
+<div class="line">A one, two, a one two three four</div>
+<div class="line"><br /></div>
+<div class="line">Half a bee, philosophically,</div>
+<div class="line-block">
+<div class="line">must, <em>ipso facto</em>, half not be.</div>
+</div>
+<div class="line">But half the bee has got to be,</div>
+<div class="line-block">
+<div class="line"><em>vis a vis</em> its entity. D'you see?</div>
+<div class="line"><br /></div>
+</div>
+<div class="line">But can a bee be said to be</div>
+<div class="line-block">
+<div class="line">or not to be an entire bee,</div>
+<div class="line-block">
+<div class="line">when half the bee is not a bee,</div>
+<div class="line-block">
+<div class="line">due to some ancient injury?</div>
+<div class="line"><br /></div>
+</div>
+</div>
+</div>
+<div class="line">Singing...</div>
+</div>
+</blockquote>
+<p>A line block, like the following poem by Christian Morgenstern, can
+also be centre-aligned:</p>
+<div class="align-center line-block" lang="de">
+<div class="line"><strong>Die Trichter</strong></div>
+<div class="line"><br /></div>
+<div class="line">Zwei Trichter wandeln durch die Nacht.</div>
+<div class="line">Durch ihres Rumpfs verengten Schacht</div>
+<div class="line">fließt weißes Mondlicht</div>
+<div class="line">still und heiter</div>
+<div class="line">auf ihren</div>
+<div class="line">Waldweg</div>
+<div class="line">u. s.</div>
+<div class="line">w.</div>
+<div class="line"><br /></div>
+</div>
+</div>
+<div class="section" id="block-quotes">
+<h2><a class="toc-backref" href="#id52"><span class="sectnum">2.9</span> Block Quotes</a></h2>
+<p>Block quotes consist of indented body elements:</p>
+<blockquote>
+<p>My theory by A. Elk. Brackets Miss, brackets. This theory goes
+as follows and begins now. All brontosauruses are thin at one
+end, much much thicker in the middle and then thin again at the
+far end. That is my theory, it is mine, and belongs to me and I
+own it, and what it is too.</p>
+<p class="attribution">—<cite>Anne Elk (Miss)</cite></p>
+</blockquote>
+<p>The language of a quote (like any other object) can be specified by
+a class attribute:</p>
+<!-- -->
+<blockquote lang="fr">
+<p>ReStructuredText est un langage de balisage léger utilisé
+notamment dans la documentation du langage Python.</p>
+</blockquote>
+</div>
+<div class="section" id="doctest-blocks">
+<h2><a class="toc-backref" href="#id53"><span class="sectnum">2.10</span> Doctest Blocks</a></h2>
+<pre class="code python doctest">>>> print 'Python-specific usage examples; begun with ">>>"'
+Python-specific usage examples; begun with ">>>"
+>>> print '(cut and pasted from interactive Python sessions)'
+(cut and pasted from interactive Python sessions)
+</pre>
+</div>
+<div class="section" id="footnotes">
+<h2><a class="toc-backref" href="#id54"><span class="sectnum">2.11</span> Footnotes</a></h2>
+<dl class="footnote brackets">
+<dt class="label" id="id8"><span class="brackets">1</span><span class="fn-backref">(<a href="#id1">1</a>,<a href="#id9">2</a>,<a href="#id22">3</a>)</span></dt>
+<dd><p>A footnote contains body elements, consistently indented by at
+least 3 spaces.</p>
+<p>This is the footnote's second paragraph.</p>
+</dd>
+<dt class="label" id="label"><span class="brackets">2</span><span class="fn-backref">(<a href="#id3">1</a>,<a href="#id10">2</a>)</span></dt>
+<dd><p>Footnotes may be numbered, either manually (as in <a class="footnote-reference brackets" href="#id8" id="id9">1</a>) or
+automatically using a "#"-prefixed label. This footnote has a
+label so it can be referred to from multiple places, both as a
+footnote reference (<a class="footnote-reference brackets" href="#label" id="id10">2</a>) and as a <a class="reference internal" href="#label">hyperlink reference</a>.</p>
+</dd>
+<dt class="label" id="id12"><span class="brackets"><a class="fn-backref" href="#id2">3</a></span></dt>
+<dd><p>This footnote is numbered automatically and anonymously using a
+label of "#" only.</p>
+<p>This is the second paragraph.</p>
+<p>And this is the third paragraph.</p>
+</dd>
+<dt class="label" id="id13"><span class="brackets"><a class="fn-backref" href="#id4">*</a></span></dt>
+<dd><p>Footnotes may also use symbols, specified with a "*" label.
+Here's a reference to the next footnote: <a class="footnote-reference brackets" href="#id15" id="id14">†</a>.</p>
+</dd>
+<dt class="label" id="id15"><span class="brackets"><a class="fn-backref" href="#id14">†</a></span></dt>
+<dd><p>This footnote shows the next symbol in the sequence.</p>
+</dd>
+<dt class="label" id="id16"><span class="brackets">4</span></dt>
+<dd><p>Here's an unreferenced footnote, with a reference to a
+nonexistent footnote: <a href="#id96"><span class="problematic" id="id97"><span id="id17"></span>[5]_</span></a>.</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="citations">
+<h2><a class="toc-backref" href="#id55"><span class="sectnum">2.12</span> Citations</a></h2>
+<dl class="citation">
+<dt class="label" id="cit2002"><span class="brackets">CIT2002</span><span class="fn-backref">(<a href="#id5">1</a>,<a href="#id18">2</a>)</span></dt>
+<dd><p>Citations are text-labeled footnotes. They may be
+rendered separately and differently from footnotes.</p>
+</dd>
+</dl>
+<p>Here's a reference to the above, <a class="citation-reference" href="#cit2002" id="id18">[CIT2002]</a>, and a <a href="#id98"><span class="problematic" id="id99"><span id="id19"></span>[nonexistent]_</span></a>
+citation.</p>
+</div>
+<div class="section" id="targets">
+<span id="another-target"></span><h2><a class="toc-backref" href="#id56"><span class="sectnum">2.13</span> Targets</a></h2>
+<p id="example">This paragraph is pointed to by the explicit "example" target. A
+reference can be found under <a class="reference internal" href="#inline-markup">Inline Markup</a>, above. <a class="reference internal" href="#inline-hyperlink-targets">Inline
+hyperlink targets</a> are also possible.</p>
+<p>Section headers are implicit targets, referred to by name. See
+<a class="reference internal" href="#targets">Targets</a>, which is a subsection of <a class="reference internal" href="#body-elements">Body Elements</a>.</p>
+<p>Explicit external targets are interpolated into references such as
+"<a class="reference external" href="http://www.python.org/">Python</a> <a class="footnote-reference brackets" href="#id25" id="id27">5</a>".</p>
+<p>Targets may be indirect and anonymous. Thus <a class="reference internal" href="#targets">this phrase</a> may also
+refer to the <a class="reference internal" href="#targets">Targets</a> section.</p>
+<p>Here's a <a href="#id100"><span class="problematic" id="id101">`hyperlink reference without a target`_</span></a>, which generates an
+error.</p>
+<div class="section" id="duplicate-target-names">
+<h3><a class="toc-backref" href="#id57"><span class="sectnum">2.13.1</span> Duplicate Target Names</a></h3>
+<p>Duplicate names in section headers or other implicit targets will
+generate "info" (level-1) system messages. Duplicate names in
+explicit targets will generate "warning" (level-2) system messages.</p>
+</div>
+<div class="section" id="id21">
+<h3><a class="toc-backref" href="#id58"><span class="sectnum">2.13.2</span> Duplicate Target Names</a></h3>
+<p>Since there are two "Duplicate Target Names" section headers, we
+cannot uniquely refer to either of them by name. If we try to (like
+this: <a href="#id102"><span class="problematic" id="id103">`Duplicate Target Names`_</span></a>), an error is generated.</p>
+</div>
+</div>
+<div class="section" id="directives">
+<h2><a class="toc-backref" href="#id59"><span class="sectnum">2.14</span> Directives</a></h2>
+<div class="contents local topic" id="contents">
+<ul class="auto-toc simple">
+<li><p><a class="reference internal" href="#document-parts" id="id87"><span class="sectnum">2.14.1</span> Document Parts</a></p></li>
+<li><p><a class="reference internal" href="#images-and-figures" id="id88"><span class="sectnum">2.14.2</span> Images and Figures</a></p></li>
+<li><p><a class="reference internal" href="#admonitions" id="id89"><span class="sectnum">2.14.3</span> Admonitions</a></p></li>
+<li><p><a class="reference internal" href="#topics-sidebars-and-rubrics" id="id90"><span class="sectnum">2.14.4</span> Topics, Sidebars, and Rubrics</a></p></li>
+<li><p><a class="reference internal" href="#target-footnotes" id="id91"><span class="sectnum">2.14.5</span> Target Footnotes</a></p></li>
+<li><p><a class="reference internal" href="#replacement-text" id="id92"><span class="sectnum">2.14.6</span> Replacement Text</a></p></li>
+<li><p><a class="reference internal" href="#compound-paragraph" id="id93"><span class="sectnum">2.14.7</span> Compound Paragraph</a></p></li>
+<li><p><a class="reference internal" href="#parsed-literal-blocks" id="id94"><span class="sectnum">2.14.8</span> Parsed Literal Blocks</a></p></li>
+<li><p><a class="reference internal" href="#code" id="id95"><span class="sectnum">2.14.9</span> Code</a></p></li>
+</ul>
+</div>
+<p>These are just a sample of the many reStructuredText Directives. For
+others, please see
+<a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/directives.html">http://docutils.sourceforge.net/docs/ref/rst/directives.html</a>.</p>
+<div class="section" id="document-parts">
+<h3><a class="toc-backref" href="#id87"><span class="sectnum">2.14.1</span> Document Parts</a></h3>
+<p>An example of the "contents" directive can be seen above this section
+(a local, untitled table of <a class="reference internal" href="#contents">contents</a>) and at the beginning of the
+document (a document-wide <a class="reference internal" href="#table-of-contents">table of contents</a>).</p>
+</div>
+<div class="section" id="images-and-figures">
+<h3><a class="toc-backref" href="#id88"><span class="sectnum">2.14.2</span> Images and Figures</a></h3>
+<p>An image directive (also clickable -- a hyperlink reference):</p>
+<a class="reference internal image-reference" href="#directives"><img alt="../../../docs/user/rst/images/title.png" class="class1 class2" src="../../../docs/user/rst/images/title.png" /></a>
+<p>Image with multiple IDs:</p>
+<span id="image-target-2"></span><span id="image-target-1"></span><img alt="../../../docs/user/rst/images/title.png" id="image-target-3" src="../../../docs/user/rst/images/title.png" />
+<p>A centered image:</p>
+<img alt="../../../docs/user/rst/images/biohazard.png" class="align-center" src="../../../docs/user/rst/images/biohazard.png" />
+<p>A left-aligned image:</p>
+<img alt="../../../docs/user/rst/images/biohazard.png" class="align-left" src="../../../docs/user/rst/images/biohazard.png" />
+<p>This paragraph might flow around the image.
+The specific behavior depends upon the style sheet and
+the browser or rendering software used.</p>
+<p>A right-aligned image:</p>
+<img alt="../../../docs/user/rst/images/biohazard.png" class="align-right" src="../../../docs/user/rst/images/biohazard.png" />
+<p>This paragraph might flow around the image.
+The specific behavior depends upon the style sheet and
+the browser or rendering software used.</p>
+<p>For inline images see <a class="reference internal" href="#substitution-definitions">Substitution Definitions</a>.</p>
+<p>Image size:</p>
+<p>An image 2 em wide:</p>
+<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 2em;" />
+<p>An image 2 em wide and 15 pixel high:</p>
+<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 2em; height: 15px;" />
+<p>An image occupying 50% of the line width:</p>
+<img alt="../../../docs/user/rst/images/title.png" src="../../../docs/user/rst/images/title.png" style="width: 50%;" />
+<p>An image 2 cm high:</p>
+<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="height: 2cm;" />
+<p>A <em>figure</em> is an image with a caption and/or a legend. With page-based output
+media, figures might float to a different position if this helps the page
+layout.</p>
+<div class="figclass1 figclass2 figure">
+<img alt="reStructuredText, the markup syntax" class="class1 class2" src="../../../docs/user/rst/images/title.png" style="width: 258px;" />
+<p class="caption">Plaintext markup syntax and parser system.</p>
+<div class="legend">
+<table>
+<colgroup>
+<col style="width: 20%" />
+<col style="width: 80%" />
+</colgroup>
+<tbody>
+<tr><td><p>re</p></td>
+<td><p>Revised, revisited, based on 're' module.</p></td>
+</tr>
+<tr><td><p>Structured</p></td>
+<td><p>Structure-enhanced text, structuredtext.</p></td>
+</tr>
+<tr><td><p>Text</p></td>
+<td><p>Well it is, isn't it?</p></td>
+</tr>
+</tbody>
+</table>
+<p>This paragraph is also part of the legend.</p>
+</div>
+</div>
+<p>A left-aligned figure:</p>
+<div class="figclass1 figclass2 figure align-left" style="width: 70%">
+<img alt="reStructuredText, the markup syntax" class="class1 class2" src="../../../docs/user/rst/images/biohazard.png" style="width: 40px;" />
+<p class="caption">This is the caption.</p>
+<div class="legend">
+<p>This is the legend.</p>
+<p>The legend may consist of several paragraphs.</p>
+</div>
+</div>
+<p>This paragraph might flow around the figure.</p>
+<p>The specific behavior depends upon the style sheet and the browser or
+rendering software used.</p>
+<p>A centered figure:</p>
+<div class="figure align-center">
+<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 40px;" />
+<p class="caption">This is the caption.</p>
+<div class="legend">
+<p>This is the legend.</p>
+<p>The legend may consist of several paragraphs.</p>
+</div>
+</div>
+<p>This paragraph might flow around the figure.</p>
+<p>The specific behavior depends upon the style sheet and the browser or
+rendering software used.</p>
+<p>A right-aligned figure:</p>
+<div class="figure align-right">
+<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 40px;" />
+<p class="caption">This is the caption.</p>
+<div class="legend">
+<p>This is the legend.</p>
+<p>The legend may consist of several paragraphs.</p>
+</div>
+</div>
+<p>This paragraph might flow around the figure. The specific behavior depends
+upon the style sheet and the browser or rendering software used.</p>
+<p>Tables may be given titles and additional arguments with the <em>table</em>
+directive:</p>
+<table class="align-left">
+<caption>left-aligned table</caption>
+<colgroup>
+<col style="width: 50%" />
+<col style="width: 50%" />
+</colgroup>
+<thead>
+<tr><th class="head"><p>A</p></th>
+<th class="head"><p>not A</p></th>
+</tr>
+</thead>
+<tbody>
+<tr><td><p>False</p></td>
+<td><p>True</p></td>
+</tr>
+<tr><td><p>True</p></td>
+<td><p>False</p></td>
+</tr>
+</tbody>
+</table>
+<table class="align-center">
+<caption>center-aligned table</caption>
+<colgroup>
+<col style="width: 50%" />
+<col style="width: 50%" />
+</colgroup>
+<thead>
+<tr><th class="head"><p>A</p></th>
+<th class="head"><p>not A</p></th>
+</tr>
+</thead>
+<tbody>
+<tr><td><p>False</p></td>
+<td><p>True</p></td>
+</tr>
+<tr><td><p>True</p></td>
+<td><p>False</p></td>
+</tr>
+</tbody>
+</table>
+<table class="align-right">
+<caption>right-aligned table</caption>
+<colgroup>
+<col style="width: 50%" />
+<col style="width: 50%" />
+</colgroup>
+<thead>
+<tr><th class="head"><p>A</p></th>
+<th class="head"><p>not A</p></th>
+</tr>
+</thead>
+<tbody>
+<tr><td><p>False</p></td>
+<td><p>True</p></td>
+</tr>
+<tr><td><p>True</p></td>
+<td><p>False</p></td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="admonitions">
+<h3><a class="toc-backref" href="#id89"><span class="sectnum">2.14.3</span> Admonitions</a></h3>
+<div class="admonition attention">
+<p class="admonition-title">Attention!</p>
+<p>Directives at large.</p>
+</div>
+<div class="admonition caution">
+<p class="admonition-title">Caution!</p>
+<p>Don't take any wooden nickels.</p>
+</div>
+<div class="admonition danger">
+<p class="admonition-title">!DANGER!</p>
+<p>Mad scientist at work!</p>
+</div>
+<div class="admonition error">
+<p class="admonition-title">Error</p>
+<p>Does not compute.</p>
+</div>
+<div class="admonition hint">
+<p class="admonition-title">Hint</p>
+<p>It's bigger than a bread box.</p>
+</div>
+<div class="admonition important">
+<p class="admonition-title">Important</p>
+<ul class="simple">
+<li><p>Wash behind your ears.</p></li>
+<li><p>Clean up your room.</p></li>
+<li><p>Call your mother.</p></li>
+<li><p>Back up your data.</p></li>
+</ul>
+</div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>This is a note.</p>
+</div>
+<div class="admonition tip">
+<p class="admonition-title">Tip</p>
+<p>15% if the service is good.</p>
+</div>
+<div class="admonition warning">
+<p class="admonition-title">Warning</p>
+<p>Strong prose may provoke extreme mental exertion.
+Reader discretion is strongly advised.</p>
+</div>
+<div class="admonition admonition-and-by-the-way">
+<p class="admonition-title">And, by the way...</p>
+<p>You can make up your own admonition too.</p>
+</div>
+</div>
+<div class="section" id="topics-sidebars-and-rubrics">
+<h3><a class="toc-backref" href="#id90"><span class="sectnum">2.14.4</span> Topics, Sidebars, and Rubrics</a></h3>
+<p><em>Sidebars</em> are like miniature, parallel documents.</p>
+<div class="sidebar">
+<p class="sidebar-title">Sidebar Title</p>
+<p class="sidebar-subtitle">Optional Subtitle</p>
+<p>This is a sidebar. It is for text outside the flow of the main
+text.</p>
+<p class="rubric">This is a rubric inside a sidebar</p>
+<p>Sidebars often appear beside the main text with a border and a different
+background or font color.</p>
+</div>
+<p>A <em>topic</em> is like a block quote with a title, or a self-contained section
+with no subsections.</p>
+<div class="topic">
+<p class="topic-title first">Topic Title</p>
+<p>This is a topic.</p>
+</div>
+<p>A <em>rubric</em> is like an informal heading that doesn't correspond to the
+document's structure. It is typically highlighted in red (hence the name).</p>
+<p class="rubric">This is a rubric</p>
+<p>Topics and rubrics can be used at places where a <a class="reference internal" href="#section-title">section title</a> is not
+allowed (e.g. inside a directive).</p>
+</div>
+<div class="section" id="target-footnotes">
+<h3><a class="toc-backref" href="#id91"><span class="sectnum">2.14.5</span> Target Footnotes</a></h3>
+<dl class="footnote brackets">
+<dt class="label" id="id25"><span class="brackets">5</span><span class="fn-backref">(<a href="#id26">1</a>,<a href="#id27">2</a>,<a href="#id28">3</a>,<a href="#id35">4</a>)</span></dt>
+<dd><p><a class="reference external" href="http://www.python.org/">http://www.python.org/</a></p>
+</dd>
+<dt class="label" id="id29"><span class="brackets"><a class="fn-backref" href="#id30">6</a></span></dt>
+<dd><p><a class="reference external" href="http://pygments.org/">http://pygments.org/</a></p>
+</dd>
+<dt class="label" id="id31"><span class="brackets"><a class="fn-backref" href="#id32">7</a></span></dt>
+<dd><p><a class="reference external" href="http://docutils.sourceforge.net/docs/user/config.html#table-style">http://docutils.sourceforge.net/docs/user/config.html#table-style</a></p>
+</dd>
+<dt class="label" id="id33"><span class="brackets"><a class="fn-backref" href="#id34">8</a></span></dt>
+<dd><p><a class="reference external" href="http://tug.ctan.org/tex-archive/macros/latex/contrib/booktabs/booktabs.pdf">http://tug.ctan.org/tex-archive/macros/latex/contrib/booktabs/booktabs.pdf</a></p>
+</dd>
+<dt class="label" id="id36"><span class="brackets"><a class="fn-backref" href="#id37">9</a></span></dt>
+<dd><p><a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a></p>
+</dd>
+</dl>
+</div>
+<div class="section" id="replacement-text">
+<h3><a class="toc-backref" href="#id92"><span class="sectnum">2.14.6</span> Replacement Text</a></h3>
+<p>I recommend you try <a class="reference external" href="http://www.python.org/">Python, <em>the</em> best language around</a> <a class="footnote-reference brackets" href="#id25" id="id28">5</a>.</p>
+</div>
+<div class="section" id="compound-paragraph">
+<h3><a class="toc-backref" href="#id93"><span class="sectnum">2.14.7</span> Compound Paragraph</...
[truncated message content] |