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 \setcounter{secnumdepth
}{0}
20 \usepackage{longtable,ltcaption,array
}
21 \setlength{\extrarowheight}{2pt
}
22 \newlength{\DUtablewidth} % internal use in tables
24 \usepackage{textcomp
} % text symbol macros
26 %%% Custom LaTeX preamble
28 \usepackage{mathptmx
} % Times
29 \usepackage[scaled=
.90]{helvet
}
32 %%% User specified packages and stylesheets
34 %%% Fallback definitions for Docutils-specific commands
36 % providelength (provide a length variable and set default, if it is new)
37 \providecommand*
{\DUprovidelength}[2]{
38 \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{}
42 \providecommand*
{\DUtitleabstract}[1]{\centering\textbf{#1}}
44 % admonition (specially marked topic)
45 \providecommand{\DUadmonition}[2][class-arg
]{%
46 % try \DUadmonition#1{#2}:
47 \ifcsname DUadmonition
#1\endcsname%
48 \csname DUadmonition
#1\endcsname{#2}%
51 \fbox{\parbox{0.9\linewidth}{#2}}
57 \@namedef
{DUrolealign-center
}{\centering}
62 \providecommand{\DUtopicdedication}[1]{\begin{center
}#1\end{center
}}
64 % docinfo (width of docinfo table)
65 \DUprovidelength{\DUdocinfowidth}{0.9\linewidth}
67 % subtitle (in document title)
68 \providecommand*
{\DUdocumentsubtitle}[1]{{\large #1}}
70 % error admonition title
71 \providecommand*
{\DUtitleerror}[1]{\DUtitle{\color{red
}#1}}
73 % fieldlist environment
74 \ifthenelse{\isundefined{\DUfieldlist}}{
75 \newenvironment{DUfieldlist
}%
77 {\enddescription\endquote}
79 % numeric or symbol footnotes with hyperlinks
80 \providecommand*
{\DUfootnotemark}[3]{%
81 \raisebox{1em
}{\hypertarget{#1}{}}%
82 \hyperlink{#2}{\textsuperscript{#3}}%
84 \providecommand{\DUfootnotetext}[4]{%
86 \renewcommand{\thefootnote}{%
87 \protect\raisebox{1em
}{\protect\hypertarget{#1}{}}%
88 \protect\hyperlink{#2}{#3}}%
93 % inline markup (custom roles)
94 % \DUrole{#1}{#2} tries \DUrole#1{#2}
95 \providecommand*
{\DUrole}[2]{%
96 \ifcsname DUrole
#1\endcsname%
97 \csname DUrole
#1\endcsname{#2}%
98 \else% backwards compatibility: try \docutilsrole#1{#2}
99 \ifcsname docutilsrole
#1\endcsname%
100 \csname docutilsrole
#1\endcsname{#2}%
108 \ifthenelse{\isundefined{\DUlegend}}{
109 \newenvironment{DUlegend
}{\small}{}
112 % lineblock environment
113 \DUprovidelength{\DUlineblockindent}{2.5em
}
114 \ifthenelse{\isundefined{\DUlineblock}}{
115 \newenvironment{DUlineblock
}[1]{%
116 \list{}{\setlength{\partopsep}{\parskip}
117 \addtolength{\partopsep}{\baselineskip}
118 \setlength{\topsep}{0pt
}
119 \setlength{\itemsep}{0.15\baselineskip}
120 \setlength{\parsep}{0pt
}
121 \setlength{\leftmargin}{#1}}
127 % optionlist environment
128 \providecommand*
{\DUoptionlistlabel}[1]{\bf #1 \hfill}
129 \DUprovidelength{\DUoptionlistindent}{3cm
}
130 \ifthenelse{\isundefined{\DUoptionlist}}{
131 \newenvironment{DUoptionlist
}{%
132 \list{}{\setlength{\labelwidth}{\DUoptionlistindent}
133 \setlength{\rightmargin}{1cm
}
134 \setlength{\leftmargin}{\rightmargin}
135 \addtolength{\leftmargin}{\labelwidth}
136 \addtolength{\leftmargin}{\labelsep}
137 \renewcommand{\makelabel}{\DUoptionlistlabel}}
142 % rubric (informal heading)
143 \providecommand*
{\DUrubric}[2][class-arg
]{%
144 \subsubsection*
{\centering\textit{\textmd{#2}}}}
146 % sidebar (text outside the main text flow)
147 \providecommand{\DUsidebar}[2][class-arg
]{%
149 \colorbox[gray
]{0.80}{\parbox{0.9\linewidth}{#2}}
153 % subtitle (for topic/sidebar)
154 \providecommand*
{\DUsubtitle}[2][class-arg
]{\par\emph{#2}\smallskip}
156 % title for topics, admonitions, unsupported section levels, and sidebar
157 \providecommand*
{\DUtitle}[2][class-arg
]{%
158 % call \DUtitle#1{#2} if it exists:
159 \ifcsname DUtitle
#1\endcsname%
160 \csname DUtitle
#1\endcsname{#2}%
162 \smallskip\noindent\textbf{#2}\smallskip%
166 % titlereference role
167 \providecommand*
{\DUroletitlereference}[1]{\textsl{#1}}
169 % topic (quote with heading)
170 \providecommand{\DUtopic}[2][class-arg
]{%
171 \ifcsname DUtopic
#1\endcsname%
172 \csname DUtopic
#1\endcsname{#2}%
174 \begin{quote
}#2\end{quote
}
178 % transition (break, fancybreak, anonymous section)
179 \providecommand*
{\DUtransition}[1][class-arg
]{%
180 \hspace*
{\fill}\hrulefill\hspace*
{\fill}
181 \vskip 0.5\baselineskip
185 \ifthenelse{\isundefined{\hypersetup}}{
186 \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue
]{hyperref
}
187 \urlstyle{same
} % normal text font (alternatives: tt, rm, sf)
190 pdftitle=
{reStructuredText Test Document
},
191 pdfauthor=
{David Goodger;Me;Myself;I
}
195 \title{\phantomsection%
196 reStructuredText Test Document
%
197 \label{restructuredtext-test-
document}%
200 \DUdocumentsubtitle{Examples of Syntax Constructs
}%
201 \label{examples-of-syntax-constructs
}%
212 \begin{tabularx
}{\DUdocinfowidth}{lX
}
221 \href{mailto:goodger@python.org
}{goodger@python.org
} \\
228 \textbf{Organization
}: &
231 Now, or yesterday. Or maybe even
\emph{before
} yesterday. \\
233 This is a “work in progress” \\
235 is managed by a version control system. \\
238 \textbf{Copyright
}: &
239 This
document has been placed in the public domain. You
240 may do with it as you wish. You may copy, modify,
241 redistribute, reattribute, sell, buy, rent, lease,
242 destroy, or improve it, quote it at length, excerpt,
243 incorporate, collate, fold, staple, or mutilate it, or do
244 anything else to it that your or anyone else’s heart
246 \textbf{field name
}: &
247 This is a “generic bibliographic field”.
249 \textbf{field name “
2”
}: &
250 Generic bibliographic fields may contain multiple body elements.
257 \DUtopic[dedication
]{
258 \DUtitle[dedication
]{Dedication
}
260 For Docutils users \& co-developers.
264 \DUtitle[abstract
]{Abstract
}
266 This is a test
document, containing at least one example of each
267 reStructuredText construct.
270 % This is a comment. Note how any initial comments are moved by
271 % transforms to after the document title, subtitle, and docinfo.
273 % Above is the document title, and below is the subtitle.
274 % They are transformed from section titles after parsing.
276 % bibliographic fields (which also require a transform):
278 \pagebreak[4] % start ToC on new page
280 \phantomsection\label{table-of-contents
}
281 \pdfbookmark[1]{Table of Contents
}{table-of-contents
}
282 \renewcommand{\contentsname}{Table of Contents
}
287 \section{1~~~Structural Elements
%
288 \label{structural-elements
}%
292 \subsection{1.1~~~Section Title
%
293 \label{section-title
}%
295 \subsubsection*
{Section Subtitle
}
297 Lone subsections are converted to a section subtitle by a transform
298 activated with the
\texttt{-
{}-section-subtitles
} command line option or the
299 \texttt{sectsubtitle-xform
} configuration value.
302 \subsection{1.2~~~Empty Section
%
303 \label{empty-section
}%
307 \subsection{1.3~~~Transitions
%
314 %___________________________________________________________________________
318 It divides the section. Transitions may also occur between sections:
321 %___________________________________________________________________________
326 \section{2~~~Body Elements
%
327 \label{body-elements
}%
331 \subsection{2.1~~~Paragraphs
%
338 \subsubsection{2.1.1~~~Inline Markup
%
339 \label{inline-markup
}%
342 Paragraphs contain text and may contain inline markup:
\emph{emphasis
},
343 \textbf{strong emphasis
},
\texttt{inline literals
}, standalone hyperlinks
344 (
\url{http://www.python.org
}), external hyperlinks (
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id30
}{id29
}{5}), internal
345 cross-references (
\hyperref[example
]{example
}), external hyperlinks with embedded URIs
346 (
\href{http://www.python.org
}{Python web site
}),
\href{http://www.python.org/
}{anonymous hyperlink
347 references
}\DUfootnotemark{id38
}{id29
}{5} (
\href{http://docutils.sourceforge.net/
}{a second reference
}\DUfootnotemark{id40
}{id39
}{8}), footnote references (manually
348 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
]}),
349 substitution references (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}), and
%
350 \phantomsection\label{inline-hyperlink-targets
}inline hyperlink targets
351 (see
\hyperref[targets
]{Targets
} below for a reference back to here). Character-level
352 inline markup is also possible (although exceedingly ugly!) in
\emph{re
}\texttt{Structured
}\emph{Text
}. Problems are indicated by
%
353 \raisebox{1em
}{\hypertarget{id28
}{}}\hyperlink{id27
}{\textbf{\color{red
}|problematic|
}} text
354 (generated by processing errors; this one is intentional). Here is a
355 reference to the
\hyperref[doctitle
]{doctitle
} and the
\hyperref[subtitle
]{subtitle
}.
357 The default role for interpreted text is
\DUroletitlereference{Title Reference
}. Here are
358 some explicit interpreted text roles: a PEP reference (
\href{http://www.python.org/dev/peps/pep-
0287}{PEP
287}); an
359 RFC reference (
\href{http://tools.ietf.org/html/rfc2822.html
}{RFC
2822}); an abbreviation (
\DUrole{abbreviation
}{abb.
}), an acronym
360 (
\DUrole{acronym
}{reST
}), code (
\texttt{\DUrole{code
}{print
\textquotedbl{}hello world
\textquotedbl{}}}); a
\textsubscript{subscript
};
361 a
\textsuperscript{superscript
} and explicit roles for
\DUroletitlereference{Docutils
}’
362 \emph{standard
} \textbf{inline
} \texttt{markup
}.
364 % DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
366 Let’s test wrapping and whitespace significance in inline literals:
367 \texttt{This is an example of -
{}-inline-literal -
{}-text, -
{}-including some-
{}-
368 strangely-
{}-hyphenated-words. ~Adjust-the-width-of-your-browser-window
369 to see how the text is wrapped. ~-
{}- -
{}-
{}-
{}- -
{}-
{}-
{}-
{}-
{}-
{}-
{}- ~Now note ~ ~the
370 spacing ~ ~between the ~ ~words of ~ ~this sentence ~ ~(words
371 should ~ ~be grouped ~ ~in pairs).
}
373 If the
\texttt{-
{}-pep-references
} option was supplied, there should be a
374 live link to PEP
258 here.
377 \subsection{2.2~~~Bullet Lists
%
378 \label{bullet-lists
}%
387 \item Nested bullet list.
395 Paragraph
2 of item
2.
399 \item Nested bullet list.
413 \item This nested list should be compacted by the HTML writer.
415 \phantomsection\label{target
}
416 % Even if this item contains a target and a comment.
423 \subsection{2.3~~~Enumerated Lists
%
424 \label{enumerated-lists
}%
426 \newcounter{listcnt0
}
427 \begin{list
}{\arabic{listcnt0
}.
}
429 \usecounter{listcnt0
}
430 \setlength{\rightmargin}{\leftmargin}
433 \item Arabic numerals.
434 \newcounter{listcnt1
}
435 \begin{list
}{\alph{listcnt1
})
}
437 \usecounter{listcnt1
}
438 \setlength{\rightmargin}{\leftmargin}
442 \newcounter{listcnt2
}
443 \begin{list
}{(
\roman{listcnt2
})
}
445 \usecounter{listcnt2
}
446 \setlength{\rightmargin}{\leftmargin}
450 \newcounter{listcnt3
}
451 \begin{list
}{\Alph{listcnt3
}.
}
453 \usecounter{listcnt3
}
454 \setlength{\rightmargin}{\leftmargin}
458 \newcounter{listcnt4
}
459 \begin{list
}{\Roman{listcnt4
})
}
461 \usecounter{listcnt4
}
462 \setlength{\rightmargin}{\leftmargin}
471 \item Lists that don’t start at
1:
472 \setcounter{listcnt1
}{0}
473 \begin{list
}{\arabic{listcnt1
}.
}
475 \usecounter{listcnt1
}
476 \addtocounter{listcnt1
}{2}
477 \setlength{\rightmargin}{\leftmargin}
484 \setcounter{listcnt1
}{0}
485 \begin{list
}{\Alph{listcnt1
}.
}
487 \usecounter{listcnt1
}
488 \addtocounter{listcnt1
}{2}
489 \setlength{\rightmargin}{\leftmargin}
496 \setcounter{listcnt1
}{0}
497 \begin{list
}{\roman{listcnt1
}.
}
499 \usecounter{listcnt1
}
500 \addtocounter{listcnt1
}{2}
501 \setlength{\rightmargin}{\leftmargin}
511 \subsection{2.4~~~Definition Lists
%
512 \label{definition-lists
}%
516 \item[{Term
}] \leavevmode
519 \item[{Term
}] \leavevmode (
\textbf{classifier
})
521 Definition paragraph
1.
523 Definition paragraph
2.
525 \item[{Term
}] \leavevmode
528 \item[{Term
}] \leavevmode (
\textbf{classifier one
})
529 (
\textbf{classifier two
})
536 \subsection{2.5~~~Field Lists
%
542 Field lists map field names to field bodies, like database
543 records. They are often part of an extension syntax. They are
544 an unambiguous variant of RFC
2822 fields.
546 \item[{how arg1 arg2:
}]
547 The field marker is a colon, the field name, and a colon.
549 The field body may contain one or more body elements, indented
550 relative to the field marker.
553 \DUrole{credits
}{This paragraph has the
\DUroletitlereference{credits
} class set. (This is actually not
554 about credits but just for ensuring that the class attribute
555 doesn’t get stripped away.)
}
560 \subsection{2.6~~~Option Lists
%
561 \label{option-lists
}%
564 For listing command-line options:
568 \item[-a
] command-line option “a”
570 \item[-b file
] options can have arguments
571 and long descriptions
573 \item[-
{}-long
] options can be long also
575 \item[-
{}-input=file
] long options can also have
578 \item[-
{}-very-long-option
] The description can also start on the next line.
580 The description may contain multiple body elements,
581 regardless of where it starts.
583 \item[-x, -y, -z
] Multiple options are an “option group”.
585 \item[-v, -
{}-verbose
] Commonly-seen: short \& long options.
587 \item[-
1 file, -
{}-one=file, -
{}-two file
] Multiple options with arguments.
589 \item[/V
] DOS/VMS-style options too
593 There must be at least two spaces between the option and the
597 \subsection{2.7~~~Literal Blocks
%
598 \label{literal-blocks
}%
601 Literal blocks are indicated with a double-colon (“::”) at the end of
602 the preceding paragraph (over there
\texttt{-
{}->
}). They can be indented:
604 \begin{quote
}{\ttfamily \raggedright \noindent
606 ~~~~text~=~'is~left~as-is'\\
607 ~~~~spaces
\_and\_linebreaks~=~'are~preserved'\\
608 ~~~~markup
\_processing~=~None
612 Or they can be quoted without indentation:
614 \begin{quote
}{\ttfamily \raggedright \noindent
617 >~Why~didn't~I~think~of~that?
622 \subsection{2.8~~~Line Blocks
%
626 This section tests line blocks. Line blocks are body elements which
627 consist of lines and other line blocks. Nested line blocks cause
630 \begin{DUlineblock
}{0em
}
631 \item[] This is a line block. It ends with a blank line.
633 \begin{DUlineblock
}{\DUlineblockindent}
634 \item[] New lines begin with a vertical bar (“|”).
635 \item[] Line breaks and initial indent are significant, and preserved.
637 \begin{DUlineblock
}{\DUlineblockindent}
638 \item[] Continuation lines are also possible. A long line that is intended
639 to wrap should begin with a space in place of the vertical bar.
641 \item[] The left edge of a continuation line need not be aligned with
642 the left edge of the text above it.
646 \begin{DUlineblock
}{0em
}
647 \item[] This is a second line block.
649 \item[] Blank lines are permitted internally, but they must begin with a “|”.
652 Another line block, surrounded by paragraphs:
654 \begin{DUlineblock
}{0em
}
655 \item[] And it’s no good waiting by the window
656 \item[] It’s no good waiting for the sun
657 \item[] Please believe me, the things you dream of
658 \item[] They don’t fall in the lap of no-one
661 Take it away, Eric the Orchestra Leader!
665 \begin{DUlineblock
}{0em
}
666 \item[] A one, two, a one two three four
668 \item[] Half a bee, philosophically,
670 \begin{DUlineblock
}{\DUlineblockindent}
671 \item[] must,
\emph{ipso facto
}, half not be.
673 \item[] But half the bee has got to be,
675 \begin{DUlineblock
}{\DUlineblockindent}
676 \item[] \emph{vis a vis
} its entity. D’you see?
679 \item[] But can a bee be said to be
681 \begin{DUlineblock
}{\DUlineblockindent}
682 \item[] or not to be an entire bee,
684 \begin{DUlineblock
}{\DUlineblockindent}
685 \item[] when half the bee is not a bee,
687 \begin{DUlineblock
}{\DUlineblockindent}
688 \item[] due to some ancient injury?
698 A line block, like the following poem by Christian Morgenstern, can
699 also be centre-aligned:
701 \begin{DUlineblock
}{0em
}
702 \foreignlanguage{ngerman}{\DUrole{align-center
}{
703 \item[] \textbf{Die Trichter
}
705 \item[] Zwei Trichter wandeln durch die Nacht.
706 \item[] Durch ihres Rumpfs verengten Schacht
707 \item[] fließt weißes Mondlicht
708 \item[] still und heiter
718 \subsection{2.9~~~Block Quotes
%
719 \label{block-quotes
}%
722 Block quotes consist of indented body elements:
726 My theory by A. Elk. Brackets Miss, brackets. This theory goes
727 as follows and begins now. All brontosauruses are thin at one
728 end, much much thicker in the middle and then thin again at the
729 far end. That is my theory, it is mine, and belongs to me and I
730 own it, and what it is too.
733 \raggedleft —Anne Elk (Miss)
737 The language of a quote (like any other object) can be specified by
743 \foreignlanguage{french
}{
744 ReStructuredText est un langage de balisage léger utilisé
745 notamment dans la documentation du langage Python.
750 \subsection{2.10~~~Doctest Blocks
%
751 \label{doctest-blocks
}%
754 \begin{quote
}{\ttfamily \raggedright \noindent
755 >
{}>
{}>~print~'Python-specific~usage~examples;~begun~with~
\textquotedbl{}>
{}>
{}>
\textquotedbl{}'\\
756 Python-specific~usage~examples;~begun~with~
\textquotedbl{}>
{}>
{}>
\textquotedbl{}\\
757 >
{}>
{}>~print~'(cut~and~pasted~from~interactive~Python~sessions)'\\
758 (cut~and~pasted~from~interactive~Python~sessions)
763 \subsection{2.11~~~Footnotes
%
767 \DUfootnotetext{id8
}{id1
}{1}{%
768 A footnote contains body elements, consistently indented by at
771 This is the footnote’s second paragraph.
774 \DUfootnotetext{label
}{id3
}{2}{\phantomsection\label{label
}%
775 Footnotes may be numbered, either manually (as in
\DUfootnotemark{id9
}{id8
}{1}) or
776 automatically using a “\#”-prefixed label. This footnote has a
777 label so it can be referred to from multiple places, both as a
778 footnote reference (
\DUfootnotemark{id10
}{label
}{2}) and as a
\hyperref[label
]{hyperlink reference
}.
781 \DUfootnotetext{id12
}{id2
}{3}{%
782 This footnote is numbered automatically and anonymously using a
785 This is the second paragraph.
787 And this is the third paragraph.
790 \DUfootnotetext{id13
}{id4
}{*
}{%
791 Footnotes may also use symbols, specified with a “*” label.
792 Here’s a reference to the next footnote:
\DUfootnotemark{id14
}{id15
}{†
}.
795 \DUfootnotetext{id15
}{id14
}{†
}{%
796 This footnote shows the next symbol in the sequence.
799 \DUfootnotetext{id16
}{id16
}{4}{%
800 Here’s an unreferenced footnote, with a reference to a
801 nonexistent footnote:
%
802 \raisebox{1em
}{\hypertarget{id46
}{}}%
803 \raisebox{1em
}{\hypertarget{id17
}{}}\hyperlink{id45
}{\textbf{\color{red
}{[}5{]}\_}}.
807 \subsection{2.12~~~Citations
%
810 \begin{figure
}[b
]\raisebox{1em
}{\hypertarget{cit2002
}{}}[CIT2002
]
811 Citations are text-labeled footnotes. They may be
812 rendered separately and differently from footnotes.
815 Here’s a reference to the above,
\hyperlink{cit2002
}{[CIT2002
]}, and a
%
816 \raisebox{1em
}{\hypertarget{id48
}{}}%
817 \raisebox{1em
}{\hypertarget{id19
}{}}\hyperlink{id47
}{\textbf{\color{red
}{[}nonexistent
{]}\_}}
821 \subsection{2.13~~~Targets
%
823 \label{another-target
}%
826 \phantomsection\label{example
}
827 This paragraph is pointed to by the explicit “example” target. A
828 reference can be found under
\hyperref[inline-markup
]{Inline Markup
}, above.
\hyperref[inline-hyperlink-targets
]{Inline
829 hyperlink targets
} are also possible.
831 Section headers are implicit targets, referred to by name. See
832 \hyperref[targets
]{Targets
}, which is a subsection of
\hyperref[body-elements
]{Body Elements
}.
834 Explicit external targets are interpolated into references such as
835 “
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id31
}{id29
}{5}”.
837 Targets may be indirect and anonymous. Thus
\hyperref[targets
]{this phrase
} may also
838 refer to the
\hyperref[targets
]{Targets
} section.
841 \raisebox{1em
}{\hypertarget{id50
}{}}\hyperlink{id49
}{\textbf{\color{red
}`hyperlink reference without a target`
\_}}, which generates an
845 \subsubsection{2.13.1~~~Duplicate Target Names
%
846 \label{duplicate-target-names
}%
849 Duplicate names in section headers or other implicit targets will
850 generate “info” (level-
1) system messages. Duplicate names in
851 explicit targets will generate “warning” (level-
2) system messages.
854 \subsubsection{2.13.2~~~Duplicate Target Names
%
858 Since there are two “Duplicate Target Names” section headers, we
859 cannot uniquely refer to either of them by name. If we try to (like
861 \raisebox{1em
}{\hypertarget{id52
}{}}\hyperlink{id51
}{\textbf{\color{red
}`Duplicate Target Names`
\_}}), an error is generated.
864 \subsection{2.14~~~Directives
%
868 \phantomsection\label{contents
}
869 These are just a sample of the many reStructuredText Directives. For
871 \url{http://docutils.sourceforge.net/docs/ref/rst/directives.html
}.
874 \subsubsection{2.14.1~~~Document Parts
%
875 \label{document-parts
}%
878 An example of the “contents” directive can be seen above this section
879 (a local, untitled table of
\hyperref[contents
]{contents
}) and at the beginning of the
880 document (a
document-wide
\hyperref[table-of-contents
]{table of contents
}).
883 \subsubsection{2.14.2~~~Images and Figures
%
884 \label{images-and-figures
}%
887 An image directive (also clickable – a hyperlink reference):
889 \hyperref[directives
]{\includegraphics{../../../docs/user/rst/images/title.png
}}
891 Image with multiple IDs:
893 \includegraphics{../../../docs/user/rst/images/title.png
}
894 \phantomsection\label{image-target-
3}\label{image-target-
2}\label{image-target-
1}
898 \noindent\makebox[\linewidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
900 A left-aligned image:
902 \noindent{\includegraphics{../../../docs/user/rst/images/biohazard.png
}\hfill}
904 This paragraph might flow around the image.
905 The specific behavior depends upon the style sheet and
906 the browser or rendering software used.
908 A right-aligned image:
910 \noindent{\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
912 This paragraph might flow around the image.
913 The specific behavior depends upon the style sheet and
914 the browser or rendering software used.
916 For inline images see
\hyperref[substitution-definitions
]{Substitution Definitions
}.
922 \includegraphics[width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
924 An image
2 em wide and
15 pixel high:
926 \includegraphics[height=
15px,width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
928 An image occupying
50\% of the line width:
930 \includegraphics[width=
0.500\linewidth]{../../../docs/user/rst/images/title.png
}
934 \includegraphics[height=
2cm
]{../../../docs/user/rst/images/biohazard.png
}
936 A
\emph{figure
} is an image with a caption and/or a legend. With page-based output
937 media, figures might float to a different position if this helps the page
941 \noindent\makebox[\linewidth][c
]{\includegraphics[width=
258bp
]{../../../docs/user/rst/images/title.png
}}
942 \caption{Plaintext markup syntax and parser system.
}
944 \setlength{\DUtablewidth}{\linewidth}
945 \begin{longtable*
}[c
]{|p
{0.156\DUtablewidth}|p
{0.563\DUtablewidth}|
}
950 Revised, revisited, based on ‘re’ module.
956 Structure-enhanced text, structuredtext.
962 Well it is, isn’t it?
967 This paragraph is also part of the legend.
971 A left-aligned figure:
973 \begin{figure
} % align = "left"
974 \noindent\makebox[\linewidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
975 \caption{This is the caption.
}
979 The legend may consist of several paragraphs.
983 This paragraph might flow around the figure.
985 The specific behavior depends upon the style sheet and the browser or
986 rendering software used.
991 \noindent\makebox[\linewidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
992 \caption{This is the caption.
}
996 The legend may consist of several paragraphs.
1000 This paragraph might flow around the figure.
1002 The specific behavior depends upon the style sheet and the browser or
1003 rendering software used.
1005 A right-aligned figure:
1007 \begin{figure
} % align = "right"
1008 \noindent\makebox[\linewidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
1009 \caption{This is the caption.
}
1013 The legend may consist of several paragraphs.
1017 This paragraph might flow around the figure. The specific behavior depends
1018 upon the style sheet and the browser or rendering software used.
1021 \subsubsection{2.14.3~~~Admonitions
%
1022 \label{admonitions
}%
1025 \DUadmonition[attention
]{
1026 \DUtitle[attention
]{Attention!
}
1028 Directives at large.
1031 \DUadmonition[caution
]{
1032 \DUtitle[caution
]{Caution!
}
1034 Don’t take any wooden nickels.
1037 \DUadmonition[danger
]{
1038 \DUtitle[danger
]{!DANGER!
}
1040 Mad scientist at work!
1043 \DUadmonition[error
]{
1044 \DUtitle[error
]{Error
}
1049 \DUadmonition[hint
]{
1050 \DUtitle[hint
]{Hint
}
1052 It’s bigger than a bread box.
1055 \DUadmonition[important
]{
1056 \DUtitle[important
]{Important
}
1060 \item Wash behind your ears.
1062 \item Clean up your room.
1064 \item Call your mother.
1066 \item Back up your data.
1071 \DUadmonition[note
]{
1072 \DUtitle[note
]{Note
}
1080 15\% if the service is good.
1083 \DUadmonition[warning
]{
1084 \DUtitle[warning
]{Warning
}
1086 Strong prose may provoke extreme mental exertion.
1087 Reader discretion is strongly advised.
1090 \DUadmonition[admonition-and-by-the-way
]{
1091 \DUtitle[admonition-and-by-the-way
]{And, by the way…
}
1093 You can make up your own admonition too.
1097 \subsubsection{2.14.4~~~Topics, Sidebars, and Rubrics
%
1098 \label{topics-sidebars-and-rubrics
}%
1101 \emph{Sidebars
} are like miniature, parallel documents.
1104 \DUtitle[title
]{Sidebar Title
}
1106 \DUsubtitle[sidebar
]{Optional Subtitle
}
1108 This is a sidebar. It is for text outside the flow of the main
1111 \DUrubric{This is a rubric inside a sidebar
}
1113 Sidebars often appear beside the main text with a border and a different
1114 background or font
color.
1117 A
\emph{topic
} is like a block quote with a title, or a self-contained section
1118 with no subsections.
1121 \DUtitle[title
]{Topic Title
}
1126 A
\emph{rubric
} is like an informal heading that doesn’t correspond to the
1127 document’s structure. It is typically highlighted in red (hence the name).
1129 \DUrubric{This is a rubric
}
1131 Topics and rubrics can be used at places where a
\hyperref[section-title
]{section title
} is not
1132 allowed (e.g. inside a directive).
1135 \subsubsection{2.14.5~~~Target Footnotes
%
1136 \label{target-footnotes
}%
1139 \DUfootnotetext{id29
}{id30
}{5}{%
1140 \url{http://www.python.org/
}
1143 \DUfootnotetext{id33
}{id34
}{6}{%
1144 \url{http://pygments.org/
}
1147 \DUfootnotetext{id35
}{id36
}{7}{%
1148 \url{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
}
1151 \DUfootnotetext{id39
}{id40
}{8}{%
1152 \url{http://docutils.sourceforge.net/
}
1155 \DUfootnotetext{id41
}{id42
}{9}{%
1160 \subsubsection{2.14.6~~~Replacement Text
%
1161 \label{replacement-text
}%
1164 I recommend you try
\href{http://www.python.org/
}{Python,
\emph{the
} best language around
}\DUfootnotemark{id32
}{id29
}{5}.
1167 \subsubsection{2.14.7~~~Compound Paragraph
%
1168 \label{compound-paragraph
}%
1171 Compound
1, paragraph
1.
1173 Compound
1, paragraph
2.
1177 \item Compound
1, list item one.
1179 \item Compound
1, list item two.
1183 Another compound statement:
1185 Compound
2, a literal block:
1187 \begin{quote
}{\ttfamily \raggedright \noindent
1188 Compound~
2,~literal.
1191 Compound
2, this is a test.
1193 Compound
3, only consisting of one paragraph.
1195 \begin{quote
}{\ttfamily \raggedright \noindent
1197 This~one~starts~with~a~literal~block.
1200 Compound
4, a paragraph.
1202 Now something
\emph{really
} perverted – a nested compound block. This is
1203 just to test that it works at all; the results don’t have to be
1206 Compound
5, block
1 (a paragraph).
1208 Compound
6, block
2 in compound
5.
1210 Compound
6, another paragraph.
1212 Compound
5, block
3 (a paragraph).
1214 Compound
7, with a table inside:
1216 \setlength{\DUtablewidth}{\linewidth}
1217 \begin{longtable*
}[c
]{|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|
}
1239 Compound
7, a paragraph after the table.
1241 Compound
7, another paragraph.
1244 \subsubsection{2.14.8~~~Parsed Literal Blocks
%
1245 \label{parsed-literal-blocks
}%
1248 \begin{quote
}{\ttfamily \raggedright \noindent
1249 This~is~a~parsed~literal~block.\\
1250 ~~~~This~line~is~indented.~~The~next~line~is~blank.\\
1252 Inline~markup~is~supported,~e.g.~
\emph{emphasis
},~
\textbf{strong
},~
\texttt{literal\\
1253 text
},~footnotes
\DUfootnotemark{id22
}{id8
}{1},~
%
1254 \phantomsection\label{hyperlink-targets
}hyperlink~targets,~and~
\href{http://www.python.org/
}{references
}.
1259 \subsubsection{2.14.9~~~Code
%
1263 Blocks of source code can be set with the
\DUroletitlereference{code
} directive. If the code
1264 language is specified, the content is parsed and tagged by the
\href{http://pygments.org/
}{Pygments
}\DUfootnotemark{id34
}{id33
}{6}
1265 syntax highlighter and can be formatted with a style sheet. (Code parsing
1266 is turned off using the
\texttt{syntax-highlight
} config setting in the test
1267 conversions in order to get identical results with/without installed
1268 Pygments highlighter.)
1270 \begin{quote
}{\ttfamily \raggedright \noindent
1271 print~'This~is~Python~code.'
1275 The
\texttt{:number-lines:
} option (with optional start value) generates line
1278 \begin{quote
}{\ttfamily \raggedright \noindent
1279 \DUrole{ln
}{~
8~
}\#~print~integers~from~
0~to~
9:\\
1280 \DUrole{ln
}{~
9~
}for~i~in~range(
10):\\
1281 \DUrole{ln
}{10~
}~~~~print~i
1285 For inline code snippets, there is the
\DUroletitlereference{code
} role, which can be used
1286 directly (the code will not be parsed/tagged, as the language is not known)
1287 or as base for special code roles, e.g. the LaTeX code in the next
1290 Docutils uses LaTeX syntax for math directives and roles:
1291 \texttt{\DUrole{code
}{\DUrole{tex
}{\textbackslash{}alpha = f(x)
}}} prints $
\alpha = f(x)$.
1293 The
\texttt{:code:
} option of the
\DUroletitlereference{include
} directive sets the included content
1294 as a code block, here the rst file
\texttt{header
\_footer.txt
} with line numbers:
1296 \begin{quote
}{\ttfamily \raggedright \noindent
1297 \DUrole{ln
}{1~
}..~header::~Document~header\\
1298 \DUrole{ln
}{2~
}..~footer::~Document~footer
1303 \subsection{2.15~~~Substitution Definitions
%
1304 \label{substitution-definitions
}%
1307 An inline image (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}) example:
1309 (Substitution definitions are not visible in the HTML source.)
1312 \subsection{2.16~~~Comments
%
1318 % Comments begin with two dots and a space. Anything may
1319 % follow, except for the syntax of footnotes, hyperlink
1320 % targets, directives, or substitution definitions.
1322 % Double-dashes -- "--" -- must be escaped somehow in HTML output.
1324 % Comments may contain non-ASCII characters: ä ö ü æ ø å
1326 (View the HTML source to see the comment.)
1329 \subsection{2.17~~~Raw text
%
1333 This does not necessarily look nice, because there may be missing white space.
1335 It’s just there to freeze the behavior.
1341 \DUrole{myclass
}{Another test with myclass set.
}
1343 This is the
\DUrole{myrawroleclass
}{fourth test
} with myrawroleclass set.
1345 Fifth test in LaTeX.\
\Line two.
1348 \subsection{2.18~~~Container
%
1356 % currently not implemented in LaTeX:
1357 % .. include:: data/header_footer.txt
1360 \subsection{2.19~~~Colspanning tables
%
1361 \label{colspanning-tables
}%
1364 This table has a cell spanning two columns:
1366 \setlength{\DUtablewidth}{\linewidth}
1367 \begin{longtable*
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.086\DUtablewidth}|
}
1369 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1385 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1400 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1438 \subsection{2.20~~~Rowspanning tables
%
1439 \label{rowspanning-tables
}%
1442 Here’s a table with cells spanning several rows:
1444 \setlength{\DUtablewidth}{\linewidth}
1445 \begin{longtable*
}[c
]{|p
{0.296\DUtablewidth}|p
{0.156\DUtablewidth}|p
{0.226\DUtablewidth}|
}
1448 Header row, column
1
1449 (header rows optional)
1459 Header row, column
1
1460 (header rows optional)
1468 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1472 body row
1, column
1
1481 &
\multirow{2}{0.16\DUtablewidth}{%
1484 } &
\multirow{2}{0.23\DUtablewidth}{%
1497 \subsection{2.21~~~Custom Roles
%
1498 \label{custom-roles
}%
1503 \item A role based on an existing role.
1505 \texttt{\DUrole{custom
}{one
}} \texttt{\DUrole{custom
}{two
}} \texttt{\DUrole{custom
}{three
}}
1509 \DUrole{customnew
}{one two three
}
1511 \item A role with class attribute.
1513 \DUrole{special
}{interpreted text
}
1515 \item A language-switching role:
1517 Let’s count in German
\foreignlanguage{ngerman}{eins zwei drei
}.
1519 \item A role with multiple class attributes, styled with raw directives:
1521 \newcommand{\DUrolegreen}[1]{\textcolor{green
}{#1}}
1522 \newcommand{\DUrolesc}[1]{\textsc{#1}}
1524 The following works in most browsers but does not validate
1525 (
\texttt{<style>
} is only allowed in the
document head):
1527 \begin{quote
}{\ttfamily \raggedright \noindent
1530 ~~<style~type=
\textquotedbl{}text/css
\textquotedbl{}><!-
{}-\\
1531 ~~~.green~\
{color:~green;\
}\\
1532 ~~~.sc~\
{font-variant:~small-caps;\
}\\
1537 \DUrole{green
}{\DUrole{sc
}{\foreignlanguage{british
}{British colourful text in small-caps
}}}.
1542 \subsection{2.22~~~Mathematics
%
1543 \label{mathematics
}%
1546 Docutils supports inline math with the prefix or postfix
\texttt{:math:
}
1547 role specificator, $n! +
\sin(x_n^
2)$ and $A_
\text{c
} =
1548 \frac{\pi}{4} d^
2$, as well as displayed math via the
1549 \DUroletitlereference{math
} directive:
1552 f(
\epsilon) =
\frac{1}{1 +
\exp\left(
\frac{\varepsilon}{k_
\text{B
}T
}\right)
}
1554 Content may start on the first line of the directive, e.g.
1557 N =
\frac{\text{number of apples
}}{7}
1559 Equations can be labeled with a reference name using the
\texttt{:name:
} option.
1560 See
\hyperref[eq-m
]{eq:M
} and
\hyperref[eq-schrodinger
]{eq:schrödinger
} below.
1562 The determinant of the matrix
1565 \mathbf{M
} =
\left(
\begin{matrix
}a&b\
\c&d
\end{matrix
}\right)
1569 is $|
\mathbf{M
}| = ad - bc$.
1571 More than one display math block can be put in one math directive.
1572 For example, the following sum and integral with limits:
1575 \int_0^
1 x^n dx =
\frac{1}{n +
1}
1578 \sum_{n=
1}^m n =
\frac{m(m+
1)
}{2}
1580 LaTeX-supported Unicode math symbols can be used in math roles and
1583 The Schrödinger equation
1586 i
\hbar \frac{\partial }{\partial t
}\Psi =
\hat{H
}\Psi ,
1588 \label{eq-schrodinger
}
1590 with the
\emph{wave function
} $
\Psi $, describes how the quantum state of a
1591 physical system changes in time.
1594 \item[{Math-Accents:
}] \leavevmode
1595 \setlength{\DUtablewidth}{\linewidth}
1596 \begin{longtable*
}[c
]{p
{0.315\DUtablewidth}p
{0.315\DUtablewidth}p
{0.315\DUtablewidth}}
1598 $
\acute{a
}$
\texttt{\textbackslash{}acute\
{a\
}}
1600 $
\dot{t
}$
\texttt{\textbackslash{}dot\
{t\
}}
1602 $
\hat{\gamma}$
\texttt{\textbackslash{}hat\
{\textbackslash{}gamma\
}}
1605 $
\grave{a
}$
\texttt{\textbackslash{}grave\
{a\
}}
1607 $
\ddot{t
}$
\texttt{\textbackslash{}ddot\
{t\
}}
1609 $
\tilde{\alpha}$
\texttt{\textbackslash{}tilde\
{\textbackslash{}alpha\
}}
1612 $
\breve{x
}$
\texttt{\textbackslash{}breve\
{x\
}}
1614 $
\dddot{t
}$
\texttt{\textbackslash{}dddot\
{t\
}}
1616 $
\vec{\imath}$
\texttt{\textbackslash{}vec\
{\textbackslash{}imath\
}}
1619 $
\check{a
}$
\texttt{\textbackslash{}check\
{a\
}}
1621 $
\bar{a
}$
\texttt{\textbackslash{}bar\
{a\
}}
1623 $
\vec{R
}$
\texttt{\textbackslash{}vec\
{R\
}}
1632 Modulation Transfer Function:
1635 \text{MTF
} =
\left|
\frac{\mathcal{F
}\
{s(x)\
}}
1636 {\mathcal{F
}\
{ s(x)\
} |_
{\omega _
{x
}=
0}}\right|
1637 =
\mathrm{abs
}\left(
\frac
1638 {\int _
{-
\infty }^
{\infty }s(x)
\mathrm{e
}^
{\mathrm{i
}\omega _
{x
}x
}\mathrm{d
}{x
}}
1639 {\int _
{-
\infty }^
{\infty }s(x)
\mathrm{d
}{x
}}
1642 Math split over two lines: If a double backslash is detected outside a
1643 \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}
1644 \texttt{align
} environment:
1647 s_
{\mathrm{out
}}(x) & = s_
{\mathrm{in
}}(x') * s_
\delta (x-x') \\
1648 & =
\int s_
{\mathrm{in
}}(x')s_
\delta (x-x')
\mathrm{d
}x'
1650 Cases (“manually”, with
\texttt{matrix
} environment):
1653 \mathrm{sgn
}(x) =
\left\
{\begin{matrix
}
1658 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
1659 HTML writers with
\texttt{-
{}-math-output=MathML
}):
1662 \mathrm{sgn
}(x) =
\begin{cases
}
1668 \section{3~~~Tests for the LaTeX writer
%
1669 \label{tests-for-the-latex-writer
}%
1672 Test syntax elements which may cause trouble for the LaTeX writer but might
1673 not need to be tested with other writers (e.g. the HTML writer).
1676 \subsection{3.1~~~Custom Roles in LaTeX
%
1677 \label{custom-roles-in-latex
}%
1682 \item Role names and class arguments are converted to conform to the
1683 regular expression
\texttt{{[}a-z
{]}{[}-a-z0-
9{]}*
} (letters are downcased,
1684 accents and similar decoration is stripped, non-conforming
1685 characters are replaced by a hyphen).
1687 Class arguments may contain numbers and hyphens, which need special
1688 treatment in LaTeX command names.
1690 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}}
1692 \item With LaTeX, roles can be styled within the
document using the
\DUroletitlereference{raw
}
1695 \newcommand{\DUrolelarge}[1]{{\large #1}}
1697 \@namedef
{DUrolesmall-caps
}{\textsc}
1698 \@namedef
{DUrolecustom4
}{\textbf}
1701 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}} in large, bold, small-caps.
1703 \item Custom roles can be based on standard roles:
1705 This is a
\emph{\DUrole{custom-emphasis
}{customized emphasis text role
}}
1707 This is a
\texttt{\DUrole{custom-literal
}{customized literal text role
}}
1709 This is a
\textbf{\DUrole{custom-strong
}{customized strong text role
}}
1711 This is a
\textsubscript{\DUrole{custom-subscript
}{customized subscript text role
}}
1713 This is a
\textsuperscript{\DUrole{custom-superscript
}{customized superscript text role
}}
1715 This is a
\DUroletitlereference{\DUrole{custom-title-reference
}{customized title-reference text role
}}
1720 \subsection{3.2~~~More Tables
%
1721 \label{more-tables
}%
1724 A multicolumn table with multi-paragraph rowspanning cells:
1726 \setlength{\DUtablewidth}{\linewidth}
1727 \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}|
}
1733 &
\multicolumn{3}{p
{0.41\DUtablewidth}|
}{
1736 With a second paragraph
1741 \multicolumn{2}{|p
{0.31\DUtablewidth}|
}{
1744 With a second paragraph
1757 &
\multicolumn{2}{p
{0.36\DUtablewidth}|
}{
1758 multicolumn
3 (one line,
1759 but very very very very
1775 &
\multicolumn{3}{p
{0.38\DUtablewidth}|
}{
1781 A table with multirow header
1785 \setlength{\DUtablewidth}{\linewidth}
1786 \begin{longtable*
}[c
]{|p
{0.156\DUtablewidth}|p
{0.238\DUtablewidth}|
}
1788 \multirow{2}{0.16\DUtablewidth}{%
1801 \multirow{2}{0.16\DUtablewidth}{%
1813 \multicolumn{2}{c
}{\hfill ... continued on next page
} \\
1816 \multicolumn{2}{|p
{0.39\DUtablewidth}|
}{
1817 multirow header breaks latex
1824 % This file is used by the standalone_rst_latex test.
1827 \subsection{3.3~~~Option lists
%
1831 The LaTeX-
2e description environment is used for definition lists.
1832 The definition is continued on the same line as the term, this should
1833 not happen if a option-list is at the top of the definition.
1835 If the option list is not at the first element in the definition, it
1836 is contained in a quote
1840 \begin{DUoptionlist
}
1842 \item[-
{}-help
] show help
1851 \item[{In a definition list:
}] \leavevmode %
1852 \begin{DUoptionlist
}
1854 \item[-
{}-help
] show help
1863 \subsection{3.4~~~Monospaced non-alphanumeric characters
%
1864 \label{monospaced-non-alphanumeric-characters
}%
1867 These are all ASCII characters except a-zA-Z0-
9 and space:
1869 \texttt{!!!
\textquotedbl{}\textquotedbl{}\textquotedbl{}\#\#\#\$\$\$\%\%\%\&\&\&'
{}'
{}'((()))***+++,
{},
{},-
{}-
{}-...///:::
}
1871 \texttt{;;;<
{}<
{}<===>
{}>
{}>???@@@
{[}{[}{[}\textbackslash{}\textbackslash{}\textbackslash{}{]}{]}{]}\textasciicircum{}\textasciicircum{}\textasciicircum{}\_\_\_`
{}`
{}`\
{\
{\
{|||\
}\
}\
}\textasciitilde{}\textasciitilde{}\textasciitilde{}}
1873 \texttt{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
1875 The two lines of non-alphanumeric characters should both have the same
1876 width as the third line.
1879 \subsection{3.5~~~Non-ASCII characters
%
1880 \label{non-ascii-characters
}%
1883 Punctuation and footnote symbols
1885 \setlength{\DUtablewidth}{\linewidth}
1886 \begin{longtable*
}[c
]{|p
{0.028\DUtablewidth}|p
{0.424\DUtablewidth}|
}
1903 single turned comma quotation mark
1909 single comma quotation mark
1915 low single comma quotation mark
1921 double turned comma quotation mark
1927 double comma quotation mark
1933 low double comma quotation mark
1987 left-right double arrow
1992 The
\DUroletitlereference{Latin-
1 extended
} Unicode block
1994 \setlength{\DUtablewidth}{\linewidth}
1995 \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}|
}
2253 \item The following line should not be wrapped, because it uses
2254 no-break spaces (
\textbackslash{}u00a0):
2256 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
2258 \item Line wrapping with/without breakpoints marked by soft hyphens
2259 (
\textbackslash{}u00ad):
2261 pdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-sch
2263 pdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrisch
2265 \item The currency sign (
\textbackslash{}u00a4) is not supported by all fonts
2266 (some have an Euro sign at its place). You might see an error
2269 \begin{quote
}{\ttfamily \raggedright \noindent
2270 !~Package~textcomp~Error:~Symbol~
\textbackslash{}textcurrency~not~provided~by\\
2271 (textcomp)~~~~~~~~~~~~~~~~font~family~ptm~in~TS1~encoding.\\
2272 (textcomp)~~~~~~~~~~~~~~~~Default~family~used~instead.
2276 (which in case of font family ptm is a false positive). Add either
2280 turn the error in a warning, use the default symbol (bitmap), or
2282 \item[{force,almostfull:
}]
2283 use the symbol provided by the font at the users
2288 to the
document options or use a different font package.
2293 \subsection{3.6~~~Encoding special chars
%
2294 \label{encoding-special-chars
}%
2297 The LaTeX Info pages lists under “
2.18 Special Characters”
2301 The following characters play a special role in LaTeX and are called
2302 “special printing characters”, or simply “special characters”.
2306 \# \$ \% \&
\textasciitilde{} \_ \textasciicircum{} \textbackslash{} \
{ \
}
2312 The special chars verbatim:
2314 \begin{quote
}{\ttfamily \raggedright \noindent
2315 \#~\$~\%~\&~
\textasciitilde{}~
\_~
\textasciicircum{}~
\textbackslash{}~\
{~\
}
2319 However also
\emph{square brackets
} {[}{]} need special care.
2323 item and all the other commands with optional arguments check
2324 if the token right after the macro name is an opening bracket.
2325 In that case the contents between that bracket and the following
2326 closing bracket on the same grouping level are taken as the
2327 optional argument. What makes this unintuitive is the fact that
2328 the square brackets aren’t grouping characters themselves, so in
2329 your last example item
{[}{[}…
{]}{]} the optional argument consists of
2330 {[}… (without the closing bracket).
2334 Compare the items in the following lists:
2340 \item {[}bracketed
{]} item
2345 \item[{simple
}] \leavevmode
2348 \item[{{[}bracketed
{]}}] \leavevmode
2353 The OT1 font-encoding has different characters for the less-than,
2354 greater-than and bar, < | >, except for typewriter font
\DUroletitlereference{cmtt
}:
2356 \begin{quote
}{\ttfamily \raggedright \noindent
2362 \subsection{3.7~~~Hyperlinks and -targets
%
2363 \label{hyperlinks-and-targets
}%
2366 In LaTeX, we must set an explicit anchor (
\texttt{\textbackslash{}phantomsection
}) for a
2368 \phantomsection\label{hypertarget-in-plain-text
}hypertarget in plain text or in a figure but not in a longtable or
2371 \setlength{\DUtablewidth}{\linewidth}
2372 \begin{longtable
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
2373 \caption{Table with
%
2374 \label{hypertarget-in-table-title
}hypertarget in table title.
}\\
2388 \phantomsection\label{figure-label
}
2389 \noindent\makebox[\linewidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
2390 \caption{Figure with
%
2391 \label{hypertarget-in-figure-caption
}hypertarget in figure caption.
}
2394 \phantomsection\label{hypertarget-in-figure-legend
}hypertarget in figure legend.
2398 \includegraphics{../../../docs/user/rst/images/biohazard.png
}
2399 \phantomsection\label{image-label
}
2401 See
\hyperref[hypertarget-in-plain-text
]{hypertarget in plain text
},
2402 \hyperref[table-label
]{table label
},
\hyperref[hypertarget-in-table-title
]{hypertarget in table title
},
2403 \hyperref[figure-label
]{figure label
},
\hyperref[hypertarget-in-figure-caption
]{hypertarget in figure caption
},
2404 \hyperref[hypertarget-in-figure-legend
]{hypertarget in figure legend
}, and
2405 \hyperref[image-label
]{image label
}.
2408 \subsection{3.8~~~External references
%
2409 \label{external-references
}%
2412 Long URLs should be wrapped in the PDF.
2413 This can be achieved with the url command which is used by the LaTeX writer
2414 whenever the content (name) of a reference node equals the link URL.
2417 \item[{Example:
}] \leavevmode
2418 a long URL that should wrap in the output
2419 \url{http://docutils.sourceforge.net/docs/user/latex.html\#id79
}
2423 If the argument contains any “\%”, “\#”, or “
\textasciicircum{}\textasciicircum{}”, or ends with
\texttt{\textbackslash{}}, it can’t
2424 be used in the argument to another command. The argument must not contain
2427 The characters
\textasciicircum{}, \
{, \
}, and
\texttt{\textbackslash{}} are invalid in a “http:” or “ftp:” URL
2428 and not recognized as part of it:
2430 \begin{DUlineblock
}{0em
}
2431 \item[] \url{http://www.example.org
}/strange
\textasciicircum{}\textasciicircum{}name
2432 \item[] \url{http://www.example.org
}\textbackslash{}using
\textbackslash{}DOS
\textbackslash{}paths
\textbackslash{}
2433 \item[] \url{http://www.example.org/XML
}/strange\
{n\
}ame
2436 They can, however be used in paths and/or filenames.
2438 Handling by the LaTeX writer:
2442 \item \texttt{\#
},
\texttt{\textbackslash{}} and
\texttt{\%
} are escaped:
2444 \begin{DUlineblock
}{0em
}
2445 \item[] \href{http://www.w3.org/XML/Schema\#dev
}{URL with \#
}
2446 \url{http://www.w3.org/XML/Schema\#dev
}
2447 \item[] \href{http://www.w3.org/XML/Schema\%dev
}{URL with \%
}
2448 \url{http://example.org/Schema\%dev
}
2449 \item[] \href{A:DOS\
\path\\
}{file with DOS path
}\DUfootnotemark{id42
}{id41
}{9} \url{A:DOS\
\path\\
}\DUfootnotemark{id43
}{id41
}{9}
2452 \DUadmonition[note
]{
2453 \DUtitle[note
]{Note
}
2455 These URLs are typeset inside a LaTeX command without error.
2457 \begin{DUlineblock
}{0em
}
2458 \item[] \url{http://www.w3.org/XML/Schema\#dev
}
2459 \item[] \url{http://example.org/Schema\%dev
}
2460 \item[] \url{A:DOS\
\path\\
}\DUfootnotemark{id44
}{id41
}{9}
2468 \item \textasciicircum{}\textasciicircum{} LaTeX’s special syntax for characters results in “strange” replacements
2469 (both with href and url). A warning is given.
2471 \href{../strange^^name
}{file with
\textasciicircum{}\textasciicircum{}}:
2472 \url{../strange^^name
}
2474 \item Unbalanced braces, \
{ or \
}, will fail (both with href and url):
2476 \begin{quote
}{\ttfamily \raggedright \noindent
2477 `file~with~\
{~<../strange\
{name>`
\_\_\\
2478 `<../strange\
{name>`
\_\_
2482 while balanced braces are suported:
2484 \begin{DUlineblock
}{0em
}
2485 \item[] \url{../strange
{n
}ame
}
2486 \item[] \url{../st
{r
}ange
{n
}ame
}
2487 \item[] \url{../
{st
{r
}ange
{n
}ame
}}
2493 \subsection{3.9~~~Section titles with
\hyperref[inline-markup
]{inline markup
}%
2494 \label{section-titles-with-inline-markup
}%
2498 \subsubsection{3.9.1~~~
\emph{emphasized
}, H
\textsubscript{2}O and $x^
2$
%
2499 \label{emphasized-h2o-and-x-
2}%
2503 \subsubsection{3.9.2~~~Substitutions work
%
2504 \label{substitutions-fail
}%
2508 \subsection{3.10~~~Deeply nested sections
%
2509 \label{deeply-nested-sections
}%
2515 \subsubsection{3.10.1~~~Level
3%
2522 \paragraph{3.10.1.1~~~level
4%
2529 \subparagraph{3.10.1.1.1~~~level
5%
2533 (depending on the
document class)
2536 \DUtitle[sectionVI
]{3.10.1.1.1.1~~~level
6%
2540 an unsupported level.
2542 % unusual combinations (from newlatex, for interactive testing)
2543 % .. include:: data/latex.txt
2545 % Preface for System Messages:
2548 \section{4~~~Error Handling
%
2549 \label{error-handling
}%
2552 Any errors caught during processing will generate system messages.
2554 There should be five messages in the following, auto-generated
2555 section, “Docutils System Messages”:
2557 % section should be added by Docutils automatically
2560 \section[Docutils System Messages
]{\color{red
}Docutils System Messages
%
2563 \DUadmonition[system-message
]{
2564 \DUtitle[system-message
]{system-message
}
2565 \raisebox{1em
}{\hypertarget{id27
}{}}
2567 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
104
2570 Undefined substitution referenced:
\textquotedbl{}problematic
\textquotedbl{}.
2573 \DUadmonition[system-message
]{
2574 \DUtitle[system-message
]{system-message
}
2575 \raisebox{1em
}{\hypertarget{id45
}{}}
2577 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
391
2580 Unknown target name:
\textquotedbl{}5\textquotedbl{}.
2583 \DUadmonition[system-message
]{
2584 \DUtitle[system-message
]{system-message
}
2585 \raisebox{1em
}{\hypertarget{id47
}{}}
2587 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
400
2590 Unknown target name:
\textquotedbl{}nonexistent
\textquotedbl{}.
2593 \DUadmonition[system-message
]{
2594 \DUtitle[system-message
]{system-message
}
2595 \raisebox{1em
}{\hypertarget{id49
}{}}
2597 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
427
2600 Unknown target name:
\textquotedbl{}hyperlink reference without a target
\textquotedbl{}.
2603 \DUadmonition[system-message
]{
2604 \DUtitle[system-message
]{system-message
}
2605 \raisebox{1em
}{\hypertarget{id51
}{}}
2607 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
440
2610 Duplicate target name, cannot be used as a unique reference:
\textquotedbl{}duplicate target names
\textquotedbl{}.