diff options
Diffstat (limited to 'docs/user/rst')
| -rw-r--r-- | docs/user/rst/cheatsheet.txt | 125 | ||||
| -rw-r--r-- | docs/user/rst/demo.txt | 552 | ||||
| -rw-r--r-- | docs/user/rst/images/ball1.gif | bin | 0 -> 4361 bytes | |||
| -rw-r--r-- | docs/user/rst/images/biohazard.png | bin | 0 -> 179 bytes | |||
| -rw-r--r-- | docs/user/rst/images/title.png | bin | 0 -> 1171 bytes | |||
| -rw-r--r-- | docs/user/rst/quickref.html | 1352 | ||||
| -rw-r--r-- | docs/user/rst/quickstart.txt | 387 |
7 files changed, 2416 insertions, 0 deletions
diff --git a/docs/user/rst/cheatsheet.txt b/docs/user/rst/cheatsheet.txt new file mode 100644 index 000000000..dfea5bcb7 --- /dev/null +++ b/docs/user/rst/cheatsheet.txt @@ -0,0 +1,125 @@ +===================================================== + The reStructuredText_ Cheat Sheet: Syntax Reminders +===================================================== +:Info: See <http://docutils.sf.net/rst.html> for introductory docs. +:Author: David Goodger <goodger@python.org> +:Date: $Date$ +:Revision: $Revision$ +:Description: This is a "docinfo block", or bibliographic field list + +Section Structure +================= +Section titles are underlined or overlined & underlined. + +Body Elements +============= +Grid table: + ++--------------------------------+-----------------------------------+ +| Paragraphs are flush-left, | Literal block, preceded by "::":: | +| separated by blank lines. | | +| | Indented | +| Block quotes are indented. | | ++--------------------------------+ or:: | +| >>> print 'Doctest block' | | +| Doctest block | > Quoted | ++--------------------------------+-----------------------------------+ +| | Line blocks preserve line breaks & indents. [new in 0.3.6] | +| | Useful for addresses, verse, and adornment-free lists; long | +| lines can be wrapped with continuation lines. | ++--------------------------------------------------------------------+ + +Simple tables: + +================ ============================================================ +List Type Examples +================ ============================================================ +Bullet list * items begin with "-", "+", or "*" +Enumerated list 1. items use any variation of "1.", "A)", and "(i)" + #. also auto-enumerated +Definition list Term is flush-left : optional classifier + Definition is indented, no blank line between +Field list :field name: field body +Option list -o at least 2 spaces between option & description +================ ============================================================ + +================ ============================================================ +Explicit Markup Examples (visible in the `text source <cheatsheet.txt>`_) +================ ============================================================ +Footnote .. [1] Manually numbered or [#] auto-numbered + (even [#labelled]) or [*] auto-symbol +Citation .. [CIT2002] A citation. +Hyperlink Target .. _reStructuredText: http://docutils.sf.net/rst.html + .. _indirect target: reStructuredText_ + .. _internal target: +Anonymous Target __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html +Directive ("::") .. image:: images/biohazard.png +Substitution Def .. |substitution| replace:: like an inline directive +Comment .. is anything else +================ ============================================================ + +Inline Markup +============= +*emphasis*; **strong emphasis**; `interpreted text`; `interpreted text +with role`:emphasis:; ``inline literal text``; standalone hyperlink, +http://docutils.sourceforge.net; named reference, reStructuredText_; +`anonymous reference`__; footnote reference, [1]_; citation reference, +[CIT2002]_; |substitution|; _`inline internal target`. + +Directive Quick Reference +========================= +See <http://docutils.sf.net/docs/ref/rst/directives.html> for full info. + +================ ============================================================ +Directive Name Description (Docutils version added to, in [brackets]) +================ ============================================================ +attention Specific admonition; also "caution", "danger", + "error", "hint", "important", "note", "tip", "warning" +admonition Generic titled admonition: ``.. admonition:: By The Way`` +image ``.. image:: picture.png``; many options possible +figure Like "image", but with optional caption and legend +topic ``.. topic:: Title``; like a mini section +sidebar ``.. sidebar:: Title``; like a mini parallel document +parsed-literal A literal block with parsed inline markup +rubric ``.. rubric:: Informal Heading`` +epigraph Block quote with class="epigraph" +highlights Block quote with class="highlights" +pull-quote Block quote with class="pull-quote" +compound Compound paragraphs [0.3.6] +container Generic block-level container element [0.3.10] +table Create a titled table [0.3.1] +list-table Create a table from a uniform two-level bullet list [0.3.8] +csv-table Create a table from CSV data (requires Python 2.3+) [0.3.4] +contents Generate a table of contents +sectnum Automatically number sections, subsections, etc. +header, footer Create document decorations [0.3.8] +target-notes Create an explicit footnote for each external target +meta HTML-specific metadata +include Read an external reST file as if it were inline +raw Non-reST data passed untouched to the Writer +replace Replacement text for substitution definitions +unicode Unicode character code conversion for substitution defs +date Generates today's date; for substitution defs +class Set a "class" attribute on the next element +role Create a custom interpreted text role [0.3.2] +default-role Set the default interpreted text role [0.3.10] +title Set the metadata document title [0.3.10] +================ ============================================================ + +Interpreted Text Role Quick Reference +===================================== +See <http://docutils.sf.net/docs/ref/rst/roles.html> for full info. + +================ ============================================================ +Role Name Description +================ ============================================================ +emphasis Equivalent to *emphasis* +literal Equivalent to ``literal`` but processes backslash escapes +PEP Reference to a numbered Python Enhancement Proposal +RFC Reference to a numbered Internet Request For Comments +raw For non-reST data; cannot be used directly (see docs) [0.3.6] +strong Equivalent to **strong** +sub Subscript +sup Superscript +title Title reference (book, etc.); standard default role +================ ============================================================ diff --git a/docs/user/rst/demo.txt b/docs/user/rst/demo.txt new file mode 100644 index 000000000..7a0abd033 --- /dev/null +++ b/docs/user/rst/demo.txt @@ -0,0 +1,552 @@ +.. This is a comment. Note how any initial comments are moved by + transforms to after the document title, subtitle, and docinfo. + +================================ + reStructuredText Demonstration +================================ + +.. Above is the document title, and below is the subtitle. + They are transformed from section titles after parsing. + +-------------------------------- + Examples of Syntax Constructs +-------------------------------- + +.. bibliographic fields (which also require a transform): + +:Author: David Goodger +:Address: 123 Example Street + Example, EX Canada + A1B 2C3 +:Contact: goodger@users.sourceforge.net +:Authors: Me; Myself; I +:organization: humankind +:date: $Date$ +:status: This is a "work in progress" +:revision: $Revision$ +:version: 1 +: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. +:field name: This is a generic bibliographic field. +:field name 2: + Generic bibliographic fields may contain multiple body elements. + + Like this. + +:Dedication: + + For Docutils users & co-developers. + +:abstract: + + This document is a demonstration of the reStructuredText markup + language, containing examples of all basic reStructuredText + constructs and many advanced constructs. + +.. meta:: + :keywords: reStructuredText, demonstration, demo, parser + :description lang=en: A demonstration of the reStructuredText + markup language, containing examples of all basic + constructs and many advanced constructs. + +.. contents:: Table of Contents +.. section-numbering:: + + +Structural Elements +=================== + +Section Title +------------- + +That's it, the text just above this line. + +Transitions +----------- + +Here's a transition: + +--------- + +It divides the section. + +Body Elements +============= + +Paragraphs +---------- + +A paragraph. + +Inline Markup +````````````` + +Paragraphs contain text and may contain inline markup: *emphasis*, +**strong emphasis**, ``inline literals``, standalone hyperlinks +(http://www.python.org), external hyperlinks (Python_), internal +cross-references (example_), external hyperlinks with embedded URIs +(`Python web site <http://www.python.org>`__), footnote references +(manually numbered [1]_, anonymous auto-numbered [#]_, labeled +auto-numbered [#label]_, or symbolic [*]_), citation references +([CIT2002]_), substitution references (|example|), and _`inline +hyperlink targets` (see Targets_ below for a reference back to here). +Character-level inline markup is also possible (although exceedingly +ugly!) in *re*\ ``Structured``\ *Text*. Problems are indicated by +|problematic| text (generated by processing errors; this one is +intentional). + +The default role for interpreted text is `Title Reference`. Here are +some explicit interpreted text roles: a PEP reference (:PEP:`287`); an +RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`; +and explicit roles for :emphasis:`standard` :strong:`inline` +:literal:`markup`. + +.. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! + +Let's test wrapping and whitespace significance in inline literals: +``This is an example of --inline-literal --text, --including some-- +strangely--hyphenated-words. Adjust-the-width-of-your-browser-window +to see how the text is wrapped. -- ---- -------- Now note the +spacing between the words of this sentence (words +should be grouped in pairs).`` + +If the ``--pep-references`` option was supplied, there should be a +live link to PEP 258 here. + +Bullet Lists +------------ + +- A bullet list + + + Nested bullet list. + + Nested item 2. + +- Item 2. + + Paragraph 2 of item 2. + + * Nested bullet list. + * Nested item 2. + + - Third level. + - Item 2. + + * Nested item 3. + +Enumerated Lists +---------------- + +1. Arabic numerals. + + a) lower alpha) + + (i) (lower roman) + + A. upper alpha. + + I) upper roman) + +2. Lists that don't start at 1: + + 3. Three + + 4. Four + + C. C + + D. D + + iii. iii + + iv. iv + +#. List items may also be auto-enumerated. + +Definition Lists +---------------- + +Term + Definition +Term : classifier + Definition paragraph 1. + + Definition paragraph 2. +Term + Definition + +Field Lists +----------- + +:what: 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. + +:how arg1 arg2: + + The field marker is a colon, the field name, and a colon. + + The field body may contain one or more body elements, indented + relative to the field marker. + +Option Lists +------------ + +For listing command-line options: + +-a command-line option "a" +-b file options can have arguments + and long descriptions +--long options can be long also +--input=file long options can also have + arguments + +--very-long-option + The description can also start on the next line. + + The description may contain multiple body elements, + regardless of where it starts. + +-x, -y, -z Multiple options are an "option group". +-v, --verbose Commonly-seen: short & long options. +-1 file, --one=file, --two file + Multiple options with arguments. +/V DOS/VMS-style options too + +There must be at least two spaces between the option and the +description. + +Literal Blocks +-------------- + +Literal blocks are indicated with a double-colon ("::") at the end of +the preceding paragraph (over there ``-->``). They can be indented:: + + if literal_block: + text = 'is left as-is' + spaces_and_linebreaks = 'are preserved' + markup_processing = None + +Or they can be quoted without indentation:: + +>> Great idea! +> +> Why didn't I think of that? + +Line Blocks +----------- + +| This is a line block. It ends with a blank line. +| Each new line begins with a vertical bar ("|"). +| Line breaks and initial indents are preserved. +| Continuation lines are wrapped portions of long lines; + they begin with a space in place of the vertical bar. +| The left edge of a continuation line need not be aligned with + the left edge of the text above it. + +| This is a second line block. +| +| Blank lines are permitted internally, but they must begin with a "|". + +Take it away, Eric the Orchestra Leader! + + | A one, two, a one two three four + | + | Half a bee, philosophically, + | must, *ipso facto*, half not be. + | But half the bee has got to be, + | *vis a vis* its entity. D'you see? + | + | But can a bee be said to be + | or not to be an entire bee, + | when half the bee is not a bee, + | due to some ancient injury? + | + | Singing... + +Block Quotes +------------ + +Block quotes consist of indented body elements: + + 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. + + -- Anne Elk (Miss) + +Doctest Blocks +-------------- + +>>> 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) + +Tables +------ + +Here's a grid table followed by a simple table: + ++------------------------+------------+----------+----------+ +| Header row, column 1 | Header 2 | Header 3 | Header 4 | +| (header rows optional) | | | | ++========================+============+==========+==========+ +| body row 1, column 1 | column 2 | column 3 | column 4 | ++------------------------+------------+----------+----------+ +| body row 2 | Cells may span columns. | ++------------------------+------------+---------------------+ +| body row 3 | Cells may | - Table cells | ++------------------------+ span rows. | - contain | +| body row 4 | | - body elements. | ++------------------------+------------+----------+----------+ +| body row 5 | Cells may also be | | +| | empty: ``-->`` | | ++------------------------+-----------------------+----------+ + +===== ===== ====== + Inputs Output +------------ ------ + A B A or B +===== ===== ====== +False False False +True False True +False True True +True True True +===== ===== ====== + +Footnotes +--------- + +.. [1] A footnote contains body elements, consistently indented by at + least 3 spaces. + + This is the footnote's second paragraph. + +.. [#label] Footnotes may be numbered, either manually (as in [1]_) 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 ([#label]_) and as a hyperlink reference + (label_). + +.. [#] This footnote is numbered automatically and anonymously using a + label of "#" only. + +.. [*] Footnotes may also use symbols, specified with a "*" label. + Here's a reference to the next footnote: [*]_. + +.. [*] This footnote shows the next symbol in the sequence. + +.. [4] Here's an unreferenced footnote, with a reference to a + nonexistent footnote: [5]_. + +Citations +--------- + +.. [CIT2002] Citations are text-labeled footnotes. They may be + rendered separately and differently from footnotes. + +Here's a reference to the above, [CIT2002]_, and a [nonexistent]_ +citation. + +Targets +------- + +.. _example: + +This paragraph is pointed to by the explicit "example" target. A +reference can be found under `Inline Markup`_, above. `Inline +hyperlink targets`_ are also possible. + +Section headers are implicit targets, referred to by name. See +Targets_, which is a subsection of `Body Elements`_. + +Explicit external targets are interpolated into references such as +"Python_". + +.. _Python: http://www.python.org/ + +Targets may be indirect and anonymous. Thus `this phrase`__ may also +refer to the Targets_ section. + +__ Targets_ + +Here's a `hyperlink reference without a target`_, which generates an +error. + +Duplicate Target Names +`````````````````````` + +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. + +Duplicate Target Names +`````````````````````` + +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: `Duplicate Target Names`_), an error is generated. + +Directives +---------- + +.. contents:: :local: + +These are just a sample of the many reStructuredText Directives. For +others, please see +http://docutils.sourceforge.net/docs/ref/rst/directives.html. + +Document Parts +`````````````` + +An example of the "contents" directive can be seen above this section +(a local, untitled table of contents_) and at the beginning of the +document (a document-wide `table of contents`_). + +Images +`````` + +An image directive (also clickable -- a hyperlink reference): + +.. image:: images/title.png + :target: directives_ + +A figure directive: + +.. figure:: images/title.png + :alt: reStructuredText, the markup syntax + + A figure is an image with a caption and/or a legend: + + +------------+-----------------------------------------------+ + | re | Revised, revisited, based on 're' module. | + +------------+-----------------------------------------------+ + | Structured | Structure-enhanced text, structuredtext. | + +------------+-----------------------------------------------+ + | Text | Well it is, isn't it? | + +------------+-----------------------------------------------+ + + This paragraph is also part of the legend. + +Admonitions +``````````` + +.. Attention:: Directives at large. + +.. Caution:: + + Don't take any wooden nickels. + +.. DANGER:: Mad scientist at work! + +.. Error:: Does not compute. + +.. Hint:: It's bigger than a bread box. + +.. Important:: + - Wash behind your ears. + - Clean up your room. + - Call your mother. + - Back up your data. + +.. Note:: This is a note. + +.. Tip:: 15% if the service is good. + +.. WARNING:: Strong prose may provoke extreme mental exertion. + Reader discretion is strongly advised. + +.. admonition:: And, by the way... + + You can make up your own admonition too. + +Topics, Sidebars, and Rubrics +````````````````````````````` + +.. sidebar:: Sidebar Title + :subtitle: Optional Subtitle + + This is a sidebar. It is for text outside the flow of the main + text. + + .. rubric:: This is a rubric inside a sidebar + + Sidebars often appears beside the main text with a border and + background color. + +.. topic:: Topic Title + + This is a topic. + +.. rubric:: This is a rubric + +Target Footnotes +```````````````` + +.. target-notes:: + +Replacement Text +```````````````` + +I recommend you try |Python|_. + +.. |Python| replace:: Python, *the* best language around + +Compound Paragraph +`````````````````` + +.. compound:: + + This paragraph contains a literal block:: + + Connecting... OK + Transmitting data... OK + Disconnecting... OK + + and thus consists of a simple paragraph, a literal block, and + another simple paragraph. Nonetheless it is semantically *one* + paragraph. + +This construct is called a *compound paragraph* and can be produced +with the "compound" directive. + +Substitution Definitions +------------------------ + +An inline image (|example|) example: + +.. |EXAMPLE| image:: images/biohazard.png + +(Substitution definitions are not visible in the HTML source.) + +Comments +-------- + +Here's one: + +.. 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. + +(View the HTML source to see the comment.) + +Error Handling +============== + +Any errors caught during processing will generate system messages. + +|*** Expect 6 errors (including this one). ***| + +There should be six messages in the following, auto-generated +section, "Docutils System Messages": + +.. section should be added by Docutils automatically diff --git a/docs/user/rst/images/ball1.gif b/docs/user/rst/images/ball1.gif Binary files differnew file mode 100644 index 000000000..3e14441d9 --- /dev/null +++ b/docs/user/rst/images/ball1.gif diff --git a/docs/user/rst/images/biohazard.png b/docs/user/rst/images/biohazard.png Binary files differnew file mode 100644 index 000000000..ae4629d8b --- /dev/null +++ b/docs/user/rst/images/biohazard.png diff --git a/docs/user/rst/images/title.png b/docs/user/rst/images/title.png Binary files differnew file mode 100644 index 000000000..cc6218efe --- /dev/null +++ b/docs/user/rst/images/title.png diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html new file mode 100644 index 000000000..604cfe6bc --- /dev/null +++ b/docs/user/rst/quickref.html @@ -0,0 +1,1352 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> + +<html> + <head> + <title>Quick reStructuredText</title> + <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> + + <style type="text/css"><!-- + a.backref { text-decoration: none ; color: black } + div.line-block { display: block } + div.line-block div.line-block { margin-left: 1.5em } + --></style> + + </head> + + <body> + <h1>Quick <i>re</i><font size="+4"><tt>Structured</tt></font><i>Text</i></h1> + + <!-- Caveat: if you're reading the HTML for the examples, --> + <!-- beware that it was hand-generated, not by Docutils/ReST. --> + + <p align="right"><em><a href="http://docutils.sourceforge.net/docs/user/rst/quickref.html" + >http://docutils.sourceforge.net/docs/user/rst/quickref.html</a></em> + <br><em>Being a cheat-sheet for reStructuredText</em> + <br><em>Updated $Date$</em> + + <blockquote> + <p>Copyright: This document has been placed in the public domain. + </blockquote> + + + <p>The full details of the markup may be found on the + <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> + page. This document is just intended as a reminder. + + <p>Links that look like "(<a href="#details">details</a>)" point + into the HTML version of the full <a + href="../../ref/rst/restructuredtext.html">reStructuredText + specification</a> document. These are relative links; if they + don't work, please use the <a + href="http://docutils.sourceforge.net/docs/user/rst/quickref.html" + >master "Quick reStructuredText"</a> document. + + <h2><a name="contents">Contents</a></h2> + + <ul> + <li><a href="#inline-markup">Inline Markup</a></li> + <li><a href="#escaping">Escaping with Backslashes</a></li> + <li><a href="#section-structure">Section Structure</a></li> + <li><a href="#paragraphs">Paragraphs</a></li> + <li><a href="#bullet-lists">Bullet Lists</a></li> + <li><a href="#enumerated-lists">Enumerated Lists</a></li> + <li><a href="#definition-lists">Definition Lists</a></li> + <li><a href="#field-lists">Field Lists</a></li> + <li><a href="#option-lists">Option Lists</a></li> + <li><a href="#literal-blocks">Literal Blocks</a></li> + <li><a href="#line-blocks">Line Blocks</a></li> + <li><a href="#block-quotes">Block Quotes</a></li> + <li><a href="#doctest-blocks">Doctest Blocks</a></li> + <li><a href="#tables">Tables</a></li> + <li><a href="#transitions">Transitions</a></li> + <li><a href="#explicit-markup">Explicit Markup</a> + <ul> + <li><a href="#footnotes">Footnotes</a></li> + <li><a href="#citations">Citations</a></li> + <li><a href="#hyperlink-targets">Hyperlink Targets</a> + <ul> + <li><a href="#external-hyperlink-targets">External Hyperlink Targets</a></li> + <li><a href="#internal-hyperlink-targets">Internal Hyperlink Targets</a></li> + <li><a href="#indirect-hyperlink-targets">Indirect Hyperlink Targets</a></li> + <li><a href="#implicit-hyperlink-targets">Implicit Hyperlink Targets</a></li> + </ul></li> + <li><a href="#directives">Directives</a></li> + <li><a href="#substitution-references-and-definitions">Substitution References and Definitions</a></li> + <li><a href="#comments">Comments</a></li> + </ul></li> + <li><a href="#getting-help">Getting Help</a></li> + </ul> + + <h2><a href="#contents" name="inline-markup" class="backref" + >Inline Markup</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#inline-markup">details</a>) + + <p>Inline markup allows words and phrases within text to have + character styles (like italics and boldface) and functionality + (like hyperlinks). + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th>Plain text + <th>Typical result + <th>Notes + </thead> + <tbody> + <tr valign="top"> + <td nowrap><samp>*emphasis*</samp> + <td><em>emphasis</em> + <td>Normally rendered as italics. + + <tr valign="top"> + <td nowrap><samp>**strong emphasis**</samp> + <td><strong>strong emphasis</strong> + <td>Normally rendered as boldface. + + <tr valign="top"> + <td nowrap><samp>`interpreted text`</samp> + <td>(see note at right) + <td>The rendering and <em>meaning</em> of interpreted text is + domain- or application-dependent. It can be used for things + like index entries or explicit descriptive markup (like program + identifiers). + + <tr valign="top"> + <td nowrap><samp>``inline literal``</samp> + <td><code>inline literal</code> + <td>Normally rendered as monospaced text. Spaces should be + preserved, but line breaks will not be. + + <tr valign="top"> + <td nowrap><samp>reference_</samp> + <td><a href="#hyperlink-targets">reference</a> + <td>A simple, one-word hyperlink reference. See <a + href="#hyperlink-targets">Hyperlink Targets</a>. + + <tr valign="top"> + <td nowrap><samp>`phrase reference`_</samp> + <td><a href="#hyperlink-targets">phrase reference</a> + <td>A hyperlink reference with spaces or punctuation needs to be + quoted with backquotes. See <a + href="#hyperlink-targets">Hyperlink Targets</a>. + + <tr valign="top"> + <td nowrap><samp>anonymous__</samp> + <td><a href="#hyperlink-targets">anonymous</a> + <td>With two underscores instead of one, both simple and phrase + references may be anonymous (the reference text is not repeated + at the target). See <a + href="#hyperlink-targets">Hyperlink Targets</a>. + + <tr valign="top"> + <td nowrap><samp>_`inline internal target`</samp> + <td><a name="inline-internal-target">inline internal target</a> + <td>A crossreference target within text. + See <a href="#hyperlink-targets">Hyperlink Targets</a>. + + <tr valign="top"> + <td nowrap><samp>|substitution reference|</samp> + <td>(see note at right) + <td>The result is substituted in from the <a + href="#substitution-references-and-definitions">substitution + definition</a>. It could be text, an image, a hyperlink, or a + combination of these and others. + + <tr valign="top"> + <td nowrap><samp>footnote reference [1]_</samp> + <td>footnote reference <sup><a href="#footnotes">1</a></sup> + <td>See <a href="#footnotes">Footnotes</a>. + + <tr valign="top"> + <td nowrap><samp>citation reference [CIT2002]_</samp> + <td>citation reference <a href="#citations">[CIT2002]</a> + <td>See <a href="#citations">Citations</a>. + + <tr valign="top"> + <td nowrap><samp>http://docutils.sf.net/</samp> + <td><a href="http://docutils.sf.net/">http://docutils.sf.net/</a> + <td>A standalone hyperlink. + + </table> + + <p>Asterisk, backquote, vertical bar, and underscore are inline + delimiter characters. Asterisk, backquote, and vertical bar act + like quote marks; matching characters surround the marked-up word + or phrase, whitespace or other quoting is required outside them, + and there can't be whitespace just inside them. If you want to use + inline delimiter characters literally, <a href="#escaping">escape + (with backslash)</a> or quote them (with double backquotes; i.e. + use inline literals). + + <p>In detail, the reStructuredText specification says that in + inline markup, the following rules apply to start-strings and + end-strings (inline markup delimiters): + + <ol> + <li>The start-string must start a text block or be + immediately preceded by whitespace or any of + <samp>' " ( [ {</samp> or <samp><</samp>. + <li>The start-string must be immediately followed by non-whitespace. + <li>The end-string must be immediately preceded by non-whitespace. + <li>The end-string must end a text block (end of document or + followed by a blank line) or be immediately followed by whitespace + or any of <samp>' " . , : ; ! ? - ) ] } / \</samp> + or <samp>></samp>. + <li>If a start-string is immediately preceded by one of + <samp>' " ( [ {</samp> or <samp><</samp>, it must not be + immediately followed by the corresponding character from + <samp>' " ) ] }</samp> or <samp>></samp>. + <li>An end-string must be separated by at least one + character from the start-string. + <li>An <a href="#escaping">unescaped</a> backslash preceding a + start-string or end-string will disable markup recognition, except + for the end-string of inline literals. + </ol> + + <p>Also remember that inline markup may not be nested (well, + except that inline literals can contain any of the other inline + markup delimiter characters, but that doesn't count because + nothing is processed). + + <h2><a href="#contents" name="escaping" class="backref" + >Escaping with Backslashes</a></h2> + + <p>(<a + href="../../ref/rst/restructuredtext.html#escaping-mechanism">details</a>) + + <p>reStructuredText uses backslashes ("\") to override the special + meaning given to markup characters and get the literal characters + themselves. To get a literal backslash, use an escaped backslash + ("\\"). For example: + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Raw reStructuredText + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"><td> + <samp>*escape* ``with`` "\"</samp> + <td><em>escape</em> <samp>with</samp> "" + <tr valign="top"><td> + <samp>\*escape* \``with`` "\\"</samp> + <td>*escape* ``with`` "\" + </table> + + <p>In Python strings it will, of course, be necessary + to escape any backslash characters so that they actually + <em>reach</em> reStructuredText. + The simplest way to do this is to use raw strings: + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Python string + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"><td> + <samp>r"""\*escape* \`with` "\\""""</samp> + <td>*escape* `with` "\" + <tr valign="top"><td> + <samp> """\\*escape* \\`with` "\\\\""""</samp> + <td>*escape* `with` "\" + <tr valign="top"><td> + <samp> """\*escape* \`with` "\\""""</samp> + <td><em>escape</em> with "" + </table> + + <h2><a href="#contents" name="section-structure" class="backref" + >Section Structure</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#sections">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> +<samp>=====</samp> +<br><samp>Title</samp> +<br><samp>=====</samp> +<br><samp>Subtitle</samp> +<br><samp>--------</samp> +<br><samp>Titles are underlined (or over-</samp> +<br><samp>and underlined) with a printing</samp> +<br><samp>nonalphanumeric 7-bit ASCII</samp> +<br><samp>character. Recommended choices</samp> +<br><samp>are "``= - ` : ' " ~ ^ _ * + # < >``".</samp> +<br><samp>The underline/overline must be at</samp> +<br><samp>least as long as the title text.</samp> +<br><samp></samp> +<br><samp>A lone top-level (sub)section</samp> +<br><samp>is lifted up to be the document's</samp> +<br><samp>(sub)title.</samp> + + <td> + <font size="+2"><strong>Title</strong></font> + <p><font size="+1"><strong>Subtitle</strong></font> + <p>Titles are underlined (or over- + and underlined) with a printing + nonalphanumeric 7-bit ASCII + character. Recommended choices + are "<samp>= - ` : ' " ~ ^ _ * + # < ></samp>". + The underline/overline must be at + least as long as the title text. + <p>A lone top-level (sub)section is + lifted up to be the document's + (sub)title. + </table> + + <h2><a href="#contents" name="paragraphs" class="backref" + >Paragraphs</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#paragraphs">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> +<p><samp>This is a paragraph.</samp> + +<p><samp>Paragraphs line up at their left</samp> +<br><samp>edges, and are normally separated</samp> +<br><samp>by blank lines.</samp> + + <td> + <p>This is a paragraph. + + <p>Paragraphs line up at their left edges, and are normally + separated by blank lines. + + </table> + + <h2><a href="#contents" name="bullet-lists" class="backref" + >Bullet Lists</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#bullet-lists">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> +<samp>Bullet lists:</samp> + +<p><samp>- This is item 1</samp> +<br><samp>- This is item 2</samp> + +<p><samp>- Bullets are "-", "*" or "+".</samp> +<br><samp> Continuing text must be aligned</samp> +<br><samp> after the bullet and whitespace.</samp> + +<p><samp>Note that a blank line is required</samp> +<br><samp>before the first item and after the</samp> +<br><samp>last, but is optional between items.</samp> + <td>Bullet lists: + <ul> + <li>This is item 1 + <li>This is item 2 + <li>Bullets are "-", "*" or "+". + Continuing text must be aligned + after the bullet and whitespace. + </ul> + <p>Note that a blank line is required before the first + item and after the last, but is optional between items. + </table> + + <h2><a href="#contents" name="enumerated-lists" class="backref" + >Enumerated Lists</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#enumerated-lists">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> +<samp>Enumerated lists:</samp> + +<p><samp>3. This is the first item</samp> +<br><samp>4. This is the second item</samp> +<br><samp>5. Enumerators are arabic numbers,</samp> +<br><samp> single letters, or roman numerals</samp> +<br><samp>6. List items should be sequentially</samp> +<br><samp> numbered, but need not start at 1</samp> +<br><samp> (although not all formatters will</samp> +<br><samp> honour the first index).</samp> +<br><samp>#. This item is auto-enumerated</samp> + <td>Enumerated lists: + <ol type="1"> + <li value="3">This is the first item + <li>This is the second item + <li>Enumerators are arabic numbers, single letters, + or roman numerals + <li>List items should be sequentially numbered, + but need not start at 1 (although not all + formatters will honour the first index). + <li>This item is auto-enumerated + </ol> + </table> + + <h2><a href="#contents" name="definition-lists" class="backref" + >Definition Lists</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#definition-lists">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> +<samp>Definition lists:</samp> +<br> +<br><samp>what</samp> +<br><samp> Definition lists associate a term with</samp> +<br><samp> a definition.</samp> +<br> +<br><samp>how</samp> +<br><samp> The term is a one-line phrase, and the</samp> +<br><samp> definition is one or more paragraphs or</samp> +<br><samp> body elements, indented relative to the</samp> +<br><samp> term. Blank lines are not allowed</samp> +<br><samp> between term and definition.</samp> + <td>Definition lists: + <dl> + <dt><strong>what</strong> + <dd>Definition lists associate a term with + a definition. + + <dt><strong>how</strong> + <dd>The term is a one-line phrase, and the + definition is one or more paragraphs or + body elements, indented relative to the + term. Blank lines are not allowed + between term and definition. + </dl> + </table> + + <h2><a href="#contents" name="field-lists" class="backref" + >Field Lists</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#field-lists">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> +<samp>:Authors:</samp> +<br><samp> Tony J. (Tibs) Ibbs,</samp> +<br><samp> David Goodger</samp> + +<p><samp> (and sundry other good-natured folks)</samp> + +<p><samp>:Version: 1.0 of 2001/08/08</samp> +<br><samp>:Dedication: To my father.</samp> + <td> + <table> + <tr valign="top"> + <td><strong>Authors:</strong> + <td>Tony J. (Tibs) Ibbs, + David Goodger + <tr><td><td>(and sundry other good-natured folks) + <tr><td><strong>Version:</strong><td>1.0 of 2001/08/08 + <tr><td><strong>Dedication:</strong><td>To my father. + </table> + </table> + + <p>Field lists are used as part of an extension syntax, such as + options for <a href="#directives">directives</a>, or database-like + records meant for further processing. Field lists may also be + used as generic two-column table constructs in documents. + + <h2><a href="#contents" name="option-lists" class="backref" + >Option Lists</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#option-lists">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <p><samp> +-a command-line option "a" +<br>-b file options can have arguments +<br> and long descriptions +<br>--long options can be long also +<br>--input=file long options can also have +<br> arguments +<br>/V DOS/VMS-style options too +</samp> + + <td> + <table border="0" width="100%"> + <tbody valign="top"> + <tr> + <td width="30%"><samp>-a</samp> + <td>command-line option "a" + <tr> + <td><samp>-b <i>file</i></samp> + <td>options can have arguments and long descriptions + <tr> + <td><samp>--long</samp> + <td>options can be long also + <tr> + <td><samp>--input=<i>file</i></samp> + <td>long options can also have arguments + <tr> + <td><samp>/V</samp> + <td>DOS/VMS-style options too + </table> + </table> + + <p>There must be at least two spaces between the option and the + description. + + <h2><a href="#contents" name="literal-blocks" class="backref" + >Literal Blocks</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#literal-blocks">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> +<samp>A paragraph containing only two colons</samp> +<br><samp>indicates that the following indented</samp> +<br><samp>or quoted text is a literal block.</samp> +<br> +<br><samp>::</samp> +<br> +<br><samp> Whitespace, newlines, blank lines, and</samp> +<br><samp> all kinds of markup (like *this* or</samp> +<br><samp> \this) is preserved by literal blocks.</samp> +<br> +<br><samp> The paragraph containing only '::'</samp> +<br><samp> will be omitted from the result.</samp> +<br> +<br><samp>The ``::`` may be tacked onto the very</samp> +<br><samp>end of any paragraph. The ``::`` will be</samp> +<br><samp>omitted if it is preceded by whitespace.</samp> +<br><samp>The ``::`` will be converted to a single</samp> +<br><samp>colon if preceded by text, like this::</samp> +<br> +<br><samp> It's very convenient to use this form.</samp> +<br> +<br><samp>Literal blocks end when text returns to</samp> +<br><samp>the preceding paragraph's indentation.</samp> +<br><samp>This means that something like this</samp> +<br><samp>is possible::</samp> +<br> +<br><samp> We start here</samp> +<br><samp> and continue here</samp> +<br><samp> and end here.</samp> +<br> +<br><samp>Per-line quoting can also be used on</samp> +<br><samp>unindented literal blocks:</samp> +<br> +<br><samp>> Useful for quotes from email and</samp> +<br><samp>> for Haskell literate programming.</samp> + + <td> + <p>A paragraph containing only two colons +indicates that the following indented or quoted +text is a literal block. + + <pre> + Whitespace, newlines, blank lines, and + all kinds of markup (like *this* or + \this) is preserved by literal blocks. + + The paragraph containing only '::' + will be omitted from the result.</pre> + + <p>The <samp>::</samp> may be tacked onto the very +end of any paragraph. The <samp>::</samp> will be +omitted if it is preceded by whitespace. +The <samp>::</samp> will be converted to a single +colon if preceded by text, like this: + + <pre> + It's very convenient to use this form.</pre> + + <p>Literal blocks end when text returns to +the preceding paragraph's indentation. +This means that something like this is possible: + + <pre> + We start here + and continue here + and end here.</pre> + + <p>Per-line quoting can also be used on +unindented literal blocks: + + <pre> + > Useful for quotes from email and + > for Haskell literate programming.</pre> + </table> + + <h2><a href="#contents" name="line-blocks" class="backref" + >Line Blocks</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#line-blocks">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> +<samp>| Line blocks are useful for addresses,</samp> +<br><samp>| verse, and adornment-free lists.</samp> +<br><samp>|</samp> +<br><samp>| Each new line begins with a</samp> +<br><samp>| vertical bar ("|").</samp> +<br><samp>| Line breaks and initial indents</samp> +<br><samp>| are preserved.</samp> +<br><samp>| Continuation lines are wrapped</samp> +<br><samp> portions of long lines; they begin</samp> +<br><samp> with spaces in place of vertical bars.</samp> + + <td> + <div class="line-block"> + <div class="line">Line blocks are useful for addresses,</div> + <div class="line">verse, and adornment-free lists.</div> + <div class="line"><br /></div> + <div class="line">Each new line begins with a</div> + <div class="line">vertical bar ("|").</div> + <div class="line-block"> + <div class="line">Line breaks and initial indents</div> + <div class="line">are preserved.</div> + </div> + <div class="line">Continuation lines are wrapped portions + of long lines; they begin + with spaces in place of vertical bars.</div> + </div> + </table> + + <h2><a href="#contents" name="block-quotes" class="backref" + >Block Quotes</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#block-quotes">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> +<samp>Block quotes are just:</samp> + +<p><samp> Indented paragraphs,</samp> + +<p><samp> and they may nest.</samp> + <td> + Block quotes are just: + <blockquote> + <p>Indented paragraphs, + <blockquote> + <p>and they may nest. + </blockquote> + </blockquote> + </table> + + <h2><a href="#contents" name="doctest-blocks" class="backref" + >Doctest Blocks</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#doctest-blocks">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <p><samp>Doctest blocks are interactive +<br>Python sessions. They begin with +<br>"``>>>``" and end with a blank line.</samp> + + <p><samp>>>> print "This is a doctest block." +<br>This is a doctest block.</samp> + + <td> + <p>Doctest blocks are interactive + Python sessions. They begin with + "<samp>>>></samp>" and end with a blank line. + + <p><samp>>>> print "This is a doctest block." +<br>This is a doctest block.</samp> + </table> + + <p>"The <a + href="http://www.python.org/doc/current/lib/module-doctest.html">doctest</a> + module searches a module's docstrings for text that looks like an + interactive Python session, then executes all such sessions to + verify they still work exactly as shown." (From the doctest docs.) + + <h2><a href="#contents" name="tables" class="backref" + >Tables</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#tables">details</a>) + + <p>There are two syntaxes for tables in reStructuredText. Grid + tables are complete but cumbersome to create. Simple tables are + easy to create but limited (no row spans, etc.).</p> + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> +<p><samp>Grid table:</samp></p> + +<p><samp>+------------+------------+-----------+</samp> +<br><samp>| Header 1 | Header 2 | Header 3 |</samp> +<br><samp>+============+============+===========+</samp> +<br><samp>| body row 1 | column 2 | column 3 |</samp> +<br><samp>+------------+------------+-----------+</samp> +<br><samp>| body row 2 | Cells may span columns.|</samp> +<br><samp>+------------+------------+-----------+</samp> +<br><samp>| body row 3 | Cells may | - Cells |</samp> +<br><samp>+------------+ span rows. | - contain |</samp> +<br><samp>| body row 4 | | - blocks. |</samp> +<br><samp>+------------+------------+-----------+</samp></p> + <td> + <p>Grid table:</p> + <table border="1"> + <thead valign="bottom"> + <tr> + <th>Header 1 + <th>Header 2 + <th>Header 3 + </tr> + </thead> + <tbody valign="top"> + <tr> + <td>body row 1 + <td>column 2 + <td>column 3 + </tr> + <tr> + <td>body row 2 + <td colspan="2">Cells may span columns. + </tr> + <tr> + <td>body row 3 + <td rowspan="2">Cells may<br>span rows. + <td rowspan="2"> + <ul> + <li>Cells + <li>contain + <li>blocks. + </ul> + </tr> + <tr> + <td>body row 4 + </tr> + </table> + <tr valign="top"> + <td> +<p><samp>Simple table:</samp></p> + +<p><samp>===== ===== ======</samp> +<br><samp> Inputs Output</samp> +<br><samp>------------ ------</samp> +<br><samp> A B A or B</samp> +<br><samp>===== ===== ======</samp> +<br><samp>False False False</samp> +<br><samp>True False True</samp> +<br><samp>False True True</samp> +<br><samp>True True True</samp> +<br><samp>===== ===== ======</samp></p> + + <td> + <p>Simple table:</p> + <table border="1"> + <colgroup> + <col width="31%"> + <col width="31%"> + <col width="38%"> + </colgroup> + <thead valign="bottom"> + <tr> + <th colspan="2">Inputs + <th>Output + <tr> + <th>A + <th>B + <th>A or B + <tbody valign="top"> + <tr> + <td>False + <td>False + <td>False + <tr> + <td>True + <td>False + <td>True + <tr> + <td>False + <td>True + <td>True + <tr> + <td>True + <td>True + <td>True + </table> + + </table> + + <h2><a href="#contents" name="transitions" class="backref" + >Transitions</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#transitions">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <p><samp> +A transition marker is a horizontal line +<br>of 4 or more repeated punctuation +<br>characters.</samp> + + <p><samp>------------</samp> + + <p><samp>A transition should not begin or end a +<br>section or document, nor should two +<br>transitions be immediately adjacent.</samp> + + <td> + <p>A transition marker is a horizontal line + of 4 or more repeated punctuation + characters.</p> + + <hr> + + <p>A transition should not begin or end a + section or document, nor should two + transitions be immediately adjacent. + </table> + + <p>Transitions are commonly seen in novels and short fiction, as a + gap spanning one or more lines, marking text divisions or + signaling changes in subject, time, point of view, or emphasis. + + <h2><a href="#contents" name="explicit-markup" class="backref" + >Explicit Markup</a></h2> + + <p>Explicit markup blocks are used for constructs which float + (footnotes), have no direct paper-document representation + (hyperlink targets, comments), or require specialized processing + (directives). They all begin with two periods and whitespace, the + "explicit markup start". + + <h3><a href="#contents" name="footnotes" class="backref" + >Footnotes</a></h3> + + <p>(<a href="../../ref/rst/restructuredtext.html#footnotes">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td> + <samp>Footnote references, like [5]_.</samp> + <br><samp>Note that footnotes may get</samp> + <br><samp>rearranged, e.g., to the bottom of</samp> + <br><samp>the "page".</samp> + + <p><samp>.. [5] A numerical footnote. Note</samp> + <br><samp> there's no colon after the ``]``.</samp> + + <td> + Footnote references, like <sup><a href="#5">5</a></sup>. + Note that footnotes may get rearranged, e.g., to the bottom of + the "page". + + <p><table> + <tr><td colspan="2"><hr> + <!-- <tr><td colspan="2">Footnotes: --> + <tr><td><a name="5"><strong>[5]</strong></a><td> A numerical footnote. + Note there's no colon after the <samp>]</samp>. + </table> + + <tr valign="top"> + <td> + <samp>Autonumbered footnotes are</samp> + <br><samp>possible, like using [#]_ and [#]_.</samp> + <p><samp>.. [#] This is the first one.</samp> + <br><samp>.. [#] This is the second one.</samp> + + <p><samp>They may be assigned 'autonumber</samp> + <br><samp>labels' - for instance, + <br>[#fourth]_ and [#third]_.</samp> + + <p><samp>.. [#third] a.k.a. third_</samp> + <p><samp>.. [#fourth] a.k.a. fourth_</samp> + <td> + Autonumbered footnotes are possible, like using <sup><a + href="#auto1">1</a></sup> and <sup><a href="#auto2">2</a></sup>. + + <p>They may be assigned 'autonumber labels' - for instance, + <sup><a href="#fourth">4</a></sup> and <sup><a + href="#third">3</a></sup>. + + <p><table> + <tr><td colspan="2"><hr> + <!-- <tr><td colspan="2">Footnotes: --> + <tr><td><a name="auto1"><strong>[1]</strong></a><td> This is the first one. + <tr><td><a name="auto2"><strong>[2]</strong></a><td> This is the second one. + <tr><td><a name="third"><strong>[3]</strong></a><td> a.k.a. <a href="#third">third</a> + <tr><td><a name="fourth"><strong>[4]</strong></a><td> a.k.a. <a href="#fourth">fourth</a> + </table> + + <tr valign="top"> + <td> + <samp>Auto-symbol footnotes are also</samp> + <br><samp>possible, like this: [*]_ and [*]_.</samp> + <p><samp>.. [*] This is the first one.</samp> + <br><samp>.. [*] This is the second one.</samp> + + <td> + Auto-symbol footnotes are also + possible, like this: <sup><a href="#symbol1">*</a></sup> + and <sup><a href="#symbol2">†</a></sup>. + + <p><table> + <tr><td colspan="2"><hr> + <!-- <tr><td colspan="2">Footnotes: --> + <tr><td><a name="symbol1"><strong>[*]</strong></a><td> This is the first symbol footnote + <tr><td><a name="symbol2"><strong>[†]</strong></a><td> This is the second one. + </table> + + </table> + + <p>The numbering of auto-numbered footnotes is determined by the + order of the footnotes, not of the references. For auto-numbered + footnote references without autonumber labels + ("<samp>[#]_</samp>"), the references and footnotes must be in the + same relative order. Similarly for auto-symbol footnotes + ("<samp>[*]_</samp>"). + + <h3><a href="#contents" name="citations" class="backref" + >Citations</a></h3> + + <p>(<a href="../../ref/rst/restructuredtext.html#citations">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td> + <samp>Citation references, like [CIT2002]_.</samp> + <br><samp>Note that citations may get</samp> + <br><samp>rearranged, e.g., to the bottom of</samp> + <br><samp>the "page".</samp> + + <p><samp>.. [CIT2002] A citation</samp> + <br><samp> (as often used in journals).</samp> + + <p><samp>Citation labels contain alphanumerics,</samp> + <br><samp>underlines, hyphens and fullstops.</samp> + <br><samp>Case is not significant.</samp> + + <p><samp>Given a citation like [this]_, one</samp> + <br><samp>can also refer to it like this_.</samp> + + <p><samp>.. [this] here.</samp> + + <td> + Citation references, like <a href="#cit2002">[CIT2002]</a>. + Note that citations may get rearranged, e.g., to the bottom of + the "page". + + <p>Citation labels contain alphanumerics, underlines, hyphens + and fullstops. Case is not significant. + + <p>Given a citation like <a href="#this">[this]</a>, one + can also refer to it like <a href="#this">this</a>. + + <p><table> + <tr><td colspan="2"><hr> + <!-- <tr><td colspan="2">Citations: --> + <tr><td><a name="cit2002"><strong>[CIT2002]</strong></a><td> A citation + (as often used in journals). + <tr><td><a name="this"><strong>[this]</strong></a><td> here. + </table> + + </table> + + <h3><a href="#contents" name="hyperlink-targets" class="backref" + >Hyperlink Targets</a></h3> + + <p>(<a href="../../ref/rst/restructuredtext.html#hyperlink-targets">details</a>) + + <h4><a href="#contents" name="external-hyperlink-targets" class="backref" + >External Hyperlink Targets</a></h4> + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td rowspan="2"> + <samp>External hyperlinks, like Python_.</samp> + + <p><samp>.. _Python: http://www.python.org/</samp> + <td> + <table width="100%"> + <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> + <tr><td>External hyperlinks, like + <a href="http://www.python.org/">Python</a>. + </table> + <tr valign="top"> + <td> + <table width="100%"> + <tr bgcolor="#99CCFF"><td><em>Call-out form</em> + <tr><td>External hyperlinks, like + <a href="#labPython"><i>Python</i></a>. + + <p><table> + <tr><td colspan="2"><hr> + <tr><td><a name="labPython"><i>Python:</i></a> + <td> <a href="http://www.python.org/">http://www.python.org/</a> + </table> + </table> + </table> + + <p>"<em>Fold-in</em>" is the representation typically used in HTML + documents (think of the indirect hyperlink being "folded in" like + ingredients into a cake), and "<em>call-out</em>" is more suitable for + printed documents, where the link needs to be presented explicitly, for + example as a footnote. You can force usage of the call-out form by + using the + "<a href="../../ref/rst/directives.html#target-notes">target-notes</a>" + directive. + + <p>reStructuredText also provides for <b>embedded URIs</b> (<a + href="../../ref/rst/restructuredtext.html#embedded-uris">details</a>), + a convenience at the expense of readability. A hyperlink + reference may directly embed a target URI inline, within angle + brackets. The following is exactly equivalent to the example above: + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td rowspan="2"> + <samp>External hyperlinks, like `Python +<br><http://www.python.org/>`_.</samp> + <td>External hyperlinks, like + <a href="http://www.python.org/">Python</a>. + </table> + + <h4><a href="#contents" name="internal-hyperlink-targets" class="backref" + >Internal Hyperlink Targets</a></h4> + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td rowspan="2"><samp>Internal crossreferences, like example_.</samp> + + <p><samp>.. _example:</samp> + + <p><samp>This is an example crossreference target.</samp> + <td> + <table width="100%"> + <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> + <!-- Note that some browsers may not like an "a" tag that --> + <!-- does not have any content, so we could arbitrarily --> + <!-- use the first word as content - *or* just trust to --> + <!-- luck! --> + <tr><td>Internal crossreferences, like <a href="#example-foldin">example</a> + <p><a name="example-foldin">This</a> is an example + crossreference target. + </table> + <tr valign="top"> + <td> + <table width="100%"> + <tr><td bgcolor="#99CCFF"><em>Call-out form</em> + <tr><td>Internal crossreferences, like <a href="#example-callout">example</a> + + <p><a name="example-callout"><i>example:</i></a> + <br>This is an example crossreference target. + </table> + + </table> + + <h4><a href="#contents" name="indirect-hyperlink-targets" class="backref" + >Indirect Hyperlink Targets</a></h4> + + <p>(<a href="../../ref/rst/restructuredtext.html#indirect-hyperlink-targets">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td> + <samp>Python_ is `my favourite +<br>programming language`__.</samp> + + <p><samp>.. _Python: http://www.python.org/</samp> + + <p><samp>__ Python_</samp> + + <td> + <p><a href="http://www.python.org/">Python</a> is + <a href="http://www.python.org/">my favourite + programming language</a>. + + </table> + + <p>The second hyperlink target (the line beginning with + "<samp>__</samp>") is both an indirect hyperlink target + (<i>indirectly</i> pointing at the Python website via the + "<samp>Python_</samp>" reference) and an <b>anonymous hyperlink + target</b>. In the text, a double-underscore suffix is used to + indicate an <b>anonymous hyperlink reference</b>. In an anonymous + hyperlink target, the reference text is not repeated. This is + useful for references with long text or throw-away references, but + the target should be kept close to the reference to prevent them + going out of sync. + + <h4><a href="#contents" name="implicit-hyperlink-targets" class="backref" + >Implicit Hyperlink Targets</a></h4> + + <p>(<a href="../../ref/rst/restructuredtext.html#implicit-hyperlink-targets">details</a>) + + <p>Section titles, footnotes, and citations automatically generate + hyperlink targets (the title text or footnote/citation label is + used as the hyperlink name). + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead><tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td> + <samp>Titles are targets, too</samp> + <br><samp>=======================</samp> + <br><samp>Implict references, like `Titles are</samp> + <br><samp>targets, too`_.</samp> + <td> + <font size="+2"><strong><a name="title">Titles are targets, too</a></strong></font> + <p>Implict references, like <a href="#title">Titles are + targets, too</a>. + </table> + + <h3><a href="#contents" name="directives" class="backref" + >Directives</a></h3> + + <p>(<a href="../../ref/rst/restructuredtext.html#directives">details</a>) + + <p>Directives are a general-purpose extension mechanism, a way of + adding support for new constructs without adding new syntax. For + a description of all standard directives, see <a + href="../../ref/rst/directives.html" >reStructuredText + Directives</a>. + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td><samp>For instance:</samp> + + <p><samp>.. image:: images/ball1.gif</samp> + + <td> + For instance: + <p><img src="images/ball1.gif" alt="ball1"> + </table> + + <h3><a href="#contents" name="substitution-references-and-definitions" + class="backref" >Substitution References and Definitions</a></h3> + + <p>(<a href="../../ref/rst/restructuredtext.html#substitution-definitions">details</a>) + + <p>Substitutions are like inline directives, allowing graphics and + arbitrary constructs within text. + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td><samp> +The |biohazard| symbol must be +used on containers used to +dispose of medical waste.</samp> + + <p><samp> +.. |biohazard| image:: biohazard.png</samp> + + <td> + + <p>The <img src="images/biohazard.png" align="bottom" alt="biohazard"> symbol + must be used on containers used to dispose of medical waste. + + </table> + + <h3><a href="#contents" name="comments" class="backref" + >Comments</a></h3> + + <p>(<a href="../../ref/rst/restructuredtext.html#comments">details</a>) + + <p>Any text which begins with an explicit markup start but doesn't + use the syntax of any of the constructs above, is a comment. + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td><samp>.. This text will not be shown</samp> + <br><samp> (but, for instance, in HTML might be</samp> + <br><samp> rendered as an HTML comment)</samp> + + <td> + <!-- This text will not be shown --> + <!-- (but, for instance in HTML might be --> + <!-- rendered as an HTML comment) --> + + <tr valign="top"> + <td> + <samp>An empty "comment" does not</samp> + <br><samp>"consume" following blocks.</samp> + <p><samp>..</samp> + <p><samp> So this block is not "lost",</samp> + <br><samp> despite its indentation.</samp> + <td> + An empty "comment" does not + "consume" following blocks. + <blockquote> + So this block is not "lost", + despite its indentation. + </blockquote> + </table> + + <h2><a href="#contents" name="getting-help" class="backref" + >Getting Help</a></h2> + + <p>Users who have questions or need assistance with Docutils or + reStructuredText should <a + href="mailto:docutils-users@lists.sourceforge.net" >post a + message</a> to the <a + href="http://lists.sourceforge.net/lists/listinfo/docutils-users" + >Docutils-Users mailing list</a>. The <a + href="http://docutils.sourceforge.net/" >Docutils project web + site</a> has more information. + + <p><hr> + <address> + <p>Authors: + <a href="http://www.tibsnjoan.co.uk/">Tibs</a> + (<a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>) + and David Goodger + (<a href="mailto:goodger@python.org">goodger@python.org</a>) + </address> + <!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 --> + </body> +</html> diff --git a/docs/user/rst/quickstart.txt b/docs/user/rst/quickstart.txt new file mode 100644 index 000000000..735dcf512 --- /dev/null +++ b/docs/user/rst/quickstart.txt @@ -0,0 +1,387 @@ +A ReStructuredText Primer +========================= + +:Author: Richard Jones +:Version: $Revision$ +:Copyright: This document has been placed in the public domain. + +.. contents:: + + +The text below contains links that look like "(quickref__)". These +are relative links that point to the `Quick reStructuredText`_ user +reference. If these links don't work, please refer to the `master +quick reference`_ document. + +__ +.. _Quick reStructuredText: quickref.html +.. _master quick reference: + http://docutils.sourceforge.net/docs/user/rst/quickref.html + + +Structure +--------- + +From the outset, let me say that "Structured Text" is probably a bit +of a misnomer. It's more like "Relaxed Text" that uses certain +consistent patterns. These patterns are interpreted by a HTML +converter to produce "Very Structured Text" that can be used by a web +browser. + +The most basic pattern recognised is a **paragraph** (quickref__). +That's a chunk of text that is separated by blank lines (one is +enough). Paragraphs must have the same indentation -- that is, line +up at their left edge. Paragraphs that start indented will result in +indented quote paragraphs. For example:: + + This is a paragraph. It's quite + short. + + This paragraph will result in an indented block of + text, typically used for quoting other text. + + This is another one. + +Results in: + + This is a paragraph. It's quite + short. + + This paragraph will result in an indented block of + text, typically used for quoting other text. + + This is another one. + +__ quickref.html#paragraphs + +Text styles +----------- + +(quickref__) + +__ quickref.html#inline-markup + +Inside paragraphs and other bodies of text, you may additionally mark +text for *italics* with "``*italics*``" or **bold** with +"``**bold**``". + +If you want something to appear as a fixed-space literal, use +"````double back-quotes````". Note that no further fiddling is done +inside the double back-quotes -- so asterisks "``*``" etc. are left +alone. + +If you find that you want to use one of the "special" characters in +text, it will generally be OK -- reStructuredText is pretty smart. +For example, this * asterisk is handled just fine. If you actually +want text \*surrounded by asterisks* to **not** be italicised, then +you need to indicate that the asterisk is not special. You do this by +placing a backslash just before it, like so "``\*``" (quickref__), or +by enclosing it in double back-quotes (inline literals), like this:: + + ``\*`` + +__ quickref.html#escaping + +Lists +----- + +Lists of items come in three main flavours: **enumerated**, +**bulleted** and **definitions**. In all list cases, you may have as +many paragraphs, sublists, etc. as you want, as long as the left-hand +side of the paragraph or whatever aligns with the first line of text +in the list item. + +Lists must always start a new paragraph -- that is, they must appear +after a blank line. + +**enumerated** lists (numbers, letters or roman numerals; quickref__) + __ quickref.html#enumerated-lists + + Start a line off with a number or letter followed by a period ".", + right bracket ")" or surrounded by brackets "( )" -- whatever you're + comfortable with. All of the following forms are recognised:: + + 1. numbers + + A. upper-case letters + and it goes over many lines + + with two paragraphs and all! + + a. lower-case letters + + 3. with a sub-list starting at a different number + 4. make sure the numbers are in the correct sequence though! + + I. upper-case roman numerals + + i. lower-case roman numerals + + (1) numbers again + + 1) and again + + Results in (note: the different enumerated list styles are not + always supported by every web browser, so you may not get the full + effect here): + + 1. numbers + + A. upper-case letters + and it goes over many lines + + with two paragraphs and all! + + a. lower-case letters + + 3. with a sub-list starting at a different number + 4. make sure the numbers are in the correct sequence though! + + I. upper-case roman numerals + + i. lower-case roman numerals + + (1) numbers again + + 1) and again + +**bulleted** lists (quickref__) + __ quickref.html#bullet-lists + + Just like enumerated lists, start the line off with a bullet point + character - either "-", "+" or "*":: + + * a bullet point using "*" + + - a sub-list using "-" + + + yet another sub-list + + - another item + + Results in: + + * a bullet point using "*" + + - a sub-list using "-" + + + yet another sub-list + + - another item + +**definition** lists (quickref__) + __ quickref.html#definition-lists + + Unlike the other two, the definition lists consist of a term, and + the definition of that term. The format of a definition list is:: + + what + Definition lists associate a term with a definition. + + *how* + The term is a one-line phrase, and the definition is one or more + paragraphs or body elements, indented relative to the term. + Blank lines are not allowed between term and definition. + + Results in: + + what + Definition lists associate a term with a definition. + + *how* + The term is a one-line phrase, and the definition is one or more + paragraphs or body elements, indented relative to the term. + Blank lines are not allowed between term and definition. + +Preformatting (code samples) +---------------------------- +(quickref__) + +__ quickref.html#literal-blocks + +To just include a chunk of preformatted, never-to-be-fiddled-with +text, finish the prior paragraph with "``::``". The preformatted +block is finished when the text falls back to the same indentation +level as a paragraph prior to the preformatted block. For example:: + + An example:: + + Whitespace, newlines, blank lines, and all kinds of markup + (like *this* or \this) is preserved by literal blocks. + Lookie here, I've dropped an indentation level + (but not far enough) + + no more example + +Results in: + + An example:: + + Whitespace, newlines, blank lines, and all kinds of markup + (like *this* or \this) is preserved by literal blocks. + Lookie here, I've dropped an indentation level + (but not far enough) + + no more example + +Note that if a paragraph consists only of "``::``", then it's removed +from the output:: + + :: + + This is preformatted text, and the + last "::" paragraph is removed + +Results in: + +:: + + This is preformatted text, and the + last "::" paragraph is removed + +Sections +-------- + +(quickref__) + +__ quickref.html#section-structure + +To break longer text up into sections, you use **section headers**. +These are a single line of text (one or more words) with adornment: an +underline alone, or an underline and an overline together, in dashes +"``-----``", equals "``======``", tildes "``~~~~~~``" or any of the +non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you +feel comfortable with. An underline-only adornment is distinct from +an overline-and-underline adornment using the same character. The +underline/overline must be at least as long as the title text. Be +consistent, since all sections marked with the same adornment style +are deemed to be at the same level:: + + Chapter 1 Title + =============== + + Section 1.1 Title + ----------------- + + Subsection 1.1.1 Title + ~~~~~~~~~~~~~~~~~~~~~~ + + Section 1.2 Title + ----------------- + + Chapter 2 Title + =============== + +This results in the following structure, illustrated by simplified +pseudo-XML:: + + <section> + <title> + Chapter 1 Title + <section> + <title> + Section 1.1 Title + <section> + <title> + Subsection 1.1.1 Title + <section> + <title> + Section 1.2 Title + <section> + <title> + Chapter 2 Title + +(Pseudo-XML uses indentation for nesting and has no end-tags. It's +not possible to show actual processed output, as in the other +examples, because sections cannot exist inside block quotes. For a +concrete example, compare the section structure of this document's +source text and processed output.) + +Note that section headers are available as link targets, just using +their name. To link to the Lists_ heading, I write "``Lists_``". If +the heading has a space in it like `text styles`_, we need to quote +the heading "```text styles`_``". + + +Document Title / Subtitle +````````````````````````` + +The title of the whole document is distinct from section titles and +may be formatted somewhat differently (e.g. the HTML writer by default +shows it as a centered heading). + +To indicate the document title in reStructuredText, use a unique adornment +style at the beginning of the document. To indicate the document subtitle, +use another unique adornment style immediately after the document title. For +example:: + + ================ + Document Title + ================ + ---------- + Subtitle + ---------- + + Section Title + ============= + + ... + +Note that "Document Title" and "Section Title" above both use equals +signs, but are distict and unrelated styles. The text of +overline-and-underlined titles (but not underlined-only) may be inset +for aesthetics. + + +Images +------ + +(quickref__) + +__ quickref.html#directives + +To include an image in your document, you use the the ``image`` directive__. +For example:: + + .. image:: images/biohazard.png + +results in: + +.. image:: images/biohazard.png + +The ``images/biohazard.png`` part indicates the filename of the image +you wish to appear in the document. There's no restriction placed on +the image (format, size etc). If the image is to appear in HTML and +you wish to supply additional information, you may:: + + .. image:: images/biohazard.png + :height: 100 + :width: 200 + :scale: 50 + :alt: alternate text + +See the full `image directive documentation`__ for more info. + +__ ../../ref/rst/directives.html +__ ../../ref/rst/directives.html#images + + +What Next? +---------- + +This primer introduces the most common features of reStructuredText, +but there are a lot more to explore. The `Quick reStructuredText`_ +user reference is a good place to go next. For complete details, the +`reStructuredText Markup Specification`_ is the place to go [#]_. + +Users who have questions or need assistance with Docutils or +reStructuredText should post a message to the Docutils-users_ mailing +list. + +.. [#] If that relative link doesn't work, try the master document: + http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html. + +.. _reStructuredText Markup Specification: + ../../ref/rst/restructuredtext.html +.. _Docutils-users: ../mailing-lists.html#docutils-users +.. _Docutils project web site: http://docutils.sourceforge.net/ |
