diff options
| author | goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2002-04-20 03:01:52 +0000 |
|---|---|---|
| committer | goodger <goodger@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2002-04-20 03:01:52 +0000 |
| commit | 172e90b630ef837e4634f9f2a276fcfda36f1a3e (patch) | |
| tree | c3e859c167fc0259d708de65ec5e703293d63f68 /docs/user/rst/quickref.html | |
| parent | bdb61b5304ca936ac98d164e21b927348a5ddb89 (diff) | |
| download | docutils-172e90b630ef837e4634f9f2a276fcfda36f1a3e.tar.gz | |
Initial revision
git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk/docutils@18 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
Diffstat (limited to 'docs/user/rst/quickref.html')
| -rw-r--r-- | docs/user/rst/quickref.html | 1096 |
1 files changed, 1096 insertions, 0 deletions
diff --git a/docs/user/rst/quickref.html b/docs/user/rst/quickref.html new file mode 100644 index 000000000..886a02107 --- /dev/null +++ b/docs/user/rst/quickref.html @@ -0,0 +1,1096 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<html> + <head> + <title>Quick reStructuredText</title> + + </head> + + <body> + <h1>Quick <i>re</i><font size="+4"><tt>Structured</tt></font><i>Text</i></h1> + <!-- Hmm - does that (relative) font size work for you? --> + <!-- If David produces a smaller version of the reST title --> + <!-- page's title image, we could do something like: --> + <!-- <h1>Quick <img src="images/title.png" --> + <!-- alt="Quick reStructuredText"></h1> --> + <!-- which might be a better idea... --> + + <!-- 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/rst/quickref.html" + >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> + <br align="right"><em>Being a cheat-sheet for reStructuredText</em> + <br align="right"><em>Version 0.8 of 2002-04-19</em> + + + <p>The full details may be found on the + <a href="http://docutils.sourceforge.net/rest.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="../../spec/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/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 Bashslashes</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="#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="#footnotes">Footnotes</a></li> + <li><a href="#citations">Citations</a></li> + <li><a href="#hyperlink-targets">Hyperlink Targets</a></li> + <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><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> + + <h2><a href="#contents" name="inline-markup">Inline Markup</a></h2> + + <p>(<a href="../../spec/rst/reStructuredText.html#inline-markup">details?</a>) + + <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> + + <tr valign="top"> + <td nowrap><samp>**strong emphasis**</samp> + <td><strong>strong emphasis</strong> + <td> + + <tr valign="top"> + <td nowrap><samp>`interpreted text`</samp> + <td>interpreted text + <td>What interpreted text <em>means</em> is domain dependent. + + <tr valign="top"> + <td nowrap><samp>``inline literal``</samp> + <td><code>inline literal</code> + <td>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="#hyperlinks">Hyperlinks</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">Hyperlinks</a>. + + <tr valign="top"> + <td nowrap><samp>anonymous__</samp> + <td><a href="#hyperlink-targets">anonymous</a> + <td>Both simple and phrase references may be anonymous (two underscores). + See <a href="#hyperlink-targets">Hyperlinks</a>. + + <tr valign="top"> + <td nowrap><samp>_`inline hyperlink target`</samp> + <td><a name="inline-hyperlink-target">inline hyperlink target</a> + <td>A crossreference target within text. + See <a href="#hyperlink-targets">Hyperlinks</a>. + + <tr valign="top"> + <td nowrap><samp>|substitution reference|</samp> + <td>(see note) + <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 <a href="#footnotes">[1]</a> + <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 specifications says that in + inline markup: + <ol> + <li>The start-string must start a text block or be + immediately preceded by whitespace, + <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 or be immediately + followed by whitespace, + <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">Escaping with Bashslashes</a></h2> + + <p>(<a + href="../../spec/rst/reStructuredText.html#backslashes">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">Section Structure</a></h2> + + <p>(<a href="../../spec/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> + <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>". + </table> + + <h2><a href="#contents" name="paragraphs">Paragraphs</a></h2> + + <p>(<a href="../../spec/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">Bullet Lists</a></h2> + + <p>(<a href="../../spec/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">Enumerated Lists</a></h2> + + <p>(<a href="../../spec/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> + <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). + </ol> + </table> + + <h2><a href="#contents" name="definition-lists">Definition Lists</a></h2> + + <p>(<a href="../../spec/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">Field Lists</a></h2> + + <p>(<a href="../../spec/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> + + <h2><a href="#contents" name="option-lists">Option Lists</a></h2> + + <p>(<a href="../../spec/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%"><p><samp>-a</samp> + <td><p>command-line option "a" + <tr> + <td><p><samp>-b <i>file</i></samp> + <td><p>options can have arguments and long descriptions + <tr> + <td><p><samp>--long</samp> + <td><p>options can be long also + <tr> + <td><p><samp>--input=<i>file</i></samp> + <td><p>long options can also have arguments + <tr> + <td><p><samp>/V</samp> + <td><p>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">Literal Blocks</a></h2> + + <p>(<a href="../../spec/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>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::</samp> +<br> +<br><samp> We start here</samp> +<br><samp> and continue here</samp> +<br><samp> and end here.</samp> +<br> +<br><samp>is possible.</samp> + + <td> + <p>A paragraph containing only two colons +indicates that the following indented +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: + + <pre> + We start here + and continue here + and end here.</pre> + + <p>is possible. + </table> + + <h2><a href="#contents" name="block-quotes">Block Quotes</a></h2> + + <p>(<a href="../../spec/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">Doctest Blocks</a></h2> + + <p>(<a href="../../spec/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">Tables</a></h2> + + <p>(<a href="../../spec/rst/reStructuredText.html#tables">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> | 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> + <td> + <table align="center" border="1"> + <tr valign="top"> + <th>Header 1 + <th>Header 2 + <th>Header 3 + <tr> + <td>body row 1 + <td>column 2 + <td>column 3 + <tr> + <td>body row 2 + <td colspan="2">Cells may span columns. + <tr valign="top"> + <td>body row 3 + <td rowspan="2">Cells may<br>span rows. + <td rowspan="2"> + <ul> + <li>Cells + <li>contain + <li>blocks. + </ul> + <tr valign="top"> + <td>body row 4 + </table> + </table> + + <h2><a href="#contents" name="transitions">Transitions</a></h2> + + <p>(<a href="../../spec/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="footnotes">Footnotes</a></h2> + + <p>(<a href="../../spec/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>"). + + <h2><a href="#contents" name="citations">Citations</a></h2> + + <p>(<a href="../../spec/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> + + <h2><a href="#contents" name="hyperlink-targets">Hyperlink Targets</a></h2> + + <p>(<a href="../../spec/rst/reStructuredText.html#hyperlink-targets">details?</a>) + + <h3><a href="#contents" name="external-hyperlink-targets">External Hyperlink Targets</a></h3> + + <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>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>Indirect hyperlinks, like + <a href="http://www.python.org">Python</a>. + <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. + + <h3><a href="#contents" name="internal-hyperlink-targets">Internal Hyperlink Targets</a></h3> + + <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>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. + <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> + + <h3><a href="#contents" name="indirect-hyperlink-targets">Indirect Hyperlink Targets</a></h3> + + <p>(<a href="../../spec/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>. + + <h3><a href="#contents" name="implicit-hyperlink-targets">Implicit Hyperlink Targets</a></h3> + + <p>(<a href="../../spec/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"> <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> + + <h2><a href="#contents" name="directives">Directives</a></h2> + + <p>(<a href="../../spec/rst/reStructuredText.html#directives">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>For instance:</samp> + + <p><samp>.. image:: images/ball1.gif</samp> + + <td> + For instance: + <p><img src="images/ball1.gif" alt="ball1"> + </table> + + <h2><a href="#contents" name="substitution-references-and-definitions">Substitution References and Definitions</a></h2> + + <p>(<a href="../../spec/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> + + <h2><a href="#contents" name="comments">Comments</a></h2> + + <p>(<a href="../../spec/rst/reStructuredText.html#comments">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>.. 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" directive 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" directive does not + "consume" following blocks. + <blockquote> + So this block is not "lost", + despite its indentation. + </blockquote> + </table> + + <p><hr> + <address> + <p>Authors: + <a href="http://www.tibsnjoan.co.uk/">Tibs</a> + (<a href="mailto:tony@lsl.co.uk"><tt>tony@lsl.co.uk</tt></a> or + <a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>) + and David Goodger + (<a href="mailto:goodger@users.sourceforge.net">goodger@users.sourceforge.net</a>) + </address> + <!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 --> + </body> +</html> |