1 \documentclass[10pt,
a4paper,english
]{article
}
6 \usepackage[latin1]{inputenc}
9 \setlength{\extrarowheight}{2pt
}
15 \usepackage[DIV12
]{typearea
}
16 % generated by Docutils <http://docutils.sourceforge.net/>
17 \newlength{\admonitionwidth}
18 \setlength{\admonitionwidth}{0.9\textwidth}
19 \newlength{\docinfowidth}
20 \setlength{\docinfowidth}{0.9\textwidth}
21 \newlength{\locallinewidth}
22 \newcommand{\optionlistlabel}[1]{\bf #1 \hfill}
23 \newenvironment{optionlist
}[1]
25 {\setlength{\labelwidth}{#1}
26 \setlength{\rightmargin}{1cm
}
27 \setlength{\leftmargin}{\rightmargin}
28 \addtolength{\leftmargin}{\labelwidth}
29 \addtolength{\leftmargin}{\labelsep}
30 \renewcommand{\makelabel}{\optionlistlabel}}
32 \newlength{\lineblockindentation}
33 \setlength{\lineblockindentation}{2.5em
}
34 \newenvironment{lineblock
}[1]
36 {\setlength{\partopsep}{\parskip}
37 \addtolength{\partopsep}{\baselineskip}
38 \topsep0pt\itemsep0.15
\baselineskip\parsep0pt
42 % begin: floats for footnotes tweaking.
43 \setlength{\floatsep}{0.5em
}
44 \setlength{\textfloatsep}{\fill}
45 \addtolength{\textfloatsep}{3em
}
46 \renewcommand{\textfraction}{0.5}
47 \renewcommand{\topfraction}{0.5}
48 \renewcommand{\bottomfraction}{0.5}
49 \setcounter{totalnumber
}{50}
50 \setcounter{topnumber
}{50}
51 \setcounter{bottomnumber
}{50}
52 % end floats for footnotes
53 % some commands, that could be overwritten in the style file.
54 \newcommand{\rubric}[1]{\subsection*
{~
\hfill {\it #1} \hfill ~
}}
55 \newcommand{\titlereference}[1]{\textsl{#1}}
56 % end of "some commands"
57 \ifthenelse{\isundefined{\hypersetup}}{
58 \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue
]{hyperref
}
60 \title{reStructuredText Test Document\\
61 \large{Examples of Syntax Constructs
}
66 pdftitle=
{reStructuredText Test Document
},
67 pdfauthor=
{David Goodger;Me;Myself;I
}
72 %___________________________________________________________________________
74 \begin{tabularx
}{\docinfowidth}{lX
}
83 \href{mailto:goodger@python.org
}{goodger@python.org
} \\
90 \textbf{Organization
}: &
93 Now, or yesterday. Or maybe even
\emph{before
} yesterday. \\
95 This is a ``work in progress'' \\
97 is managed by a version control system. \\
100 \textbf{Copyright
}: &
101 This
document has been placed in the public domain. You
102 may do with it as you wish. You may copy, modify,
103 redistribute, reattribute, sell, buy, rent, lease,
104 destroy, or improve it, quote it at length, excerpt,
105 incorporate, collate, fold, staple, or mutilate it, or do
106 anything else to it that your or anyone else's heart
108 \textbf{field name
}: &
109 This is a ``generic bibliographic field''. \\
110 \textbf{field name ``
2''
}: &
111 Generic bibliographic fields may contain multiple body elements.
117 \setlength{\locallinewidth}{\linewidth}
120 \subsubsection*
{~
\hfill Dedication
\hfill ~
}
122 For Docutils users
{\&
} co-developers.
124 \subsubsection*
{~
\hfill Abstract
\hfill ~
}
126 This is a test
document, containing at least one example of each
127 reStructuredText construct.
129 % This is a comment. Note how any initial comments are moved by
130 % transforms to after the document title, subtitle, and docinfo.
131 \hypertarget{doctitle
}{}% Above is the document title, and below is the subtitle.
132 % They are transformed from section titles after parsing.
133 \hypertarget{subtitle
}{}% bibliographic fields (which also require a transform):
134 \hypertarget{table-of-contents
}{}
135 \pdfbookmark[0]{Table of Contents
}{table-of-contents
}
136 \subsubsection*
{~
\hfill Table of Contents
\hfill ~
}
137 \label{table-of-contents
}
139 \item {} \href{\#structural-elements
}{1~~~Structural Elements
}
141 \item {} \href{\#section-title
}{1.1~~~Section Title
}
143 \item {} \href{\#empty-section
}{1.2~~~Empty Section
}
145 \item {} \href{\#transitions
}{1.3~~~Transitions
}
149 \item {} \href{\#body-elements
}{2~~~Body Elements
}
151 \item {} \href{\#paragraphs
}{2.1~~~Paragraphs
}
153 \item {} \href{\#inline-markup
}{2.1.1~~~Inline Markup
}
157 \item {} \href{\#bullet-lists
}{2.2~~~Bullet Lists
}
159 \item {} \href{\#enumerated-lists
}{2.3~~~Enumerated Lists
}
161 \item {} \href{\#definition-lists
}{2.4~~~Definition Lists
}
163 \item {} \href{\#field-lists
}{2.5~~~Field Lists
}
165 \item {} \href{\#option-lists
}{2.6~~~Option Lists
}
167 \item {} \href{\#literal-blocks
}{2.7~~~Literal Blocks
}
169 \item {} \href{\#line-blocks
}{2.8~~~Line Blocks
}
171 \item {} \href{\#block-quotes
}{2.9~~~Block Quotes
}
173 \item {} \href{\#doctest-blocks
}{2.10~~~Doctest Blocks
}
175 \item {} \href{\#footnotes
}{2.11~~~Footnotes
}
177 \item {} \href{\#citations
}{2.12~~~Citations
}
179 \item {} \href{\#targets
}{2.13~~~Targets
}
181 \item {} \href{\#duplicate-target-names
}{2.13.1~~~Duplicate Target Names
}
183 \item {} \href{\#id21
}{2.13.2~~~Duplicate Target Names
}
187 \item {} \href{\#directives
}{2.14~~~Directives
}
189 \item {} \href{\#
document-parts
}{2.14.1~~~Document Parts
}
191 \item {} \href{\#images
}{2.14.2~~~Images
}
193 \item {} \href{\#admonitions
}{2.14.3~~~Admonitions
}
195 \item {} \href{\#topics-sidebars-and-rubrics
}{2.14.4~~~Topics, Sidebars, and Rubrics
}
197 \item {} \href{\#target-footnotes
}{2.14.5~~~Target Footnotes
}
199 \item {} \href{\#replacement-text
}{2.14.6~~~Replacement Text
}
201 \item {} \href{\#compound-paragraph
}{2.14.7~~~Compound Paragraph
}
203 \item {} \href{\#parsed-literal-blocks
}{2.14.8~~~Parsed Literal Blocks
}
207 \item {} \href{\#substitution-definitions
}{2.15~~~Substitution Definitions
}
209 \item {} \href{\#comments
}{2.16~~~Comments
}
211 \item {} \href{\#raw-text
}{2.17~~~Raw text
}
213 \item {} \href{\#container
}{2.18~~~Container
}
215 \item {} \href{\#colspanning-tables
}{2.19~~~Colspanning tables
}
217 \item {} \href{\#rowspanning-tables
}{2.20~~~Rowspanning tables
}
221 \item {} \href{\#tests-for-the-latex-writer
}{3~~~Tests for the LaTeX writer
}
223 \item {} \href{\#some-tests-for-the-latex2e-writer
}{4~~~Some Tests for the LaTeX2e Writer
}
225 \item {} \href{\#id24
}{5~~~Option lists
}
227 \item {} \href{\#monospaced-non-alphanumeric-characters
}{5.1~~~Monospaced non-alphanumeric characters
}
229 \item {} \href{\#various-non-ascii-characters
}{5.2~~~Various non-ASCII characters
}
231 \item {} \href{\#custom-roles
}{5.3~~~Custom Roles
}
235 \item {} \href{\#error-handling
}{6~~~Error Handling
}
241 %___________________________________________________________________________
243 \hypertarget{structural-elements
}{}
244 \pdfbookmark[0]{1~~~Structural Elements
}{structural-elements
}
245 \section*
{1~~~Structural Elements
}
246 \label{structural-elements
}
249 %___________________________________________________________________________
251 \hypertarget{section-title
}{}
252 \pdfbookmark[1]{1.1~~~Section Title
}{section-title
}
253 \subsection*
{1.1~~~Section Title
}
254 \label{section-title
}
255 \textbf{Section Subtitle
}\vspace{0.2cm
}
258 That's it, the text just above this line.
261 %___________________________________________________________________________
263 \hypertarget{empty-section
}{}
264 \pdfbookmark[1]{1.2~~~Empty Section
}{empty-section
}
265 \subsection*
{1.2~~~Empty Section
}
266 \label{empty-section
}
269 %___________________________________________________________________________
271 \hypertarget{transitions
}{}
272 \pdfbookmark[1]{1.3~~~Transitions
}{transitions
}
273 \subsection*
{1.3~~~Transitions
}
279 %___________________________________________________________________________
280 \hspace*
{\fill}\hrulefill\hspace*
{\fill}
283 It divides the section. Transitions may also occur between sections:
286 %___________________________________________________________________________
287 \hspace*
{\fill}\hrulefill\hspace*
{\fill}
291 %___________________________________________________________________________
293 \hypertarget{body-elements
}{}
294 \pdfbookmark[0]{2~~~Body Elements
}{body-elements
}
295 \section*
{2~~~Body Elements
}
296 \label{body-elements
}
299 %___________________________________________________________________________
301 \hypertarget{paragraphs
}{}
302 \pdfbookmark[1]{2.1~~~Paragraphs
}{paragraphs
}
303 \subsection*
{2.1~~~Paragraphs
}
309 %___________________________________________________________________________
311 \hypertarget{inline-markup
}{}
312 \pdfbookmark[2]{2.1.1~~~Inline Markup
}{inline-markup
}
313 \subsubsection*
{2.1.1~~~Inline Markup
}
314 \label{inline-markup
}
316 Paragraphs contain text and may contain inline markup:
\emph{emphasis
},
317 \textbf{strong emphasis
},
\texttt{inline literals
}, standalone hyperlinks
318 (
\href{http://www.python.org
}{http://www.python.org
}), external hyperlinks (
\href{http://www.python.org/
}{Python
}\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id27
}{5}}), internal
319 cross-references (
\href{\#example
}{example
}), external hyperlinks with embedded URIs
320 (
\href{http://www.python.org
}{Python web site
}),
\href{http://www.python.org/
}{anonymous hyperlink
321 references
}\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id27
}{5}} (
\href{http://docutils.sourceforge.net/
}{a second reference
}\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id32
}{6}}), footnote references (manually
322 numbered
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id8
}{1}}, anonymous auto-numbered
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id12
}{3}}, labeled auto-numbered
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{label
}{2}}, or symbolic
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id13
}{*
}}), citation references (
[\hyperlink{cit2002
}{CIT2002
}]),
323 substitution references (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}), and
\hypertarget{inline-hyperlink-targets
}{inline hyperlink targets
}
324 (see
\href{\#id23
}{Targets
} below for a reference back to here). Character-level
325 inline markup is also possible (although exceedingly ugly!) in
\emph{re
}\texttt{Structured
}\emph{Text
}. Problems are indicated by
{\color{red
}\bfseries{}{\textbar}problematic
{\textbar}} text
326 (generated by processing errors; this one is intentional). Here is a
327 reference to the
\href{\#doctitle
}{doctitle
} and the
\href{\#subtitle
}{subtitle
}.
329 The default role for interpreted text is
\titlereference{Title Reference
}. Here are
330 some explicit interpreted text roles: a PEP reference (
\href{http://www.python.org/dev/peps/pep-
0287}{PEP
287}); an
331 RFC reference (
\href{http://www.faqs.org/rfcs/rfc2822.html
}{RFC
2822}); a $_
{subscript
}$; a $^
{superscript
}$;
332 and explicit roles for
\emph{standard
} \textbf{inline
}
334 % DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
336 Let's test wrapping and whitespace significance in inline literals:
337 \texttt{This is an example of -
{}-inline-literal -
{}-text, -
{}-including some-
{}-
338 strangely-
{}-hyphenated-words. Adjust-the-width-of-your-browser-window
339 to see how the text is wrapped. -
{}- -
{}-
{}-
{}- -
{}-
{}-
{}-
{}-
{}-
{}-
{}- Now note the
340 spacing between the words of this sentence (words
341 should be grouped in pairs).
}
343 If the
\texttt{-
{}-pep-references
} option was supplied, there should be a
344 live link to PEP
258 here.
347 %___________________________________________________________________________
349 \hypertarget{bullet-lists
}{}
350 \pdfbookmark[1]{2.2~~~Bullet Lists
}{bullet-lists
}
351 \subsection*
{2.2~~~Bullet Lists
}
368 Paragraph
2 of item
2.
388 This nested list should be compacted by the HTML writer.
389 \hypertarget{target
}{}% Even if this item contains a target and a comment.
396 %___________________________________________________________________________
398 \hypertarget{enumerated-lists
}{}
399 \pdfbookmark[1]{2.3~~~Enumerated Lists
}{enumerated-lists
}
400 \subsection*
{2.3~~~Enumerated Lists
}
401 \label{enumerated-lists
}
402 \newcounter{listcnt0
}
403 \begin{list
}{\arabic{listcnt0
}.
}
405 \usecounter{listcnt0
}
406 \setlength{\rightmargin}{\leftmargin}
410 \newcounter{listcnt1
}
411 \begin{list
}{\alph{listcnt1
})
}
413 \usecounter{listcnt1
}
414 \setlength{\rightmargin}{\leftmargin}
418 \newcounter{listcnt2
}
419 \begin{list
}{(
\roman{listcnt2
})
}
421 \usecounter{listcnt2
}
422 \setlength{\rightmargin}{\leftmargin}
426 \newcounter{listcnt3
}
427 \begin{list
}{\Alph{listcnt3
}.
}
429 \usecounter{listcnt3
}
430 \setlength{\rightmargin}{\leftmargin}
434 \newcounter{listcnt4
}
435 \begin{list
}{\Roman{listcnt4
})
}
437 \usecounter{listcnt4
}
438 \setlength{\rightmargin}{\leftmargin}
452 Lists that don't start at
1:
453 \setcounter{listcnt1
}{0}
454 \begin{list
}{\arabic{listcnt1
}.
}
456 \usecounter{listcnt1
}
457 \addtocounter{listcnt1
}{2}
458 \setlength{\rightmargin}{\leftmargin}
467 \setcounter{listcnt1
}{0}
468 \begin{list
}{\Alph{listcnt1
}.
}
470 \usecounter{listcnt1
}
471 \addtocounter{listcnt1
}{2}
472 \setlength{\rightmargin}{\leftmargin}
481 \setcounter{listcnt1
}{0}
482 \begin{list
}{\roman{listcnt1
}.
}
484 \usecounter{listcnt1
}
485 \addtocounter{listcnt1
}{2}
486 \setlength{\rightmargin}{\leftmargin}
499 %___________________________________________________________________________
501 \hypertarget{definition-lists
}{}
502 \pdfbookmark[1]{2.4~~~Definition Lists
}{definition-lists
}
503 \subsection*
{2.4~~~Definition Lists
}
504 \label{definition-lists
}
506 \item[{Term
}] \leavevmode
509 \item[{Term
}] \leavevmode (
\textbf{classifier
})
511 Definition paragraph
1.
513 Definition paragraph
2.
515 \item[{Term
}] \leavevmode
518 \item[{Term
}] \leavevmode (
\textbf{classifier one
})
519 (
\textbf{classifier two
})
526 %___________________________________________________________________________
528 \hypertarget{field-lists
}{}
529 \pdfbookmark[1]{2.5~~~Field Lists
}{field-lists
}
530 \subsection*
{2.5~~~Field Lists
}
535 Field lists map field names to field bodies, like database
536 records. They are often part of an extension syntax. They are
537 an unambiguous variant of RFC
2822 fields.
540 \item [how arg1 arg2:
]
541 The field marker is a colon, the field name, and a colon.
543 The field body may contain one or more body elements, indented
544 relative to the field marker.
548 This paragraph has the
\titlereference{credits
} class set. (This is actually not
549 about credits but just for ensuring that the class attribute
550 doesn't get stripped away.)
557 %___________________________________________________________________________
559 \hypertarget{option-lists
}{}
560 \pdfbookmark[1]{2.6~~~Option Lists
}{option-lists
}
561 \subsection*
{2.6~~~Option Lists
}
564 For listing command-line options:
565 \begin{optionlist
}{3cm
}
567 command-line option ``a''
569 options can have arguments
570 and long descriptions
572 options can be long also
573 \item [-
{}-input=file
]
574 long options can also have
576 \item [-
{}-very-long-option
]
577 The description can also start on the next line.
579 The description may contain multiple body elements,
580 regardless of where it starts.
582 Multiple options are an ``option group''.
583 \item [-v, -
{}-verbose
]
584 Commonly-seen: short
{\&
} long options.
585 \item [-
1 file, -
{}-one=file, -
{}-two file
]
586 Multiple options with arguments.
588 DOS/VMS-style options too
591 There must be at least two spaces between the option and the
595 %___________________________________________________________________________
597 \hypertarget{literal-blocks
}{}
598 \pdfbookmark[1]{2.7~~~Literal Blocks
}{literal-blocks
}
599 \subsection*
{2.7~~~Literal Blocks
}
600 \label{literal-blocks
}
602 Literal blocks are indicated with a double-colon (``::'') at the end of
603 the preceding paragraph (over there
\texttt{-
{}->
}). They can be indented:
604 \begin{quote
}{\ttfamily \raggedright \noindent
605 if~literal
{\_}block:~\\
606 ~~~~text~=~'is~left~as-is'~\\
607 ~~~~spaces
{\_}and
{\_}linebreaks~=~'are~preserved'~\\
608 ~~~~markup
{\_}processing~=~None
611 Or they can be quoted without indentation:
612 \begin{quote
}{\ttfamily \raggedright \noindent
615 >~Why~didn't~I~think~of~that?
619 %___________________________________________________________________________
621 \hypertarget{line-blocks
}{}
622 \pdfbookmark[1]{2.8~~~Line Blocks
}{line-blocks
}
623 \subsection*
{2.8~~~Line Blocks
}
626 This section tests line blocks. Line blocks are body elements which
627 consist of lines and other line blocks. Nested line blocks cause
630 \begin{lineblock
}{0em
}
631 \item[] This is a line block. It ends with a blank line.
633 \begin{lineblock
}{\lineblockindentation}
634 \item[] New lines begin with a vertical bar (``
{\textbar}'').
635 \item[] Line breaks and initial indent are significant, and preserved.
637 \begin{lineblock
}{\lineblockindentation}
638 \item[] Continuation lines are also possible. A long line that is intended
639 to wrap should begin with a space in place of the vertical bar.
641 \item[] The left edge of a continuation line need not be aligned with
642 the left edge of the text above it.
646 \begin{lineblock
}{0em
}
647 \item[] This is a second line block.
649 \item[] Blank lines are permitted internally, but they must begin with a ``
{\textbar}''.
652 Another line block, surrounded by paragraphs:
654 \begin{lineblock
}{0em
}
655 \item[] And it's no good waiting by the window
656 \item[] It's no good waiting for the sun
657 \item[] Please believe me, the things you dream of
658 \item[] They don't fall in the lap of no-one
661 Take it away, Eric the Orchestra Leader!
664 \begin{lineblock
}{0em
}
665 \item[] A one, two, a one two three four
667 \item[] Half a bee, philosophically,
669 \begin{lineblock
}{\lineblockindentation}
670 \item[] must,
\emph{ipso facto
}, half not be.
672 \item[] But half the bee has got to be,
674 \begin{lineblock
}{\lineblockindentation}
675 \item[] \emph{vis a vis
} its entity. D'you see?
678 \item[] But can a bee be said to be
680 \begin{lineblock
}{\lineblockindentation}
681 \item[] or not to be an entire bee,
683 \begin{lineblock
}{\lineblockindentation}
684 \item[] when half the bee is not a bee,
686 \begin{lineblock
}{\lineblockindentation}
687 \item[] due to some ancient injury?
697 %___________________________________________________________________________
699 \hypertarget{block-quotes
}{}
700 \pdfbookmark[1]{2.9~~~Block Quotes
}{block-quotes
}
701 \subsection*
{2.9~~~Block Quotes
}
704 Block quotes consist of indented body elements:
707 My theory by A. Elk. Brackets Miss, brackets. This theory goes
708 as follows and begins now. All brontosauruses are thin at one
709 end, much much thicker in the middle and then thin again at the
710 far end. That is my theory, it is mine, and belongs to me and I
711 own it, and what it is too.
719 %___________________________________________________________________________
721 \hypertarget{doctest-blocks
}{}
722 \pdfbookmark[1]{2.10~~~Doctest Blocks
}{doctest-blocks
}
723 \subsection*
{2.10~~~Doctest Blocks
}
724 \label{doctest-blocks
}
725 \begin{verbatim
}>>> print 'Python-specific usage examples; begun with ">>>"'
726 Python-specific usage examples; begun with ">>>"
727 >>> print '(cut and pasted from interactive Python sessions)'
728 (cut and pasted from interactive Python sessions)
\end{verbatim
}
731 %___________________________________________________________________________
733 \hypertarget{footnotes
}{}
734 \pdfbookmark[1]{2.11~~~Footnotes
}{footnotes
}
735 \subsection*
{2.11~~~Footnotes
}
737 \begin{figure
}[b
]\hypertarget{id8
}$^
{1}$
738 A footnote contains body elements, consistently indented by at
741 This is the footnote's second paragraph.
743 \begin{figure
}[b
]\hypertarget{label
}$^
{2}$
744 Footnotes may be numbered, either manually (as in
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id8
}{1}}) or
745 automatically using a ``
{\#
}''-prefixed label. This footnote has a
746 label so it can be referred to from multiple places, both as a
747 footnote reference (
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{label
}{2}}) and as a
\href{\#label
}{hyperlink reference
}.
748 \hypertarget{label
}{}\end{figure
}
749 \begin{figure
}[b
]\hypertarget{id12
}$^
{3}$
750 This footnote is numbered automatically and anonymously using a
751 label of ``
{\#
}'' only.
753 This is the second paragraph.
755 And this is the third paragraph.
757 \begin{figure
}[b
]\hypertarget{id13
}$^
{*
}$
758 Footnotes may also use symbols, specified with a ``*'' label.
759 Here's a reference to the next footnote:
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id15
}{{\dag}}}.
761 \begin{figure
}[b
]\hypertarget{id15
}$^
{{\dag}}$
762 This footnote shows the next symbol in the sequence.
764 \begin{figure
}[b
]\hypertarget{id16
}$^
{4}$
765 Here's an unreferenced footnote, with a reference to a
766 nonexistent footnote:
{\color{red
}\bfseries{}{[}5{]}{\_}}.
770 %___________________________________________________________________________
772 \hypertarget{citations
}{}
773 \pdfbookmark[1]{2.12~~~Citations
}{citations
}
774 \subsection*
{2.12~~~Citations
}
776 \begin{figure
}[b
]\hypertarget{cit2002
}[CIT2002
]
777 Citations are text-labeled footnotes. They may be
778 rendered separately and differently from footnotes.
781 Here's a reference to the above,
[\hyperlink{cit2002
}{CIT2002
}], and a
{\color{red
}\bfseries{}{[}nonexistent
{]}{\_}}
783 \hypertarget{another-target
}{}
785 %___________________________________________________________________________
787 \hypertarget{targets
}{}
788 \hypertarget{another-target
}{}
789 \pdfbookmark[1]{2.13~~~Targets
}{targets
}
790 \pdfbookmark[1]{2.13~~~Targets
}{another-target
}
791 \subsection*
{2.13~~~Targets
}
793 \label{another-target
}
794 \hypertarget{example
}{}
795 This paragraph is pointed to by the explicit ``example'' target. A
796 reference can be found under
\href{\#inline-markup
}{Inline Markup
}, above.
\href{\#inline-hyperlink-targets
}{Inline
797 hyperlink targets
} are also possible.
799 Section headers are implicit targets, referred to by name. See
800 \href{\#id23
}{Targets
}, which is a subsection of
\href{\#body-elements
}{Body Elements
}.
802 Explicit external targets are interpolated into references such as
803 ``
\href{http://www.python.org/
}{Python
}\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id27
}{5}}''.
805 Targets may be indirect and anonymous. Thus
\href{\#id23
}{this phrase
} may also
806 refer to the
\href{\#id23
}{Targets
} section.
808 Here's a
{\color{red
}\bfseries{}`hyperlink reference without a target`
{\_}}, which generates an
812 %___________________________________________________________________________
814 \hypertarget{duplicate-target-names
}{}
815 \pdfbookmark[2]{2.13.1~~~Duplicate Target Names
}{duplicate-target-names
}
816 \subsubsection*
{2.13.1~~~Duplicate Target Names
}
817 \label{duplicate-target-names
}
819 Duplicate names in section headers or other implicit targets will
820 generate ``info'' (level-
1) system messages. Duplicate names in
821 explicit targets will generate ``warning'' (level-
2) system messages.
824 %___________________________________________________________________________
827 \pdfbookmark[2]{2.13.2~~~Duplicate Target Names
}{id21
}
828 \subsubsection*
{2.13.2~~~Duplicate Target Names
}
831 Since there are two ``Duplicate Target Names'' section headers, we
832 cannot uniquely refer to either of them by name. If we try to (like
833 this:
{\color{red
}\bfseries{}`Duplicate Target Names`
{\_}}), an error is generated.
836 %___________________________________________________________________________
838 \hypertarget{directives
}{}
839 \pdfbookmark[1]{2.14~~~Directives
}{directives
}
840 \subsection*
{2.14~~~Directives
}
843 \item {} \href{\#
document-parts
}{2.14.1~~~Document Parts
}
845 \item {} \href{\#images
}{2.14.2~~~Images
}
847 \item {} \href{\#admonitions
}{2.14.3~~~Admonitions
}
849 \item {} \href{\#topics-sidebars-and-rubrics
}{2.14.4~~~Topics, Sidebars, and Rubrics
}
851 \item {} \href{\#target-footnotes
}{2.14.5~~~Target Footnotes
}
853 \item {} \href{\#replacement-text
}{2.14.6~~~Replacement Text
}
855 \item {} \href{\#compound-paragraph
}{2.14.7~~~Compound Paragraph
}
857 \item {} \href{\#parsed-literal-blocks
}{2.14.8~~~Parsed Literal Blocks
}
862 These are just a sample of the many reStructuredText Directives. For
864 \href{http://docutils.sourceforge.net/docs/ref/rst/directives.html
}{http://docutils.sourceforge.net/docs/ref/rst/directives.html
}.
867 %___________________________________________________________________________
869 \hypertarget{document-parts
}{}
870 \pdfbookmark[2]{2.14.1~~~Document Parts
}{document-parts
}
871 \subsubsection*
{2.14.1~~~Document Parts
}
872 \label{document-parts
}
874 An example of the ``contents'' directive can be seen above this section
875 (a local, untitled table of
\href{\#contents
}{contents
}) and at the beginning of the
876 document (a
document-wide
\href{\#table-of-contents
}{table of contents
}).
879 %___________________________________________________________________________
881 \hypertarget{images
}{}
882 \pdfbookmark[2]{2.14.2~~~Images
}{images
}
883 \subsubsection*
{2.14.2~~~Images
}
886 An image directive (also clickable -
{}- a hyperlink reference):
887 \href{\#directives
}{\includegraphics{../../../docs/user/rst/images/title.png
}}
888 Image with multiple IDs:
889 \hypertarget{image-target-
1}{}\hypertarget{image-target-
2}{}\hypertarget{image-target-
3}{}
890 \includegraphics{../../../docs/user/rst/images/title.png
}
894 {\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png
}\hfill}
896 A left-aligned image:
898 {\includegraphics{../../../docs/user/rst/images/biohazard.png
}\hfill}
900 A right-aligned image:
902 {\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
905 \begin{figure
}[htbp
]\begin{flushright
}
907 \includegraphics[width=
50]{../../../docs/user/rst/images/biohazard.png
}
908 \caption{A figure is an image with a caption and/or a legend:
}{\small
910 \begin{longtable
}[c
]{|p
{0.156\locallinewidth}|p
{0.563\locallinewidth}|
}
915 Revised, revisited, based on 're' module.
921 Structure-enhanced text, structuredtext.
927 Well it is, isn't it?
932 This paragraph is also part of the legend.
933 }\end{flushright
}\end{figure
}
934 \begin{figure
}[htbp
]\begin{flushleft
}
936 \includegraphics[width=
50]{../../../docs/user/rst/images/biohazard.png
}
937 \caption{A left-aligned figure.
}{\small
939 }\end{flushleft
}\end{figure
}
941 This paragraph might flow around the figure...
947 \includegraphics[width=
50]{../../../docs/user/rst/images/biohazard.png
}
948 \caption{This is the caption.
}{\small
951 The legend may consist of several paragraphs.
954 This paragraph might flow around the figure...
956 A left-aligned figure:
957 \begin{figure
}[htbp
]\begin{flushleft
}
959 \includegraphics[width=
50]{../../../docs/user/rst/images/biohazard.png
}
960 \caption{This is the caption.
}{\small
963 The legend may consist of several paragraphs.
964 }\end{flushleft
}\end{figure
}
966 This paragraph might flow around the figure...
972 \includegraphics[width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
974 An image
2 em wide and
30 pixel high:
976 \includegraphics[width=
2em,height=
30pt
]{../../../docs/user/rst/images/biohazard.png
}
978 An image occupying
70{\%
} of the line width:
980 \includegraphics[width=
0.700\linewidth]{../../../docs/user/rst/images/biohazard.png
}
984 \includegraphics[height=
3cm
]{../../../docs/user/rst/images/biohazard.png
}
987 %___________________________________________________________________________
989 \hypertarget{admonitions
}{}
990 \pdfbookmark[2]{2.14.3~~~Admonitions
}{admonitions
}
991 \subsubsection*
{2.14.3~~~Admonitions
}
993 \begin{center
}\begin{sffamily
}
994 \fbox{\parbox{\admonitionwidth}{
995 \textbf{\large Attention!
}
1002 \begin{center
}\begin{sffamily
}
1003 \fbox{\parbox{\admonitionwidth}{
1004 \textbf{\large Caution!
}
1007 Don't take any wooden nickels.
1011 \begin{center
}\begin{sffamily
}
1012 \fbox{\parbox{\admonitionwidth}{
1013 \textbf{\large !DANGER!
}
1016 Mad scientist at work!
1020 \begin{center
}\begin{sffamily
}
1021 \fbox{\parbox{\admonitionwidth}{
1022 \textbf{\large Error
}
1029 \begin{center
}\begin{sffamily
}
1030 \fbox{\parbox{\admonitionwidth}{
1031 \textbf{\large Hint
}
1034 It's bigger than a bread box.
1038 \begin{center
}\begin{sffamily
}
1039 \fbox{\parbox{\admonitionwidth}{
1040 \textbf{\large Important
}
1044 Wash behind your ears.
1059 \begin{center
}\begin{sffamily
}
1060 \fbox{\parbox{\admonitionwidth}{
1061 \textbf{\large Note
}
1068 \begin{center
}\begin{sffamily
}
1069 \fbox{\parbox{\admonitionwidth}{
1073 15{\%
} if the service is good.
1077 \begin{center
}\begin{sffamily
}
1078 \fbox{\parbox{\admonitionwidth}{
1079 \textbf{\large Warning
}
1082 Strong prose may provoke extreme mental exertion.
1083 Reader discretion is strongly advised.
1087 \begin{center
}\begin{sffamily
}
1088 \fbox{\parbox{\admonitionwidth}{
1090 \textbf{\large And, by the way...
}
1093 You can make up your own admonition too.
1099 %___________________________________________________________________________
1101 \hypertarget{topics-sidebars-and-rubrics
}{}
1102 \pdfbookmark[2]{2.14.4~~~Topics, Sidebars, and Rubrics
}{topics-sidebars-and-rubrics
}
1103 \subsubsection*
{2.14.4~~~Topics, Sidebars, and Rubrics
}
1104 \label{topics-sidebars-and-rubrics
}
1106 \setlength{\locallinewidth}{0.9\admonitionwidth}
1107 \begin{center
}\begin{sffamily
}
1108 \fbox{\colorbox[gray
]{0.80}{\parbox{\admonitionwidth}{
1109 \textbf{\large Sidebar Title
}
1112 \textbf{Optional Subtitle
}
1115 This is a sidebar. It is for text outside the flow of the main
1117 \rubric{This is a rubric inside a sidebar
}
1119 Sidebars often appears beside the main text with a border and
1125 \setlength{\locallinewidth}{\linewidth}
1126 \subsubsection*
{~
\hfill Topic Title
\hfill ~
}
1130 \rubric{This is a rubric
}
1133 %___________________________________________________________________________
1135 \hypertarget{target-footnotes
}{}
1136 \pdfbookmark[2]{2.14.5~~~Target Footnotes
}{target-footnotes
}
1137 \subsubsection*
{2.14.5~~~Target Footnotes
}
1138 \label{target-footnotes
}
1139 \begin{figure
}[b
]\hypertarget{id27
}$^
{5}$
1140 \href{http://www.python.org/
}{http://www.python.org/
}
1142 \begin{figure
}[b
]\hypertarget{id32
}$^
{6}$
1143 \href{http://docutils.sourceforge.net/
}{http://docutils.sourceforge.net/
}
1147 %___________________________________________________________________________
1149 \hypertarget{replacement-text
}{}
1150 \pdfbookmark[2]{2.14.6~~~Replacement Text
}{replacement-text
}
1151 \subsubsection*
{2.14.6~~~Replacement Text
}
1152 \label{replacement-text
}
1154 I recommend you try
\href{http://www.python.org/
}{Python,
\emph{the
} best language around
}\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id27
}{5}}.
1157 %___________________________________________________________________________
1159 \hypertarget{compound-paragraph
}{}
1160 \pdfbookmark[2]{2.14.7~~~Compound Paragraph
}{compound-paragraph
}
1161 \subsubsection*
{2.14.7~~~Compound Paragraph
}
1162 \label{compound-paragraph
}
1164 Compound
1, paragraph
1.
1166 Compound
1, paragraph
2.
1169 Compound
1, list item one.
1172 Compound
1, list item two.
1176 Another compound statement:
1178 Compound
2, a literal block:
1179 \begin{quote
}{\ttfamily \raggedright \noindent
1180 Compound~
2,~literal.
1182 Compound
2, this is a test.
1184 Compound
3, only consisting of one paragraph.
1185 \begin{quote
}{\ttfamily \raggedright \noindent
1187 This~one~starts~with~a~literal~block.
1189 Compound
4, a paragraph.
1191 Now something
\emph{really
} perverted -
{}- a nested compound block. This is
1192 just to test that it works at all; the results don't have to be
1195 Compound
5, block
1 (a paragraph).
1197 Compound
6, block
2 in compound
5.
1199 Compound
6, another paragraph.
1201 Compound
5, block
3 (a paragraph).
1203 Compound
7, with a table inside:
1206 \begin{longtable
}[c
]{|p
{0.249\locallinewidth}|p
{0.249\locallinewidth}|p
{0.249\locallinewidth}|
}
1228 Compound
7, a paragraph after the table.
1230 Compound
7, another paragraph.
1233 %___________________________________________________________________________
1235 \hypertarget{parsed-literal-blocks
}{}
1236 \pdfbookmark[2]{2.14.8~~~Parsed Literal Blocks
}{parsed-literal-blocks
}
1237 \subsubsection*
{2.14.8~~~Parsed Literal Blocks
}
1238 \label{parsed-literal-blocks
}
1239 \begin{quote
}{\ttfamily \raggedright \noindent
1240 This~is~a~parsed~literal~block.~\\
1241 ~~~~This~line~is~indented.~~The~next~line~is~blank.~\\
1243 Inline~markup~is~supported,~e.g.~
\emph{emphasis
},~
\textbf{strong
},~
\texttt{literal~\\
1244 text
},~footnotes
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id8
}{1}},~
\hypertarget{id23
}{targets
},~and~
\href{http://www.python.org/
}{references
}.
1248 %___________________________________________________________________________
1250 \hypertarget{substitution-definitions
}{}
1251 \pdfbookmark[1]{2.15~~~Substitution Definitions
}{substitution-definitions
}
1252 \subsection*
{2.15~~~Substitution Definitions
}
1253 \label{substitution-definitions
}
1255 An inline image (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}) example:
1257 (Substitution definitions are not visible in the HTML source.)
1260 %___________________________________________________________________________
1262 \hypertarget{comments
}{}
1263 \pdfbookmark[1]{2.16~~~Comments
}{comments
}
1264 \subsection*
{2.16~~~Comments
}
1268 % Comments begin with two dots and a space. Anything may
1269 % follow, except for the syntax of footnotes, hyperlink
1270 % targets, directives, or substitution definitions.
1272 % Double-dashes -- "--" -- must be escaped somehow in HTML output.
1274 % Comments may contain non-ASCII characters: ä ö ü æ ø å
1276 (View the HTML source to see the comment.)
1279 %___________________________________________________________________________
1281 \hypertarget{raw-text
}{}
1282 \pdfbookmark[1]{2.17~~~Raw text
}{raw-text
}
1283 \subsection*
{2.17~~~Raw text
}
1286 This does not necessarily look nice, because there may be missing white space.
1288 It's just there to freeze the behavior.
1289 A test.Second test.Another test with myclass set.
1290 This is the fourth test with myrawroleclass set.
1291 Fifth test in LaTeX.\
\Line two.
1293 %___________________________________________________________________________
1295 \hypertarget{container
}{}
1296 \pdfbookmark[1]{2.18~~~Container
}{container
}
1297 \subsection*
{2.18~~~Container
}
1305 %___________________________________________________________________________
1307 \hypertarget{colspanning-tables
}{}
1308 \pdfbookmark[1]{2.19~~~Colspanning tables
}{colspanning-tables
}
1309 \subsection*
{2.19~~~Colspanning tables
}
1310 \label{colspanning-tables
}
1312 This table has a cell spanning two columns:
1315 \begin{longtable
}[c
]{|p
{0.075\locallinewidth}|p
{0.075\locallinewidth}|p
{0.086\locallinewidth}|
}
1317 \multicolumn{2}{|l|
}{\textbf{
1333 \multicolumn{2}{|l|
}{\textbf{
1348 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1386 %___________________________________________________________________________
1388 \hypertarget{rowspanning-tables
}{}
1389 \pdfbookmark[1]{2.20~~~Rowspanning tables
}{rowspanning-tables
}
1390 \subsection*
{2.20~~~Rowspanning tables
}
1391 \label{rowspanning-tables
}
1393 Here's a table with cells spanning several rows:
1396 \begin{longtable
}[c
]{|p
{0.296\locallinewidth}|p
{0.156\locallinewidth}|p
{0.226\locallinewidth}|
}
1399 Header row, column
1
1400 (header rows optional)
1410 Header row, column
1
1411 (header rows optional)
1419 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1423 body row
1, column
1
1432 &
\multirow{2}{0.16\locallinewidth}{
1435 } &
\multirow{2}{0.23\locallinewidth}{
1448 %___________________________________________________________________________
1450 \hypertarget{tests-for-the-latex-writer
}{}
1451 \pdfbookmark[0]{3~~~Tests for the LaTeX writer
}{tests-for-the-latex-writer
}
1452 \section*
{3~~~Tests for the LaTeX writer
}
1453 \label{tests-for-the-latex-writer
}
1456 %___________________________________________________________________________
1458 \hypertarget{some-tests-for-the-latex2e-writer
}{}
1459 \pdfbookmark[0]{4~~~Some Tests for the LaTeX2e Writer
}{some-tests-for-the-latex2e-writer
}
1460 \section*
{4~~~Some Tests for the LaTeX2e Writer
}
1461 \label{some-tests-for-the-latex2e-writer
}
1463 These tests have been written to exercise some unusual combinations of
1464 syntax elements which may cause trouble for the LaTeX writer but do
1465 not need to be tested with other writers (e.g. the HTML writer).
1467 This file is user by the standalone
{\_}rst
{\_}latex test.
1470 %___________________________________________________________________________
1472 \hypertarget{id24
}{}
1473 \pdfbookmark[0]{5~~~Option lists
}{id24
}
1474 \section*
{5~~~Option lists
}
1477 The LaTeX-
2e description environment is used for definition lists.
1478 The definition is continued on the same line as the term, this should
1479 not happen if a option-list is at the top of the definition.
1481 If the option list is not at the first element in the definition, it
1482 is contained in a quote
1484 \begin{optionlist
}{3cm
}
1492 \item[{In a definition list:
}] \leavevmode \begin{optionlist
}{3cm
}
1502 %___________________________________________________________________________
1504 \hypertarget{monospaced-non-alphanumeric-characters
}{}
1505 \pdfbookmark[1]{5.1~~~Monospaced non-alphanumeric characters
}{monospaced-non-alphanumeric-characters
}
1506 \subsection*
{5.1~~~Monospaced non-alphanumeric characters
}
1507 \label{monospaced-non-alphanumeric-characters
}
1509 These are all ASCII characters except a-zA-Z0-
9 and space:
1511 \texttt{!!!"
{}"
{}"
{\#
}{\#
}{\#
}{\$
}{\$
}{\$
}{\%
}{\%
}{\%
}{\&
}{\&
}{\&
}'
{}'
{}'((()))***+++,
{},
{},-
{}-
{}-...///:::
}
1513 \texttt{;;;<
{}<
{}<===>
{}>
{}>???@@@
{[}{[}{[}{\textbackslash}{\textbackslash}{\textbackslash}{]}{]}{]}{\textasciicircum}{\textasciicircum}{\textasciicircum}{\_}{\_}{\_}`
{}`
{}`
{\
{}{\
{}{\
{}|||
{\
}}{\
}}{\
}}{\textasciitilde}{\textasciitilde}{\textasciitilde}}
1515 \texttt{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
1517 The two lines of non-alphanumeric characters should both have the same
1518 width as the third line.
1521 %___________________________________________________________________________
1523 \hypertarget{various-non-ascii-characters
}{}
1524 \pdfbookmark[1]{5.2~~~Various non-ASCII characters
}{various-non-ascii-characters
}
1525 \subsection*
{5.2~~~Various non-ASCII characters
}
1526 \label{various-non-ascii-characters
}
1529 \begin{longtable
}[c
]{|p
{0.028\locallinewidth}|p
{0.424\locallinewidth}|
}
1546 left pointing guillemet
1552 right pointing guillemet
1570 single turned comma quotation mark
1576 single comma quotation mark
1582 low single comma quotation mark
1588 double turned comma quotation mark
1594 double comma quotation mark
1600 low double comma quotation mark
1630 left-right double arrow
1635 The following line should not be wrapped, because it uses
1636 non-breakable spaces:
1638 X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X~X
1641 %___________________________________________________________________________
1643 \hypertarget{custom-roles
}{}
1644 \pdfbookmark[1]{5.3~~~Custom Roles
}{custom-roles
}
1645 \subsection*
{5.3~~~Custom Roles
}
1646 \label{custom-roles
}
1649 A role based on an existing role.
1651 \texttt{one
} \texttt{two
} \texttt{three
}
1656 \docutilsrolecustomnew{one two three
}
1659 A role with class attribute.
1661 \docutilsrolespecial{interpreted text
}
1664 A role with class attribute.
1666 \docutilsrolevery{\docutilsrolespecial{interpreted text
}}
1671 %___________________________________________________________________________
1673 \hypertarget{error-handling
}{}
1674 \pdfbookmark[0]{6~~~Error Handling
}{error-handling
}
1675 \section*
{6~~~Error Handling
}
1676 \label{error-handling
}
1678 Any errors caught during processing will generate system messages.
1680 There should be five messages in the following, auto-generated
1681 section, ``Docutils System Messages'':
1682 % section should be added by Docutils automatically
1685 %___________________________________________________________________________
1687 \section*
{Docutils System Messages
}
1689 Undefined substitution referenced: ``problematic''.
1692 Unknown target name: ``
5''.
1695 Unknown target name: ``nonexistent''.
1698 Unknown target name: ``hyperlink reference without a target''.
1701 Duplicate target name, cannot be used as a unique reference: ``duplicate target names''.