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
20 \setcounter{secnumdepth
}{0}
21 \usepackage{longtable,ltcaption,array
}
22 \setlength{\extrarowheight}{2pt
}
23 \newlength{\DUtablewidth} % internal use in tables
25 \usepackage{textcomp
} % text symbol macros
27 %%% Custom LaTeX preamble
29 \usepackage{mathptmx
} % Times
30 \usepackage[scaled=
.90]{helvet
}
33 %%% User specified packages and stylesheets
35 %%% Fallback definitions for Docutils-specific commands
37 % providelength (provide a length variable and set default, if it is new)
38 \providecommand*
{\DUprovidelength}[2]{
39 \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{}
43 \providecommand*
{\DUtitleabstract}[1]{\centering\textbf{#1}}
45 % admonition (specially marked topic)
46 \providecommand{\DUadmonition}[2][class-arg
]{%
47 % try \DUadmonition#1{#2}:
48 \ifcsname DUadmonition
#1\endcsname%
49 \csname DUadmonition
#1\endcsname{#2}%
52 \fbox{\parbox{0.9\linewidth}{#2}}
58 \@namedef
{DUrolealign-center
}{\centering}
63 \providecommand{\DUtopicdedication}[1]{\begin{center
}#1\end{center
}}
65 % docinfo (width of docinfo table)
66 \DUprovidelength{\DUdocinfowidth}{0.9\linewidth}
68 % subtitle (in document title)
69 \providecommand*
{\DUdocumentsubtitle}[1]{{\large #1}}
72 % error admonition title
73 \providecommand*
{\DUtitleerror}[1]{\DUtitle{\color{red
}#1}}
75 % fieldlist environment
76 \ifthenelse{\isundefined{\DUfieldlist}}{
77 \newenvironment{DUfieldlist
}%
79 {\enddescription\endquote}
81 % numeric or symbol footnotes with hyperlinks
82 \providecommand*
{\DUfootnotemark}[3]{%
83 \raisebox{1em
}{\hypertarget{#1}{}}%
84 \hyperlink{#2}{\textsuperscript{#3}}%
86 \providecommand{\DUfootnotetext}[4]{%
88 \renewcommand{\thefootnote}{%
89 \protect\raisebox{1em
}{\protect\hypertarget{#1}{}}%
90 \protect\hyperlink{#2}{#3}}%
95 % inline markup (custom roles)
96 % \DUrole{#1}{#2} tries \DUrole#1{#2}
97 \providecommand*
{\DUrole}[2]{%
98 \ifcsname DUrole
#1\endcsname%
99 \csname DUrole
#1\endcsname{#2}%
100 \else% backwards compatibility: try \docutilsrole#1{#2}
101 \ifcsname docutilsrole
#1\endcsname%
102 \csname docutilsrole
#1\endcsname{#2}%
110 \ifthenelse{\isundefined{\DUlegend}}{
111 \newenvironment{DUlegend
}{\small}{}
114 % lineblock environment
115 \DUprovidelength{\DUlineblockindent}{2.5em
}
116 \ifthenelse{\isundefined{\DUlineblock}}{
117 \newenvironment{DUlineblock
}[1]{%
118 \list{}{\setlength{\partopsep}{\parskip}
119 \addtolength{\partopsep}{\baselineskip}
120 \setlength{\topsep}{0pt
}
121 \setlength{\itemsep}{0.15\baselineskip}
122 \setlength{\parsep}{0pt
}
123 \setlength{\leftmargin}{#1}}
129 % optionlist environment
130 \providecommand*
{\DUoptionlistlabel}[1]{\bf #1 \hfill}
131 \DUprovidelength{\DUoptionlistindent}{3cm
}
132 \ifthenelse{\isundefined{\DUoptionlist}}{
133 \newenvironment{DUoptionlist
}{%
134 \list{}{\setlength{\labelwidth}{\DUoptionlistindent}
135 \setlength{\rightmargin}{1cm
}
136 \setlength{\leftmargin}{\rightmargin}
137 \addtolength{\leftmargin}{\labelwidth}
138 \addtolength{\leftmargin}{\labelsep}
139 \renewcommand{\makelabel}{\DUoptionlistlabel}}
144 % rubric (informal heading)
145 \providecommand*
{\DUrubric}[2][class-arg
]{%
146 \subsubsection*
{\centering\textit{\textmd{#2}}}}
148 % sidebar (text outside the main text flow)
149 \providecommand{\DUsidebar}[2][class-arg
]{%
151 \colorbox[gray
]{0.80}{\parbox{0.9\linewidth}{#2}}
155 % subtitle (for topic/sidebar)
156 \providecommand*
{\DUsubtitle}[2][class-arg
]{\par\emph{#2}\smallskip}
158 % title for topics, admonitions, unsupported section levels, and sidebar
159 \providecommand*
{\DUtitle}[2][class-arg
]{%
160 % call \DUtitle#1{#2} if it exists:
161 \ifcsname DUtitle
#1\endcsname%
162 \csname DUtitle
#1\endcsname{#2}%
164 \smallskip\noindent\textbf{#2}\smallskip%
168 % titlereference role
169 \providecommand*
{\DUroletitlereference}[1]{\textsl{#1}}
171 % topic (quote with heading)
172 \providecommand{\DUtopic}[2][class-arg
]{%
173 \ifcsname DUtopic
#1\endcsname%
174 \csname DUtopic
#1\endcsname{#2}%
176 \begin{quote
}#2\end{quote
}
180 % transition (break, fancybreak, anonymous section)
181 \providecommand*
{\DUtransition}[1][class-arg
]{%
182 \hspace*
{\fill}\hrulefill\hspace*
{\fill}
183 \vskip 0.5\baselineskip
187 \ifthenelse{\isundefined{\hypersetup}}{
188 \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue
]{hyperref
}
189 \usepackage{bookmark
}
190 \urlstyle{same
} % normal text font (alternatives: tt, rm, sf)
193 pdftitle=
{reStructuredText Test Document
},
194 pdfauthor=
{David Goodger;Me;Myself;I
}
198 \title{\phantomsection%
199 reStructuredText Test Document
%
200 \label{restructuredtext-test-
document}%
203 \DUdocumentsubtitle{Examples of Syntax Constructs
}%
204 \label{examples-of-syntax-constructs
}%
215 \begin{tabularx
}{\DUdocinfowidth}{lX
}
224 \href{mailto:goodger@python.org
}{goodger@python.org
} \\
231 \textbf{Organization
}: &
234 Now, or yesterday. Or maybe even
\emph{before
} yesterday. \\
236 This is a “work in progress” \\
238 is managed by a version control system. \\
241 \textbf{Copyright
}: &
242 This
document has been placed in the public domain. You
243 may do with it as you wish. You may copy, modify,
244 redistribute, reattribute, sell, buy, rent, lease,
245 destroy, or improve it, quote it at length, excerpt,
246 incorporate, collate, fold, staple, or mutilate it, or do
247 anything else to it that your or anyone else’s heart
249 \textbf{field name
}: &
250 This is a “generic bibliographic field”.
252 \textbf{field name “
2”
}: &
253 Generic bibliographic fields may contain multiple body elements.
260 \DUtopic[dedication
]{
261 \DUtitle[dedication
]{Dedication
}
263 For Docutils users \& co-developers.
267 \DUtitle[abstract
]{Abstract
}
269 This is a test
document, containing at least one example of each
270 reStructuredText construct.
273 % This is a comment. Note how any initial comments are moved by
274 % transforms to after the document title, subtitle, and docinfo.
276 % Above is the document title, and below is the subtitle.
277 % They are transformed from section titles after parsing.
279 % bibliographic fields (which also require a transform):
281 \pagebreak[4] % start ToC on new page
283 \phantomsection\label{table-of-contents
}
284 \pdfbookmark[1]{Table of Contents
}{table-of-contents
}
285 \renewcommand{\contentsname}{Table of Contents
}
290 \section{1~~~Structural Elements
%
291 \label{structural-elements
}%
295 \subsection{1.1~~~Section Title
%
296 \label{section-title
}%
298 \subsubsection*
{Section Subtitle
}
300 Lone subsections are converted to a section subtitle by a transform
301 activated with the
\texttt{-
{}-section-subtitles
} command line option or the
302 \texttt{sectsubtitle-xform
} configuration value.
305 \subsection{1.2~~~Empty Section
%
306 \label{empty-section
}%
310 \subsection{1.3~~~Transitions
%
317 %___________________________________________________________________________
321 It divides the section. Transitions may also occur between sections:
324 %___________________________________________________________________________
329 \section{2~~~Body Elements
%
330 \label{body-elements
}%
334 \subsection{2.1~~~Paragraphs
%
341 \subsubsection{2.1.1~~~Inline Markup
%
342 \label{inline-markup
}%
345 Paragraphs contain text and may contain inline markup:
\emph{emphasis
},
346 \textbf{strong emphasis
},
\texttt{inline literals
}, standalone hyperlinks
347 (
\url{http://www.python.org
}), external hyperlinks (
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id30
}{id29
}{5}), internal
348 cross-references (
\hyperref[example
]{example
}), external hyperlinks with embedded URIs
349 (
\href{http://www.python.org
}{Python web site
}),
\href{http://www.python.org/
}{anonymous hyperlink
350 references
}\DUfootnotemark{id38
}{id29
}{5} (
\href{http://docutils.sourceforge.net/
}{a second reference
}\DUfootnotemark{id40
}{id39
}{8}), footnote references (manually
351 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
]}),
352 substitution references (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}), and
%
353 \phantomsection\label{inline-hyperlink-targets
}inline hyperlink targets
354 (see
\hyperref[targets
]{Targets
} below for a reference back to here). Character-level
355 inline markup is also possible (although exceedingly ugly!) in
\emph{re
}\texttt{Structured
}\emph{Text
}. Problems are indicated by
%
356 \raisebox{1em
}{\hypertarget{id28
}{}}\hyperlink{id27
}{\textbf{\color{red
}|problematic|
}} text
357 (generated by processing errors; this one is intentional). Here is a
358 reference to the
\hyperref[doctitle
]{doctitle
} and the
\hyperref[subtitle
]{subtitle
}.
360 The default role for interpreted text is
\DUroletitlereference{Title Reference
}. Here are
361 some explicit interpreted text roles: a PEP reference (
\href{http://www.python.org/dev/peps/pep-
0287}{PEP
287}); an
362 RFC reference (
\href{http://tools.ietf.org/html/rfc2822.html
}{RFC
2822}); an abbreviation (
\DUrole{abbreviation
}{abb.
}), an acronym
363 (
\DUrole{acronym
}{reST
}), code (
\texttt{\DUrole{code
}{print
\textquotedbl{}hello world
\textquotedbl{}}}); a
\textsubscript{subscript
};
364 a
\textsuperscript{superscript
} and explicit roles for
\DUroletitlereference{Docutils
}’
365 \emph{standard
} \textbf{inline
} \texttt{markup
}.
367 % DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
369 Let’s test wrapping and whitespace significance in inline literals:
370 \texttt{This is an example of -
{}-inline-literal -
{}-text, -
{}-including some-
{}-
371 strangely-
{}-hyphenated-words. ~Adjust-the-width-of-your-browser-window
372 to see how the text is wrapped. ~-
{}- -
{}-
{}-
{}- -
{}-
{}-
{}-
{}-
{}-
{}-
{}- ~Now note ~ ~the
373 spacing ~ ~between the ~ ~words of ~ ~this sentence ~ ~(words
374 should ~ ~be grouped ~ ~in pairs).
}
376 If the
\texttt{-
{}-pep-references
} option was supplied, there should be a
377 live link to PEP
258 here.
380 \subsection{2.2~~~Bullet Lists
%
381 \label{bullet-lists
}%
390 \item Nested bullet list.
398 Paragraph
2 of item
2.
402 \item Nested bullet list.
416 \item This nested list should be compacted by the HTML writer.
418 \phantomsection\label{target
}
419 % Even if this item contains a target and a comment.
426 \subsection{2.3~~~Enumerated Lists
%
427 \label{enumerated-lists
}%
431 \item Arabic numerals.
433 \renewcommand{\labelenumii}{\alph{enumii
})
}
437 \renewcommand{\labelenumiii}{(
\roman{enumiii
})
}
443 \begin{list
}{\Roman{enumv
})
}{\usecounter{enumv
}}
451 \item Lists that don’t start at
1:
453 \renewcommand{\labelenumii}{\arabic{enumii
}.
}
454 \setcounter{enumii
}{2}
461 \renewcommand{\labelenumii}{\Alph{enumii
}.
}
462 \setcounter{enumii
}{2}
469 \renewcommand{\labelenumii}{\roman{enumii
}.
}
470 \setcounter{enumii
}{2}
479 \subsection{2.4~~~Definition Lists
%
480 \label{definition-lists
}%
484 \item[{Term
}] \leavevmode
487 \item[{Term
}] \leavevmode (
\textbf{classifier
})
489 Definition paragraph
1.
491 Definition paragraph
2.
493 \item[{Term
}] \leavevmode
496 \item[{Term
}] \leavevmode (
\textbf{classifier one
})
497 (
\textbf{classifier two
})
504 \subsection{2.5~~~Field Lists
%
510 Field lists map field names to field bodies, like database
511 records. They are often part of an extension syntax. They are
512 an unambiguous variant of RFC
2822 fields.
514 \item[{how arg1 arg2:
}]
515 The field marker is a colon, the field name, and a colon.
517 The field body may contain one or more body elements, indented
518 relative to the field marker.
521 \DUrole{credits
}{This paragraph has the
\DUroletitlereference{credits
} class set. (This is actually not
522 about credits but just for ensuring that the class attribute
523 doesn’t get stripped away.)
}
528 \subsection{2.6~~~Option Lists
%
529 \label{option-lists
}%
532 For listing command-line options:
536 \item[-a
] command-line option “a”
538 \item[-b file
] options can have arguments
539 and long descriptions
541 \item[-
{}-long
] options can be long also
543 \item[-
{}-input=file
] long options can also have
546 \item[-
{}-very-long-option
] The description can also start on the next line.
548 The description may contain multiple body elements,
549 regardless of where it starts.
551 \item[-x, -y, -z
] Multiple options are an “option group”.
553 \item[-v, -
{}-verbose
] Commonly-seen: short \& long options.
555 \item[-
1 file, -
{}-one=file, -
{}-two file
] Multiple options with arguments.
557 \item[/V
] DOS/VMS-style options too
561 There must be at least two spaces between the option and the
565 \subsection{2.7~~~Literal Blocks
%
566 \label{literal-blocks
}%
569 Literal blocks are indicated with a double-colon (“::”) at the end of
570 the preceding paragraph (over there
\texttt{-
{}->
}). They can be indented:
575 text = 'is left as-is'
576 spaces_and_linebreaks = 'are preserved'
577 markup_processing = None
581 Or they can be quoted without indentation:
587 > Why didn't I think of that?
592 \subsection{2.8~~~Line Blocks
%
596 This section tests line blocks. Line blocks are body elements which
597 consist of lines and other line blocks. Nested line blocks cause
600 \begin{DUlineblock
}{0em
}
601 \item[] This is a line block. It ends with a blank line.
603 \begin{DUlineblock
}{\DUlineblockindent}
604 \item[] New lines begin with a vertical bar (“|”).
605 \item[] Line breaks and initial indent are significant, and preserved.
607 \begin{DUlineblock
}{\DUlineblockindent}
608 \item[] Continuation lines are also possible. A long line that is intended
609 to wrap should begin with a space in place of the vertical bar.
611 \item[] The left edge of a continuation line need not be aligned with
612 the left edge of the text above it.
616 \begin{DUlineblock
}{0em
}
617 \item[] This is a second line block.
619 \item[] Blank lines are permitted internally, but they must begin with a “|”.
622 Another line block, surrounded by paragraphs:
624 \begin{DUlineblock
}{0em
}
625 \item[] And it’s no good waiting by the window
626 \item[] It’s no good waiting for the sun
627 \item[] Please believe me, the things you dream of
628 \item[] They don’t fall in the lap of no-one
631 Take it away, Eric the Orchestra Leader!
635 \begin{DUlineblock
}{0em
}
636 \item[] A one, two, a one two three four
638 \item[] Half a bee, philosophically,
640 \begin{DUlineblock
}{\DUlineblockindent}
641 \item[] must,
\emph{ipso facto
}, half not be.
643 \item[] But half the bee has got to be,
645 \begin{DUlineblock
}{\DUlineblockindent}
646 \item[] \emph{vis a vis
} its entity. D’you see?
649 \item[] But can a bee be said to be
651 \begin{DUlineblock
}{\DUlineblockindent}
652 \item[] or not to be an entire bee,
654 \begin{DUlineblock
}{\DUlineblockindent}
655 \item[] when half the bee is not a bee,
657 \begin{DUlineblock
}{\DUlineblockindent}
658 \item[] due to some ancient injury?
668 A line block, like the following poem by Christian Morgenstern, can
669 also be centre-aligned:
671 \begin{DUlineblock
}{0em
}
672 \foreignlanguage{ngerman}{\DUrole{align-center
}{
673 \item[] \textbf{Die Trichter
}
675 \item[] Zwei Trichter wandeln durch die Nacht.
676 \item[] Durch ihres Rumpfs verengten Schacht
677 \item[] fließt weißes Mondlicht
678 \item[] still und heiter
688 \subsection{2.9~~~Block Quotes
%
689 \label{block-quotes
}%
692 Block quotes consist of indented body elements:
696 My theory by A. Elk. Brackets Miss, brackets. This theory goes
697 as follows and begins now. All brontosauruses are thin at one
698 end, much much thicker in the middle and then thin again at the
699 far end. That is my theory, it is mine, and belongs to me and I
700 own it, and what it is too.
703 \raggedleft —Anne Elk (Miss)
707 The language of a quote (like any other object) can be specified by
713 \foreignlanguage{french
}{
714 ReStructuredText est un langage de balisage léger utilisé
715 notamment dans la documentation du langage Python.
720 \subsection{2.10~~~Doctest Blocks
%
721 \label{doctest-blocks
}%
726 >>> print 'Python-specific usage examples; begun with ">>>"'
727 Python-specific usage examples; begun with ">>>"
728 >>> print '(cut and pasted from interactive Python sessions)'
729 (cut and pasted from interactive Python sessions)
734 \subsection{2.11~~~Footnotes
%
738 \DUfootnotetext{id8
}{id1
}{1}{%
739 A footnote contains body elements, consistently indented by at
742 This is the footnote’s second paragraph.
745 \DUfootnotetext{label
}{id3
}{2}{\phantomsection\label{label
}%
746 Footnotes may be numbered, either manually (as in
\DUfootnotemark{id9
}{id8
}{1}) or
747 automatically using a “\#”-prefixed label. This footnote has a
748 label so it can be referred to from multiple places, both as a
749 footnote reference (
\DUfootnotemark{id10
}{label
}{2}) and as a
\hyperref[label
]{hyperlink reference
}.
752 \DUfootnotetext{id12
}{id2
}{3}{%
753 This footnote is numbered automatically and anonymously using a
756 This is the second paragraph.
758 And this is the third paragraph.
761 \DUfootnotetext{id13
}{id4
}{*
}{%
762 Footnotes may also use symbols, specified with a “*” label.
763 Here’s a reference to the next footnote:
\DUfootnotemark{id14
}{id15
}{†
}.
766 \DUfootnotetext{id15
}{id14
}{†
}{%
767 This footnote shows the next symbol in the sequence.
770 \DUfootnotetext{id16
}{id16
}{4}{%
771 Here’s an unreferenced footnote, with a reference to a
772 nonexistent footnote:
%
773 \raisebox{1em
}{\hypertarget{id46
}{}}%
774 \raisebox{1em
}{\hypertarget{id17
}{}}\hyperlink{id45
}{\textbf{\color{red
}{[}5{]}\_}}.
778 \subsection{2.12~~~Citations
%
781 \begin{figure
}[b
]\raisebox{1em
}{\hypertarget{cit2002
}{}}[CIT2002
]
782 Citations are text-labeled footnotes. They may be
783 rendered separately and differently from footnotes.
786 Here’s a reference to the above,
\hyperlink{cit2002
}{[CIT2002
]}, and a
%
787 \raisebox{1em
}{\hypertarget{id48
}{}}%
788 \raisebox{1em
}{\hypertarget{id19
}{}}\hyperlink{id47
}{\textbf{\color{red
}{[}nonexistent
{]}\_}}
792 \subsection{2.13~~~Targets
%
794 \label{another-target
}%
797 \phantomsection\label{example
}
798 This paragraph is pointed to by the explicit “example” target. A
799 reference can be found under
\hyperref[inline-markup
]{Inline Markup
}, above.
\hyperref[inline-hyperlink-targets
]{Inline
800 hyperlink targets
} are also possible.
802 Section headers are implicit targets, referred to by name. See
803 \hyperref[targets
]{Targets
}, which is a subsection of
\hyperref[body-elements
]{Body Elements
}.
805 Explicit external targets are interpolated into references such as
806 “
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id31
}{id29
}{5}”.
808 Targets may be indirect and anonymous. Thus
\hyperref[targets
]{this phrase
} may also
809 refer to the
\hyperref[targets
]{Targets
} section.
812 \raisebox{1em
}{\hypertarget{id50
}{}}\hyperlink{id49
}{\textbf{\color{red
}`hyperlink reference without a target`
\_}}, which generates an
816 \subsubsection{2.13.1~~~Duplicate Target Names
%
817 \label{duplicate-target-names
}%
820 Duplicate names in section headers or other implicit targets will
821 generate “info” (level-
1) system messages. Duplicate names in
822 explicit targets will generate “warning” (level-
2) system messages.
825 \subsubsection{2.13.2~~~Duplicate Target Names
%
829 Since there are two “Duplicate Target Names” section headers, we
830 cannot uniquely refer to either of them by name. If we try to (like
832 \raisebox{1em
}{\hypertarget{id52
}{}}\hyperlink{id51
}{\textbf{\color{red
}`Duplicate Target Names`
\_}}), an error is generated.
835 \subsection{2.14~~~Directives
%
839 \phantomsection\label{contents
}
840 These are just a sample of the many reStructuredText Directives. For
842 \url{http://docutils.sourceforge.net/docs/ref/rst/directives.html
}.
845 \subsubsection{2.14.1~~~Document Parts
%
846 \label{document-parts
}%
849 An example of the “contents” directive can be seen above this section
850 (a local, untitled table of
\hyperref[contents
]{contents
}) and at the beginning of the
851 document (a
document-wide
\hyperref[table-of-contents
]{table of contents
}).
854 \subsubsection{2.14.2~~~Images and Figures
%
855 \label{images-and-figures
}%
858 An image directive (also clickable – a hyperlink reference):
860 \hyperref[directives
]{\includegraphics{../../../docs/user/rst/images/title.png
}}
862 Image with multiple IDs:
864 \includegraphics{../../../docs/user/rst/images/title.png
}
865 \phantomsection\label{image-target-
3}\label{image-target-
2}\label{image-target-
1}
869 \noindent\makebox[\linewidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
871 A left-aligned image:
873 \noindent{\includegraphics{../../../docs/user/rst/images/biohazard.png
}\hfill}
875 This paragraph might flow around the image.
876 The specific behavior depends upon the style sheet and
877 the browser or rendering software used.
879 A right-aligned image:
881 \noindent{\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
883 This paragraph might flow around the image.
884 The specific behavior depends upon the style sheet and
885 the browser or rendering software used.
887 For inline images see
\hyperref[substitution-definitions
]{Substitution Definitions
}.
893 \includegraphics[width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
895 An image
2 em wide and
15 pixel high:
897 \includegraphics[height=
15px,width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
899 An image occupying
50\% of the line width:
901 \includegraphics[width=
0.500\linewidth]{../../../docs/user/rst/images/title.png
}
905 \includegraphics[height=
2cm
]{../../../docs/user/rst/images/biohazard.png
}
907 A
\emph{figure
} is an image with a caption and/or a legend. With page-based output
908 media, figures might float to a different position if this helps the page
912 \noindent\makebox[\linewidth][c
]{\includegraphics[width=
258bp
]{../../../docs/user/rst/images/title.png
}}
913 \caption{Plaintext markup syntax and parser system.
}
915 \setlength{\DUtablewidth}{\linewidth}
916 \begin{longtable*
}[c
]{|p
{0.156\DUtablewidth}|p
{0.563\DUtablewidth}|
}
921 Revised, revisited, based on ‘re’ module.
927 Structure-enhanced text, structuredtext.
933 Well it is, isn’t it?
938 This paragraph is also part of the legend.
942 A left-aligned figure:
944 \begin{figure
} % align = "left"
945 \noindent\makebox[\linewidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
946 \caption{This is the caption.
}
950 The legend may consist of several paragraphs.
954 This paragraph might flow around the figure.
956 The specific behavior depends upon the style sheet and the browser or
957 rendering software used.
962 \noindent\makebox[\linewidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
963 \caption{This is the caption.
}
967 The legend may consist of several paragraphs.
971 This paragraph might flow around the figure.
973 The specific behavior depends upon the style sheet and the browser or
974 rendering software used.
976 A right-aligned figure:
978 \begin{figure
} % align = "right"
979 \noindent\makebox[\linewidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
980 \caption{This is the caption.
}
984 The legend may consist of several paragraphs.
988 This paragraph might flow around the figure. The specific behavior depends
989 upon the style sheet and the browser or rendering software used.
991 Tables may be given titles and additional arguments with the
\emph{table
}
994 \setlength{\DUtablewidth}{\linewidth}
995 \begin{longtable
}[l
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
996 \caption{left-aligned table
}\\
1005 \caption[]{left-aligned table (... continued)
}\\
1014 \multicolumn{2}{c
}{\hfill ... continued on next page
} \\
1031 \setlength{\DUtablewidth}{\linewidth}
1032 \begin{longtable
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
1033 \caption{center-aligned table
}\\
1042 \caption[]{center-aligned table (... continued)
}\\
1051 \multicolumn{2}{c
}{\hfill ... continued on next page
} \\
1068 \setlength{\DUtablewidth}{\linewidth}
1069 \begin{longtable
}[r
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
1070 \caption{right-aligned table
}\\
1079 \caption[]{right-aligned table (... continued)
}\\
1088 \multicolumn{2}{c
}{\hfill ... continued on next page
} \\
1106 \subsubsection{2.14.3~~~Admonitions
%
1107 \label{admonitions
}%
1110 \DUadmonition[attention
]{
1111 \DUtitle[attention
]{Attention!
}
1113 Directives at large.
1116 \DUadmonition[caution
]{
1117 \DUtitle[caution
]{Caution!
}
1119 Don’t take any wooden nickels.
1122 \DUadmonition[danger
]{
1123 \DUtitle[danger
]{!DANGER!
}
1125 Mad scientist at work!
1128 \DUadmonition[error
]{
1129 \DUtitle[error
]{Error
}
1134 \DUadmonition[hint
]{
1135 \DUtitle[hint
]{Hint
}
1137 It’s bigger than a bread box.
1140 \DUadmonition[important
]{
1141 \DUtitle[important
]{Important
}
1145 \item Wash behind your ears.
1147 \item Clean up your room.
1149 \item Call your mother.
1151 \item Back up your data.
1156 \DUadmonition[note
]{
1157 \DUtitle[note
]{Note
}
1165 15\% if the service is good.
1168 \DUadmonition[warning
]{
1169 \DUtitle[warning
]{Warning
}
1171 Strong prose may provoke extreme mental exertion.
1172 Reader discretion is strongly advised.
1175 \DUadmonition[admonition-and-by-the-way
]{
1176 \DUtitle[admonition-and-by-the-way
]{And, by the way…
}
1178 You can make up your own admonition too.
1182 \subsubsection{2.14.4~~~Topics, Sidebars, and Rubrics
%
1183 \label{topics-sidebars-and-rubrics
}%
1186 \emph{Sidebars
} are like miniature, parallel documents.
1189 \DUtitle[title
]{Sidebar Title
}
1191 \DUsubtitle[sidebar
]{Optional Subtitle
}
1193 This is a sidebar. It is for text outside the flow of the main
1196 \DUrubric{This is a rubric inside a sidebar
}
1198 Sidebars often appear beside the main text with a border and a different
1199 background or font
color.
1202 A
\emph{topic
} is like a block quote with a title, or a self-contained section
1203 with no subsections.
1206 \DUtitle[title
]{Topic Title
}
1211 A
\emph{rubric
} is like an informal heading that doesn’t correspond to the
1212 document’s structure. It is typically highlighted in red (hence the name).
1214 \DUrubric{This is a rubric
}
1216 Topics and rubrics can be used at places where a
\hyperref[section-title
]{section title
} is not
1217 allowed (e.g. inside a directive).
1220 \subsubsection{2.14.5~~~Target Footnotes
%
1221 \label{target-footnotes
}%
1224 \DUfootnotetext{id29
}{id30
}{5}{%
1225 \url{http://www.python.org/
}
1228 \DUfootnotetext{id33
}{id34
}{6}{%
1229 \url{http://pygments.org/
}
1232 \DUfootnotetext{id35
}{id36
}{7}{%
1233 \url{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
}
1236 \DUfootnotetext{id39
}{id40
}{8}{%
1237 \url{http://docutils.sourceforge.net/
}
1240 \DUfootnotetext{id41
}{id42
}{9}{%
1245 \subsubsection{2.14.6~~~Replacement Text
%
1246 \label{replacement-text
}%
1249 I recommend you try
\href{http://www.python.org/
}{Python,
\emph{the
} best language around
}\DUfootnotemark{id32
}{id29
}{5}.
1252 \subsubsection{2.14.7~~~Compound Paragraph
%
1253 \label{compound-paragraph
}%
1256 Compound
1, paragraph
1.
1258 Compound
1, paragraph
2.
1262 \item Compound
1, list item one.
1264 \item Compound
1, list item two.
1268 Another compound statement:
1270 Compound
2, a literal block:
1274 Compound
2, literal.
1277 Compound
2, this is a test.
1279 Compound
3, only consisting of one paragraph.
1284 This one starts with a literal block.
1287 Compound
4, a paragraph.
1289 Now something
\emph{really
} perverted – a nested compound block. This is
1290 just to test that it works at all; the results don’t have to be
1293 Compound
5, block
1 (a paragraph).
1295 Compound
6, block
2 in compound
5.
1297 Compound
6, another paragraph.
1299 Compound
5, block
3 (a paragraph).
1301 Compound
7, with a table inside:
1303 \setlength{\DUtablewidth}{\linewidth}
1304 \begin{longtable*
}[c
]{|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|
}
1326 Compound
7, a paragraph after the table.
1328 Compound
7, another paragraph.
1331 \subsubsection{2.14.8~~~Parsed Literal Blocks
%
1332 \label{parsed-literal-blocks
}%
1336 {\ttfamily \raggedright \noindent
1337 This~is~a~parsed~literal~block.\\
1338 ~~~~This~line~is~indented.~~The~next~line~is~blank.\\
1340 Inline~markup~is~supported,~e.g.~
\emph{emphasis
},~
\textbf{strong
},~
\texttt{literal\\
1341 text
},~
\textsubscript{sub-
}~and~
\textsuperscript{super
}scripts,\\
1342 inline~formulas:~$A =
2 \pi r^
2$,\\
1343 footnotes
\DUfootnotemark{id22
}{id8
}{1},~
%
1344 \phantomsection\label{hyperlink-targets
}hyperlink~targets,~and~
\href{http://www.python.org/
}{references
}.
1349 \subsubsection{2.14.9~~~Code
%
1353 Blocks of source code can be set with the
\DUroletitlereference{code
} directive. If the code
1354 language is specified, the content is parsed and tagged by the
\href{http://pygments.org/
}{Pygments
}\DUfootnotemark{id34
}{id33
}{6}
1355 syntax highlighter and can be formatted with a style sheet. (Code parsing
1356 is turned off using the
\texttt{syntax-highlight
} config setting in the test
1357 conversions in order to get identical results with/without installed
1358 Pygments highlighter.)
1362 print 'This is Python code.'
1366 The
\texttt{:number-lines:
} option (with optional start value) generates line
1370 {\ttfamily \raggedright \noindent
1371 \DUrole{ln
}{~
8~
}\#~print~integers~from~
0~to~
9:\\
1372 \DUrole{ln
}{~
9~
}for~i~in~range(
10):\\
1373 \DUrole{ln
}{10~
}~~~~print~i
1377 For inline code snippets, there is the
\DUroletitlereference{code
} role, which can be used
1378 directly (the code will not be parsed/tagged, as the language is not known)
1379 or as base for special code roles, e.g. the LaTeX code in the next
1382 Docutils uses LaTeX syntax for math directives and roles:
1383 \texttt{\DUrole{code
}{\DUrole{tex
}{\textbackslash{}alpha = f(x)
}}} prints $
\alpha = f(x)$.
1385 The
\texttt{:code:
} option of the
\DUroletitlereference{include
} directive sets the included content
1386 as a code block, here the rst file
\texttt{header
\_footer.txt
} with line numbers:
1389 {\ttfamily \raggedright \noindent
1390 \DUrole{ln
}{1~
}..~header::~Document~header\\
1391 \DUrole{ln
}{2~
}..~footer::~Document~footer
1396 \subsection{2.15~~~Substitution Definitions
%
1397 \label{substitution-definitions
}%
1400 An inline image (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}) example:
1402 (Substitution definitions are not visible in the HTML source.)
1405 \subsection{2.16~~~Comments
%
1411 % Comments begin with two dots and a space. Anything may
1412 % follow, except for the syntax of footnotes, hyperlink
1413 % targets, directives, or substitution definitions.
1415 % Double-dashes -- "--" -- must be escaped somehow in HTML output.
1417 % Comments may contain non-ASCII characters: ä ö ü æ ø å
1419 (View the HTML source to see the comment.)
1422 \subsection{2.17~~~Raw text
%
1426 This does not necessarily look nice, because there may be missing white space.
1428 It’s just there to freeze the behavior.
1434 \DUrole{myclass
}{Another test with myclass set.
}
1436 This is the
\DUrole{myrawroleclass
}{fourth test
} with myrawroleclass set.
1438 Fifth test in LaTeX.\
\Line two.
1441 \subsection{2.18~~~Container
%
1449 % currently not implemented in LaTeX:
1450 % .. include:: data/header_footer.txt
1453 \subsection{2.19~~~Colspanning tables
%
1454 \label{colspanning-tables
}%
1457 This table has a cell spanning two columns:
1459 \setlength{\DUtablewidth}{\linewidth}
1460 \begin{longtable*
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.086\DUtablewidth}|
}
1462 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1478 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1493 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1531 \subsection{2.20~~~Rowspanning tables
%
1532 \label{rowspanning-tables
}%
1535 Here’s a table with cells spanning several rows:
1537 \setlength{\DUtablewidth}{\linewidth}
1538 \begin{longtable*
}[c
]{|p
{0.296\DUtablewidth}|p
{0.156\DUtablewidth}|p
{0.226\DUtablewidth}|
}
1541 Header row, column
1
1542 (header rows optional)
1552 Header row, column
1
1553 (header rows optional)
1561 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1565 body row
1, column
1
1574 &
\multirow{2}{0.16\DUtablewidth}{%
1577 } &
\multirow{2}{0.23\DUtablewidth}{%
1590 \subsection{2.21~~~Custom Roles
%
1591 \label{custom-roles
}%
1596 \item A role based on an existing role.
1598 \texttt{\DUrole{custom
}{one
}} \texttt{\DUrole{custom
}{two
}} \texttt{\DUrole{custom
}{three
}}
1602 \DUrole{customnew
}{one two three
}
1604 \item A role with class attribute.
1606 \DUrole{special
}{interpreted text
}
1608 \item A language-switching role:
1610 Let’s count in German
\foreignlanguage{ngerman}{eins zwei drei
}.
1612 \item A role with multiple class attributes, styled with raw directives:
1614 \newcommand{\DUrolegreen}[1]{\textcolor{green
}{#1}}
1615 \newcommand{\DUrolesc}[1]{\textsc{#1}}
1617 The following works in most browsers but does not validate
1618 (
\texttt{<style>
} is only allowed in the
document head):
1624 <style type="text/css"><!-
{}-
1625 .green \
{color: green;\
}
1626 .sc \
{font-variant: small-caps;\
}
1631 \DUrole{green
}{\DUrole{sc
}{\foreignlanguage{british
}{British colourful text in small-caps
}}}.
1636 \subsection{2.22~~~Mathematics
%
1637 \label{mathematics
}%
1640 Docutils supports inline math with the prefix or postfix
\texttt{:math:
}
1641 role specificator, $n! +
\sin(x_n^
2)$ and $A_
\text{c
} =
1642 \frac{\pi}{4} d^
2$, as well as displayed math via the
1643 \DUroletitlereference{math
} directive:
1646 f(
\epsilon) =
\frac{1}{1 +
\exp\left(
\frac{\varepsilon}{k_
\text{B
}T
}\right)
}
1648 Content may start on the first line of the directive, e.g.
1651 N =
\frac{\text{number of apples
}}{7}
1653 Equations can be labeled with a reference name using the
\texttt{:name:
} option.
1654 See
\hyperref[eq-m
]{eq:M
} and
\hyperref[eq-schrodinger
]{eq:schrödinger
} below.
1656 The determinant of the matrix
1659 \mathbf{M
} =
\left(
\begin{matrix
}a&b\
\c&d
\end{matrix
}\right)
1663 is $|
\mathbf{M
}| = ad - bc$.
1665 More than one display math block can be put in one math directive.
1666 For example, the following sum and integral with limits:
1669 \int_0^
1 x^n dx =
\frac{1}{n +
1}
1672 \sum_{n=
1}^m n =
\frac{m(m+
1)
}{2}
1674 LaTeX-supported Unicode math symbols can be used in math roles and
1677 The Schrödinger equation
1680 i
\hbar \frac{\partial }{\partial t
}\Psi =
\hat{H
}\Psi ,
1682 \label{eq-schrodinger
}
1684 with the
\emph{wave function
} $
\Psi $, describes how the quantum state of a
1685 physical system changes in time.
1688 \item[{Math-Accents:
}] \leavevmode
1689 \setlength{\DUtablewidth}{\linewidth}
1690 \begin{longtable*
}[c
]{p
{0.315\DUtablewidth}p
{0.315\DUtablewidth}p
{0.315\DUtablewidth}}
1692 $
\acute{a
}$
\texttt{\textbackslash{}acute\
{a\
}}
1694 $
\dot{t
}$
\texttt{\textbackslash{}dot\
{t\
}}
1696 $
\hat{\gamma}$
\texttt{\textbackslash{}hat\
{\textbackslash{}gamma\
}}
1699 $
\grave{a
}$
\texttt{\textbackslash{}grave\
{a\
}}
1701 $
\ddot{t
}$
\texttt{\textbackslash{}ddot\
{t\
}}
1703 $
\tilde{\alpha}$
\texttt{\textbackslash{}tilde\
{\textbackslash{}alpha\
}}
1706 $
\breve{x
}$
\texttt{\textbackslash{}breve\
{x\
}}
1708 $
\dddot{t
}$
\texttt{\textbackslash{}dddot\
{t\
}}
1710 $
\vec{\imath}$
\texttt{\textbackslash{}vec\
{\textbackslash{}imath\
}}
1713 $
\check{a
}$
\texttt{\textbackslash{}check\
{a\
}}
1715 $
\bar{a
}$
\texttt{\textbackslash{}bar\
{a\
}}
1717 $
\vec{R
}$
\texttt{\textbackslash{}vec\
{R\
}}
1726 Modulation Transfer Function:
1729 \text{MTF
} =
\left|
\frac{\mathcal{F
}\
{s(x)\
}}
1730 {\mathcal{F
}\
{ s(x)\
} |_
{\omega _
{x
}=
0}}\right|
1731 =
\mathrm{abs
}\left(
\frac
1732 {\int _
{-
\infty }^
{\infty }s(x)
\mathrm{e
}^
{\mathrm{i
}\omega _
{x
}x
}\mathrm{d
}{x
}}
1733 {\int _
{-
\infty }^
{\infty }s(x)
\mathrm{d
}{x
}}
1736 Math split over two lines: If a double backslash is detected outside a
1737 \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}
1738 \texttt{align
} environment:
1741 s_
{\mathrm{out
}}(x) & = s_
{\mathrm{in
}}(x') * s_
\delta (x-x') \\
1742 & =
\int s_
{\mathrm{in
}}(x')s_
\delta (x-x')
\mathrm{d
}x'
1744 Cases (“manually”, with
\texttt{matrix
} environment):
1747 \mathrm{sgn
}(x) =
\left\
{\begin{matrix
}
1752 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
1753 HTML writers with
\texttt{-
{}-math-output=MathML
}):
1756 \mathrm{sgn
}(x) =
\begin{cases
}
1762 \section{3~~~Tests for the LaTeX writer
%
1763 \label{tests-for-the-latex-writer
}%
1766 Test syntax elements which may cause trouble for the LaTeX writer but might
1767 not need to be tested with other writers (e.g. the HTML writer).
1770 \subsection{3.1~~~Custom Roles in LaTeX
%
1771 \label{custom-roles-in-latex
}%
1776 \item Role names and class arguments are converted to conform to the
1777 regular expression
\texttt{{[}a-z
{]}{[}-a-z0-
9{]}*
} (letters are downcased,
1778 accents and similar decoration is stripped, non-conforming
1779 characters are replaced by a hyphen).
1781 Class arguments may contain numbers and hyphens, which need special
1782 treatment in LaTeX command names.
1784 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}}
1786 \item With LaTeX, roles can be styled within the
document using the
\DUroletitlereference{raw
}
1789 \newcommand{\DUrolelarge}[1]{{\large #1}}
1791 \@namedef
{DUrolesmall-caps
}{\textsc}
1792 \@namedef
{DUrolecustom4
}{\textbf}
1795 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}} in large, bold, small-caps.
1797 \item Custom roles can be based on standard roles:
1799 This is a
\emph{\DUrole{custom-emphasis
}{customized emphasis text role
}}
1801 This is a
\texttt{\DUrole{custom-literal
}{customized literal text role
}}
1803 This is a
\textbf{\DUrole{custom-strong
}{customized strong text role
}}
1805 This is a
\textsubscript{\DUrole{custom-subscript
}{customized subscript text role
}}
1807 This is a
\textsuperscript{\DUrole{custom-superscript
}{customized superscript text role
}}
1809 This is a
\DUroletitlereference{\DUrole{custom-title-reference
}{customized title-reference text role
}}
1814 \subsection{3.2~~~More Tables
%
1815 \label{more-tables
}%
1818 A table with multi-paragraph multicolumn cells:
1820 \setlength{\DUtablewidth}{\linewidth}
1821 \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}|
}
1827 &
\multicolumn{3}{p
{0.41\DUtablewidth}|
}{%
1830 With a second paragraph
1835 \multicolumn{2}{|p
{0.31\DUtablewidth}|
}{%
1838 With a second paragraph
1851 &
\multicolumn{2}{p
{0.36\DUtablewidth}|
}{%
1852 multicolumn
3 (one line,
1853 but very very very very
1869 &
\multicolumn{3}{p
{0.38\DUtablewidth}|
}{%
1875 Tables with multi-paragraph multirow cells currently fail due to a LaTeX
1876 limitation (see
\url{https://sourceforge.net/p/docutils/bugs/
225/
}).
1878 A table with multirow header and column-widths set by LaTeX:
1880 \begin{longtable*
}[c
]{|l|l|
}
1882 \multirow{2}{*
}{\textbf{XXX
}} &
\textbf{Variable Summary
} \\
1884 &
\textbf{Description
} \\
1888 \multirow{2}{*
}{\textbf{XXX
}} &
\textbf{Variable Summary
} \\
1890 &
\textbf{Description
} \\
1893 \multicolumn{2}{c
}{\hfill ... continued on next page
} \\
1896 \multicolumn{2}{|l|
}{multicollumn cell
} \\
1900 In a table with column-widths set by LaTeX, each cell has just one line.
1901 Paragraphs are merged (a warning is given).
1903 \begin{longtable*
}[c
]{|l|l|
}
1905 11 & first paragraph
1913 % This file is used by the standalone_rst_latex test.
1916 \subsection{3.3~~~Option lists
%
1920 The LaTeX-
2e description environment is used for definition lists.
1921 The definition is continued on the same line as the term, this should
1922 not happen if a option-list is at the top of the definition.
1924 If the option list is not at the first element in the definition, it
1925 is contained in a quote
1929 \begin{DUoptionlist
}
1931 \item[-
{}-help
] show help
1940 \item[{In a definition list:
}] \leavevmode %
1941 \begin{DUoptionlist
}
1943 \item[-
{}-help
] show help
1952 \subsection{3.4~~~Monospaced non-alphanumeric characters
%
1953 \label{monospaced-non-alphanumeric-characters
}%
1956 These are all ASCII characters except a-zA-Z0-
9 and space:
1958 \texttt{!!!
\textquotedbl{}\textquotedbl{}\textquotedbl{}\#\#\#\$\$\$\%\%\%\&\&\&'
{}'
{}'((()))***+++,
{},
{},-
{}-
{}-...///:::
}
1960 \texttt{;;;<
{}<
{}<===>
{}>
{}>???@@@
{[}{[}{[}\textbackslash{}\textbackslash{}\textbackslash{}{]}{]}{]}\textasciicircum{}\textasciicircum{}\textasciicircum{}\_\_\_`
{}`
{}`\
{\
{\
{|||\
}\
}\
}\textasciitilde{}\textasciitilde{}\textasciitilde{}}
1962 \texttt{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
1964 The two lines of non-alphanumeric characters should both have the same
1965 width as the third line.
1968 \subsection{3.5~~~Non-ASCII characters
%
1969 \label{non-ascii-characters
}%
1972 Punctuation and footnote symbols
1974 \setlength{\DUtablewidth}{\linewidth}
1975 \begin{longtable*
}[c
]{|p
{0.028\DUtablewidth}|p
{0.424\DUtablewidth}|
}
1992 single turned comma quotation mark
1998 single comma quotation mark
2004 low single comma quotation mark
2010 double turned comma quotation mark
2016 double comma quotation mark
2022 low double comma quotation mark
2076 left-right double arrow
2081 The
\DUroletitlereference{Latin-
1 extended
} Unicode block
2083 \setlength{\DUtablewidth}{\linewidth}
2084 \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}|
}
2342 \item The following line should not be wrapped, because it uses
2343 no-break spaces (
\textbackslash{}u00a0):
2345 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
2347 \item Line wrapping with/without breakpoints marked by soft hyphens
2348 (
\textbackslash{}u00ad):
2350 pdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-sch
2352 pdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrisch
2354 \item The currency sign (
\textbackslash{}u00a4) is not supported by all fonts
2355 (some have an Euro sign at its place). You might see an error
2360 ! Package textcomp Error: Symbol
\textbackslash{}textcurrency not provided by
2361 (textcomp) font family ptm in TS1 encoding.
2362 (textcomp) Default family used instead.
2366 (which in case of font family ptm is a false positive). Add either
2370 turn the error in a warning, use the default symbol (bitmap), or
2372 \item[{force,almostfull:
}]
2373 use the symbol provided by the font at the users
2378 to the
document options or use a different font package.
2383 \subsection{3.6~~~Encoding special chars
%
2384 \label{encoding-special-chars
}%
2387 The LaTeX Info pages lists under “
2.18 Special Characters”
2391 The following characters play a special role in LaTeX and are called
2392 “special printing characters”, or simply “special characters”.
2396 \# \$ \% \&
\textasciitilde{} \_ \textasciicircum{} \textbackslash{} \
{ \
}
2402 The special chars verbatim:
2406 # $
% & ~ _ ^ \textbackslash{} \{ \}
2410 However also
\emph{square brackets
} {[}{]} need special care.
2414 Commands with optional arguments (e.g.
\texttt{\textbackslash{}item
}) check
2415 if the token right after the macro name is an opening bracket.
2416 In that case the contents between that bracket and the following
2417 closing bracket on the same grouping level are taken as the
2418 optional argument. What makes this unintuitive is the fact that
2419 the square brackets aren’t grouping characters themselves, so in
2420 your last example item
{[}{[}…
{]}{]} the optional argument consists of
2421 {[}… (without the closing bracket).
2425 Compare the items in the following lists:
2431 \item {[}bracketed
{]} item
2436 \item[{simple
}] \leavevmode
2439 \item[{{[}bracketed
{]}}] \leavevmode
2444 The OT1 font-encoding has different characters for the less-than,
2445 greater-than and bar, < | >, except for typewriter font
\DUroletitlereference{cmtt
}:
2454 \subsection{3.7~~~Hyperlinks and -targets
%
2455 \label{hyperlinks-and-targets
}%
2458 In LaTeX, we must set an explicit anchor (
\texttt{\textbackslash{}phantomsection
}) for a
2460 \phantomsection\label{hypertarget-in-plain-text
}hypertarget in plain text or in a figure but not in a longtable or
2463 \setlength{\DUtablewidth}{\linewidth}
2464 \begin{longtable
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
2465 \caption{Table with
%
2466 \label{hypertarget-in-table-title
}hypertarget in table title.
}\\
2480 \phantomsection\label{figure-label
}
2481 \noindent\makebox[\linewidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
2482 \caption{Figure with
%
2483 \label{hypertarget-in-figure-caption
}hypertarget in figure caption.
}
2486 \phantomsection\label{hypertarget-in-figure-legend
}hypertarget in figure legend.
2490 \includegraphics{../../../docs/user/rst/images/biohazard.png
}
2491 \phantomsection\label{image-label
}
2493 See
\hyperref[hypertarget-in-plain-text
]{hypertarget in plain text
},
2494 \hyperref[table-label
]{table label
},
\hyperref[hypertarget-in-table-title
]{hypertarget in table title
},
2495 \hyperref[figure-label
]{figure label
},
\hyperref[hypertarget-in-figure-caption
]{hypertarget in figure caption
},
2496 \hyperref[hypertarget-in-figure-legend
]{hypertarget in figure legend
}, and
2497 \hyperref[image-label
]{image label
}.
2500 \subsection{3.8~~~External references
%
2501 \label{external-references
}%
2504 Long URLs should be wrapped in the PDF.
2505 This can be achieved with the url command which is used by the LaTeX writer
2506 whenever the content (name) of a reference node equals the link URL.
2509 \item[{Example:
}] \leavevmode
2510 a long URL that should wrap in the output
2511 \url{http://docutils.sourceforge.net/docs/user/latex.html\#id79
}
2515 If the argument contains any “\%”, “\#”, or “
\textasciicircum{}\textasciicircum{}”, or ends with
\texttt{\textbackslash{}}, it can’t
2516 be used in the argument to another command. The argument must not contain
2519 The characters
\textasciicircum{}, \
{, \
}, and
\texttt{\textbackslash{}} are invalid in a “http:” or “ftp:” URL
2520 and not recognized as part of it:
2522 \begin{DUlineblock
}{0em
}
2523 \item[] \url{http://www.example.org
}/strange
\textasciicircum{}\textasciicircum{}name
2524 \item[] \url{http://www.example.org
}\textbackslash{}using
\textbackslash{}DOS
\textbackslash{}paths
\textbackslash{}
2525 \item[] \url{http://www.example.org/XML
}/strange\
{n\
}ame
2528 They can, however be used in paths and/or filenames.
2530 Handling by the LaTeX writer:
2534 \item \texttt{\#
},
\texttt{\textbackslash{}} and
\texttt{\%
} are escaped:
2536 \begin{DUlineblock
}{0em
}
2537 \item[] \href{http://www.w3.org/XML/Schema\#dev
}{URL with \#
}
2538 \url{http://www.w3.org/XML/Schema\#dev
}
2539 \item[] \href{http://www.w3.org/XML/Schema\%dev
}{URL with \%
}
2540 \url{http://example.org/Schema\%dev
}
2541 \item[] \href{A:DOS\
\path\\
}{file with DOS path
}\DUfootnotemark{id42
}{id41
}{9} \url{A:DOS\
\path\\
}\DUfootnotemark{id43
}{id41
}{9}
2544 \DUadmonition[note
]{
2545 \DUtitle[note
]{Note
}
2547 These URLs are typeset inside a LaTeX command without error.
2549 \begin{DUlineblock
}{0em
}
2550 \item[] \url{http://www.w3.org/XML/Schema\#dev
}
2551 \item[] \url{http://example.org/Schema\%dev
}
2552 \item[] \url{A:DOS\
\path\\
}\DUfootnotemark{id44
}{id41
}{9}
2560 \item \textasciicircum{}\textasciicircum{} LaTeX’s special syntax for characters results in “strange” replacements
2561 (both with href and url). A warning is given.
2563 \href{../strange^^name
}{file with
\textasciicircum{}\textasciicircum{}}:
2564 \url{../strange^^name
}
2566 \item Unbalanced braces, \
{ or \
}, will fail (both with href and url):
2570 `file with \
{ <../strange\
{name>`__
2571 `<../strange\
{name>`__
2575 while balanced braces are suported:
2577 \begin{DUlineblock
}{0em
}
2578 \item[] \url{../strange
{n
}ame
}
2579 \item[] \url{../st
{r
}ange
{n
}ame
}
2580 \item[] \url{../
{st
{r
}ange
{n
}ame
}}
2586 \subsection{3.9~~~Section titles with
\hyperref[inline-markup
]{inline markup
}%
2587 \label{section-titles-with-inline-markup
}%
2591 \subsubsection{3.9.1~~~
\emph{emphasized
}, H
\textsubscript{2}O and $x^
2$
%
2592 \label{emphasized-h2o-and-x-
2}%
2596 \subsubsection{3.9.2~~~Substitutions work
%
2597 \label{substitutions-fail
}%
2601 \subsection{3.10~~~Deeply nested sections
%
2602 \label{deeply-nested-sections
}%
2608 \subsubsection{3.10.1~~~Level
3%
2615 \paragraph{3.10.1.1~~~level
4%
2622 \subparagraph{3.10.1.1.1~~~level
5%
2626 (depending on the
document class)
2629 \DUtitle[sectionVI
]{3.10.1.1.1.1~~~level
6%
2633 an unsupported level.
2635 % unusual combinations (currently separately tested)
2636 % .. include:: data/latex_cornercases.txt
2638 % Preface for System Messages:
2641 \section{4~~~Error Handling
%
2642 \label{error-handling
}%
2645 Any errors caught during processing will generate system messages.
2647 There should be five messages in the following, auto-generated
2648 section, “Docutils System Messages”:
2650 % section should be added by Docutils automatically
2653 \section[Docutils System Messages
]{\color{red
}Docutils System Messages
%
2656 \DUadmonition[system-message
]{
2657 \DUtitle[system-message
]{system-message
}
2658 \raisebox{1em
}{\hypertarget{id27
}{}}
2660 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
104
2663 Undefined substitution referenced:
\textquotedbl{}problematic
\textquotedbl{}.
2666 \DUadmonition[system-message
]{
2667 \DUtitle[system-message
]{system-message
}
2668 \raisebox{1em
}{\hypertarget{id45
}{}}
2670 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
391
2673 Unknown target name:
\textquotedbl{}5\textquotedbl{}.
2676 \DUadmonition[system-message
]{
2677 \DUtitle[system-message
]{system-message
}
2678 \raisebox{1em
}{\hypertarget{id47
}{}}
2680 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
400
2683 Unknown target name:
\textquotedbl{}nonexistent
\textquotedbl{}.
2686 \DUadmonition[system-message
]{
2687 \DUtitle[system-message
]{system-message
}
2688 \raisebox{1em
}{\hypertarget{id49
}{}}
2690 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
427
2693 Unknown target name:
\textquotedbl{}hyperlink reference without a target
\textquotedbl{}.
2696 \DUadmonition[system-message
]{
2697 \DUtitle[system-message
]{system-message
}
2698 \raisebox{1em
}{\hypertarget{id51
}{}}
2700 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
440
2703 Duplicate target name, cannot be used as a unique reference:
\textquotedbl{}duplicate target names
\textquotedbl{}.