diff options
| author | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2015-03-10 14:26:05 +0000 |
|---|---|---|
| committer | milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2015-03-10 14:26:05 +0000 |
| commit | 214dab031c19b50c6cb493481bdea7262283debb (patch) | |
| tree | 150db0cb44dc30c04ed883ea4d51265c7e1d72ec /docutils/test/functional | |
| parent | 0ffe9bdccf2b0a8022f3c904eefeb07f4cc3a5ed (diff) | |
| download | docutils-214dab031c19b50c6cb493481bdea7262283debb.tar.gz | |
Tests for the basic HTML writer.
git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@7816 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
Diffstat (limited to 'docutils/test/functional')
| -rw-r--r-- | docutils/test/functional/expected/standalone_rst_html_base.html | 1443 | ||||
| -rw-r--r-- | docutils/test/functional/input/standalone_rst_html_base.txt | 234 |
2 files changed, 1677 insertions, 0 deletions
diff --git a/docutils/test/functional/expected/standalone_rst_html_base.html b/docutils/test/functional/expected/standalone_rst_html_base.html new file mode 100644 index 000000000..521b1154d --- /dev/null +++ b/docutils/test/functional/expected/standalone_rst_html_base.html @@ -0,0 +1,1443 @@ +<!DOCTYPE html> +<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.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/html-base.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>field name</dt> +<dd><p>This is a "generic bibliographic field".</p> +</dd> +<dt>field name "2"</dt> +<dd><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="#description-list" id="id81"><span class="sectnum">3.1</span> Description list</a></p></li> +<li><p><a class="reference internal" href="#field-list-handling" id="id82"><span class="sectnum">3.2</span> Field list handling</a></p> +<ul class="auto-toc"> +<li><p><a class="reference internal" href="#styling-with-class-arguments" id="id83"><span class="sectnum">3.2.1</span> Styling with class arguments</a></p></li> +</ul> +</li> +<li><p><a class="reference internal" href="#table-styling-with-class-arguments" id="id84"><span class="sectnum">3.3</span> Table styling with class arguments</a></p></li> +<li><p><a class="reference internal" href="#maths" id="id85"><span class="sectnum">3.4</span> Maths</a></p></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" 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" href="#id25" id="id35">[5]</a> (<a class="reference external" href="http://docutils.sourceforge.net/">a second reference</a> <a class="footnote-reference" href="#id36" id="id37">[9]</a>), footnote references (manually +numbered <a class="footnote-reference" href="#id8" id="id1">[1]</a>, anonymous auto-numbered <a class="footnote-reference" href="#id12" id="id2">[3]</a>, labeled auto-numbered +<a class="footnote-reference" href="#label" id="id3">[2]</a>, or symbolic <a class="footnote-reference" 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"> +<li><p>(lower roman)</p> +<ol class="upperalpha"> +<li><p>upper alpha.</p> +<ol class="upperroman"> +<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">—Anne Elk (Miss)</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 pycon doctest-block">>>> 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"> +<dt class="label" id="id8">[1]<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">[2]<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" 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" 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"><a class="fn-backref" href="#id2">[3]</a></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"><a class="fn-backref" href="#id4">[*]</a></dt> +<dd><p>Footnotes may also use symbols, specified with a "*" label. +Here's a reference to the next footnote: <a class="footnote-reference" href="#id15" id="id14">[†]</a>.</p> +</dd> +<dt class="label" id="id15"><a class="fn-backref" href="#id14">[†]</a></dt> +<dd><p>This footnote shows the next symbol in the sequence.</p> +</dd> +<dt class="label" id="id16">[4]</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">[CIT2002]<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" 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> +</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"> +<dt class="label" id="id25">[5]<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"><a class="fn-backref" href="#id30">[6]</a></dt> +<dd><p><a class="reference external" href="http://pygments.org/">http://pygments.org/</a></p> +</dd> +<dt class="label" id="id31"><a class="fn-backref" href="#id32">[7]</a></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"><a class="fn-backref" href="#id34">[8]</a></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"><a class="fn-backref" href="#id37">[9]</a></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" 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</a></h3> +<div class="some-class compound"> +<p class="compound-first">Compound 1, paragraph 1.</p> +<p class="compound-middle">Compound 1, paragraph 2.</p> +<ul class="compound-last simple"> +<li><p>Compound 1, list item one.</p></li> +<li><p>Compound 1, list item two.</p></li> +</ul> +</div> +<p>Another compound statement:</p> +<div class="compound"> +<p class="compound-first">Compound 2, a literal block:</p> +<pre class="compound-middle literal-block">Compound 2, literal. +</pre> +<p class="compound-last">Compound 2, this is a test.</p> +</div> +<div class="compound"> +<p>Compound 3, only consisting of one paragraph.</p> +</div> +<div class="compound"> +<pre class="compound-first literal-block">Compound 4. +This one starts with a literal block. +</pre> +<p class="compound-last">Compound 4, a paragraph.</p> +</div> +<p>Now something <em>really</em> perverted -- a nested compound block. This is +just to test that it works at all; the results don't have to be +meaningful.</p> +<div class="compound"> +<p class="compound-first">Compound 5, block 1 (a paragraph).</p> +<div class="compound-middle compound"> +<p class="compound-first">Compound 6, block 2 in compound 5.</p> +<p class="compound-last">Compound 6, another paragraph.</p> +</div> +<p class="compound-last">Compound 5, block 3 (a paragraph).</p> +</div> +<div class="compound"> +<p class="compound-first">Compound 7, with a table inside:</p> +<table class="compound-middle"> +<colgroup> +<col style="width: 33%" /> +<col style="width: 33%" /> +<col style="width: 33%" /> +</colgroup> +<tbody> +<tr><td><p>Left cell, first +paragraph.</p> +<p>Left cell, second +paragraph.</p> +</td> +<td><p>Middle cell, +consisting of +exactly one +paragraph.</p></td> +<td><p>Right cell.</p> +<p>Paragraph 2.</p> +<p>Paragraph 3.</p> +</td> +</tr> +</tbody> +</table> +<p class="compound-middle">Compound 7, a paragraph after the table.</p> +<p class="compound-last">Compound 7, another paragraph.</p> +</div> +</div> +<div class="section" id="parsed-literal-blocks"> +<h3><a class="toc-backref" href="#id94"><span class="sectnum">2.14.8</span> Parsed Literal Blocks</a></h3> +<pre class="literal-block">This is a parsed literal block. + This line is indented. The next line is blank. + +Inline markup is supported, e.g. <em>emphasis</em>, <strong>strong</strong>, <span class="docutils literal">literal +text</span>, footnotes <a class="footnote-reference" href="#id8" id="id22">[1]</a>, <span class="target" id="hyperlink-targets">hyperlink targets</span>, and <a class="reference external" href="http://www.python.org/">references</a>. +</pre> +</div> +<div class="section" id="code"> +<h3><a class="toc-backref" href="#id95"><span class="sectnum">2.14.9</span> Code</a></h3> +<p>Blocks of source code can be set with the <cite>code</cite> directive. If the code +language is specified, the content is parsed and tagged by the <a class="reference external" href="http://pygments.org/">Pygments</a> <a class="footnote-reference" href="#id29" id="id30">[6]</a> +syntax highlighter and can be formatted with a style sheet. (Code parsing +is turned off using the <span class="docutils literal"><span class="pre">syntax-highlight</span></span> config setting in the test +conversions in order to get identical results with/without installed +Pygments highlighter.)</p> +<pre class="code python literal-block">print 'This is Python code.' +</pre> +<p>The <span class="docutils literal"><span class="pre">:number-lines:</span></span> option (with optional start value) generates line +numbers:</p> +<pre class="code python literal-block"><span class="ln"> 8 </span># print integers from 0 to 9: +<span class="ln"> 9 </span>for i in range(10): +<span class="ln">10 </span> print i +</pre> +<p>For inline code snippets, there is the <cite>code</cite> role, which can be used +directly (the code will not be parsed/tagged, as the language is not known) +or as base for special code roles, e.g. the LaTeX code in the next +paragraph.</p> +<p>Docutils uses LaTeX syntax for math directives and roles: +<code class="tex">\alpha = f(x)</code> prints <span class="formula"><i>α</i> = <i>f</i>(<i>x</i>)</span>.</p> +<p>The <span class="docutils literal">:code:</span> option of the <cite>include</cite> directive sets the included content +as a code block, here the rst file <span class="docutils literal">header_footer.txt</span> with line numbers:</p> +<pre class="code rst literal-block"><span class="ln">1 </span>.. header:: Document header +<span class="ln">2 </span>.. footer:: Document footer +</pre> +</div> +</div> +<div class="section" id="substitution-definitions"> +<h2><a class="toc-backref" href="#id69"><span class="sectnum">2.15</span> Substitution Definitions</a></h2> +<p>An inline image (<img alt="EXAMPLE" src="../../../docs/user/rst/images/biohazard.png" />) example:</p> +<p>(Substitution definitions are not visible in the HTML source.)</p> +</div> +<div class="section" id="comments"> +<h2><a class="toc-backref" href="#id70"><span class="sectnum">2.16</span> Comments</a></h2> +<p>Here's one:</p> +<!-- Comments begin with two dots and a space. Anything may +follow, except for the syntax of footnotes, hyperlink +targets, directives, or substitution definitions. + +Double-dashes - - "- -" - - must be escaped somehow in HTML output. + +Comments may contain non-ASCII characters: ä ö ü æ ø å --> +<p>(View the HTML source to see the comment.)</p> +</div> +<div class="section" id="raw-text"> +<h2><a class="toc-backref" href="#id71"><span class="sectnum">2.17</span> Raw text</a></h2> +<p>This does not necessarily look nice, because there may be missing white space.</p> +<p>It's just there to freeze the behavior.</p> +A test.Second test.<div class="myclass">Another test with myclass set.</div><p>This is the <span class="myrawroleclass">fourth test</span> with myrawroleclass set.</p> +Fifth test in HTML.<br />Line two.</div> +<div class="section" id="container"> +<h2><a class="toc-backref" href="#id72"><span class="sectnum">2.18</span> Container</a></h2> +<div class="custom docutils container"> +<p>paragraph 1</p> +<p>paragraph 2</p> +</div> +</div> +<div class="section" id="colspanning-tables"> +<h2><a class="toc-backref" href="#id73"><span class="sectnum">2.19</span> Colspanning tables</a></h2> +<p>This table has a cell spanning two columns:</p> +<table> +<colgroup> +<col style="width: 31%" /> +<col style="width: 31%" /> +<col style="width: 38%" /> +</colgroup> +<thead> +<tr><th class="head" colspan="2"><p>Inputs</p></th> +<th class="head"><p>Output</p></th> +</tr> +<tr><th class="head"><p>A</p></th> +<th class="head"><p>B</p></th> +<th class="head"><p>A or B</p></th> +</tr> +</thead> +<tbody> +<tr><td><p>False</p></td> +<td><p>False</p></td> +<td><p>False</p></td> +</tr> +<tr><td><p>True</p></td> +<td><p>False</p></td> +<td><p>True</p></td> +</tr> +<tr><td><p>False</p></td> +<td><p>True</p></td> +<td><p>True</p></td> +</tr> +<tr><td><p>True</p></td> +<td><p>True</p></td> +<td><p>True</p></td> +</tr> +</tbody> +</table> +</div> +<div class="section" id="rowspanning-tables"> +<h2><a class="toc-backref" href="#id74"><span class="sectnum">2.20</span> Rowspanning tables</a></h2> +<p>Here's a table with cells spanning several rows:</p> +<table> +<colgroup> +<col style="width: 44%" /> +<col style="width: 22%" /> +<col style="width: 33%" /> +</colgroup> +<thead> +<tr><th class="head"><p>Header row, column 1 +(header rows optional)</p></th> +<th class="head"><p>Header 2</p></th> +<th class="head"><p>Header 3</p></th> +</tr> +</thead> +<tbody> +<tr><td><p>body row 1, column 1</p></td> +<td><p>column 2</p></td> +<td><p>column 3</p></td> +</tr> +<tr><td><p>body row 2</p></td> +<td rowspan="2"><p>Cells may +span rows.</p></td> +<td rowspan="2"><p>Another +rowspanning +cell.</p></td> +</tr> +<tr><td><p>body row 3</p></td> +</tr> +</tbody> +</table> +</div> +<div class="section" id="complex-tables"> +<h2><a class="toc-backref" href="#id75"><span class="sectnum">2.21</span> Complex tables</a></h2> +<p>Here's a complex table, which should test all features.</p> +<table> +<colgroup> +<col style="width: 43%" /> +<col style="width: 21%" /> +<col style="width: 18%" /> +<col style="width: 18%" /> +</colgroup> +<thead> +<tr><th class="head"><p>Header row, column 1 +(header rows optional)</p></th> +<th class="head"><p>Header 2</p></th> +<th class="head"><p>Header 3</p></th> +<th class="head"><p>Header 4</p></th> +</tr> +</thead> +<tbody> +<tr><td><p>body row 1, column 1</p></td> +<td><p>column 2</p></td> +<td><p>column 3</p></td> +<td><p>column 4</p></td> +</tr> +<tr><td><p>body row 2</p></td> +<td colspan="3"><p>Cells may span columns.</p></td> +</tr> +<tr><td><p>body row 3</p></td> +<td rowspan="2"><p>Cells may +span rows.</p> +<p>Paragraph.</p> +</td> +<td colspan="2" rowspan="2"><ul class="simple"> +<li><p>Table cells</p></li> +<li><p>contain</p></li> +<li><p>body elements.</p></li> +</ul> +</td> +</tr> +<tr><td><p>body row 4</p></td> +</tr> +<tr><td><p>body row 5</p></td> +<td colspan="2"><p>Cells may also be +empty: <span class="docutils literal"><span class="pre">--></span></span></p></td> +<td> </td> +</tr> +</tbody> +</table> +</div> +<div class="section" id="list-tables"> +<h2><a class="toc-backref" href="#id76"><span class="sectnum">2.22</span> List Tables</a></h2> +<p>Here's a list table exercising all features:</p> +<table class="test"> +<caption>list table with integral header</caption> +<colgroup> +<col style="width: 17%" /> +<col style="width: 33%" /> +<col style="width: 50%" /> +</colgroup> +<thead> +<tr><th class="head stub"><p>Treat</p></th> +<th class="head"><p>Quantity</p></th> +<th class="head"><p>Description</p></th> +</tr> +</thead> +<tbody> +<tr><th class="stub"><p>Albatross</p></th> +<td><p>2.99</p></td> +<td><p>On a stick!</p></td> +</tr> +<tr><th class="stub"><p>Crunchy Frog</p></th> +<td><p>1.49</p></td> +<td><p>If we took the bones out, it wouldn't be +crunchy, now would it?</p></td> +</tr> +<tr><th class="stub"><p>Gannet Ripple</p></th> +<td><p>1.99</p></td> +<td><p>On a stick!</p></td> +</tr> +</tbody> +</table> +</div> +<div class="section" id="custom-roles"> +<h2><a class="toc-backref" href="#id77"><span class="sectnum">2.23</span> Custom Roles</a></h2> +<ul> +<li><p>A role based on an existing role.</p> +<p><span class="custom docutils literal">one</span> <span class="custom docutils literal">two</span> <span class="custom docutils literal">three</span></p> +</li> +<li><p>A new role.</p> +<p><span class="customnew">one two three</span></p> +</li> +<li><p>A role with class attribute.</p> +<p><span class="special">interpreted text</span></p> +</li> +<li><p>A language-switching role:</p> +<p>Let's count in German <span lang="de">eins zwei drei</span>.</p> +</li> +<li><p>A role with multiple class attributes, styled with raw directives:</p> +<p>The following works in most browsers but does not validate +(<span class="docutils literal"><style></span> is only allowed in the document head):</p> +<pre class="literal-block">.. raw:: html + + <style type="text/css"><!-- + .green {color: green;} + .sc {font-variant: small-caps;} + --></style> +</pre> +<p><span class="green sc" lang="en-gb">British colourful text in small-caps</span>.</p> +</li> +</ul> +</div> +<div class="section" id="svg-images"> +<h2><a class="toc-backref" href="#id78"><span class="sectnum">2.24</span> SVG Images</a></h2> +<object class="align-left" data="../../../docs/user/rst/images/biohazard.svg" style="width: 48px; height: 48px;" type="image/svg+xml"> +../../../docs/user/rst/images/biohazard.svg</object> +<p>Scalable vector graphics (SVG) images are not supported by all backends. +Rendering depends partially on the backend, especially if the size is +not explicitely given.</p> +<object class="align-left" data="../../../docs/user/rst/images/title-scaling.svg" style="width: 50%;" type="image/svg+xml"> +../../../docs/user/rst/images/title-scaling.svg</object> +<p>A scaling image occupying 50% of the line width (scales with the browser +window).</p> +<p>Whether an SVG image is scaled or clipped/padded cannot be set in the +containing HTML. If the image is wrapped in <span class="docutils literal"><object></span> tags, it +depends on the viewport declaration inside its root <svg> element, if it is +wrapped in <span class="docutils literal"><img></span> it depends on the browser.</p> +<object class="align-left" data="../../../docs/user/rst/images/title.svg" style="width: 50%; height: 15px;" type="image/svg+xml"> +../../../docs/user/rst/images/title.svg</object> +<p>A fixed-size image in a box with 50% of the line width, 15 pixles high.</p> +<object class="align-right" data="../../../docs/user/rst/images/title-scaling.svg" style="width: 50%; height: 1.2em;" type="image/svg+xml"> +../../../docs/user/rst/images/title-scaling.svg</object> +<p>A scaling image occupying 50% of the line width and 1.2 em high, +right aligned (this SVG image keeps the aspect ratio):</p> +<ul class="simple"> +<li><p>An inline SVG image <object data="../../../docs/user/rst/images/biohazard-scaling.svg" style="height: 0.8em;" type="image/svg+xml">inline-svg</object> scaled to a height of 0.8 em.</p></li> +</ul> +<object class="align-left" data="../../../docs/user/rst/images/biohazard-scaling.svg" style="height: 1em;" type="image/svg+xml"> +../../../docs/user/rst/images/biohazard-scaling.svg</object> +<p>A scaling image 1 em high, left aligned.</p> +<p>A scaling image 5 mm x 5 mm, centered, with hyperlink reference:</p> +<a class="reference internal image-reference" href="#directives"><object class="align-center" data="../../../docs/user/rst/images/biohazard-scaling.svg" style="width: 5mm; height: 5mm;" type="image/svg+xml">../../../docs/user/rst/images/biohazard-scaling.svg</object></a> +<object class="align-left" data="../../../docs/user/rst/images/biohazard.svg" style="width: 4cm; height: 2em;" type="image/svg+xml"> +../../../docs/user/rst/images/biohazard.svg</object> +<p>A fixed-size image in a 4 cm x 2 em box.</p> +<div class="figure"> +<object data="../../../docs/user/rst/images/title.svg" style="width: 290px; height: 28px;" type="image/svg+xml"> +reStructuredText, the markup syntax</object> +<p class="caption">SVG image in a figure.</p> +</div> +<object class="align-right" data="../../../docs/user/rst/images/biohazard-bitmap.svg" style="width: 3em;" type="image/svg+xml"> +../../../docs/user/rst/images/biohazard-bitmap.svg</object> +<p>An SVG image with embedded bitmap, 3 em wide, right aligned. +Older versions of <cite>webkit</cite> based browsers (chromium, safari, midori, +konqueror) cannot display the contained bitmap image if the SVG is wrapped +in <span class="docutils literal"><img></span> tags. The image does not scale properly if wrapped in +<span class="docutils literal"><object></span> tags.</p> +</div> +<div class="section" id="swf-images"> +<h2><a class="toc-backref" href="#id79"><span class="sectnum">2.25</span> SWF Images</a></h2> +<p>Shockwave Flash is an image/movie format that most modern web browsers +support via a plugin. It is sometimes blocked due to privacy/security +concerns.</p> +<p>Images with extension <span class="docutils literal">.swf</span> are placed inside <object> elements. +For complete control over display options use raw HTML.</p> +<object class="align-left" data="../../../docs/user/rst/images/biohazard.swf" style="width: 4cm; height: 2em;" type="application/x-shockwave-flash"> +[biohazard.swf]</object> +<p>An SWF image in a 4 cm x 2 em box, left aligned.</p> +<p>An inline SWF image <object data="../../../docs/user/rst/images/biohazard.swf" style="width: 0.8em; height: 0.8em;" type="application/x-shockwave-flash">inline-swf</object> scaled to 0.8 em x 0.8 em.</p> +</div> +</div> +<div class="section" id="changes-to-the-html4css1-writer"> +<h1><a class="toc-backref" href="#id80"><span class="sectnum">3</span> Changes to the html4css1 writer</a></h1> +<ul class="simple"> +<li><p>Use only meta keywords recognized by HTML 5.</p></li> +<li><p>Style table column widths with CSS rule, not "width" argument.</p></li> +<li><p>Vertical alignment of table heads with CSS.</p></li> +<li><p>Field lists as styled definition lists.</p></li> +<li><p>Do not drop paragraph objects, use CSS rules to prevent unwanted vertical +space.</p></li> +<li><p>Put subtitles in <p> elements.</p></li> +</ul> +<div class="section" id="description-list"> +<h2><a class="toc-backref" href="#id81"><span class="sectnum">3.1</span> Description list</a></h2> +<p>Definition lists with the <span class="docutils literal">description</span> class argument:</p> +<dl class="description simple"> +<dt>description lists</dt> +<dd><p>Lists that are styled like in most dictionaries, encyclopedias +etc. (as well as the LaTeX <cite>description</cite> environment).</p> +</dd> +<dt>label</dt> +<dd><p>The term to be described. Put in boldface.</p> +</dd> +<dt>content</dt> +<dd><p>starts on the same line and has a hanging indent.</p> +</dd> +</dl> +</div> +<div class="section" id="field-list-handling"> +<h2><a class="toc-backref" href="#id82"><span class="sectnum">3.2</span> Field list handling</a></h2> +<p>The following list demonstrates the problems with the html4css1 +approach: the <cite>field-name-limit</cite> setting is given in "number of +characters" but the field name uses a proportional font.</p> +<dl class="field-list simple"> +<dt>The field name</dt> +<dd><p>is typeset on the same line, unless it is "long".</p> +</dd> +<dt>this field name</dt> +<dd><p>is considered "long" in the html table rendering by +the html4css1 writer with the default setting of +<span class="docutils literal"><span class="pre">--field-name-limit=14</span></span>.</p> +</dd> +<dt>iiiiiiiiiiiiiii</dt> +<dd><p>a field name that is considered "long" by html4css1 +with the default setting of <cite>field-name-limit: 14</cite>.</p> +</dd> +<dt>MMMMMMMMMMMMMM</dt> +<dd><p>a field name that is actually longer than the +previous one but regarded "short" by html4css1.</p> +</dd> +</dl> +<p>With <cite>html4css2</cite>, a <cite>field list</cite> is typeset as CSS-styled <cite>definition +list</cite>. The default layout is similar to the look with <cite>html4css1</cite>:</p> +<dl class="open field-list"> +<dt>A long field name</dt> +<dd><p>sticks into the field body.</p> +<p>The field body is pushed to the next line (you can suppress +this behaviour with the <a class="reference internal" href="#run-in">run-in</a> class argument).</p> +</dd> +<dt>Customization</dt> +<dd><p>of the field name width is possible with CSS instead +of the <cite>field-name-limit</cite> configuration setting, for +example:</p> +<pre class="literal-block">dl.field-list > dd { margin-left: 6em; } +</pre> +</dd> +</dl> +<div class="section" id="styling-with-class-arguments"> +<h3><a class="toc-backref" href="#id83"><span class="sectnum">3.2.1</span> Styling with class arguments</a></h3> +<p>The <span class="docutils literal">xhtml11.css</span> style sheet supports the following class arguments +for alternative styles:</p> +<dl class="simple"> +<dt><em>compact</em></dt> +<dd><dl class="compact field-list simple"> +<dt>Feature</dt> +<dd><p>No additional space between list items.</p> +</dd> +<dt>Option</dt> +<dd><p>The <span class="docutils literal"><span class="pre">--compact-field-lists</span></span> command line option (and the +corresponding configuration setting) set the <cite>compact</cite> +class argument on all "simple" field lists, if not +overridden with <cite>open</cite>.</p> +</dd> +<dt>Use</dt> +<dd><p>For lists with short field body.</p> +</dd> +</dl> +</dd> +<dt><em>open</em></dt> +<dd><dl class="open field-list"> +<dt>Feature</dt> +<dd><p>Additional space between list items also in "simple" lists. +(Overrides the <span class="docutils literal"><span class="pre">--compact-field-lists</span></span> command line +option and the corresponding configuration setting)</p> +</dd> +<dt>Use</dt> +<dd><p>For "simple" lists that should keep the space between list items.</p> +</dd> +</dl> +</dd> +<dt><em>narrow</em></dt> +<dd><dl class="narrow field-list simple"> +<dt>Feature</dt> +<dd><p>Less indented field body.</p> +</dd> +<dt>Use</dt> +<dd><p>For lists with short field names.</p> +</dd> +<dt>A long field name</dt> +<dd><p>sticks into the field body and the field body starts on a +new line (if not combined with <a class="reference internal" href="#run-in">run-in</a>).</p> +</dd> +</dl> +</dd> +</dl> +<dl class="simple" id="run-in"> +<dt><em>run-in</em></dt> +<dd><dl class="run-in field-list simple"> +<dt>Feature</dt> +<dd><p>Field body starts on the same line also after long field +names.</p> +</dd> +<dt>A long field name</dt> +<dd><p>sticks into the field body which continues on +the same line.</p> +</dd> +<dt>The next field name</dt> +<dd><p>and field body should align. Long text in the field +body is wrapped and aligns with other fields.</p> +</dd> +</dl> +</dd> +</dl> +</div> +</div> +<div class="section" id="table-styling-with-class-arguments"> +<h2><a class="toc-backref" href="#id84"><span class="sectnum">3.3</span> Table styling with class arguments</a></h2> +<p>The <span class="docutils literal"><span class="pre">html-base.css</span></span> style sheet provides rules for easy styling of tables +with the "class" directive or directive argument.</p> +<p>Numbered tables can be achieved with the <span class="docutils literal">numbered</span> class option</p> +<table class="numbered"> +<caption>truth values</caption> +<colgroup> +<col style="width: 29%" /> +<col style="width: 29%" /> +<col style="width: 42%" /> +</colgroup> +<thead> +<tr><th class="head"><p>A</p></th> +<th class="head"><p>B</p></th> +<th class="head"><p>A or B</p></th> +</tr> +</thead> +<tbody> +<tr><td><p>False</p></td> +<td><p>False</p></td> +<td><p>False</p></td> +</tr> +<tr><td><p>True</p></td> +<td><p>False</p></td> +<td><p>True</p></td> +</tr> +<tr><td><p>False</p></td> +<td><p>True</p></td> +<td><p>True</p></td> +</tr> +<tr><td><p>True</p></td> +<td><p>True</p></td> +<td><p>True</p></td> +</tr> +</tbody> +</table> +<p>Currently, referencing to the table by number is not supported. This is a +common request and already on the <cite>TODO list</cite>.</p> +<p>In addition to the "borderless" <a class="reference external" href="http://docutils.sourceforge.net/docs/user/config.html#table-style">table-style</a> <a class="footnote-reference" href="#id31" id="id32">[7]</a>, the style sheet also +defines "booktabs", that will be rendered similar to the style from +the <a class="reference external" href="http://tug.ctan.org/tex-archive/macros/latex/contrib/booktabs/booktabs.pdf">booktabs</a> <a class="footnote-reference" href="#id33" id="id34">[8]</a> LaTeX package.</p> +<table class="booktabs"> +<colgroup> +<col style="width: 31%" /> +<col style="width: 31%" /> +<col style="width: 38%" /> +</colgroup> +<tbody> +<tr><td><p>False</p></td> +<td><p>False</p></td> +<td><p>False</p></td> +</tr> +<tr><td><p>True</p></td> +<td><p>False</p></td> +<td><p>True</p></td> +</tr> +<tr><td><p>False</p></td> +<td><p>True</p></td> +<td><p>True</p></td> +</tr> +<tr><td><p>True</p></td> +<td><p>True</p></td> +<td><p>True</p></td> +</tr> +</tbody> +</table> +<p>This table also uses the "align-left" class argument, to left-align +the headers:</p> +<table class="booktabs align-left"> +<colgroup> +<col style="width: 29%" /> +<col style="width: 29%" /> +<col style="width: 41%" /> +</colgroup> +<thead> +<tr><th class="head"><p>A</p></th> +<th class="head"><p>B</p></th> +<th class="head"><p>A or B</p></th> +</tr> +</thead> +<tbody> +<tr><td><p>False</p></td> +<td><p>False</p></td> +<td><p>False</p></td> +</tr> +<tr><td><p>True</p></td> +<td><p>False</p></td> +<td><p>True</p></td> +</tr> +<tr><td><p>False</p></td> +<td><p>True</p></td> +<td><p>True</p></td> +</tr> +<tr><td><p>True</p></td> +<td><p>True</p></td> +<td><p>True</p></td> +</tr> +</tbody> +</table> +<p>Of course, also "booktabs" style tables can be numbered:</p> +<table class="numbered booktabs"> +<caption>I/O values</caption> +<colgroup> +<col style="width: 31%" /> +<col style="width: 31%" /> +<col style="width: 38%" /> +</colgroup> +<thead> +<tr><th class="head" colspan="2"><p>Inputs</p></th> +<th class="head"><p>Output</p></th> +</tr> +<tr><th class="head"><p>A</p></th> +<th class="head"><p>B</p></th> +<th class="head"><p>A or B</p></th> +</tr> +</thead> +<tbody> +<tr><td><p>False</p></td> +<td><p>False</p></td> +<td><p>False</p></td> +</tr> +<tr><td><p>True</p></td> +<td><p>False</p></td> +<td><p>True</p></td> +</tr> +<tr><td><p>False</p></td> +<td><p>True</p></td> +<td><p>True</p></td> +</tr> +<tr><td><p>True</p></td> +<td><p>True</p></td> +<td><p>True</p></td> +</tr> +</tbody> +</table> +</div> +<div class="section" id="maths"> +<h2><a class="toc-backref" href="#id85"><span class="sectnum">3.4</span> Maths</a></h2> +<p>For maximal compatibility, the <span class="docutils literal"><span class="pre">html-output</span></span> setting defaults to »HTML«. +(HTML 5 accepts also MathML and SVG as nested languages.)</p> +<p>The linear mapping <span class="formula"><i>f</i> : ℂ<sup><i>N</i></sup>⟼ℂ<sup><i>N</i></sup></span> +with</p> +<div class="formula"> +<i>c</i><sub><i>k</i></sub> = <i>F</i>(<i>kf</i><sub>0</sub>) = <i>T</i><sub><span class="text">A</span></sub><span class="limits"><sup class="limit"> + <i>N</i> ⁄ 2</sup><span class="limit">⎲</span><span class="limit">⎳</span><sub class="limit"><i>n</i> = − <i>N</i> ⁄ 2</sub></span><i>f</i>(<i>x</i><sub><i>n</i></sub>)<span class="text">e</span><sup> − 2<i>π</i><span class="text">i</span><span class="fraction"><span class="ignored">(</span><span class="numerator"><i>nk</i></span><span class="ignored">)/(</span><span class="denominator"><i>N</i></span><span class="ignored">)</span></span></sup> +</div> +<p>for all <span class="formula"><i>a</i> ∈ ℂ<sup><i>N</i></sup></span> is called discrete Fourier +transformation (DFT).</p> +</div> +</div> +<div class="section" id="error-handling"> +<h1><a class="toc-backref" href="#id86"><span class="sectnum">4</span> Error Handling</a></h1> +<p>Any errors caught during processing will generate system messages.</p> +<p>There should be five messages in the following, auto-generated +section, "Docutils System Messages":</p> +<!-- section should be added by Docutils automatically --> +</div> +<div class="system-messages section"> +<h1>Docutils System Messages</h1> +<div class="system-message" id="id23"> +<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 104); <em><a href="#id24">backlink</a></em></p> +<p>Undefined substitution referenced: "problematic".</p> +</div> +<div class="system-message" id="id96"> +<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 391); <em><a href="#id97">backlink</a></em></p> +<p>Unknown target name: "5".</p> +</div> +<div class="system-message" id="id98"> +<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 400); <em><a href="#id99">backlink</a></em></p> +<p>Unknown target name: "nonexistent".</p> +</div> +<div class="system-message" id="id100"> +<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 427); <em><a href="#id101">backlink</a></em></p> +<p>Unknown target name: "hyperlink reference without a target".</p> +</div> +<div class="system-message" id="id102"> +<p class="system-message-title">System Message: ERROR/3 (<span class="docutils literal">functional/input/data/standard.txt</span>, line 440); <em><a href="#id103">backlink</a></em></p> +<p>Duplicate target name, cannot be used as a unique reference: "duplicate target names".</p> +</div> +</div> +</div> +<div class="footer"> +<hr class="footer" /> +<p>Document footer</p> +<p><a class="reference external" href="http://validator.w3.org/check?uri=referer"><img alt="Conforms to HTML 5!" src="https://validator-suite.w3.org/icons/vs-blue-256.png" style="width: 88px; height: 31px;" /></a> <a class="reference external" href="http://jigsaw.w3.org/css-validator/check/referer"><img alt="Valid CSS 2.1!" src="http://jigsaw.w3.org/css-validator/images/vcss" style="width: 88px; height: 31px;" /></a></p> + +</div> +</body> +</html> diff --git a/docutils/test/functional/input/standalone_rst_html_base.txt b/docutils/test/functional/input/standalone_rst_html_base.txt new file mode 100644 index 000000000..81b72b0bd --- /dev/null +++ b/docutils/test/functional/input/standalone_rst_html_base.txt @@ -0,0 +1,234 @@ +.. include:: data/standard.txt +.. include:: data/header_footer.txt +.. include:: data/table_colspan.txt +.. include:: data/table_rowspan.txt +.. include:: data/table_complex.txt +.. include:: data/list_table.txt +.. include:: data/custom_roles.txt +.. include:: data/svg_images.txt +.. include:: data/swf_images.txt + +Changes to the html4css1 writer +=============================== + +* Use only meta keywords recognized by HTML 5. + +* Style table column widths with CSS rule, not "width" argument. + +* Vertical alignment of table heads with CSS. + +* Field lists as styled definition lists. + +* Do not drop paragraph objects, use CSS rules to prevent unwanted vertical + space. + +* Put subtitles in <p> elements. + +Description list +---------------- + +Definition lists with the ``description`` class argument: + +.. class:: description + +description lists + Lists that are styled like in most dictionaries, encyclopedias + etc. (as well as the LaTeX `description` environment). +label + The term to be described. Put in boldface. +content + starts on the same line and has a hanging indent. + + +Field list handling +------------------- + +The following list demonstrates the problems with the html4css1 +approach: the `field-name-limit` setting is given in "number of +characters" but the field name uses a proportional font. + +:The field name: is typeset on the same line, unless it is "long". + +:this field name: is considered "long" in the html table rendering by + the html4css1 writer with the default setting of + ``--field-name-limit=14``. + +:iiiiiiiiiiiiiii: a field name that is considered "long" by html4css1 + with the default setting of `field-name-limit: 14`. + +:MMMMMMMMMMMMMM: a field name that is actually longer than the + previous one but regarded "short" by html4css1. + +With `html4css2`, a `field list` is typeset as CSS-styled `definition +list`. The default layout is similar to the look with `html4css1`: + +.. class:: open + +:A long field name: sticks into the field body. + + The field body is pushed to the next line (you can suppress + this behaviour with the `run-in`_ class argument). + +:Customization: of the field name width is possible with CSS instead + of the `field-name-limit` configuration setting, for + example:: + + dl.field-list > dd { margin-left: 6em; } + +Styling with class arguments +```````````````````````````` + +The ``xhtml11.css`` style sheet supports the following class arguments +for alternative styles: + +*compact* + .. class:: compact + + :Feature: No additional space between list items. + + :Option: The ``--compact-field-lists`` command line option (and the + corresponding configuration setting) set the `compact` + class argument on all "simple" field lists, if not + overridden with `open`. + + :Use: For lists with short field body. + +*open* + .. class:: open + + :Feature: Additional space between list items also in "simple" lists. + (Overrides the ``--compact-field-lists`` command line + option and the corresponding configuration setting) + + :Use: For "simple" lists that should keep the space between list items. + +*narrow* + .. class:: narrow + + :Feature: Less indented field body. + :Use: For lists with short field names. + :A long field name: + sticks into the field body and the field body starts on a + new line (if not combined with `run-in`_). + +.. _`run-in`: + +*run-in* + .. class:: run-in + + :Feature: Field body starts on the same line also after long field + names. + + :A long field name: sticks into the field body which continues on + the same line. + + :The next field name: and field body should align. Long text in the field + body is wrapped and aligns with other fields. + + +Table styling with class arguments +---------------------------------- + +The ``html-base.css`` style sheet provides rules for easy styling of tables +with the "class" directive or directive argument. + +Numbered tables can be achieved with the ``numbered`` class option + +.. table:: truth values + :class: numbered + + ======= ======= ========== + A B A or B + ======= ======= ========== + False False False + True False True + False True True + True True True + ======= ======= ========== + +Currently, referencing to the table by number is not supported. This is a +common request and already on the `TODO list`. + +In addition to the "borderless" table-style_, the style sheet also +defines "booktabs", that will be rendered similar to the style from +the booktabs_ LaTeX package. + +.. _table-style: + http://docutils.sourceforge.net/docs/user/config.html#table-style +.. _booktabs: + http://tug.ctan.org/tex-archive/macros/latex/contrib/booktabs/booktabs.pdf + +.. class:: booktabs + +===== ===== ====== +False False False +True False True +False True True +True True True +===== ===== ====== + +This table also uses the "align-left" class argument, to left-align +the headers: + +.. class:: booktabs align-left + +===== ===== ======= + A B A or B +===== ===== ======= +False False False +True False True +False True True +True True True +===== ===== ======= + + +Of course, also "booktabs" style tables can be numbered: + +.. table:: I/O values + :class: numbered booktabs + + ===== ===== ====== + Inputs Output + ------------ ------ + A B A or B + ===== ===== ====== + False False False + True False True + False True True + True True True + ===== ===== ====== + + +Maths +----- + +For maximal compatibility, the ``html-output`` setting defaults to »HTML«. +(HTML 5 accepts also MathML and SVG as nested languages.) + +The linear mapping :math:`f: \mathbb{C}^{N}\longmapsto\mathbb{C}^{N}` +with + +.. math:: + + c_{k}=F(kf_{0})=T_{\text{A}} + \sum_{n=-N/2}^{+N/2}f(x_{n})\text{e}^{-2\pi\text{i}\frac{nk}{N}} + +for all :math:`a\in\mathbb{C}^{N}` is called discrete Fourier +transformation (DFT). + + +.. include:: data/errors.txt + +.. footer:: |validator| |valid-CSS2| + +.. |validator| image:: https://validator-suite.w3.org/icons/vs-blue-256.png + :height: 31 + :width: 88 + :alt: Conforms to HTML 5! + :target: http://validator.w3.org/check?uri=referer + +.. |valid-CSS2| image:: http://jigsaw.w3.org/css-validator/images/vcss + :height: 31 + :width: 88 + :alt: Valid CSS 2.1! + :target: http://jigsaw.w3.org/css-validator/check/referer |