1 \documentclass[a4paper]{article
}
2 % generated by Docutils <http://docutils.sourceforge.net/>
3 \usepackage{fixltx2e
} % LaTeX patches, \textsubscript
4 \usepackage{cmap
} % fix search and cut-and-paste in Acrobat
6 \usepackage[T1]{fontenc}
7 \usepackage[utf8
]{inputenc}
9 \usepackage[british,french,
ngerman,english
]{babel
}
10 % Prevent side-effects if French hyphenation patterns are not loaded:
11 \frenchbsetup{StandardLayout
}
12 \AtBeginDocument{\selectlanguage{english
}\noextrasfrench}
14 \usepackage{float
} % float configuration
15 \floatplacement{figure
}{H
} % place figures here definitely
19 \usepackage{longtable,ltcaption,array
}
20 \setlength{\extrarowheight}{2pt
}
21 \newlength{\DUtablewidth} % internal use in tables
23 \usepackage{textcomp
} % text symbol macros
25 %%% Custom LaTeX preamble
27 \usepackage{mathptmx
} % Times
28 \usepackage[scaled=
.90]{helvet
}
31 %%% User specified packages and stylesheets
33 %%% Fallback definitions for Docutils-specific commands
35 % providelength (provide a length variable and set default, if it is new)
36 \providecommand*
{\DUprovidelength}[2]{
37 \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{}
41 \providecommand*
{\DUtitleabstract}[1]{\centerline{\textbf{#1}}}
43 % admonition (specially marked topic)
44 \providecommand{\DUadmonition}[2][class-arg
]{%
45 % try \DUadmonition#1{#2}:
46 \ifcsname DUadmonition
#1\endcsname%
47 \csname DUadmonition
#1\endcsname{#2}%
50 \fbox{\parbox{0.9\textwidth}{#2}}
56 \@namedef
{DUrolealign-center
}{\centering}
61 \providecommand{\DUtopicdedication}[1]{\begin{center
}#1\end{center
}}
63 % docinfo (width of docinfo table)
64 \DUprovidelength{\DUdocinfowidth}{0.9\textwidth}
66 % error admonition title
67 \providecommand*
{\DUtitleerror}[1]{\DUtitle{\color{red
}#1}}
69 % fieldlist environment
70 \ifthenelse{\isundefined{\DUfieldlist}}{
71 \newenvironment{DUfieldlist
}%
73 {\enddescription\endquote}
75 % numeric or symbol footnotes with hyperlinks
76 \providecommand*
{\DUfootnotemark}[3]{%
77 \raisebox{1em
}{\hypertarget{#1}{}}%
78 \hyperlink{#2}{\textsuperscript{#3}}%
80 \providecommand{\DUfootnotetext}[4]{%
82 \renewcommand{\thefootnote}{%
83 \protect\raisebox{1em
}{\protect\hypertarget{#1}{}}%
84 \protect\hyperlink{#2}{#3}}%
89 % inline markup (custom roles)
90 % \DUrole{#1}{#2} tries \DUrole#1{#2}
91 \providecommand*
{\DUrole}[2]{%
92 \ifcsname DUrole
#1\endcsname%
93 \csname DUrole
#1\endcsname{#2}%
94 \else% backwards compatibility: try \docutilsrole#1{#2}
95 \ifcsname docutilsrole
#1\endcsname%
96 \csname docutilsrole
#1\endcsname{#2}%
104 \ifthenelse{\isundefined{\DUlegend}}{
105 \newenvironment{DUlegend
}{\small}{}
108 % lineblock environment
109 \DUprovidelength{\DUlineblockindent}{2.5em
}
110 \ifthenelse{\isundefined{\DUlineblock}}{
111 \newenvironment{DUlineblock
}[1]{%
112 \list{}{\setlength{\partopsep}{\parskip}
113 \addtolength{\partopsep}{\baselineskip}
114 \setlength{\topsep}{0pt
}
115 \setlength{\itemsep}{0.15\baselineskip}
116 \setlength{\parsep}{0pt
}
117 \setlength{\leftmargin}{#1}}
123 % optionlist environment
124 \providecommand*
{\DUoptionlistlabel}[1]{\bf #1 \hfill}
125 \DUprovidelength{\DUoptionlistindent}{3cm
}
126 \ifthenelse{\isundefined{\DUoptionlist}}{
127 \newenvironment{DUoptionlist
}{%
128 \list{}{\setlength{\labelwidth}{\DUoptionlistindent}
129 \setlength{\rightmargin}{1cm
}
130 \setlength{\leftmargin}{\rightmargin}
131 \addtolength{\leftmargin}{\labelwidth}
132 \addtolength{\leftmargin}{\labelsep}
133 \renewcommand{\makelabel}{\DUoptionlistlabel}}
138 % rubric (informal heading)
139 \providecommand*
{\DUrubric}[2][class-arg
]{%
140 \subsubsection*
{\centering\textit{\textmd{#2}}}}
142 % sidebar (text outside the main text flow)
143 \providecommand{\DUsidebar}[2][class-arg
]{%
145 \colorbox[gray
]{0.80}{\parbox{0.9\textwidth}{#2}}
149 % subtitle (for topic/sidebar)
150 \providecommand*
{\DUsubtitle}[2][class-arg
]{\par\emph{#2}\smallskip}
152 % title for topics, admonitions and sidebar
153 \providecommand*
{\DUtitle}[2][class-arg
]{%
154 % call \DUtitle#1{#2} if it exists:
155 \ifcsname DUtitle
#1\endcsname%
156 \csname DUtitle
#1\endcsname{#2}%
158 \smallskip\noindent\textbf{#2}\smallskip%
162 % titlereference role
163 \providecommand*
{\DUroletitlereference}[1]{\textsl{#1}}
165 % topic (quote with heading)
166 \providecommand{\DUtopic}[2][class-arg
]{%
167 \ifcsname DUtopic
#1\endcsname%
168 \csname DUtopic
#1\endcsname{#2}%
170 \begin{quote
}#2\end{quote
}
174 % transition (break, fancybreak, anonymous section)
175 \providecommand*
{\DUtransition}[1][class-arg
]{%
176 \hspace*
{\fill}\hrulefill\hspace*
{\fill}
177 \vskip 0.5\baselineskip
181 \ifthenelse{\isundefined{\hypersetup}}{
182 \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue
]{hyperref
}
183 \urlstyle{same
} % normal text font (alternatives: tt, rm, sf)
186 pdftitle=
{reStructuredText Test Document
},
187 pdfauthor=
{David Goodger;Me;Myself;I
}
191 \title{\phantomsection%
192 reStructuredText Test Document
%
193 \label{restructuredtext-test-
document}%
196 \large{Examples of Syntax Constructs
}%
197 \label{examples-of-syntax-constructs
}%
208 \begin{tabularx
}{\DUdocinfowidth}{lX
}
217 \href{mailto:goodger@python.org
}{goodger@python.org
} \\
224 \textbf{Organization
}: &
227 Now, or yesterday. Or maybe even
\emph{before
} yesterday. \\
229 This is a ``work in progress'' \\
231 is managed by a version control system. \\
234 \textbf{Copyright
}: &
235 This
document has been placed in the public domain. You
236 may do with it as you wish. You may copy, modify,
237 redistribute, reattribute, sell, buy, rent, lease,
238 destroy, or improve it, quote it at length, excerpt,
239 incorporate, collate, fold, staple, or mutilate it, or do
240 anything else to it that your or anyone else's heart
242 \textbf{field name
}: &
243 This is a ``generic bibliographic field''.
245 \textbf{field name ``
2''
}: &
246 Generic bibliographic fields may contain multiple body elements.
253 \DUtopic[dedication
]{
254 \DUtitle[dedication
]{Dedication
}
256 For Docutils users \& co-developers.
260 \DUtitle[abstract
]{Abstract
}
262 This is a test
document, containing at least one example of each
263 reStructuredText construct.
266 % This is a comment. Note how any initial comments are moved by
267 % transforms to after the document title, subtitle, and docinfo.
269 % Above is the document title, and below is the subtitle.
270 % They are transformed from section titles after parsing.
272 % bibliographic fields (which also require a transform):
274 \pagebreak[4] % start ToC on new page
276 \phantomsection\label{table-of-contents
}
277 \pdfbookmark[1]{Table of Contents
}{table-of-contents
}
278 \renewcommand{\contentsname}{Table of Contents
}
283 %___________________________________________________________________________
285 \section*
{\phantomsection%
286 1~~~Structural Elements
%
287 \addcontentsline{toc
}{section
}{1~~~Structural Elements
}%
288 \label{structural-elements
}%
292 %___________________________________________________________________________
294 \subsection*
{\phantomsection%
296 \addcontentsline{toc
}{subsection
}{1.1~~~Section Title
}%
297 \label{section-title
}%
299 \subsubsection*
{Section Subtitle
}
301 Lone subsections are converted to a section subtitle by a transform
302 activated with the
\texttt{-
{}-section-subtitles
} command line option or the
303 \texttt{sectsubtitle-xform
} configuration value.
306 %___________________________________________________________________________
308 \subsection*
{\phantomsection%
310 \addcontentsline{toc
}{subsection
}{1.2~~~Empty Section
}%
311 \label{empty-section
}%
315 %___________________________________________________________________________
317 \subsection*
{\phantomsection%
319 \addcontentsline{toc
}{subsection
}{1.3~~~Transitions
}%
326 %___________________________________________________________________________
330 It divides the section. Transitions may also occur between sections:
333 %___________________________________________________________________________
338 %___________________________________________________________________________
340 \section*
{\phantomsection%
342 \addcontentsline{toc
}{section
}{2~~~Body Elements
}%
343 \label{body-elements
}%
347 %___________________________________________________________________________
349 \subsection*
{\phantomsection%
351 \addcontentsline{toc
}{subsection
}{2.1~~~Paragraphs
}%
358 %___________________________________________________________________________
360 \subsubsection*
{\phantomsection%
361 2.1.1~~~Inline Markup
%
362 \addcontentsline{toc
}{subsubsection
}{2.1.1~~~Inline Markup
}%
363 \label{inline-markup
}%
366 Paragraphs contain text and may contain inline markup:
\emph{emphasis
},
367 \textbf{strong emphasis
},
\texttt{inline literals
}, standalone hyperlinks
368 (
\url{http://www.python.org
}), external hyperlinks (
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id30
}{id29
}{5}), internal
369 cross-references (
\hyperref[example
]{example
}), external hyperlinks with embedded URIs
370 (
\href{http://www.python.org
}{Python web site
}),
\href{http://www.python.org/
}{anonymous hyperlink
371 references
}\DUfootnotemark{id38
}{id29
}{5} (
\href{http://docutils.sourceforge.net/
}{a second reference
}\DUfootnotemark{id40
}{id39
}{8}), footnote references (manually
372 numbered
\DUfootnotemark{id1
}{id8
}{1}, anonymous auto-numbered
\DUfootnotemark{id2
}{id12
}{3}, labeled auto-numbered
\DUfootnotemark{id3
}{label
}{2}, or symbolic
\DUfootnotemark{id4
}{id13
}{*
}), citation references (
\hyperlink{cit2002
}{[CIT2002
]}),
373 substitution references (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}), and
%
374 \phantomsection\label{inline-hyperlink-targets
}inline hyperlink targets
375 (see
\hyperref[targets
]{Targets
} below for a reference back to here). Character-level
376 inline markup is also possible (although exceedingly ugly!) in
\emph{re
}\texttt{Structured
}\emph{Text
}. Problems are indicated by
%
377 \raisebox{1em
}{\hypertarget{id28
}{}}\hyperlink{id27
}{\textbf{\color{red
}|problematic|
}} text
378 (generated by processing errors; this one is intentional). Here is a
379 reference to the
\hyperref[doctitle
]{doctitle
} and the
\hyperref[subtitle
]{subtitle
}.
381 The default role for interpreted text is
\DUroletitlereference{Title Reference
}. Here are
382 some explicit interpreted text roles: a PEP reference (
\href{http://www.python.org/dev/peps/pep-
0287}{PEP
287}); an
383 RFC reference (
\href{http://www.faqs.org/rfcs/rfc2822.html
}{RFC
2822}); an abbreviation (
\DUrole{abbreviation
}{abb.
}), an acronym
384 (
\DUrole{acronym
}{reST
}), code (
\texttt{\DUrole{code
}{print "hello world"
}}); a
\textsubscript{subscript
};
385 a
\textsuperscript{superscript
} and explicit roles for
\DUroletitlereference{Docutils
}'
386 \emph{standard
} \textbf{inline
} \texttt{markup
}.
388 % DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
390 Let's test wrapping and whitespace significance in inline literals:
391 \texttt{This is an example of -
{}-inline-literal -
{}-text, -
{}-including some-
{}-
392 strangely-
{}-hyphenated-words. ~Adjust-the-width-of-your-browser-window
393 to see how the text is wrapped. ~-
{}- -
{}-
{}-
{}- -
{}-
{}-
{}-
{}-
{}-
{}-
{}- ~Now note ~ ~the
394 spacing ~ ~between the ~ ~words of ~ ~this sentence ~ ~(words
395 should ~ ~be grouped ~ ~in pairs).
}
397 If the
\texttt{-
{}-pep-references
} option was supplied, there should be a
398 live link to PEP
258 here.
401 %___________________________________________________________________________
403 \subsection*
{\phantomsection%
405 \addcontentsline{toc
}{subsection
}{2.2~~~Bullet Lists
}%
406 \label{bullet-lists
}%
415 \item Nested bullet list.
423 Paragraph
2 of item
2.
427 \item Nested bullet list.
441 \item This nested list should be compacted by the HTML writer.
443 \phantomsection\label{target
}
444 % Even if this item contains a target and a comment.
451 %___________________________________________________________________________
453 \subsection*
{\phantomsection%
454 2.3~~~Enumerated Lists
%
455 \addcontentsline{toc
}{subsection
}{2.3~~~Enumerated Lists
}%
456 \label{enumerated-lists
}%
458 \newcounter{listcnt0
}
459 \begin{list
}{\arabic{listcnt0
}.
}
461 \usecounter{listcnt0
}
462 \setlength{\rightmargin}{\leftmargin}
465 \item Arabic numerals.
466 \newcounter{listcnt1
}
467 \begin{list
}{\alph{listcnt1
})
}
469 \usecounter{listcnt1
}
470 \setlength{\rightmargin}{\leftmargin}
474 \newcounter{listcnt2
}
475 \begin{list
}{(
\roman{listcnt2
})
}
477 \usecounter{listcnt2
}
478 \setlength{\rightmargin}{\leftmargin}
482 \newcounter{listcnt3
}
483 \begin{list
}{\Alph{listcnt3
}.
}
485 \usecounter{listcnt3
}
486 \setlength{\rightmargin}{\leftmargin}
490 \newcounter{listcnt4
}
491 \begin{list
}{\Roman{listcnt4
})
}
493 \usecounter{listcnt4
}
494 \setlength{\rightmargin}{\leftmargin}
503 \item Lists that don't start at
1:
504 \setcounter{listcnt1
}{0}
505 \begin{list
}{\arabic{listcnt1
}.
}
507 \usecounter{listcnt1
}
508 \addtocounter{listcnt1
}{2}
509 \setlength{\rightmargin}{\leftmargin}
516 \setcounter{listcnt1
}{0}
517 \begin{list
}{\Alph{listcnt1
}.
}
519 \usecounter{listcnt1
}
520 \addtocounter{listcnt1
}{2}
521 \setlength{\rightmargin}{\leftmargin}
528 \setcounter{listcnt1
}{0}
529 \begin{list
}{\roman{listcnt1
}.
}
531 \usecounter{listcnt1
}
532 \addtocounter{listcnt1
}{2}
533 \setlength{\rightmargin}{\leftmargin}
543 %___________________________________________________________________________
545 \subsection*
{\phantomsection%
546 2.4~~~Definition Lists
%
547 \addcontentsline{toc
}{subsection
}{2.4~~~Definition Lists
}%
548 \label{definition-lists
}%
552 \item[{Term
}] \leavevmode
555 \item[{Term
}] \leavevmode (
\textbf{classifier
})
557 Definition paragraph
1.
559 Definition paragraph
2.
561 \item[{Term
}] \leavevmode
564 \item[{Term
}] \leavevmode (
\textbf{classifier one
})
565 (
\textbf{classifier two
})
572 %___________________________________________________________________________
574 \subsection*
{\phantomsection%
576 \addcontentsline{toc
}{subsection
}{2.5~~~Field Lists
}%
582 Field lists map field names to field bodies, like database
583 records. They are often part of an extension syntax. They are
584 an unambiguous variant of RFC
2822 fields.
586 \item[{how arg1 arg2:
}]
587 The field marker is a colon, the field name, and a colon.
589 The field body may contain one or more body elements, indented
590 relative to the field marker.
593 \DUrole{credits
}{This paragraph has the
\DUroletitlereference{credits
} class set. (This is actually not
594 about credits but just for ensuring that the class attribute
595 doesn't get stripped away.)
}
600 %___________________________________________________________________________
602 \subsection*
{\phantomsection%
604 \addcontentsline{toc
}{subsection
}{2.6~~~Option Lists
}%
605 \label{option-lists
}%
608 For listing command-line options:
612 \item[-a
] command-line option ``a''
614 \item[-b file
] options can have arguments
615 and long descriptions
617 \item[-
{}-long
] options can be long also
619 \item[-
{}-input=file
] long options can also have
622 \item[-
{}-very-long-option
] The description can also start on the next line.
624 The description may contain multiple body elements,
625 regardless of where it starts.
627 \item[-x, -y, -z
] Multiple options are an ``option group''.
629 \item[-v, -
{}-verbose
] Commonly-seen: short \& long options.
631 \item[-
1 file, -
{}-one=file, -
{}-two file
] Multiple options with arguments.
633 \item[/V
] DOS/VMS-style options too
637 There must be at least two spaces between the option and the
641 %___________________________________________________________________________
643 \subsection*
{\phantomsection%
644 2.7~~~Literal Blocks
%
645 \addcontentsline{toc
}{subsection
}{2.7~~~Literal Blocks
}%
646 \label{literal-blocks
}%
649 Literal blocks are indicated with a double-colon (``::'') at the end of
650 the preceding paragraph (over there
\texttt{-
{}->
}). They can be indented:
652 \begin{quote
}{\ttfamily \raggedright \noindent
654 ~~~~text~=~'is~left~as-is'\\
655 ~~~~spaces
\_and\_linebreaks~=~'are~preserved'\\
656 ~~~~markup
\_processing~=~None
660 Or they can be quoted without indentation:
662 \begin{quote
}{\ttfamily \raggedright \noindent
665 >~Why~didn't~I~think~of~that?
670 %___________________________________________________________________________
672 \subsection*
{\phantomsection%
674 \addcontentsline{toc
}{subsection
}{2.8~~~Line Blocks
}%
678 This section tests line blocks. Line blocks are body elements which
679 consist of lines and other line blocks. Nested line blocks cause
682 \begin{DUlineblock
}{0em
}
683 \item[] This is a line block. It ends with a blank line.
685 \begin{DUlineblock
}{\DUlineblockindent}
686 \item[] New lines begin with a vertical bar (``|'').
687 \item[] Line breaks and initial indent are significant, and preserved.
689 \begin{DUlineblock
}{\DUlineblockindent}
690 \item[] Continuation lines are also possible. A long line that is intended
691 to wrap should begin with a space in place of the vertical bar.
693 \item[] The left edge of a continuation line need not be aligned with
694 the left edge of the text above it.
698 \begin{DUlineblock
}{0em
}
699 \item[] This is a second line block.
701 \item[] Blank lines are permitted internally, but they must begin with a ``|''.
704 Another line block, surrounded by paragraphs:
706 \begin{DUlineblock
}{0em
}
707 \item[] And it's no good waiting by the window
708 \item[] It's no good waiting for the sun
709 \item[] Please believe me, the things you dream of
710 \item[] They don't fall in the lap of no-one
713 Take it away, Eric the Orchestra Leader!
717 \begin{DUlineblock
}{0em
}
718 \item[] A one, two, a one two three four
720 \item[] Half a bee, philosophically,
722 \begin{DUlineblock
}{\DUlineblockindent}
723 \item[] must,
\emph{ipso facto
}, half not be.
725 \item[] But half the bee has got to be,
727 \begin{DUlineblock
}{\DUlineblockindent}
728 \item[] \emph{vis a vis
} its entity. D'you see?
731 \item[] But can a bee be said to be
733 \begin{DUlineblock
}{\DUlineblockindent}
734 \item[] or not to be an entire bee,
736 \begin{DUlineblock
}{\DUlineblockindent}
737 \item[] when half the bee is not a bee,
739 \begin{DUlineblock
}{\DUlineblockindent}
740 \item[] due to some ancient injury?
750 A line block, like the following poem by Christian Morgenstern, can
751 also be centre-aligned:
753 \begin{DUlineblock
}{0em
}
754 \otherlanguage{ngerman}{\DUrole{align-center
}{
755 \item[] \textbf{Die Trichter
}
757 \item[] Zwei Trichter wandeln durch die Nacht.
758 \item[] Durch ihres Rumpfs verengten Schacht
759 \item[] fließt weißes Mondlicht
760 \item[] still und heiter
770 %___________________________________________________________________________
772 \subsection*
{\phantomsection%
774 \addcontentsline{toc
}{subsection
}{2.9~~~Block Quotes
}%
775 \label{block-quotes
}%
778 Block quotes consist of indented body elements:
782 My theory by A. Elk. Brackets Miss, brackets. This theory goes
783 as follows and begins now. All brontosauruses are thin at one
784 end, much much thicker in the middle and then thin again at the
785 far end. That is my theory, it is mine, and belongs to me and I
786 own it, and what it is too.
789 \raggedleft —Anne Elk (Miss)
793 The language of a quote (like any other object) can be specified by
799 \otherlanguage{french
}{
800 ReStructuredText est un langage de balisage léger utilisé
801 notamment dans la documentation du langage Python.
806 %___________________________________________________________________________
808 \subsection*
{\phantomsection%
809 2.10~~~Doctest Blocks
%
810 \addcontentsline{toc
}{subsection
}{2.10~~~Doctest Blocks
}%
811 \label{doctest-blocks
}%
814 \begin{quote
}{\ttfamily \raggedright \noindent
815 >
{}>
{}>~print~'Python-specific~usage~examples;~begun~with~">
{}>
{}>"'\\
816 Python-specific~usage~examples;~begun~with~">
{}>
{}>"\\
817 >
{}>
{}>~print~'(cut~and~pasted~from~interactive~Python~sessions)'\\
818 (cut~and~pasted~from~interactive~Python~sessions)
823 %___________________________________________________________________________
825 \subsection*
{\phantomsection%
827 \addcontentsline{toc
}{subsection
}{2.11~~~Footnotes
}%
831 \DUfootnotetext{id8
}{id1
}{1}{%
832 A footnote contains body elements, consistently indented by at
835 This is the footnote's second paragraph.
838 \DUfootnotetext{label
}{id3
}{2}{\phantomsection\label{label
}%
839 Footnotes may be numbered, either manually (as in
\DUfootnotemark{id9
}{id8
}{1}) or
840 automatically using a ``\#''-prefixed label. This footnote has a
841 label so it can be referred to from multiple places, both as a
842 footnote reference (
\DUfootnotemark{id10
}{label
}{2}) and as a
\hyperref[label
]{hyperlink reference
}.
845 \DUfootnotetext{id12
}{id2
}{3}{%
846 This footnote is numbered automatically and anonymously using a
847 label of ``\#'' only.
849 This is the second paragraph.
851 And this is the third paragraph.
854 \DUfootnotetext{id13
}{id4
}{*
}{%
855 Footnotes may also use symbols, specified with a ``*'' label.
856 Here's a reference to the next footnote:
\DUfootnotemark{id14
}{id15
}{†
}.
859 \DUfootnotetext{id15
}{id14
}{†
}{%
860 This footnote shows the next symbol in the sequence.
863 \DUfootnotetext{id16
}{id16
}{4}{%
864 Here's an unreferenced footnote, with a reference to a
865 nonexistent footnote:
%
866 \raisebox{1em
}{\hypertarget{id46
}{}}%
867 \raisebox{1em
}{\hypertarget{id17
}{}}\hyperlink{id45
}{\textbf{\color{red
}{[}5{]}\_}}.
871 %___________________________________________________________________________
873 \subsection*
{\phantomsection%
875 \addcontentsline{toc
}{subsection
}{2.12~~~Citations
}%
878 \begin{figure
}[b
]\raisebox{1em
}{\hypertarget{cit2002
}{}}[CIT2002
]
879 Citations are text-labeled footnotes. They may be
880 rendered separately and differently from footnotes.
883 Here's a reference to the above,
\hyperlink{cit2002
}{[CIT2002
]}, and a
%
884 \raisebox{1em
}{\hypertarget{id48
}{}}%
885 \raisebox{1em
}{\hypertarget{id19
}{}}\hyperlink{id47
}{\textbf{\color{red
}{[}nonexistent
{]}\_}}
889 %___________________________________________________________________________
891 \subsection*
{\phantomsection%
893 \addcontentsline{toc
}{subsection
}{2.13~~~Targets
}%
895 \label{another-target
}%
898 \phantomsection\label{example
}
899 This paragraph is pointed to by the explicit ``example'' target. A
900 reference can be found under
\hyperref[inline-markup
]{Inline Markup
}, above.
\hyperref[inline-hyperlink-targets
]{Inline
901 hyperlink targets
} are also possible.
903 Section headers are implicit targets, referred to by name. See
904 \hyperref[targets
]{Targets
}, which is a subsection of
\hyperref[body-elements
]{Body Elements
}.
906 Explicit external targets are interpolated into references such as
907 ``
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id31
}{id29
}{5}''.
909 Targets may be indirect and anonymous. Thus
\hyperref[targets
]{this phrase
} may also
910 refer to the
\hyperref[targets
]{Targets
} section.
913 \raisebox{1em
}{\hypertarget{id50
}{}}\hyperlink{id49
}{\textbf{\color{red
}`hyperlink reference without a target`
\_}}, which generates an
917 %___________________________________________________________________________
919 \subsubsection*
{\phantomsection%
920 2.13.1~~~Duplicate Target Names
%
921 \addcontentsline{toc
}{subsubsection
}{2.13.1~~~Duplicate Target Names
}%
922 \label{duplicate-target-names
}%
925 Duplicate names in section headers or other implicit targets will
926 generate ``info'' (level-
1) system messages. Duplicate names in
927 explicit targets will generate ``warning'' (level-
2) system messages.
930 %___________________________________________________________________________
932 \subsubsection*
{\phantomsection%
933 2.13.2~~~Duplicate Target Names
%
934 \addcontentsline{toc
}{subsubsection
}{2.13.2~~~Duplicate Target Names
}%
938 Since there are two ``Duplicate Target Names'' section headers, we
939 cannot uniquely refer to either of them by name. If we try to (like
941 \raisebox{1em
}{\hypertarget{id52
}{}}\hyperlink{id51
}{\textbf{\color{red
}`Duplicate Target Names`
\_}}), an error is generated.
944 %___________________________________________________________________________
946 \subsection*
{\phantomsection%
948 \addcontentsline{toc
}{subsection
}{2.14~~~Directives
}%
952 \phantomsection\label{contents
}
953 These are just a sample of the many reStructuredText Directives. For
955 \url{http://docutils.sourceforge.net/docs/ref/rst/directives.html
}.
958 %___________________________________________________________________________
960 \subsubsection*
{\phantomsection%
961 2.14.1~~~Document Parts
%
962 \addcontentsline{toc
}{subsubsection
}{2.14.1~~~Document Parts
}%
963 \label{document-parts
}%
966 An example of the ``contents'' directive can be seen above this section
967 (a local, untitled table of
\hyperref[contents
]{contents
}) and at the beginning of the
968 document (a
document-wide
\hyperref[table-of-contents
]{table of contents
}).
971 %___________________________________________________________________________
973 \subsubsection*
{\phantomsection%
974 2.14.2~~~Images and Figures
%
975 \addcontentsline{toc
}{subsubsection
}{2.14.2~~~Images and Figures
}%
976 \label{images-and-figures
}%
979 An image directive (also clickable -
{}- a hyperlink reference):
981 \hyperref[directives
]{\includegraphics{../../../docs/user/rst/images/title.png
}}
983 Image with multiple IDs:
985 \includegraphics{../../../docs/user/rst/images/title.png
}
986 \phantomsection\label{image-target-
3}\label{image-target-
2}\label{image-target-
1}
990 \noindent\makebox[\textwidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
992 A left-aligned image:
994 \noindent{\includegraphics{../../../docs/user/rst/images/biohazard.png
}\hfill}
996 This paragraph might flow around the image.
997 The specific behavior depends upon the style sheet and
998 the browser or rendering software used.
1000 A right-aligned image:
1002 \noindent{\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
1004 This paragraph might flow around the image.
1005 The specific behavior depends upon the style sheet and
1006 the browser or rendering software used.
1008 For inline images see
\hyperref[substitution-definitions
]{Substitution Definitions
}.
1014 \includegraphics[width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
1016 An image
2 em wide and
15 pixel high:
1018 \includegraphics[height=
15px,width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
1020 An image occupying
50\% of the line width:
1022 \includegraphics[width=
0.500\linewidth]{../../../docs/user/rst/images/title.png
}
1026 \includegraphics[height=
2cm
]{../../../docs/user/rst/images/biohazard.png
}
1028 A
\emph{figure
} is an image with a caption and/or a legend. With page-based output
1029 media, figures might float to a different position if this helps the page
1032 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
258bp
]{../../../docs/user/rst/images/title.png
}}
1033 \caption{Plaintext markup syntax and parser system.
}
1035 \setlength{\DUtablewidth}{\linewidth}
1036 \begin{longtable*
}[c
]{|p
{0.156\DUtablewidth}|p
{0.563\DUtablewidth}|
}
1041 Revised, revisited, based on 're' module.
1047 Structure-enhanced text, structuredtext.
1053 Well it is, isn't it?
1058 This paragraph is also part of the legend.
1062 A left-aligned figure:
1064 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
1065 \caption{This is the caption.
}
1069 The legend may consist of several paragraphs.
1073 This paragraph might flow around the figure.
1075 The specific behavior depends upon the style sheet and the browser or
1076 rendering software used.
1080 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
1081 \caption{This is the caption.
}
1085 The legend may consist of several paragraphs.
1089 This paragraph might flow around the figure.
1091 The specific behavior depends upon the style sheet and the browser or
1092 rendering software used.
1094 A right-aligned figure:
1096 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
1097 \caption{This is the caption.
}
1101 The legend may consist of several paragraphs.
1105 This paragraph might flow around the figure. The specific behavior depends
1106 upon the style sheet and the browser or rendering software used.
1109 %___________________________________________________________________________
1111 \subsubsection*
{\phantomsection%
1112 2.14.3~~~Admonitions
%
1113 \addcontentsline{toc
}{subsubsection
}{2.14.3~~~Admonitions
}%
1114 \label{admonitions
}%
1117 \DUadmonition[attention
]{
1118 \DUtitle[attention
]{Attention!
}
1120 Directives at large.
1123 \DUadmonition[caution
]{
1124 \DUtitle[caution
]{Caution!
}
1126 Don't take any wooden nickels.
1129 \DUadmonition[danger
]{
1130 \DUtitle[danger
]{!DANGER!
}
1132 Mad scientist at work!
1135 \DUadmonition[error
]{
1136 \DUtitle[error
]{Error
}
1141 \DUadmonition[hint
]{
1142 \DUtitle[hint
]{Hint
}
1144 It's bigger than a bread box.
1147 \DUadmonition[important
]{
1148 \DUtitle[important
]{Important
}
1152 \item Wash behind your ears.
1154 \item Clean up your room.
1156 \item Call your mother.
1158 \item Back up your data.
1163 \DUadmonition[note
]{
1164 \DUtitle[note
]{Note
}
1172 15\% if the service is good.
1175 \DUadmonition[warning
]{
1176 \DUtitle[warning
]{Warning
}
1178 Strong prose may provoke extreme mental exertion.
1179 Reader discretion is strongly advised.
1182 \DUadmonition[admonition-and-by-the-way
]{
1183 \DUtitle[admonition-and-by-the-way
]{And, by the way...
}
1185 You can make up your own admonition too.
1189 %___________________________________________________________________________
1191 \subsubsection*
{\phantomsection%
1192 2.14.4~~~Topics, Sidebars, and Rubrics
%
1193 \addcontentsline{toc
}{subsubsection
}{2.14.4~~~Topics, Sidebars, and Rubrics
}%
1194 \label{topics-sidebars-and-rubrics
}%
1197 \emph{Sidebars
} are like miniature, parallel documents.
1200 \DUtitle[title
]{Sidebar Title
}
1202 \DUsubtitle[sidebar
]{Optional Subtitle
}
1204 This is a sidebar. It is for text outside the flow of the main
1207 \DUrubric{This is a rubric inside a sidebar
}
1209 Sidebars often appear beside the main text with a border and a different
1210 background or font
color.
1213 A
\emph{topic
} is like a block quote with a title, or a self-contained section
1214 with no subsections.
1217 \DUtitle[title
]{Topic Title
}
1222 A
\emph{rubric
} is like an informal heading that doesn't correspond to the
1223 document's structure. It is typically highlighted in red (hence the name).
1225 \DUrubric{This is a rubric
}
1227 Topics and rubrics can be used at places where a
\hyperref[section-title
]{section title
} is not
1228 allowed (e.g. inside a directive).
1231 %___________________________________________________________________________
1233 \subsubsection*
{\phantomsection%
1234 2.14.5~~~Target Footnotes
%
1235 \addcontentsline{toc
}{subsubsection
}{2.14.5~~~Target Footnotes
}%
1236 \label{target-footnotes
}%
1239 \DUfootnotetext{id29
}{id30
}{5}{%
1240 \url{http://www.python.org/
}
1243 \DUfootnotetext{id33
}{id34
}{6}{%
1244 \url{http://pygments.org/
}
1247 \DUfootnotetext{id35
}{id36
}{7}{%
1248 \url{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
}
1251 \DUfootnotetext{id39
}{id40
}{8}{%
1252 \url{http://docutils.sourceforge.net/
}
1255 \DUfootnotetext{id41
}{id42
}{9}{%
1260 %___________________________________________________________________________
1262 \subsubsection*
{\phantomsection%
1263 2.14.6~~~Replacement Text
%
1264 \addcontentsline{toc
}{subsubsection
}{2.14.6~~~Replacement Text
}%
1265 \label{replacement-text
}%
1268 I recommend you try
\href{http://www.python.org/
}{Python,
\emph{the
} best language around
}\DUfootnotemark{id32
}{id29
}{5}.
1271 %___________________________________________________________________________
1273 \subsubsection*
{\phantomsection%
1274 2.14.7~~~Compound Paragraph
%
1275 \addcontentsline{toc
}{subsubsection
}{2.14.7~~~Compound Paragraph
}%
1276 \label{compound-paragraph
}%
1279 Compound
1, paragraph
1.
1281 Compound
1, paragraph
2.
1285 \item Compound
1, list item one.
1287 \item Compound
1, list item two.
1291 Another compound statement:
1293 Compound
2, a literal block:
1295 \begin{quote
}{\ttfamily \raggedright \noindent
1296 Compound~
2,~literal.
1299 Compound
2, this is a test.
1301 Compound
3, only consisting of one paragraph.
1303 \begin{quote
}{\ttfamily \raggedright \noindent
1305 This~one~starts~with~a~literal~block.
1308 Compound
4, a paragraph.
1310 Now something
\emph{really
} perverted -
{}- a nested compound block. This is
1311 just to test that it works at all; the results don't have to be
1314 Compound
5, block
1 (a paragraph).
1316 Compound
6, block
2 in compound
5.
1318 Compound
6, another paragraph.
1320 Compound
5, block
3 (a paragraph).
1322 Compound
7, with a table inside:
1324 \setlength{\DUtablewidth}{\linewidth}
1325 \begin{longtable*
}[c
]{|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|
}
1347 Compound
7, a paragraph after the table.
1349 Compound
7, another paragraph.
1352 %___________________________________________________________________________
1354 \subsubsection*
{\phantomsection%
1355 2.14.8~~~Parsed Literal Blocks
%
1356 \addcontentsline{toc
}{subsubsection
}{2.14.8~~~Parsed Literal Blocks
}%
1357 \label{parsed-literal-blocks
}%
1360 \begin{quote
}{\ttfamily \raggedright \noindent
1361 This~is~a~parsed~literal~block.\\
1362 ~~~~This~line~is~indented.~~The~next~line~is~blank.\\
1364 Inline~markup~is~supported,~e.g.~
\emph{emphasis
},~
\textbf{strong
},~
\texttt{literal\\
1365 text
},~footnotes
\DUfootnotemark{id22
}{id8
}{1},~
%
1366 \phantomsection\label{hyperlink-targets
}hyperlink~targets,~and~
\href{http://www.python.org/
}{references
}.
1371 %___________________________________________________________________________
1373 \subsubsection*
{\phantomsection%
1375 \addcontentsline{toc
}{subsubsection
}{2.14.9~~~Code
}%
1379 Blocks of source code can be set with the
\DUroletitlereference{code
} directive. If the code
1380 language is specified, the content is parsed and tagged by the
\href{http://pygments.org/
}{Pygments
}\DUfootnotemark{id34
}{id33
}{6}
1381 syntax highlighter and can be formatted with a style sheet. (Code parsing
1382 is turned off using the
\texttt{syntax-highlight
} config setting in the test
1383 conversions in order to get identical results with/without installed
1384 Pygments highlighter.)
1386 \begin{quote
}{\ttfamily \raggedright \noindent
1387 print~'This~is~Python~code.'
1391 The
\texttt{:number-lines:
} option (with optional start value) generates line
1394 \begin{quote
}{\ttfamily \raggedright \noindent
1395 \DUrole{ln
}{~
8~
}\#~print~integers~from~
0~to~
9:\\
1396 \DUrole{ln
}{~
9~
}for~i~in~range(
10):\\
1397 \DUrole{ln
}{10~
}~~~~print~i
1401 For inline code snippets, there is the
\DUroletitlereference{code
} role, which can be used
1402 directly (the code will not be parsed/tagged, as the language is not
1403 known) or as base for special code roles, e.g.,
1409 Docutils uses LaTeX syntax for math directives and roles:
1410 \texttt{\DUrole{code
}{\DUrole{latex
}{\DUrole{tex
}{\textbackslash{}alpha = f(x)
}}}} prints $
\alpha = f(x)$.
1414 The
\texttt{:code:
} option of the
\DUroletitlereference{include
} directive sets the included content
1415 as a code block, here the rst file
\texttt{header
\_footer.txt
} with line numbers:
1417 \begin{quote
}{\ttfamily \raggedright \noindent
1418 \DUrole{ln
}{1~
}..~header::~Document~header\\
1419 \DUrole{ln
}{2~
}..~footer::~Document~footer
1424 %___________________________________________________________________________
1426 \subsection*
{\phantomsection%
1427 2.15~~~Substitution Definitions
%
1428 \addcontentsline{toc
}{subsection
}{2.15~~~Substitution Definitions
}%
1429 \label{substitution-definitions
}%
1432 An inline image (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}) example:
1434 (Substitution definitions are not visible in the HTML source.)
1437 %___________________________________________________________________________
1439 \subsection*
{\phantomsection%
1441 \addcontentsline{toc
}{subsection
}{2.16~~~Comments
}%
1447 % Comments begin with two dots and a space. Anything may
1448 % follow, except for the syntax of footnotes, hyperlink
1449 % targets, directives, or substitution definitions.
1451 % Double-dashes -- "--" -- must be escaped somehow in HTML output.
1453 % Comments may contain non-ASCII characters: ä ö ü æ ø å
1455 (View the HTML source to see the comment.)
1458 %___________________________________________________________________________
1460 \subsection*
{\phantomsection%
1462 \addcontentsline{toc
}{subsection
}{2.17~~~Raw text
}%
1466 This does not necessarily look nice, because there may be missing white space.
1468 It's just there to freeze the behavior.
1474 \DUrole{myclass
}{Another test with myclass set.
}
1476 This is the
\DUrole{myrawroleclass
}{fourth test
} with myrawroleclass set.
1478 Fifth test in LaTeX.\
\Line two.
1481 %___________________________________________________________________________
1483 \subsection*
{\phantomsection%
1485 \addcontentsline{toc
}{subsection
}{2.18~~~Container
}%
1493 % currently not implemented in LaTeX:
1494 % .. include:: data/header_footer.txt
1497 %___________________________________________________________________________
1499 \subsection*
{\phantomsection%
1500 2.19~~~Colspanning tables
%
1501 \addcontentsline{toc
}{subsection
}{2.19~~~Colspanning tables
}%
1502 \label{colspanning-tables
}%
1505 This table has a cell spanning two columns:
1507 \setlength{\DUtablewidth}{\linewidth}
1508 \begin{longtable*
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.086\DUtablewidth}|
}
1510 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1526 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1541 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1579 %___________________________________________________________________________
1581 \subsection*
{\phantomsection%
1582 2.20~~~Rowspanning tables
%
1583 \addcontentsline{toc
}{subsection
}{2.20~~~Rowspanning tables
}%
1584 \label{rowspanning-tables
}%
1587 Here's a table with cells spanning several rows:
1589 \setlength{\DUtablewidth}{\linewidth}
1590 \begin{longtable*
}[c
]{|p
{0.296\DUtablewidth}|p
{0.156\DUtablewidth}|p
{0.226\DUtablewidth}|
}
1593 Header row, column
1
1594 (header rows optional)
1604 Header row, column
1
1605 (header rows optional)
1613 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1617 body row
1, column
1
1626 &
\multirow{2}{0.16\DUtablewidth}{%
1629 } &
\multirow{2}{0.23\DUtablewidth}{%
1642 %___________________________________________________________________________
1644 \subsection*
{\phantomsection%
1645 2.21~~~Custom Roles
%
1646 \addcontentsline{toc
}{subsection
}{2.21~~~Custom Roles
}%
1647 \label{custom-roles
}%
1652 \item A role based on an existing role.
1654 \texttt{\DUrole{custom
}{one
}} \texttt{\DUrole{custom
}{two
}} \texttt{\DUrole{custom
}{three
}}
1658 \DUrole{customnew
}{one two three
}
1660 \item A role with class attribute.
1662 \DUrole{special
}{interpreted text
}
1664 \item A language-switching role:
1666 Let's count in German
\otherlanguage{ngerman}{eins zwei drei
}.
1668 \item A role with multiple class attributes, styled with raw directives:
1670 \newcommand{\DUrolegreen}[1]{\textcolor{green
}{#1}}
1671 \newcommand{\DUrolesc}[1]{\textsc{#1}}
1673 The following works in most browsers but does not validate
1674 (
\texttt{<style>
} is only allowed in the
document head):
1676 \begin{quote
}{\ttfamily \raggedright \noindent
1679 ~~<style~type="text/css"><!-
{}-\\
1680 ~~~.green~\
{color:~green;\
}\\
1681 ~~~.sc~\
{font-variant:~small-caps;\
}\\
1686 \otherlanguage{british
}{\DUrole{green
}{\DUrole{sc
}{British colourful text in small-caps
}}}.
1691 %___________________________________________________________________________
1693 \subsection*
{\phantomsection%
1695 \addcontentsline{toc
}{subsection
}{2.22~~~Mathematics
}%
1696 \label{mathematics
}%
1699 Docutils supports inline math with the prefix or postfix
\texttt{:math:
}
1700 role specificator, $n! +
\sin(x_n^
2)$ and $A_
\text{c
} =
1701 \frac{\pi}{4} d^
2$, as well as displayed math via the
1702 \DUroletitlereference{math
} directive:
1705 f(
\epsilon) =
\frac{1}{1 +
\exp\left(
\frac{\varepsilon}{k_
\text{B
}T
}\right)
}
1707 Content may start on the first line of the directive, e.g.
1710 N =
\frac{\text{number of apples
}}{7}
1712 Equations can be labeled with a reference name using the
\texttt{:name:
} option.
1713 See
\hyperref[eq-m
]{eq:M
} and
\hyperref[eq-schrodinger
]{eq:schrödinger
} below.
1715 The determinant of the matrix
1718 \mathbf{M
} =
\left(
\begin{matrix
}a&b\
\c&d
\end{matrix
}\right)
1722 is $|
\mathbf{M
}| = ad - bc$.
1724 More than one display math block can be put in one math directive.
1725 For example, the following sum and integral with limits:
1728 \int_0^
1 x^n dx =
\frac{1}{n +
1}
1731 \sum_{n=
1}^m n =
\frac{m(m+
1)
}{2}
1733 LaTeX-supported Unicode math symbols can be used in math roles and
1736 The Schrödinger equation
1739 i
\hbar \frac{\partial }{\partial t
}\Psi =
\hat{H
}\Psi ,
1741 \label{eq-schrodinger
}
1743 with the
\emph{wave function
} $
\Psi $, describes how the quantum state of a
1744 physical system changes in time.
1747 \item[{Math-Accents:
}] \leavevmode
1748 \setlength{\DUtablewidth}{\linewidth}
1749 \begin{longtable*
}[c
]{p
{0.315\DUtablewidth}p
{0.315\DUtablewidth}p
{0.315\DUtablewidth}}
1751 $
\acute{a
}$
\texttt{\textbackslash{}acute\
{a\
}}
1753 $
\dot{t
}$
\texttt{\textbackslash{}dot\
{t\
}}
1755 $
\hat{\gamma}$
\texttt{\textbackslash{}hat\
{\textbackslash{}gamma\
}}
1758 $
\grave{a
}$
\texttt{\textbackslash{}grave\
{a\
}}
1760 $
\ddot{t
}$
\texttt{\textbackslash{}ddot\
{t\
}}
1762 $
\tilde{\alpha}$
\texttt{\textbackslash{}tilde\
{\textbackslash{}alpha\
}}
1765 $
\breve{x
}$
\texttt{\textbackslash{}breve\
{x\
}}
1767 $
\dddot{t
}$
\texttt{\textbackslash{}dddot\
{t\
}}
1769 $
\vec{\imath}$
\texttt{\textbackslash{}vec\
{\textbackslash{}imath\
}}
1772 $
\check{a
}$
\texttt{\textbackslash{}check\
{a\
}}
1774 $
\bar{a
}$
\texttt{\textbackslash{}bar\
{a\
}}
1776 $
\vec{R
}$
\texttt{\textbackslash{}vec\
{R\
}}
1785 Modulation Transfer Function:
1788 \text{MTF
} =
\left|
\frac{\mathcal{F
}\
{s(x)\
}}
1789 {\mathcal{F
}\
{ s(x)\
} |_
{\omega _
{x
}=
0}}\right|
1790 =
\mathrm{abs
}\left(
\frac
1791 {\int _
{-
\infty }^
{\infty }s(x)
\mathrm{e
}^
{\mathrm{i
}\omega _
{x
}x
}\mathrm{d
}{x
}}
1792 {\int _
{-
\infty }^
{\infty }s(x)
\mathrm{d
}{x
}}
1795 Math split over two lines: If a double backslash is detected outside a
1796 \texttt{\textbackslash{}begin\
{...\
} \textbackslash{}end\
{...\
}} pair, the math code is wrapped in an
\href{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
}{AMSmath
}\DUfootnotemark{id36
}{id35
}{7}
1797 \texttt{align
} environment:
1800 s_
{\mathrm{out
}}(x) & = s_
{\mathrm{in
}}(x') * s_
\delta (x-x') \\
1801 & =
\int s_
{\mathrm{in
}}(x')s_
\delta (x-x')
\mathrm{d
}x'
1803 Cases (``manually'', with
\texttt{matrix
} environment):
1806 \mathrm{sgn
}(x) =
\left\
{\begin{matrix
}
1811 Cases with the
\href{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
}{AMSmath
}\DUfootnotemark{id37
}{id35
}{7} \texttt{cases
} environment (not (yet) supported by
1812 HTML writers with
\texttt{-
{}-math-output=MathML
}):
1815 \mathrm{sgn
}(x) =
\begin{cases
}
1821 %___________________________________________________________________________
1823 \section*
{\phantomsection%
1824 3~~~Tests for the LaTeX writer
%
1825 \addcontentsline{toc
}{section
}{3~~~Tests for the LaTeX writer
}%
1826 \label{tests-for-the-latex-writer
}%
1829 Test syntax elements which may cause trouble for the LaTeX writer but might
1830 not need to be tested with other writers (e.g. the HTML writer).
1833 %___________________________________________________________________________
1835 \subsection*
{\phantomsection%
1836 3.1~~~Custom Roles in LaTeX
%
1837 \addcontentsline{toc
}{subsection
}{3.1~~~Custom Roles in LaTeX
}%
1838 \label{custom-roles-in-latex
}%
1843 \item Role names and class arguments are converted to conform to the
1844 regular expression
\texttt{{[}a-z
{]}{[}-a-z0-
9{]}*
} (letters are downcased,
1845 accents and similar decoration is stripped, non-conforming
1846 characters are replaced by a hyphen).
1848 Class arguments may contain numbers and hyphens, which need special
1849 treatment in LaTeX command names.
1851 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}}
1853 \item With LaTeX, roles can be styled within the
document using the
\DUroletitlereference{raw
}
1856 \newcommand{\DUrolelarge}[1]{{\large #1}}
1858 \@namedef
{DUrolesmall-caps
}{\textsc}
1859 \@namedef
{DUrolecustom4
}{\textbf}
1862 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}} in large, bold, small-caps.
1864 \item Custom roles can be based on standard roles:
1866 This is a
\emph{\DUrole{custom-emphasis
}{customized emphasis text role
}}
1868 This is a
\texttt{\DUrole{custom-literal
}{customized literal text role
}}
1870 This is a
\textbf{\DUrole{custom-strong
}{customized strong text role
}}
1872 This is a
\textsubscript{\DUrole{custom-subscript
}{customized subscript text role
}}
1874 This is a
\textsuperscript{\DUrole{custom-superscript
}{customized superscript text role
}}
1876 This is a
\DUroletitlereference{\DUrole{custom-title-reference
}{customized title-reference text role
}}
1881 %___________________________________________________________________________
1883 \subsection*
{\phantomsection%
1885 \addcontentsline{toc
}{subsection
}{3.2~~~More Tables
}%
1886 \label{more-tables
}%
1889 A multicolumn table with multi-paragraph rowspanning cells:
1891 \setlength{\DUtablewidth}{\linewidth}
1892 \begin{longtable*
}[c
]{|p
{0.133\DUtablewidth}|p
{0.179\DUtablewidth}|p
{0.179\DUtablewidth}|p
{0.110\DUtablewidth}|p
{0.121\DUtablewidth}|p
{0.145\DUtablewidth}|
}
1898 &
\multicolumn{3}{p
{0.41\DUtablewidth}|
}{
1901 With a second paragraph
1906 \multicolumn{2}{|p
{0.31\DUtablewidth}|
}{
1909 With a second paragraph
1922 &
\multicolumn{2}{p
{0.36\DUtablewidth}|
}{
1923 multicolumn
3 (one line,
1924 but very very very very
1940 &
\multicolumn{3}{p
{0.38\DUtablewidth}|
}{
1946 % This file is used by the standalone_rst_latex test.
1949 %___________________________________________________________________________
1951 \subsection*
{\phantomsection%
1953 \addcontentsline{toc
}{subsection
}{3.3~~~Option lists
}%
1957 The LaTeX-
2e description environment is used for definition lists.
1958 The definition is continued on the same line as the term, this should
1959 not happen if a option-list is at the top of the definition.
1961 If the option list is not at the first element in the definition, it
1962 is contained in a quote
1966 \begin{DUoptionlist
}
1968 \item[-
{}-help
] show help
1977 \item[{In a definition list:
}] \leavevmode %
1978 \begin{DUoptionlist
}
1980 \item[-
{}-help
] show help
1989 %___________________________________________________________________________
1991 \subsection*
{\phantomsection%
1992 3.4~~~Monospaced non-alphanumeric characters
%
1993 \addcontentsline{toc
}{subsection
}{3.4~~~Monospaced non-alphanumeric characters
}%
1994 \label{monospaced-non-alphanumeric-characters
}%
1997 These are all ASCII characters except a-zA-Z0-
9 and space:
1999 \texttt{!!!"
{}"
{}"\#\#\#\$\$\$\%\%\%\&\&\&'
{}'
{}'((()))***+++,
{},
{},-
{}-
{}-...///:::
}
2001 \texttt{;;;<
{}<
{}<===>
{}>
{}>???@@@
{[}{[}{[}\textbackslash{}\textbackslash{}\textbackslash{}{]}{]}{]}\textasciicircum{}\textasciicircum{}\textasciicircum{}\_\_\_`
{}`
{}`\
{\
{\
{|||\
}\
}\
}\textasciitilde{}\textasciitilde{}\textasciitilde{}}
2003 \texttt{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
2005 The two lines of non-alphanumeric characters should both have the same
2006 width as the third line.
2009 %___________________________________________________________________________
2011 \subsection*
{\phantomsection%
2012 3.5~~~Non-ASCII characters
%
2013 \addcontentsline{toc
}{subsection
}{3.5~~~Non-ASCII characters
}%
2014 \label{non-ascii-characters
}%
2017 Punctuation and footnote symbols
2019 \setlength{\DUtablewidth}{\linewidth}
2020 \begin{longtable*
}[c
]{|p
{0.028\DUtablewidth}|p
{0.424\DUtablewidth}|
}
2037 single turned comma quotation mark
2043 single comma quotation mark
2049 low single comma quotation mark
2055 double turned comma quotation mark
2061 double comma quotation mark
2067 low double comma quotation mark
2121 left-right double arrow
2126 The
\DUroletitlereference{Latin-
1 extended
} Unicode block
2128 \setlength{\DUtablewidth}{\linewidth}
2129 \begin{longtable*
}[c
]{|p
{0.051\DUtablewidth}|p
{0.028\DUtablewidth}|p
{0.028\DUtablewidth}|p
{0.028\DUtablewidth}|p
{0.028\DUtablewidth}|p
{0.028\DUtablewidth}|p
{0.028\DUtablewidth}|p
{0.028\DUtablewidth}|p
{0.028\DUtablewidth}|p
{0.028\DUtablewidth}|p
{0.028\DUtablewidth}|
}
2387 \item The following line should not be wrapped, because it uses
2388 no-break spaces (
\textbackslash{}u00a0):
2390 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
2392 \item Line wrapping with/without breakpoints marked by soft hyphens
2393 (
\textbackslash{}u00ad):
2395 pdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-sch
2397 pdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrisch
2399 \item The currency sign (
\textbackslash{}u00a4) is not supported by all fonts
2400 (some have an Euro sign at its place). You might see an error
2403 \begin{quote
}{\ttfamily \raggedright \noindent
2404 !~Package~textcomp~Error:~Symbol~
\textbackslash{}textcurrency~not~provided~by\\
2405 (textcomp)~~~~~~~~~~~~~~~~font~family~ptm~in~TS1~encoding.\\
2406 (textcomp)~~~~~~~~~~~~~~~~Default~family~used~instead.
2410 (which in case of font family ptm is a false positive). Add either
2414 turn the error in a warning, use the default symbol (bitmap), or
2416 \item[{force,almostfull:
}]
2417 use the symbol provided by the font at the users
2422 to the
document options or use a different font package.
2427 %___________________________________________________________________________
2429 \subsection*
{\phantomsection%
2430 3.6~~~Encoding special chars
%
2431 \addcontentsline{toc
}{subsection
}{3.6~~~Encoding special chars
}%
2432 \label{encoding-special-chars
}%
2435 The LaTeX Info pages lists under ``
2.18 Special Characters''
2439 The following characters play a special role in LaTeX and are called
2440 ``special printing characters'', or simply ``special characters''.
2444 \# \$ \% \&
\textasciitilde{} \_ \textasciicircum{} \textbackslash{} \
{ \
}
2450 The special chars verbatim:
2452 \begin{quote
}{\ttfamily \raggedright \noindent
2453 \#~\$~\%~\&~
\textasciitilde{}~
\_~
\textasciicircum{}~
\textbackslash{}~\
{~\
}
2457 However also
\emph{square brackets
} {[}{]} need special care.
2461 item and all the other commands with optional arguments check
2462 if the token right after the macro name is an opening bracket.
2463 In that case the contents between that bracket and the following
2464 closing bracket on the same grouping level are taken as the
2465 optional argument. What makes this unintuitive is the fact that
2466 the square brackets aren't grouping characters themselves, so in
2467 your last example item
{[}{[}...
{]}{]} the optional argument consists of
2468 {[}... (without the closing bracket).
2472 Compare the items in the following lists:
2478 \item {[}bracketed
{]} item
2483 \item[{simple
}] \leavevmode
2486 \item[{{[}bracketed
{]}}] \leavevmode
2491 The OT1 font-encoding has different characters for the less-than,
2492 greater-than and bar, < | >, except for typewriter font
\DUroletitlereference{cmtt
}:
2494 \begin{quote
}{\ttfamily \raggedright \noindent
2500 %___________________________________________________________________________
2502 \subsection*
{\phantomsection%
2503 3.7~~~Hyperlinks and -targets
%
2504 \addcontentsline{toc
}{subsection
}{3.7~~~Hyperlinks and -targets
}%
2505 \label{hyperlinks-and-targets
}%
2508 In LaTeX, we must set an explicit anchor (
\texttt{\textbackslash{}phantomsection
}) for a
2510 \phantomsection\label{hypertarget-in-plain-text
}hypertarget in plain text or in a figure but not in a longtable or
2513 \setlength{\DUtablewidth}{\linewidth}
2514 \begin{longtable
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
2515 \caption{Table with
%
2516 \label{hypertarget-in-table-title
}hypertarget in table title.
}\\
2529 \phantomsection\label{figure-label
}
2530 \noindent\makebox[\textwidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
2531 \caption{Figure with
%
2532 \label{hypertarget-in-figure-caption
}hypertarget in figure caption.
}
2535 \phantomsection\label{hypertarget-in-figure-legend
}hypertarget in figure legend.
2539 \includegraphics{../../../docs/user/rst/images/biohazard.png
}
2540 \phantomsection\label{image-label
}
2542 See
\hyperref[hypertarget-in-plain-text
]{hypertarget in plain text
},
2543 \hyperref[table-label
]{table label
},
\hyperref[hypertarget-in-table-title
]{hypertarget in table title
},
2544 \hyperref[figure-label
]{figure label
},
\hyperref[hypertarget-in-figure-caption
]{hypertarget in figure caption
},
2545 \hyperref[hypertarget-in-figure-legend
]{hypertarget in figure legend
}, and
2546 \hyperref[image-label
]{image label
}.
2549 %___________________________________________________________________________
2551 \subsection*
{\phantomsection%
2552 3.8~~~External references
%
2553 \addcontentsline{toc
}{subsection
}{3.8~~~External references
}%
2554 \label{external-references
}%
2557 Long URLs should be wrapped in the PDF.
2558 This can be achieved with the url command which is used by the LaTeX writer
2559 wheneve the content (name) of a reference node equals the link URL.
2562 \item[{Example:
}] \leavevmode
2563 a long URL that should wrap in the output
2564 \url{http://docutils.sourceforge.net/docs/user/latex.html\#id79
}
2568 If the argument contains any ``\%'', ``\#'', or ``
\textasciicircum{}\textasciicircum{}'', or ends with
\texttt{\textbackslash{}}, it can't
2569 be used in the argument to another command. The argument must not contain
2572 The characters
\textasciicircum{}, \
{, \
}, and
\texttt{\textbackslash{}} are invalid in a ``http:'' or ``ftp:'' URL
2573 and not recognized as part of it:
2575 \begin{DUlineblock
}{0em
}
2576 \item[] \url{http://www.example.org
}/strange
\textasciicircum{}\textasciicircum{}name
2577 \item[] \url{http://www.example.org
}\textbackslash{}using
\textbackslash{}DOS
\textbackslash{}paths
\textbackslash{}
2578 \item[] \url{http://www.example.org/XML
}/strange\
{n\
}ame
2581 They can, however be used in paths and/or filenames.
2583 Handling by the LaTeX writer:
2587 \item \texttt{\#
},
\texttt{\textbackslash{}} and
\texttt{\%
} are escaped:
2589 \begin{DUlineblock
}{0em
}
2590 \item[] \href{http://www.w3.org/XML/Schema\#dev
}{URL with \#
}
2591 \url{http://www.w3.org/XML/Schema\#dev
}
2592 \item[] \href{http://www.w3.org/XML/Schema\%dev
}{URL with \%
}
2593 \url{http://example.org/Schema\%dev
}
2594 \item[] \href{A:DOS\
\path\\
}{file with DOS path
}\DUfootnotemark{id42
}{id41
}{9} \url{A:DOS\
\path\\
}\DUfootnotemark{id43
}{id41
}{9}
2597 \DUadmonition[note
]{
2598 \DUtitle[note
]{Note
}
2600 These URLs are typeset inside a LaTeX command without error.
2602 \begin{DUlineblock
}{0em
}
2603 \item[] \url{http://www.w3.org/XML/Schema\#dev
}
2604 \item[] \url{http://example.org/Schema\%dev
}
2605 \item[] \url{A:DOS\
\path\\
}\DUfootnotemark{id44
}{id41
}{9}
2613 \item \textasciicircum{}\textasciicircum{} LaTeX's special syntax for characters results in ``strange'' replacements
2614 (both with href and url). A warning is given.
2616 \href{../strange^^name
}{file with
\textasciicircum{}\textasciicircum{}}:
2617 \url{../strange^^name
}
2619 \item Unbalanced braces, \
{ or \
}, will fail (both with href and url):
2621 \begin{quote
}{\ttfamily \raggedright \noindent
2622 `file~with~\
{~<../strange\
{name>`
\_\_\\
2623 `<../strange\
{name>`
\_\_
2627 while balanced braces are suported:
2629 \begin{DUlineblock
}{0em
}
2630 \item[] \url{../strange
{n
}ame
}
2631 \item[] \url{../st
{r
}ange
{n
}ame
}
2632 \item[] \url{../
{st
{r
}ange
{n
}ame
}}
2637 % unusual combinations (from newlatex, for interactive testing)
2638 % .. include:: data/latex.txt
2640 % Preface for System Messages:
2643 %___________________________________________________________________________
2645 \section*
{\phantomsection%
2647 \addcontentsline{toc
}{section
}{4~~~Error Handling
}%
2648 \label{error-handling
}%
2651 Any errors caught during processing will generate system messages.
2653 There should be five messages in the following, auto-generated
2654 section, ``Docutils System Messages'':
2656 % section should be added by Docutils automatically
2659 %___________________________________________________________________________
2661 \section*
{\phantomsection%
2662 \color{red
}Docutils System Messages
%
2663 \addcontentsline{toc
}{section
}{Docutils System Messages
}%
2666 \DUadmonition[system-message
]{
2667 \DUtitle[system-message
]{system-message
}
2668 \raisebox{1em
}{\hypertarget{id27
}{}}
2670 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
104
2673 Undefined substitution referenced: ``problematic''.
2676 \DUadmonition[system-message
]{
2677 \DUtitle[system-message
]{system-message
}
2678 \raisebox{1em
}{\hypertarget{id45
}{}}
2680 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
391
2683 Unknown target name: ``
5''.
2686 \DUadmonition[system-message
]{
2687 \DUtitle[system-message
]{system-message
}
2688 \raisebox{1em
}{\hypertarget{id47
}{}}
2690 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
400
2693 Unknown target name: ``nonexistent''.
2696 \DUadmonition[system-message
]{
2697 \DUtitle[system-message
]{system-message
}
2698 \raisebox{1em
}{\hypertarget{id49
}{}}
2700 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
427
2703 Unknown target name: ``hyperlink reference without a target''.
2706 \DUadmonition[system-message
]{
2707 \DUtitle[system-message
]{system-message
}
2708 \raisebox{1em
}{\hypertarget{id51
}{}}
2710 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
440
2713 Duplicate target name, cannot be used as a unique reference: ``duplicate target names''.