1 \documentclass[10pt,
a4paper,english
]{article
}
6 \usepackage[latin1]{inputenc}
9 \setlength{\extrarowheight}{2pt
}
15 \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue
]{hyperref
}
16 \usepackage[DIV12
]{typearea
}
17 % generated by Docutils <http://docutils.sourceforge.net/>
18 \newlength{\admonitionwidth}
19 \setlength{\admonitionwidth}{0.9\textwidth}
20 \newlength{\docinfowidth}
21 \setlength{\docinfowidth}{0.9\textwidth}
22 \newlength{\locallinewidth}
23 \newcommand{\optionlistlabel}[1]{\bf #1 \hfill}
24 \newenvironment{optionlist
}[1]
26 {\setlength{\labelwidth}{#1}
27 \setlength{\rightmargin}{1cm
}
28 \setlength{\leftmargin}{\rightmargin}
29 \addtolength{\leftmargin}{\labelwidth}
30 \addtolength{\leftmargin}{\labelsep}
31 \renewcommand{\makelabel}{\optionlistlabel}}
33 \newlength{\lineblockindentation}
34 \setlength{\lineblockindentation}{2.5em
}
35 \newenvironment{lineblock
}[1]
37 {\setlength{\partopsep}{\parskip}
38 \addtolength{\partopsep}{\baselineskip}
39 \topsep0pt\itemsep0.15
\baselineskip\parsep0pt
43 % begin: floats for footnotes tweaking.
44 \setlength{\floatsep}{0.5em
}
45 \setlength{\textfloatsep}{\fill}
46 \addtolength{\textfloatsep}{3em
}
47 \renewcommand{\textfraction}{0.5}
48 \renewcommand{\topfraction}{0.5}
49 \renewcommand{\bottomfraction}{0.5}
50 \setcounter{totalnumber
}{50}
51 \setcounter{topnumber
}{50}
52 \setcounter{bottomnumber
}{50}
53 % end floats for footnotes
54 % some commands, that could be overwritten in the style file.
55 \newcommand{\rubric}[1]{\subsection*
{~
\hfill {\it #1} \hfill ~
}}
56 \newcommand{\titlereference}[1]{\textsl{#1}}
57 % end of "some commands"
58 \title{reStructuredText Test Document\\
59 \large{Examples of Syntax Constructs
}
64 pdftitle=
{reStructuredText Test Document
},
65 pdfauthor=
{David Goodger;Me;Myself;I
}
70 %___________________________________________________________________________
72 \begin{tabularx
}{\docinfowidth}{lX
}
81 \href{mailto:goodger@python.org
}{goodger@python.org
} \\
88 \textbf{Organization
}: &
91 Now, or yesterday. Or maybe even
\emph{before
} yesterday. \\
93 This is a ``work in progress'' \\
95 is managed by a version control system. \\
99 This
document has been placed in the public domain. You
100 may do with it as you wish. You may copy, modify,
101 redistribute, reattribute, sell, buy, rent, lease,
102 destroy, or improve it, quote it at length, excerpt,
103 incorporate, collate, fold, staple, or mutilate it, or do
104 anything else to it that your or anyone else's heart
106 \textbf{field name
}: &
107 This is a ``generic bibliographic field''. \\
108 \textbf{field name ``
2''
}: &
109 Generic bibliographic fields may contain multiple body elements.
115 \setlength{\locallinewidth}{\linewidth}
118 \subsubsection*
{~
\hfill Dedication
\hfill ~
}
120 For Docutils users
{\&
} co-developers.
122 \subsubsection*
{~
\hfill Abstract
\hfill ~
}
124 This is a test
document, containing at least one example of each
125 reStructuredText construct.
127 % This is a comment. Note how any initial comments are moved by
128 % transforms to after the document title, subtitle, and docinfo.
129 \hypertarget{doctitle
}{}% Above is the document title, and below is the subtitle.
130 % They are transformed from section titles after parsing.
131 \hypertarget{subtitle
}{}% bibliographic fields (which also require a transform):
132 \hypertarget{table-of-contents
}{}
133 \pdfbookmark[0]{Table of Contents
}{table-of-contents
}
134 \subsubsection*
{~
\hfill Table of Contents
\hfill ~
}
135 \label{table-of-contents
}
137 \item {} \href{\#structural-elements
}{1~~~Structural Elements
}
139 \item {} \href{\#section-title
}{1.1~~~Section Title
}
141 \item {} \href{\#empty-section
}{1.2~~~Empty Section
}
143 \item {} \href{\#transitions
}{1.3~~~Transitions
}
147 \item {} \href{\#body-elements
}{2~~~Body Elements
}
149 \item {} \href{\#paragraphs
}{2.1~~~Paragraphs
}
151 \item {} \href{\#inline-markup
}{2.1.1~~~Inline Markup
}
155 \item {} \href{\#bullet-lists
}{2.2~~~Bullet Lists
}
157 \item {} \href{\#enumerated-lists
}{2.3~~~Enumerated Lists
}
159 \item {} \href{\#definition-lists
}{2.4~~~Definition Lists
}
161 \item {} \href{\#field-lists
}{2.5~~~Field Lists
}
163 \item {} \href{\#option-lists
}{2.6~~~Option Lists
}
165 \item {} \href{\#literal-blocks
}{2.7~~~Literal Blocks
}
167 \item {} \href{\#line-blocks
}{2.8~~~Line Blocks
}
169 \item {} \href{\#block-quotes
}{2.9~~~Block Quotes
}
171 \item {} \href{\#doctest-blocks
}{2.10~~~Doctest Blocks
}
173 \item {} \href{\#footnotes
}{2.11~~~Footnotes
}
175 \item {} \href{\#citations
}{2.12~~~Citations
}
177 \item {} \href{\#targets
}{2.13~~~Targets
}
179 \item {} \href{\#duplicate-target-names
}{2.13.1~~~Duplicate Target Names
}
181 \item {} \href{\#id20
}{2.13.2~~~Duplicate Target Names
}
185 \item {} \href{\#directives
}{2.14~~~Directives
}
187 \item {} \href{\#
document-parts
}{2.14.1~~~Document Parts
}
189 \item {} \href{\#images
}{2.14.2~~~Images
}
191 \item {} \href{\#admonitions
}{2.14.3~~~Admonitions
}
193 \item {} \href{\#topics-sidebars-and-rubrics
}{2.14.4~~~Topics, Sidebars, and Rubrics
}
195 \item {} \href{\#target-footnotes
}{2.14.5~~~Target Footnotes
}
197 \item {} \href{\#replacement-text
}{2.14.6~~~Replacement Text
}
199 \item {} \href{\#compound-paragraph
}{2.14.7~~~Compound Paragraph
}
201 \item {} \href{\#parsed-literal-blocks
}{2.14.8~~~Parsed Literal Blocks
}
205 \item {} \href{\#substitution-definitions
}{2.15~~~Substitution Definitions
}
207 \item {} \href{\#comments
}{2.16~~~Comments
}
209 \item {} \href{\#raw-text
}{2.17~~~Raw text
}
211 \item {} \href{\#container
}{2.18~~~Container
}
213 \item {} \href{\#colspanning-tables
}{2.19~~~Colspanning tables
}
215 \item {} \href{\#rowspanning-tables
}{2.20~~~Rowspanning tables
}
219 \item {} \href{\#tests-for-the-latex-writer
}{3~~~Tests for the LaTeX writer
}
221 \item {} \href{\#some-tests-for-the-latex2e-writer
}{4~~~Some Tests for the LaTeX2e Writer
}
223 \item {} \href{\#id23
}{5~~~Option lists
}
225 \item {} \href{\#monospaced-non-alphanumeric-characters
}{5.1~~~Monospaced non-alphanumeric characters
}
227 \item {} \href{\#various-non-ascii-characters
}{5.2~~~Various non-ASCII characters
}
229 \item {} \href{\#custom-roles
}{5.3~~~Custom Roles
}
233 \item {} \href{\#error-handling
}{6~~~Error Handling
}
239 %___________________________________________________________________________
241 \hypertarget{structural-elements
}{}
242 \pdfbookmark[0]{1~~~Structural Elements
}{structural-elements
}
243 \section*
{1~~~Structural Elements
}
244 \label{structural-elements
}
247 %___________________________________________________________________________
249 \hypertarget{section-title
}{}
250 \pdfbookmark[1]{1.1~~~Section Title
}{section-title
}
251 \subsection*
{1.1~~~Section Title
}
252 \label{section-title
}
253 \textbf{Section Subtitle
}\vspace{0.2cm
}
256 That's it, the text just above this line.
259 %___________________________________________________________________________
261 \hypertarget{empty-section
}{}
262 \pdfbookmark[1]{1.2~~~Empty Section
}{empty-section
}
263 \subsection*
{1.2~~~Empty Section
}
264 \label{empty-section
}
267 %___________________________________________________________________________
269 \hypertarget{transitions
}{}
270 \pdfbookmark[1]{1.3~~~Transitions
}{transitions
}
271 \subsection*
{1.3~~~Transitions
}
277 %___________________________________________________________________________
278 \hspace*
{\fill}\hrulefill\hspace*
{\fill}
281 It divides the section. Transitions may also occur between sections:
284 %___________________________________________________________________________
285 \hspace*
{\fill}\hrulefill\hspace*
{\fill}
289 %___________________________________________________________________________
291 \hypertarget{body-elements
}{}
292 \pdfbookmark[0]{2~~~Body Elements
}{body-elements
}
293 \section*
{2~~~Body Elements
}
294 \label{body-elements
}
297 %___________________________________________________________________________
299 \hypertarget{paragraphs
}{}
300 \pdfbookmark[1]{2.1~~~Paragraphs
}{paragraphs
}
301 \subsection*
{2.1~~~Paragraphs
}
307 %___________________________________________________________________________
309 \hypertarget{inline-markup
}{}
310 \pdfbookmark[2]{2.1.1~~~Inline Markup
}{inline-markup
}
311 \subsubsection*
{2.1.1~~~Inline Markup
}
312 \label{inline-markup
}
314 Paragraphs contain text and may contain inline markup:
\emph{emphasis
},
315 \textbf{strong emphasis
},
\texttt{inline literals
}, standalone hyperlinks
316 (
\href{http://www.python.org
}{http://www.python.org
}), external hyperlinks (
\href{http://www.python.org/
}{Python
}\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id26
}{5}}), internal
317 cross-references (
\href{\#example
}{example
}), external hyperlinks with embedded URIs
318 (
\href{http://www.python.org
}{Python web site
}),
\href{http://www.python.org/
}{anonymous hyperlink
319 references
}\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id26
}{5}} (
\href{http://docutils.sourceforge.net/
}{a second reference
}\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id31
}{6}}), footnote references (manually
320 numbered
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id8
}{1}}, anonymous auto-numbered
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id11
}{3}}, labeled auto-numbered
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{label
}{2}}, or symbolic
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id12
}{*
}}), citation references (
[\hyperlink{cit2002
}{CIT2002
}]),
321 substitution references (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}), and
\hypertarget{inline-hyperlink-targets
}{inline hyperlink targets
}
322 (see
\href{\#id22
}{Targets
} below for a reference back to here). Character-level
323 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
324 (generated by processing errors; this one is intentional). Here is a
325 reference to the
\href{\#doctitle
}{doctitle
} and the
\href{\#subtitle
}{subtitle
}.
327 The default role for interpreted text is
\titlereference{Title Reference
}. Here are
328 some explicit interpreted text roles: a PEP reference (
\href{http://www.python.org/dev/peps/pep-
0287}{PEP
287}); an
329 RFC reference (
\href{http://www.faqs.org/rfcs/rfc2822.html
}{RFC
2822}); a $_
{subscript
}$; a $^
{superscript
}$;
330 and explicit roles for
\emph{standard
} \textbf{inline
}
332 % DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
334 Let's test wrapping and whitespace significance in inline literals:
335 \texttt{This is an example of -
{}-inline-literal -
{}-text, -
{}-including some-
{}-
336 strangely-
{}-hyphenated-words. Adjust-the-width-of-your-browser-window
337 to see how the text is wrapped. -
{}- -
{}-
{}-
{}- -
{}-
{}-
{}-
{}-
{}-
{}-
{}- Now note the
338 spacing between the words of this sentence (words
339 should be grouped in pairs).
}
341 If the
\texttt{-
{}-pep-references
} option was supplied, there should be a
342 live link to PEP
258 here.
345 %___________________________________________________________________________
347 \hypertarget{bullet-lists
}{}
348 \pdfbookmark[1]{2.2~~~Bullet Lists
}{bullet-lists
}
349 \subsection*
{2.2~~~Bullet Lists
}
366 Paragraph
2 of item
2.
386 This nested list should be compacted by the HTML writer.
387 \hypertarget{target
}{}% Even if this item contains a target and a comment.
394 %___________________________________________________________________________
396 \hypertarget{enumerated-lists
}{}
397 \pdfbookmark[1]{2.3~~~Enumerated Lists
}{enumerated-lists
}
398 \subsection*
{2.3~~~Enumerated Lists
}
399 \label{enumerated-lists
}
400 \newcounter{listcnt0
}
401 \begin{list
}{\arabic{listcnt0
}.
}
403 \usecounter{listcnt0
}
404 \setlength{\rightmargin}{\leftmargin}
408 \newcounter{listcnt1
}
409 \begin{list
}{\alph{listcnt1
})
}
411 \usecounter{listcnt1
}
412 \setlength{\rightmargin}{\leftmargin}
416 \newcounter{listcnt2
}
417 \begin{list
}{(
\roman{listcnt2
})
}
419 \usecounter{listcnt2
}
420 \setlength{\rightmargin}{\leftmargin}
424 \newcounter{listcnt3
}
425 \begin{list
}{\Alph{listcnt3
}.
}
427 \usecounter{listcnt3
}
428 \setlength{\rightmargin}{\leftmargin}
432 \newcounter{listcnt4
}
433 \begin{list
}{\Roman{listcnt4
})
}
435 \usecounter{listcnt4
}
436 \setlength{\rightmargin}{\leftmargin}
450 Lists that don't start at
1:
451 \setcounter{listcnt1
}{0}
452 \begin{list
}{\arabic{listcnt1
}.
}
454 \usecounter{listcnt1
}
455 \addtocounter{listcnt1
}{2}
456 \setlength{\rightmargin}{\leftmargin}
465 \setcounter{listcnt1
}{0}
466 \begin{list
}{\Alph{listcnt1
}.
}
468 \usecounter{listcnt1
}
469 \addtocounter{listcnt1
}{2}
470 \setlength{\rightmargin}{\leftmargin}
479 \setcounter{listcnt1
}{0}
480 \begin{list
}{\roman{listcnt1
}.
}
482 \usecounter{listcnt1
}
483 \addtocounter{listcnt1
}{2}
484 \setlength{\rightmargin}{\leftmargin}
497 %___________________________________________________________________________
499 \hypertarget{definition-lists
}{}
500 \pdfbookmark[1]{2.4~~~Definition Lists
}{definition-lists
}
501 \subsection*
{2.4~~~Definition Lists
}
502 \label{definition-lists
}
504 \item[{Term
}] \leavevmode
507 \item[{Term
}] \leavevmode (
\textbf{classifier
})
509 Definition paragraph
1.
511 Definition paragraph
2.
513 \item[{Term
}] \leavevmode
516 \item[{Term
}] \leavevmode (
\textbf{classifier one
})
517 (
\textbf{classifier two
})
524 %___________________________________________________________________________
526 \hypertarget{field-lists
}{}
527 \pdfbookmark[1]{2.5~~~Field Lists
}{field-lists
}
528 \subsection*
{2.5~~~Field Lists
}
533 Field lists map field names to field bodies, like database
534 records. They are often part of an extension syntax. They are
535 an unambiguous variant of RFC
2822 fields.
538 \item [how arg1 arg2:
]
539 The field marker is a colon, the field name, and a colon.
541 The field body may contain one or more body elements, indented
542 relative to the field marker.
546 This paragraph has the
\titlereference{credits
} class set. (This is actually not
547 about credits but just for ensuring that the class attribute
548 doesn't get stripped away.)
555 %___________________________________________________________________________
557 \hypertarget{option-lists
}{}
558 \pdfbookmark[1]{2.6~~~Option Lists
}{option-lists
}
559 \subsection*
{2.6~~~Option Lists
}
562 For listing command-line options:
563 \begin{optionlist
}{3cm
}
565 command-line option ``a''
567 options can have arguments
568 and long descriptions
570 options can be long also
571 \item [-
{}-input=file
]
572 long options can also have
574 \item [-
{}-very-long-option
]
575 The description can also start on the next line.
577 The description may contain multiple body elements,
578 regardless of where it starts.
580 Multiple options are an ``option group''.
581 \item [-v, -
{}-verbose
]
582 Commonly-seen: short
{\&
} long options.
583 \item [-
1 file, -
{}-one=file, -
{}-two file
]
584 Multiple options with arguments.
586 DOS/VMS-style options too
589 There must be at least two spaces between the option and the
593 %___________________________________________________________________________
595 \hypertarget{literal-blocks
}{}
596 \pdfbookmark[1]{2.7~~~Literal Blocks
}{literal-blocks
}
597 \subsection*
{2.7~~~Literal Blocks
}
598 \label{literal-blocks
}
600 Literal blocks are indicated with a double-colon (``::'') at the end of
601 the preceding paragraph (over there
\texttt{-
{}->
}). They can be indented:
602 \begin{quote
}{\ttfamily \raggedright \noindent
603 if~literal
{\_}block:~\\
604 ~~~~text~=~'is~left~as-is'~\\
605 ~~~~spaces
{\_}and
{\_}linebreaks~=~'are~preserved'~\\
606 ~~~~markup
{\_}processing~=~None
609 Or they can be quoted without indentation:
610 \begin{quote
}{\ttfamily \raggedright \noindent
613 >~Why~didn't~I~think~of~that?
617 %___________________________________________________________________________
619 \hypertarget{line-blocks
}{}
620 \pdfbookmark[1]{2.8~~~Line Blocks
}{line-blocks
}
621 \subsection*
{2.8~~~Line Blocks
}
624 This section tests line blocks. Line blocks are body elements which
625 consist of lines and other line blocks. Nested line blocks cause
628 \begin{lineblock
}{0em
}
629 \item[] This is a line block. It ends with a blank line.
631 \begin{lineblock
}{\lineblockindentation}
632 \item[] New lines begin with a vertical bar (``
{\textbar}'').
633 \item[] Line breaks and initial indent are significant, and preserved.
635 \begin{lineblock
}{\lineblockindentation}
636 \item[] Continuation lines are also possible. A long line that is intended
637 to wrap should begin with a space in place of the vertical bar.
639 \item[] The left edge of a continuation line need not be aligned with
640 the left edge of the text above it.
644 \begin{lineblock
}{0em
}
645 \item[] This is a second line block.
647 \item[] Blank lines are permitted internally, but they must begin with a ``
{\textbar}''.
650 Another line block, surrounded by paragraphs:
652 \begin{lineblock
}{0em
}
653 \item[] And it's no good waiting by the window
654 \item[] It's no good waiting for the sun
655 \item[] Please believe me, the things you dream of
656 \item[] They don't fall in the lap of no-one
659 Take it away, Eric the Orchestra Leader!
662 \begin{lineblock
}{0em
}
663 \item[] A one, two, a one two three four
665 \item[] Half a bee, philosophically,
667 \begin{lineblock
}{\lineblockindentation}
668 \item[] must,
\emph{ipso facto
}, half not be.
670 \item[] But half the bee has got to be,
672 \begin{lineblock
}{\lineblockindentation}
673 \item[] \emph{vis a vis
} its entity. D'you see?
676 \item[] But can a bee be said to be
678 \begin{lineblock
}{\lineblockindentation}
679 \item[] or not to be an entire bee,
681 \begin{lineblock
}{\lineblockindentation}
682 \item[] when half the bee is not a bee,
684 \begin{lineblock
}{\lineblockindentation}
685 \item[] due to some ancient injury?
695 %___________________________________________________________________________
697 \hypertarget{block-quotes
}{}
698 \pdfbookmark[1]{2.9~~~Block Quotes
}{block-quotes
}
699 \subsection*
{2.9~~~Block Quotes
}
702 Block quotes consist of indented body elements:
705 My theory by A. Elk. Brackets Miss, brackets. This theory goes
706 as follows and begins now. All brontosauruses are thin at one
707 end, much much thicker in the middle and then thin again at the
708 far end. That is my theory, it is mine, and belongs to me and I
709 own it, and what it is too.
717 %___________________________________________________________________________
719 \hypertarget{doctest-blocks
}{}
720 \pdfbookmark[1]{2.10~~~Doctest Blocks
}{doctest-blocks
}
721 \subsection*
{2.10~~~Doctest Blocks
}
722 \label{doctest-blocks
}
723 \begin{verbatim
}>>> print 'Python-specific usage examples; begun with ">>>"'
724 Python-specific usage examples; begun with ">>>"
725 >>> print '(cut and pasted from interactive Python sessions)'
726 (cut and pasted from interactive Python sessions)
\end{verbatim
}
729 %___________________________________________________________________________
731 \hypertarget{footnotes
}{}
732 \pdfbookmark[1]{2.11~~~Footnotes
}{footnotes
}
733 \subsection*
{2.11~~~Footnotes
}
735 \begin{figure
}[b
]\hypertarget{id8
}$^
{1}$
736 A footnote contains body elements, consistently indented by at
739 This is the footnote's second paragraph.
741 \begin{figure
}[b
]\hypertarget{label
}$^
{2}$
742 Footnotes may be numbered, either manually (as in
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id8
}{1}}) or
743 automatically using a ``
{\#
}''-prefixed label. This footnote has a
744 label so it can be referred to from multiple places, both as a
745 footnote reference (
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{label
}{2}}) and as a hyperlink reference
746 (
\href{\#label
}{label
}).
748 \begin{figure
}[b
]\hypertarget{id11
}$^
{3}$
749 This footnote is numbered automatically and anonymously using a
750 label of ``
{\#
}'' only.
752 This is the second paragraph.
754 And this is the third paragraph.
756 \begin{figure
}[b
]\hypertarget{id12
}$^
{*
}$
757 Footnotes may also use symbols, specified with a ``*'' label.
758 Here's a reference to the next footnote:
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id14
}{{\dag}}}.
760 \begin{figure
}[b
]\hypertarget{id14
}$^
{{\dag}}$
761 This footnote shows the next symbol in the sequence.
763 \begin{figure
}[b
]\hypertarget{id15
}$^
{4}$
764 Here's an unreferenced footnote, with a reference to a
765 nonexistent footnote:
{\color{red
}\bfseries{}{[}5{]}{\_}}.
769 %___________________________________________________________________________
771 \hypertarget{citations
}{}
772 \pdfbookmark[1]{2.12~~~Citations
}{citations
}
773 \subsection*
{2.12~~~Citations
}
775 \begin{figure
}[b
]\hypertarget{cit2002
}[CIT2002
]
776 Citations are text-labeled footnotes. They may be
777 rendered separately and differently from footnotes.
780 Here's a reference to the above,
[\hyperlink{cit2002
}{CIT2002
}], and a
{\color{red
}\bfseries{}{[}nonexistent
{]}{\_}}
782 \hypertarget{another-target
}{}
784 %___________________________________________________________________________
786 \hypertarget{targets
}{}
787 \hypertarget{another-target
}{}
788 \pdfbookmark[1]{2.13~~~Targets
}{targets
}
789 \pdfbookmark[1]{2.13~~~Targets
}{another-target
}
790 \subsection*
{2.13~~~Targets
}
792 \label{another-target
}
793 \hypertarget{example
}{}
794 This paragraph is pointed to by the explicit ``example'' target. A
795 reference can be found under
\href{\#inline-markup
}{Inline Markup
}, above.
\href{\#inline-hyperlink-targets
}{Inline
796 hyperlink targets
} are also possible.
798 Section headers are implicit targets, referred to by name. See
799 \href{\#id22
}{Targets
}, which is a subsection of
\href{\#body-elements
}{Body Elements
}.
801 Explicit external targets are interpolated into references such as
802 ``
\href{http://www.python.org/
}{Python
}\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id26
}{5}}''.
804 Targets may be indirect and anonymous. Thus
\href{\#id22
}{this phrase
} may also
805 refer to the
\href{\#id22
}{Targets
} section.
807 Here's a
{\color{red
}\bfseries{}`hyperlink reference without a target`
{\_}}, which generates an
811 %___________________________________________________________________________
813 \hypertarget{duplicate-target-names
}{}
814 \pdfbookmark[2]{2.13.1~~~Duplicate Target Names
}{duplicate-target-names
}
815 \subsubsection*
{2.13.1~~~Duplicate Target Names
}
816 \label{duplicate-target-names
}
818 Duplicate names in section headers or other implicit targets will
819 generate ``info'' (level-
1) system messages. Duplicate names in
820 explicit targets will generate ``warning'' (level-
2) system messages.
823 %___________________________________________________________________________
826 \pdfbookmark[2]{2.13.2~~~Duplicate Target Names
}{id20
}
827 \subsubsection*
{2.13.2~~~Duplicate Target Names
}
830 Since there are two ``Duplicate Target Names'' section headers, we
831 cannot uniquely refer to either of them by name. If we try to (like
832 this:
{\color{red
}\bfseries{}`Duplicate Target Names`
{\_}}), an error is generated.
835 %___________________________________________________________________________
837 \hypertarget{directives
}{}
838 \pdfbookmark[1]{2.14~~~Directives
}{directives
}
839 \subsection*
{2.14~~~Directives
}
842 \item {} \href{\#
document-parts
}{2.14.1~~~Document Parts
}
844 \item {} \href{\#images
}{2.14.2~~~Images
}
846 \item {} \href{\#admonitions
}{2.14.3~~~Admonitions
}
848 \item {} \href{\#topics-sidebars-and-rubrics
}{2.14.4~~~Topics, Sidebars, and Rubrics
}
850 \item {} \href{\#target-footnotes
}{2.14.5~~~Target Footnotes
}
852 \item {} \href{\#replacement-text
}{2.14.6~~~Replacement Text
}
854 \item {} \href{\#compound-paragraph
}{2.14.7~~~Compound Paragraph
}
856 \item {} \href{\#parsed-literal-blocks
}{2.14.8~~~Parsed Literal Blocks
}
861 These are just a sample of the many reStructuredText Directives. For
863 \href{http://docutils.sourceforge.net/docs/ref/rst/directives.html
}{http://docutils.sourceforge.net/docs/ref/rst/directives.html
}.
866 %___________________________________________________________________________
868 \hypertarget{document-parts
}{}
869 \pdfbookmark[2]{2.14.1~~~Document Parts
}{document-parts
}
870 \subsubsection*
{2.14.1~~~Document Parts
}
871 \label{document-parts
}
873 An example of the ``contents'' directive can be seen above this section
874 (a local, untitled table of
\href{\#contents
}{contents
}) and at the beginning of the
875 document (a
document-wide
\href{\#table-of-contents
}{table of contents
}).
878 %___________________________________________________________________________
880 \hypertarget{images
}{}
881 \pdfbookmark[2]{2.14.2~~~Images
}{images
}
882 \subsubsection*
{2.14.2~~~Images
}
885 An image directive (also clickable -
{}- a hyperlink reference):
886 \href{\#directives
}{\includegraphics{../../../docs/user/rst/images/title.png
}}
887 Image with multiple IDs:
888 \hypertarget{image-target-
1}{}\hypertarget{image-target-
2}{}\hypertarget{image-target-
3}{}
889 \includegraphics{../../../docs/user/rst/images/title.png
}
893 {\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png
}\hfill}
895 A left-aligned image:
897 {\includegraphics{../../../docs/user/rst/images/biohazard.png
}\hfill}
899 A right-aligned image:
901 {\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
904 \begin{figure
}[htbp
]\begin{flushright
}
906 \includegraphics[width=
50]{../../../docs/user/rst/images/biohazard.png
}
907 \caption{A figure is an image with a caption and/or a legend:
}{\small
909 \begin{longtable
}[c
]{|p
{0.156\locallinewidth}|p
{0.563\locallinewidth}|
}
914 Revised, revisited, based on 're' module.
920 Structure-enhanced text, structuredtext.
926 Well it is, isn't it?
931 This paragraph is also part of the legend.
932 }\end{flushright
}\end{figure
}
933 \begin{figure
}[htbp
]\begin{flushleft
}
935 \includegraphics[width=
50]{../../../docs/user/rst/images/biohazard.png
}
936 \caption{A left-aligned figure.
}{\small
938 }\end{flushleft
}\end{figure
}
940 This paragraph might flow around the figure...
946 \includegraphics[width=
50]{../../../docs/user/rst/images/biohazard.png
}
947 \caption{This is the caption.
}{\small
950 The legend may consist of several paragraphs.
953 This paragraph might flow around the figure...
955 A left-aligned figure:
956 \begin{figure
}[htbp
]\begin{flushleft
}
958 \includegraphics[width=
50]{../../../docs/user/rst/images/biohazard.png
}
959 \caption{This is the caption.
}{\small
962 The legend may consist of several paragraphs.
963 }\end{flushleft
}\end{figure
}
965 This paragraph might flow around the figure...
971 \includegraphics[width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
973 An image
2 em wide and
30 pixel high:
975 \includegraphics[width=
2em,height=
30pt
]{../../../docs/user/rst/images/biohazard.png
}
977 An image occupying
70{\%
} of the line width:
979 \includegraphics[width=
0.700\linewidth]{../../../docs/user/rst/images/biohazard.png
}
983 \includegraphics[height=
3cm
]{../../../docs/user/rst/images/biohazard.png
}
986 %___________________________________________________________________________
988 \hypertarget{admonitions
}{}
989 \pdfbookmark[2]{2.14.3~~~Admonitions
}{admonitions
}
990 \subsubsection*
{2.14.3~~~Admonitions
}
992 \begin{center
}\begin{sffamily
}
993 \fbox{\parbox{\admonitionwidth}{
994 \textbf{\large Attention!
}
1001 \begin{center
}\begin{sffamily
}
1002 \fbox{\parbox{\admonitionwidth}{
1003 \textbf{\large Caution!
}
1006 Don't take any wooden nickels.
1010 \begin{center
}\begin{sffamily
}
1011 \fbox{\parbox{\admonitionwidth}{
1012 \textbf{\large !DANGER!
}
1015 Mad scientist at work!
1019 \begin{center
}\begin{sffamily
}
1020 \fbox{\parbox{\admonitionwidth}{
1021 \textbf{\large Error
}
1028 \begin{center
}\begin{sffamily
}
1029 \fbox{\parbox{\admonitionwidth}{
1030 \textbf{\large Hint
}
1033 It's bigger than a bread box.
1037 \begin{center
}\begin{sffamily
}
1038 \fbox{\parbox{\admonitionwidth}{
1039 \textbf{\large Important
}
1043 Wash behind your ears.
1058 \begin{center
}\begin{sffamily
}
1059 \fbox{\parbox{\admonitionwidth}{
1060 \textbf{\large Note
}
1067 \begin{center
}\begin{sffamily
}
1068 \fbox{\parbox{\admonitionwidth}{
1072 15{\%
} if the service is good.
1076 \begin{center
}\begin{sffamily
}
1077 \fbox{\parbox{\admonitionwidth}{
1078 \textbf{\large Warning
}
1081 Strong prose may provoke extreme mental exertion.
1082 Reader discretion is strongly advised.
1086 \begin{center
}\begin{sffamily
}
1087 \fbox{\parbox{\admonitionwidth}{
1089 \textbf{\large And, by the way...
}
1092 You can make up your own admonition too.
1098 %___________________________________________________________________________
1100 \hypertarget{topics-sidebars-and-rubrics
}{}
1101 \pdfbookmark[2]{2.14.4~~~Topics, Sidebars, and Rubrics
}{topics-sidebars-and-rubrics
}
1102 \subsubsection*
{2.14.4~~~Topics, Sidebars, and Rubrics
}
1103 \label{topics-sidebars-and-rubrics
}
1105 \setlength{\locallinewidth}{0.9\admonitionwidth}
1106 \begin{center
}\begin{sffamily
}
1107 \fbox{\colorbox[gray
]{0.80}{\parbox{\admonitionwidth}{
1108 \textbf{\large Sidebar Title
}
1111 \textbf{Optional Subtitle
}
1114 This is a sidebar. It is for text outside the flow of the main
1116 \rubric{This is a rubric inside a sidebar
}
1118 Sidebars often appears beside the main text with a border and
1124 \setlength{\locallinewidth}{\linewidth}
1125 \subsubsection*
{~
\hfill Topic Title
\hfill ~
}
1129 \rubric{This is a rubric
}
1132 %___________________________________________________________________________
1134 \hypertarget{target-footnotes
}{}
1135 \pdfbookmark[2]{2.14.5~~~Target Footnotes
}{target-footnotes
}
1136 \subsubsection*
{2.14.5~~~Target Footnotes
}
1137 \label{target-footnotes
}
1138 \begin{figure
}[b
]\hypertarget{id26
}$^
{5}$
1139 \href{http://www.python.org/
}{http://www.python.org/
}
1141 \begin{figure
}[b
]\hypertarget{id31
}$^
{6}$
1142 \href{http://docutils.sourceforge.net/
}{http://docutils.sourceforge.net/
}
1146 %___________________________________________________________________________
1148 \hypertarget{replacement-text
}{}
1149 \pdfbookmark[2]{2.14.6~~~Replacement Text
}{replacement-text
}
1150 \subsubsection*
{2.14.6~~~Replacement Text
}
1151 \label{replacement-text
}
1153 I recommend you try
\href{http://www.python.org/
}{Python,
\emph{the
} best language around
}\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id26
}{5}}.
1156 %___________________________________________________________________________
1158 \hypertarget{compound-paragraph
}{}
1159 \pdfbookmark[2]{2.14.7~~~Compound Paragraph
}{compound-paragraph
}
1160 \subsubsection*
{2.14.7~~~Compound Paragraph
}
1161 \label{compound-paragraph
}
1163 Compound
1, paragraph
1.
1165 Compound
1, paragraph
2.
1168 Compound
1, list item one.
1171 Compound
1, list item two.
1175 Another compound statement:
1177 Compound
2, a literal block:
1178 \begin{quote
}{\ttfamily \raggedright \noindent
1179 Compound~
2,~literal.
1181 Compound
2, this is a test.
1183 Compound
3, only consisting of one paragraph.
1184 \begin{quote
}{\ttfamily \raggedright \noindent
1186 This~one~starts~with~a~literal~block.
1188 Compound
4, a paragraph.
1190 Now something
\emph{really
} perverted -
{}- a nested compound block. This is
1191 just to test that it works at all; the results don't have to be
1194 Compound
5, block
1 (a paragraph).
1196 Compound
6, block
2 in compound
5.
1198 Compound
6, another paragraph.
1200 Compound
5, block
3 (a paragraph).
1202 Compound
7, with a table inside:
1205 \begin{longtable
}[c
]{|p
{0.249\locallinewidth}|p
{0.249\locallinewidth}|p
{0.249\locallinewidth}|
}
1227 Compound
7, a paragraph after the table.
1229 Compound
7, another paragraph.
1232 %___________________________________________________________________________
1234 \hypertarget{parsed-literal-blocks
}{}
1235 \pdfbookmark[2]{2.14.8~~~Parsed Literal Blocks
}{parsed-literal-blocks
}
1236 \subsubsection*
{2.14.8~~~Parsed Literal Blocks
}
1237 \label{parsed-literal-blocks
}
1238 \begin{quote
}{\ttfamily \raggedright \noindent
1239 This~is~a~parsed~literal~block.~\\
1240 ~~~~This~line~is~indented.~~The~next~line~is~blank.~\\
1242 Inline~markup~is~supported,~e.g.~
\emph{emphasis
},~
\textbf{strong
},~
\texttt{literal~\\
1243 text
},~footnotes
\raisebox{.5em
}[0em
]{\scriptsize\hyperlink{id8
}{1}},~
\hypertarget{id22
}{targets
},~and~
\href{http://www.python.org/
}{references
}.
1247 %___________________________________________________________________________
1249 \hypertarget{substitution-definitions
}{}
1250 \pdfbookmark[1]{2.15~~~Substitution Definitions
}{substitution-definitions
}
1251 \subsection*
{2.15~~~Substitution Definitions
}
1252 \label{substitution-definitions
}
1254 An inline image (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}) example:
1256 (Substitution definitions are not visible in the HTML source.)
1259 %___________________________________________________________________________
1261 \hypertarget{comments
}{}
1262 \pdfbookmark[1]{2.16~~~Comments
}{comments
}
1263 \subsection*
{2.16~~~Comments
}
1267 % Comments begin with two dots and a space. Anything may
1268 % follow, except for the syntax of footnotes, hyperlink
1269 % targets, directives, or substitution definitions.
1271 % Double-dashes -- "--" -- must be escaped somehow in HTML output.
1273 % Comments may contain non-ASCII characters: ä ö ü æ ø å
1275 (View the HTML source to see the comment.)
1278 %___________________________________________________________________________
1280 \hypertarget{raw-text
}{}
1281 \pdfbookmark[1]{2.17~~~Raw text
}{raw-text
}
1282 \subsection*
{2.17~~~Raw text
}
1285 This does not necessarily look nice, because there may be missing white space.
1287 It's just there to freeze the behavior.
1288 A test.Second test.Another test with myclass set.
1289 This is the fourth test with myrawroleclass set.
1290 Fifth test in LaTeX.\
\Line two.
1292 %___________________________________________________________________________
1294 \hypertarget{container
}{}
1295 \pdfbookmark[1]{2.18~~~Container
}{container
}
1296 \subsection*
{2.18~~~Container
}
1304 %___________________________________________________________________________
1306 \hypertarget{colspanning-tables
}{}
1307 \pdfbookmark[1]{2.19~~~Colspanning tables
}{colspanning-tables
}
1308 \subsection*
{2.19~~~Colspanning tables
}
1309 \label{colspanning-tables
}
1311 This table has a cell spanning two columns:
1314 \begin{longtable
}[c
]{|p
{0.075\locallinewidth}|p
{0.075\locallinewidth}|p
{0.086\locallinewidth}|
}
1316 \multicolumn{2}{|l|
}{\textbf{
1366 %___________________________________________________________________________
1368 \hypertarget{rowspanning-tables
}{}
1369 \pdfbookmark[1]{2.20~~~Rowspanning tables
}{rowspanning-tables
}
1370 \subsection*
{2.20~~~Rowspanning tables
}
1371 \label{rowspanning-tables
}
1373 Here's a table with cells spanning several rows:
1376 \begin{longtable
}[c
]{|p
{0.296\locallinewidth}|p
{0.156\locallinewidth}|p
{0.226\locallinewidth}|
}
1379 Header row, column
1
1380 (header rows optional)
1389 body row
1, column
1
1398 &
\multirow{2}{0.16\locallinewidth}{
1401 } &
\multirow{2}{0.23\locallinewidth}{
1414 %___________________________________________________________________________
1416 \hypertarget{tests-for-the-latex-writer
}{}
1417 \pdfbookmark[0]{3~~~Tests for the LaTeX writer
}{tests-for-the-latex-writer
}
1418 \section*
{3~~~Tests for the LaTeX writer
}
1419 \label{tests-for-the-latex-writer
}
1422 %___________________________________________________________________________
1424 \hypertarget{some-tests-for-the-latex2e-writer
}{}
1425 \pdfbookmark[0]{4~~~Some Tests for the LaTeX2e Writer
}{some-tests-for-the-latex2e-writer
}
1426 \section*
{4~~~Some Tests for the LaTeX2e Writer
}
1427 \label{some-tests-for-the-latex2e-writer
}
1429 These tests have been written to exercise some unusual combinations of
1430 syntax elements which may cause trouble for the LaTeX writer but do
1431 not need to be tested with other writers (e.g. the HTML writer).
1433 This file is user by the standalone
{\_}rst
{\_}latex test.
1436 %___________________________________________________________________________
1438 \hypertarget{id23
}{}
1439 \pdfbookmark[0]{5~~~Option lists
}{id23
}
1440 \section*
{5~~~Option lists
}
1443 The LaTeX-
2e description environment is used for definition lists.
1444 The definition is continued on the same line as the term, this should
1445 not happen if a option-list is at the top of the definition.
1447 If the option list is not at the first element in the definition, it
1448 is contained in a quote
1450 \begin{optionlist
}{3cm
}
1458 \item[{In a definition list:
}] \leavevmode \begin{optionlist
}{3cm
}
1468 %___________________________________________________________________________
1470 \hypertarget{monospaced-non-alphanumeric-characters
}{}
1471 \pdfbookmark[1]{5.1~~~Monospaced non-alphanumeric characters
}{monospaced-non-alphanumeric-characters
}
1472 \subsection*
{5.1~~~Monospaced non-alphanumeric characters
}
1473 \label{monospaced-non-alphanumeric-characters
}
1475 These are all ASCII characters except a-zA-Z0-
9 and space:
1477 \texttt{!!!"
{}"
{}"
{\#
}{\#
}{\#
}{\$
}{\$
}{\$
}{\%
}{\%
}{\%
}{\&
}{\&
}{\&
}'
{}'
{}'((()))***+++,
{},
{},-
{}-
{}-...///:::
}
1479 \texttt{;;;<
{}<
{}<===>
{}>
{}>???@@@
{[}{[}{[}{\textbackslash}{\textbackslash}{\textbackslash}{]}{]}{]}{\textasciicircum}{\textasciicircum}{\textasciicircum}{\_}{\_}{\_}`
{}`
{}`
{\
{}{\
{}{\
{}|||
{\
}}{\
}}{\
}}{\textasciitilde}{\textasciitilde}{\textasciitilde}}
1481 \texttt{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
1483 The two lines of non-alphanumeric characters should both have the same
1484 width as the third line.
1487 %___________________________________________________________________________
1489 \hypertarget{various-non-ascii-characters
}{}
1490 \pdfbookmark[1]{5.2~~~Various non-ASCII characters
}{various-non-ascii-characters
}
1491 \subsection*
{5.2~~~Various non-ASCII characters
}
1492 \label{various-non-ascii-characters
}
1495 \begin{longtable
}[c
]{|p
{0.028\locallinewidth}|p
{0.424\locallinewidth}|
}
1512 left pointing guillemet
1518 right pointing guillemet
1536 single turned comma quotation mark
1542 single comma quotation mark
1548 low single comma quotation mark
1554 double turned comma quotation mark
1560 double comma quotation mark
1566 low double comma quotation mark
1596 left-right double arrow
1601 The following line should not be wrapped, because it uses
1602 non-breakable spaces:
1604 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
1607 %___________________________________________________________________________
1609 \hypertarget{custom-roles
}{}
1610 \pdfbookmark[1]{5.3~~~Custom Roles
}{custom-roles
}
1611 \subsection*
{5.3~~~Custom Roles
}
1612 \label{custom-roles
}
1615 A role based on an existing role.
1617 \texttt{one
} \texttt{two
} \texttt{three
}
1622 \docutilsrolecustomnew{one two three
}
1625 A role with class attribute.
1627 \docutilsrolespecial{interpreted text
}
1630 A role with class attribute.
1632 \docutilsrolevery{\docutilsrolespecial{interpreted text
}}
1637 %___________________________________________________________________________
1639 \hypertarget{error-handling
}{}
1640 \pdfbookmark[0]{6~~~Error Handling
}{error-handling
}
1641 \section*
{6~~~Error Handling
}
1642 \label{error-handling
}
1644 Any errors caught during processing will generate system messages.
1646 There should be five messages in the following, auto-generated
1647 section, ``Docutils System Messages'':
1648 % section should be added by Docutils automatically
1651 %___________________________________________________________________________
1653 \section*
{Docutils System Messages
}
1655 Undefined substitution referenced: ``problematic''.
1658 Unknown target name: ``
5''.
1661 Unknown target name: ``nonexistent''.
1664 Unknown target name: ``hyperlink reference without a target''.
1667 Duplicate target name, cannot be used as a unique reference: ``duplicate target names''.