diff options
Diffstat (limited to 'docutils/docs/user')
| -rw-r--r-- | docutils/docs/user/latex.txt | 263 | ||||
| -rw-r--r-- | docutils/docs/user/rst/images/ball1.gif | bin | 4361 -> 0 bytes | |||
| -rw-r--r-- | docutils/docs/user/rst/images/biohazard.png | bin | 179 -> 0 bytes | |||
| -rw-r--r-- | docutils/docs/user/rst/images/title.png | bin | 1171 -> 0 bytes | |||
| -rw-r--r-- | docutils/docs/user/rst/quickref.html | 1243 | ||||
| -rw-r--r-- | docutils/docs/user/rst/quickstart.txt | 382 | ||||
| -rw-r--r-- | docutils/docs/user/tools.txt | 724 |
7 files changed, 0 insertions, 2612 deletions
diff --git a/docutils/docs/user/latex.txt b/docutils/docs/user/latex.txt deleted file mode 100644 index 1b3d0b53b..000000000 --- a/docutils/docs/user/latex.txt +++ /dev/null @@ -1,263 +0,0 @@ -======================= - Docutils LaTex Writer -======================= - -:Author: Engelbert Gruber -:Contact: grubert@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -Introduction -============ - -Producing latex code from reST input could be done in at least two ways: - -a. Transform the internal markup into corresponding latex markup e.g. - a section title would be written as ```\section{this section ...}``. -b. Using latex as a typesetting system to produce desired paperwork - without caring about loosing document structure information. - -The former might be preferable, but limits to latexs capabilities, so -in reality it is a mix. - - -Options -======= - -Configuration can be done in two ways (again): - -1. Options to the docutils tool: e.g. language selection. -2. Options to latex via the stylesheet file. - -The generated latex documents should be kept processable by a standard -latex installation (if such a thing exists), therefore the document -contains default settings. To allow *overwriting defaults* the stylesheet -is included at last. - -Options on the Commandline --------------------------- - -===================== ================================================ -Setting/Config Entry Description -===================== ================================================ ---use-latex-toc To get pagenumbers in the table of contents the - table of contents must be generated by latex. - Usually latex must be run twice to get numbers - correct. ---------------------- ------------------------------------------------ ---hyperlink-color Color of any hyperlinks embedded in text - (default: "blue", "0" to disable). ---------------------- ------------------------------------------------ ---documentclass Specify latex documentclass, *but* beaware that - books have chapters articles not. - (default: "article"). ---------------------- ------------------------------------------------ ---stylesheet Specify a stylesheet file. The file will be - ``input`` by latex in the document header. - If this is set to "" disables generation of - input latex command. - (default: "style.tex"). ---------------------- ------------------------------------------------ ---footnote-references Format for footnote references: one of - "superscript" or "brackets". - Default is "brackets". ---------------------- ------------------------------------------------ ---attribution Format for block quote attributions: one of - "dash" (em-dash prefix), "parentheses"/"parens", - or "none". - - Default: "dash". Options: ``--attribution``. -===================== ================================================ - - -Options in the Stylesheet -------------------------- - -===================== ================================================ -Setting/Config Entry Description -===================== ================================================ -papersize Default: a4paper. Paper geometry can be changed - using ``\geometry{xxx}`` entries. - - Some possibilities: - - * a4paper, b3paper, letterpaper, executivepaper, - legalpaper - * landscape, portrait, twoside. - - and a ton of other option setting margins. - - An example:: - - \geometry{a5paper,landscape} ---------------------- ------------------------------------------------ -paragraph indent By default latex indents the forst line in a - paragraph. The following lines set indentation - to zero but add a vertical space between - paragraphs.:: - - \setlength{\parindent}{0pt} - \setlength{\parskip}{6pt plus 2pt minus 1pt} ---------------------- ------------------------------------------------ -admonitionwidth The width for admonitions. - Default: 0.9*textwidth, this can be changed - e.g.:: - - \setlength{\admonitionwidth}{0.7\textwidth} ---------------------- ------------------------------------------------ -docinfowidth The width for the docinfo table. - Default: 0.9*textwidth, changed to e.g.:: - - \setlength{\docinfowidth}{0.7\textwidth} ---------------------- ------------------------------------------------ -rubric style The header contains the definition of a new - LaTeX command rubric. Inserting:: - - \renewcommand{\rubric}[1]{\subsection*{ - ~\hfill {\color{red} #1} \hfill ~}} - - sets rubric to subsection style in red. - - Default: subsection style italic. ---------------------- ------------------------------------------------ -font selection see below -===================== ================================================ - -Missing options ---------------- - -* Selection of latex fontsize. -* Assumed reST linelength for table width setting. - -Font selection --------------- - -When generating pdf-files from LaTeX, use the pdflatex command, the files -are a lot smaller if postscript fonts are used. To do so put -``\usepackage{times}`` into the styleshee - -It is said that the typewriter font in computer modern font, the default -LaTeX font package, is too heavy compared to the others. There is a package -or some commands too fix this, which i currently cannot find. - -Some people diagnose a similar unbalance for the postscript fonts, the -package to fix this is ```\usepackage{pslatex}``. - - -Commands directly to LaTeX -========================== - -By means of the reST-raw directive one can give commands directly to -LaTeX, e.g. forcing a page break:: - - .. raw:: latex - - \newpage - - -Or setting formulas in LaTeX:: - - .. raw:: latex - - $$x^3 + 3x^2a + 3xa^2 + a^3,$$ - - -Or making a colorbox: If someone wants to get a red background for a textblock, -she/he can put \definecolor{bg}{rgb}{.9,0,0} into style.tex and in -reStructuredText do something like this:: - - |begincolorbox| - Nobody expects the spanish inquisition. - |endcolorbox| - - .. |begincolorbox| raw:: latex - - \\begin{center} - \\colorbox{bg}{ - \\parbox{0.985\\linewidth}{ - - .. |endcolorbox| raw:: latex - - }} - \\end{center} - - -Problems -======== - -Open to be fixed or open to discussion. - -Tables ------- - -:Tablewidth: reST-documents line length is assumed to be 80 characters. The - tablewidth is set relative to this value. If someone produces - documents with line length of 132 this will fail. - - Table width is tried to fit in page even if it is wider than - the assumed linewidth, still assumed linewidth is a hook. - -* In tools.txt the option tables right column, there should be some more spacing - between the description and the next paragraph "Default:". - - Paragraph separation in tables is hairy. - see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab - - - The strut solution did not work. - - setting extrarowheight added ad top of row not between paragraphs in - a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline. - - baselineskip/stretch does not help. -* Should there be two hlines after table head and on table end ? -* Table: multicol cells are always {l}. -* Table heads and footer for longtable (firstpage lastpage ..). -* Longtable does not work with multirow -* Tabularx says "do not use any multicolmn which spans any X column. - maybe use ltxtable instead of tabularx (Longtable combined with tabularx). - but ltxtable disables longtable's multicolumn. -* Table cells with multirow and multicolumn -* Tables have borders, and the border is missing in empty cells. - - -Miscellaneous -------------- - -* recongize LaTeX (or even latex) and replace by ```\LaTeX``. -* Support embed-stylesheet. -* the ^-sign is problematic: using mathmode wedge is usually the wrong font. -* Sidebar handling. -* Maybe add end of line after term in definition list. see - http://roundup.sf.net/doc-0.5/features.pdf -* Pdfbookmark level 4 (and greater) does not work (might be settable but OTOH). -* center subsection{Abstract} gives a latex error here. - ``! LaTeX Error: Something's wrong--perhaps a missing \item.`` - Committed a HACK: centering by hfill. -* Document errors are also too silent. -* Use optionlist for docinfo, the table does only work for single page. -* Consider peter funk's hooks for TeXpert: - - * Define his own document preamble (including the choice to - choose his own documentclass. That would make the ``--documentclass`` - option superfluous). I suggest to call this option ``--preamble`` - * Use two additional hooks to put additional stuff just behind the - ``\begin{document}`` and just before the ``\end{document}`` macros. - Typical uses would be ``\tableofcontents``, ``\listoffigures`` and - ``\appendix``, ``\makeindex``, ``\makeglossary`` and some such - for larger documents. - -* Hyphens: co-developers should be co--developers ? -* The indentional problematic error in test.txt is not referring anywhere. -* Footnotes are not all on the same page (as in tools/test.txt) and do not link back - and forth. -* No link to system errors. -* Hyperlinks are not hyphenated this leads to bad spacing. see tools/test.txt - 2.14 directives directives -* Meta keywords into pdf ? -* Pagestyle headings does not work, when sections are starred. -* For additional docinfo items: the field_body is inserted as text, i.e. no - markup is done. -* Multiple author entries in docinfo (same thing as in html). - diff --git a/docutils/docs/user/rst/images/ball1.gif b/docutils/docs/user/rst/images/ball1.gif Binary files differdeleted file mode 100644 index 3e14441d9..000000000 --- a/docutils/docs/user/rst/images/ball1.gif +++ /dev/null diff --git a/docutils/docs/user/rst/images/biohazard.png b/docutils/docs/user/rst/images/biohazard.png Binary files differdeleted file mode 100644 index ae4629d8b..000000000 --- a/docutils/docs/user/rst/images/biohazard.png +++ /dev/null diff --git a/docutils/docs/user/rst/images/title.png b/docutils/docs/user/rst/images/title.png Binary files differdeleted file mode 100644 index cc6218efe..000000000 --- a/docutils/docs/user/rst/images/title.png +++ /dev/null diff --git a/docutils/docs/user/rst/quickref.html b/docutils/docs/user/rst/quickref.html deleted file mode 100644 index b60cbf1b0..000000000 --- a/docutils/docs/user/rst/quickref.html +++ /dev/null @@ -1,1243 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> - <head> - <title>Quick reStructuredText</title> - - <style type="text/css"><!-- - a.backref { text-decoration: none ; color: black } - --></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/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>Updated 2003-06-10</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="../../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 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="#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="../../spec/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="#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>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">Hyperlinks</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">Hyperlinks</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="../../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" class="backref" - >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> -<br><samp>The underline/overline must be at</samp> -<br><samp>least as long as the title text.</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. - </table> - - <h2><a href="#contents" name="paragraphs" class="backref" - >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" class="backref" - >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" class="backref" - >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" class="backref" - >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" class="backref" - >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> - - <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="../../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" class="backref" - >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" class="backref" - >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" class="backref" - >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" class="backref" - >Tables</a></h2> - - <p>(<a href="../../spec/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"> - <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> - <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 frame="border" rules="all"> - <colgroup> - <col colwidth="31%" /> - <col colwidth="31%" /> - <col colwidth="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="../../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="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="../../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>"). - - <h3><a href="#contents" name="citations" class="backref" - >Citations</a></h3> - - <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> - - <h3><a href="#contents" name="hyperlink-targets" class="backref" - >Hyperlink Targets</a></h3> - - <p>(<a href="../../spec/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> - <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. - - <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><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> - - <h4><a href="#contents" name="indirect-hyperlink-targets" class="backref" - >Indirect Hyperlink Targets</a></h4> - - <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>. 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="../../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> - - <h3><a href="#contents" name="directives" class="backref" - >Directives</a></h3> - - <p>(<a href="../../spec/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="../../spec/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="../../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> - - <h3><a href="#contents" name="comments" class="backref" - >Comments</a></h3> - - <p>(<a href="../../spec/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@users.sourceforge.net">goodger@users.sourceforge.net</a>) - </address> - <!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 --> - </body> -</html> diff --git a/docutils/docs/user/rst/quickstart.txt b/docutils/docs/user/rst/quickstart.txt deleted file mode 100644 index d936147b0..000000000 --- a/docutils/docs/user/rst/quickstart.txt +++ /dev/null @@ -1,382 +0,0 @@ -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/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 overline 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`_``". - -To indicate the document title, 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" 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. - -__ ../../spec/rst/directives.html -__ ../../spec/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`_. The `Docutils project web site`_ has more -information. - -.. [#] If that relative link doesn't work, try the master document: - http://docutils.sourceforge.net/spec/rst/reStructuredText.html. - -.. _reStructuredText Markup Specification: - ../../spec/rst/reStructuredText.html -.. _post a message: mailto:docutils-users@lists.sourceforge.net -.. _Docutils-Users mailing list: - http://lists.sourceforge.net/lists/listinfo/docutils-users -.. _Docutils project web site: http://docutils.sourceforge.net/ diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt deleted file mode 100644 index b9af291f6..000000000 --- a/docutils/docs/user/tools.txt +++ /dev/null @@ -1,724 +0,0 @@ -========================== - Docutils Front-End Tools -========================== - -:Author: David Goodger -:Contact: goodger@users.sourceforge.net -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This document has been placed in the public domain. - -.. contents:: - - -Introduction -============ - -Once the Docutils package is unpacked, you will discover a "``tools``" -directory containing several front ends for common Docutils -processing. Rather than a single all-purpose program, Docutils has -many small front ends, each specialized for a specific "Reader" (which -knows how to interpret a file in context), a "Parser" (which -understands the syntax of the text), and a "Writer" (which knows how -to generate a specific data format). Most front ends have common -options and the same command-line usage pattern:: - - toolname [options] [<source> [<destination]] - -The exceptions are buildhtml.py_ and pep2html.py_. See html.py_ for -concrete examples. Each tool has a "``--help``" option which lists -the `command-line options`_ and arguments it supports. Processing can -also be customized with `configuration files`_. - -The two arguments, "source" and "destination", are optional. If only -one argument (source) is specified, the standard output (stdout) is -used for the destination. If no arguments are specified, the standard -input (stdin) is used for the source as well. - - -Getting Help ------------- - -First, try the "``--help``" option each front-end tool has. - -Users who have questions or need assistance with Docutils or -reStructuredText should `post a message`_ to the `Docutils-Users -mailing list`_. The `Docutils project web site`_ has more -information. - -.. _post a message: mailto:docutils-users@lists.sourceforge.net -.. _Docutils-Users mailing list: - http://lists.sourceforge.net/lists/listinfo/docutils-users -.. _Docutils project web site: http://docutils.sourceforge.net/ - - -The Tools -========= - -buildhtml.py ------------- - -:Readers: Standalone, PEP -:Parser: reStructuredText -:Writers: HTML, PEP/HTML - -Use ``buildhtml.py`` to generate .html from all the .txt files -(including PEPs) in each <directory> given, and their subdirectories -too. (Use the ``--local`` option to skip subdirectories.) - -Usage:: - - buildhtml.py [options] [<directory> ...] - -After unpacking the Docutils package, the following shell commands -will generate HTML for all included documentation:: - - cd docutils/tools - buildhtml.py .. - -For official releases, the directory may be called "docutils-X.Y", -where "X.Y" is the release version. Alternatively:: - - cd docutils - tools/buildhtml.py --config=tools/docutils.conf - -The current directory (and all subdirectories) is chosen by default if -no directory is named. Some files may generate system messages -(tools/test.txt contains intentional errors); use the ``--quiet`` -option to suppress all warnings. The ``--config`` option ensures that -the correct stylesheets, templates, and settings are in place -(``./docutils.conf`` is picked up automatically). Command-line -options may be used to override config file settings or replace them -altogether. - - -html.py -------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: HTML - -The ``html.py`` front end reads standalone reStructuredText source -files and produces HTML 4 (XHTML 1) output compatible with modern -browsers. For example, to process a reStructuredText file -"``test.txt``" into HTML:: - - html.py test.txt test.html - -In fact, there *is* a "``test.txt``" file in the "``tools``" -directory. It contains "at least one example of each reStructuredText -construct", including intentional errors. Use it to put the system -through its paces and compare input to output. - -Now open the "``test.html``" file in your favorite browser to see the -results. To get a footer with a link to the source file, date & time -of processing, and links to the Docutils projects, add some options:: - - html.py -stg test.txt test.html - - -Stylesheets -``````````` - -``html.py`` inserts into the generated HTML a link to a cascading -stylesheet, defaulting to "``default.css``" (override with a -"``--stylesheet``" or "``--stylesheet-path``" command-line option or -with configuration file settings). The -"``tools/stylesheets/default.css``" stylesheet is provided for basic -use. To experiment with styles, rather than editing the default -stylesheet (which will be updated as the project evolves), it is -recommended to use an "``@import``" statement to create a "wrapper" -stylesheet. For example, a "``my.css``" stylesheet could contain the -following:: - - @import url(default.css); - - h1, h2, h3, h4, h5, h6, p.topic-title { - font-family: sans-serif } - -Generate HTML with the following command:: - - html.py -stg --stylesheet my.css test.txt test.html - -When viewed in a browser, the new "wrapper" stylesheet will change the -typeface family of titles to "sans serif", typically Helvetica or -Arial. Other styles will not be affected. Styles in wrapper -stylesheets override styles in imported stylesheets, enabling -incremental experimentation. - - -pep.py ------- - -:Reader: PEP -:Parser: reStructuredText -:Writer: PEP/HTML - -``pep.py`` reads a new-style PEP (marked up with reStructuredText) and -produces HTML. It requires a template file and a stylesheet. By -default, it makes use of a "``pep-html-template``" file and a -"``default.css``" stylesheet in the current directory, but these can -be overridden by command-line options or configuration files. The -"``tools/stylesheets/pep.css``" stylesheet is intended specifically -for PEP use. - -The "``docutils.conf``" `configuration file`_ in the "``spec``" -directory of Docutils contains a default setup for use in processing -the PEP files there (``spec/pep-*.txt``) into HTML. It specifies a -default template (``tools/pep-html-template``) and a default -stylesheet (``tools/stylesheets/pep.css``). See Stylesheets_ above -for more information. - - -pep2html.py ------------ - -:Reader: PEP -:Parser: reStructuredText -:Writer: PEP/HTML - -``pep2html.py`` is a modified version of the original script by -Fredrik Lundh, with support for Docutils added. It reads the -beginning of a PEP text file to determine the format (old-style -indented or new-style reStructuredText) and processes accordingly. -Since it does not use the Docutils front end mechanism (the common -command-line options are not supported), it must be configured using -`configuration files`_. The template and stylesheet requirements of -``pep2html.py`` are the same as those of `pep.py`_ above. - -Arguments to ``pep2html.py`` may be a list of PEP numbers or .txt -files. If no arguments are given, all files of the form -"``pep-*.txt``" are processed. - - -rst2latex.py ------------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: LaTeX2e - -The ``rst2latex.py`` front end reads standalone reStructuredText -source files and produces LaTeX2e output. For example, to process a -reStructuredText file "``test.txt``" into LaTeX:: - - rst2latex.py test.txt test.tex - -The output file "``test.tex``" should then be processed with ``latex`` -or ``pdflatex`` to get a typeset document. - -Some limitations and difference apply: - -- Gif,jpg or png images are not handled, when processed with - ``latex``, use ``pdflatex`` instead. -- Only Latin-1 is tested up to now. -- The generated file includes a file ``style.tex``, which allows the - inclusion of special packages or changes to settings made in the - header. -- Not all constructs are possible (e.g. multirow/multicoumn entries in - tables are not). - - -docutils-xml.py ---------------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: XML (Docutils native) - -The ``docutils-xml.py`` front end produces Docutils-native XML output. -This can be transformed with standard XML tools such as XSLT -processors into arbitrary final forms. - - -publish.py ----------- - -:Reader: Standalone -:Parser: reStructuredText -:Writer: Pseudo-XML - -``publish.py`` is used for debugging the Docutils Reader to Transform -to Writer pipeline. It produces a compact pretty-printed -"pseudo-XML", where nesting is indicated by indentation (no end-tags). -External attributes for all elements are output, and internal -attributes for any leftover "pending" elements are also given. - - -quicktest.py ------------- - -:Reader: N/A -:Parser: reStructuredText -:Writer: N/A - -The ``quicktest.py`` tool is used for testing the reStructuredText -parser. It does not use a Docutils Reader or Writer or the standard -Docutils command-line options. Rather, it does its own I/O and calls -the parser directly. No transforms are applied to the parsed -document. Various forms output are possible: - -- Pretty-printed pseudo-XML (default) -- Test data (Python list of input and pseudo-XML output strings; - useful for creating new test cases) -- Pretty-printed native XML -- Raw native XML (with or without a stylesheet reference) - - - -Customization -============= - -Command-Line Options --------------------- - -Each front-end tool supports command-line options for one-off -customization. For persistent customization, use `configuration -files`_. - -Use the "--help" option on each of the front ends to list the -command-line options it supports. Command-line options and their -corresponding configuration file entry names are listed in -`Configuration File Entries`_ below. - - -.. _configuration file: - -Configuration Files -------------------- - -Configuration files are used for persistent customization; they can be -set once and take effect every time you use a front-end tool. - -By default, Docutils checks the following places for configuration -files, in the following order: - -1. ``/etc/docutils.conf``: This is a system-wide configuration file, - applicable to all Docutils processing on the system. - -2. ``./docutils.conf``: This is a project-specific configuration file, - located in the current directory. The Docutils front end has to be - executed from the directory containing this configuration file for - it to take effect (note that this may have nothing to do with the - location of the source files). Settings in the project-specific - configuration file will override corresponding settings in the - system-wide file. - -3. ``~/.docutils``: This is a user-specific configuration file, - located in the user's home directory. Settings in this file will - override corresponding settings in both the system-wide and - project-specific configuration files. - -If more than one configuration file is found, all will be read but -later entries will override earlier ones. For example, a "stylesheet" -entry in a user-specific configuration file will override a -"stylesheet" entry in the system-wide file. - -In addition, a configuration file may be explicitly specified with the -"--config" command-line option. This configuration file is read after -the three implicit ones listed above. - -Configuration files use the standard ConfigParser.py_ Python_ module. -From its documentation: - - The configuration file consists of sections, lead by a "[section]" - header and followed by "name: value" entries, with continuations - in the style of `RFC 822`_; "name=value" is also accepted. Note - that leading whitespace is removed from values. The optional - values can contain format strings which refer to other values in - the same section, or values in a special DEFAULT section. - Additional defaults can be provided upon initialization and - retrieval. Lines beginning with "#" or ";" are ignored and may be - used to provide comments. - -Docutils currently only uses an "[options]" section; all other -sections are ignored. - -.. Note:: The configuration file format may change in the future. - -Configuration entry names correspond to internal option attributes. -Underscores ("_") and hyphens ("-") can be used interchangably in -entry names. The correspondence between entry names and command-line -options is listed in `Configuration File Entries`_ below. - -.. _ConfigParser.py: - http://www.python.org/doc/current/lib/module-ConfigParser.html -.. _Python: http://www.python.org/ -.. _RFC 822: http://www.rfc-editor.org/rfc/rfc822.txt - - -Configuration File Entries --------------------------- - -Listed below are the Docutils runtime settings. Most may be specified -in `configuration files`_, where hyphens may be used in place of -underscores. Some knowledge of Python_ is assumed for some -attributes. - -attribution - (HTML Writer.) Format for block quote attributions: one of "dash" - (em-dash prefix), "parentheses"/"parens", or "none". - - Default: "dash". Options: ``--attribution``. - -compact_lists - (HTML Writer.) Remove extra vertical whitespace between items of - bullet lists and enumerated lists, when list items are "simple" - (i.e., all items each contain one paragraph and/or one "simple" - sublist only). - - Default: enabled (1). Options: ``--compact-lists, - --no-compact-lists``. - -config - Path to a configuration file to read (if it exists) - [#pwd]_. Settings may override defaults and earlier settings. - This is only effective as a command-line option; setting it in a - config file has no effect. - - Filesystem path settings contained within the config file will be - interpreted relative to the config file's location (*not* relative - to the current working directory). - - Default: None. Options: ``--config``. - -datestamp - Include a time/datestamp in the document footer. Contains a - format string for Python's ``time.strftime``. See the `time - module documentation`__. - - Default: None. Options: ``--date, -d, --time, -t, - --no-datestamp``. - - __ http://www.python.org/doc/current/lib/module-time.html - -debug - Report debug-level system messages. - - Default: don't (None). Options: ``--debug, --no-debug``. - -docinfo_xform - (Standalone Reader.) Enable or disable the bibliographic field - list transform (docutils.transforms.frontmatter.DocInfo). - - Default: enabled (1). Options: ``--no-doc-info``. - -doctitle_xform - - (Standalone Reader.) Enable or disable the promotion of a lone - top-level section title to document title (and subsequent section - title to document subtitle promotion; - docutils.transforms.frontmatter.DocTitle). - - Default: enabled (). Options: ``--no-doc-title``. - -doctype_declaration - (XML Writer.) Generate XML with a DOCTYPE declaration. - - Default: do (1). Options: ``--no-doctype``. - -dump_internals - At the end of processing, write all internal attributes of the - document (``document.__dict__``) to stderr. - - Default: don't (None). Options: ``--dump-internals`` (hidden, for - development use only). - -dump_pseudo_xml - At the end of processing, write the pseudo-XML representation of - the document to stderr. - - Default: don't (None). Options: ``--dump-pseudo-xml`` (hidden, - for development use only). - -dump_settings - At the end of processing, write all Docutils settings to stderr. - - Default: don't (None). Options: ``--dump-settings`` (hidden, for - development use only). - -dump_transforms - At the end of processing, write a list of all transforms applied - to the document to stderr. - - Default: don't (None). Options: ``--dump-transforms`` (hidden, - for development use only). - -embed_stylesheet - (HTML Writer.) Embed the stylesheet in the output HTML file. The - stylesheet file must be accessible during processing. The - stylesheet is embedded inside a comment, so it must not contain - the text "``--``" (two hyphens). - - Default: link, don't embed (None). Options: ``--embed-stylesheet, - --link-stylesheet``. - -error_encoding - The text encoding for error output. - - Default: "ascii". Options: ``--error-encoding, -e``. - -error_encoding_error_handler - The encoding error handler for unencodable characters in error - output. Acceptable values are the same as for the "error" - parameter of Python's ``encode`` string method. - - Default: "backslashreplace" for Python 2.3 and later; "replace" - otherwise. Options: ``--error-encoding-error-handler, - --error-encoding, -e``. - -exit_level - A system message level threshold; non-halting system messages at - or above this level will produce a non-zero exit status at normal - exit. Exit status is the maximum system message level plus 10 (11 - for INFO, etc.). - - Default: disabled (5). Options: ``--exit``. - -expose_internals - List of internal attribues to expose as external attributes (with - "internal:" namespace prefix). - - Default: don't (None). Options: ``--expose-internal-attribute`` - (hidden, for development use only). - -footnote_backlinks - Enable or disable backlinks from footnotes and citations to their - references. - - Default: enabled (1). Options: ``--footnote-backlinks, - --no-footnote-backlinks``. - -footnote_references - (HTML Writer.) Format for footnote references, one of - "superscript" or "brackets". - - Default: "superscript"; "brackets" in PEP/HTML Writer. Options: - ``--footnote-references``. - -generator - Include a "Generated by Docutils" credit and link in the document - footer. - - Default: off (None). Options: ``--generator, -g, - --no-generator``. - -halt_level - The threshold at or above which system messages are converted to - exceptions, halting execution immediately. - - Default: severe (4). Options: ``--halt, --strict``. - -indents - (XML Writer.) Generate XML with indents and newlines. - - Default: don't (None). Options: ``--indents``. - -input_encoding - The text encoding for input. - - Default: auto-detect (None). Options: ``--input-encoding, -i``. - -language_code - `ISO 639`_ 2-letter language code (3-letter codes used only if no - 2-letter code exists). - - Default: English ("en"). Options: ``--language, -l``. - -newlines - (XML Writer.) Generate XML with newlines before and after tags. - - Default: don't (None). Options: ``--newlines``. - -no_random - (PEP/HTML Writer.) Workaround for platforms which core-dump on - "``import random``". - - Default: random enabled (None). Options: ``--no-random`` - (hidden). - -output_encoding - The text encoding for output. - - Default: "UTF-8". Options: ``--output-encoding, -o``. - -output_encoding_error_handler - The encoding error handler for unencodable characters in output. - Acceptable values are the same as for the "error" parameter of - Python's ``encode`` string method. - - Default: "strict". Options: ``--output-encoding-error-handler, - --output-encoding, -o``. - -pep_home - (PEP/HTML Writer.) Home URL prefix for PEPs. - - Default: current directory ("."). Options: ``--pep-home``. - -pep_references - (reStructuredText Parser.) Recognize and link to PEP references - (like "PEP 258"). - - Default: disabled (None); enabled (1) in PEP Reader. Options: - ``--pep-references``. - -pep_stylesheet - (PEP/HTML Writer.) CSS stylesheet URL, used verbatim. Overrides - HTML stylesheet (``--stylesheet``). - - Default: None. Options: ``--pep-stylesheet``. - -pep_stylesheet_path - (PEP/HTML Writer.) Path to CSS stylesheet [#pwd]_. Path is - adjusted relative to the output HTML file. Overrides HTML - stylesheet (``--stylesheet``) and PEP stylesheet - (``--pep-stylesheet``). - - Default: None. Options: ``--pep-stylesheet-path``. - -pep_template - (PEP/HTML Writer.) Path to PEP template file [#pwd]_. - - Default: "pep-html-template" (in current directory). Options: - ``--pep-template``. - -python_home - (PEP/HTML Writer.) Python's home URL. - - Default: parent directory (".."). Options: ``--python-home``. - -recurse - (``buildhtml.py`` front end.) Recursively scan subdirectories. - - Default: recurse (1). Options: ``--recurse, --local``. - -report_level - Verbosity threshold at or above which system messages are - reported. - - Default: warning (2). Options: ``--report, -r, --verbose, -v, - --quiet, -q``. - -rfc_references - (reStructuredText Parser.) Recognize and link to RFC references - (like "RFC 822"). - - Default: disabled (None); enabled (1) in PEP Reader. Options: - ``--rfc-references``. - -silent - (``buildhtml.py`` front end.) Work silently (no progress - messages). Independent of "report_level". - - Default: show progress (None). Options: ``--silent``. - -source_link - Include a "View document source" link in the document footer. URL - will be relative to the destination. - - Default: don't (None). Options: ``--source-link, -s, - --no-source-link``. - -source_url - An explicit URL for a "View document source" link, used verbatim. - - Default: compute if source_link (None). Options: ``--source-uri, - --no-source-link``. - -stylesheet - (HTML Writer.) CSS stylesheet URL, used verbatim. Overridden by - "stylesheet_path" URL option (``--stylesheet-path``). - - Default: "default.css". Options: ``--stylesheet``. - -stylesheet_path - (HTML Writer.) Path to CSS stylesheet [#pwd]_. Overrides - "stylesheet" URL option (``--stylesheet``). Path is adjusted - relative to the output HTML file. - - Default: None. Options: ``--stylesheet``. - -tab_width - (reStructuredText Parser.) Number of spaces for hard tab - expansion. - - Default: 8. Options: ``--tab-width``. - -toc_backlinks - Enable backlinks from section titles to table of contents entries - ("entry"), to the top of the TOC ("top"), or disable ("none"). - - Default: "entry". Options: ``--toc-entry-backlinks, - --toc-top-backlinks, --no-toc-backlinks``. - -traceback - Enable Python tracebacks when an error occurs. - - Default: disabled (None). Options: ``--traceback, - --no-traceback``. - -trim-footnote-reference-space - (reStructuredText Parser.) Remove spaces before footnote - references. - - Default: don't (None). Options: - ``--trim-footnote-reference-space``. - -warning_stream - Path to a file for the output of system messages (warnings) - [#pwd]_. - - Default: stderr (None). Options: ``--warnings``. - -xml_declaration - (XML and HTML Writers.) Generate XML with an XML declaration. - - .. Caution:: The XML declaration carries text encoding - information, without which standard tools may be unable to read - the generated XML. - - Default: do (1). Options: ``--no-xml-declaration``. - - -For Internal Use Only -````````````````````` - -Setting these in a config file has no effect. - - -_directories - (``buildhtml.py`` front end.) List of paths to source - directories, set from positional arguments. - - Default: current working directory (None). No command-line - options. - -_disable_config - Prevent standard configuration files from being read. - - Default: config files enabled (None). No command-line options. - -_destination - Path to output destination, set from positional arguments. - - Default: stdout (None). No command-line options. - -_source - Path to input source, set from positional arguments. - - Default: stdin (None). No command-line options. - -.. _ISO 639: http://lcweb.loc.gov/standards/iso639-2/englangn.html - -.. [#pwd] Path relative to the working directory of the process at - launch. - - -.. - Local Variables: - mode: indented-text - indent-tabs-mode: nil - sentence-end-double-space: t - fill-column: 70 - End: |
