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]{\centerline{\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\textwidth}{#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\textwidth}
67 % error admonition title
68 \providecommand*
{\DUtitleerror}[1]{\DUtitle{\color{red
}#1}}
70 % fieldlist environment
71 \ifthenelse{\isundefined{\DUfieldlist}}{
72 \newenvironment{DUfieldlist
}%
74 {\enddescription\endquote}
76 % numeric or symbol footnotes with hyperlinks
77 \providecommand*
{\DUfootnotemark}[3]{%
78 \raisebox{1em
}{\hypertarget{#1}{}}%
79 \hyperlink{#2}{\textsuperscript{#3}}%
81 \providecommand{\DUfootnotetext}[4]{%
83 \renewcommand{\thefootnote}{%
84 \protect\raisebox{1em
}{\protect\hypertarget{#1}{}}%
85 \protect\hyperlink{#2}{#3}}%
90 % inline markup (custom roles)
91 % \DUrole{#1}{#2} tries \DUrole#1{#2}
92 \providecommand*
{\DUrole}[2]{%
93 \ifcsname DUrole
#1\endcsname%
94 \csname DUrole
#1\endcsname{#2}%
95 \else% backwards compatibility: try \docutilsrole#1{#2}
96 \ifcsname docutilsrole
#1\endcsname%
97 \csname docutilsrole
#1\endcsname{#2}%
105 \ifthenelse{\isundefined{\DUlegend}}{
106 \newenvironment{DUlegend
}{\small}{}
109 % lineblock environment
110 \DUprovidelength{\DUlineblockindent}{2.5em
}
111 \ifthenelse{\isundefined{\DUlineblock}}{
112 \newenvironment{DUlineblock
}[1]{%
113 \list{}{\setlength{\partopsep}{\parskip}
114 \addtolength{\partopsep}{\baselineskip}
115 \setlength{\topsep}{0pt
}
116 \setlength{\itemsep}{0.15\baselineskip}
117 \setlength{\parsep}{0pt
}
118 \setlength{\leftmargin}{#1}}
124 % optionlist environment
125 \providecommand*
{\DUoptionlistlabel}[1]{\bf #1 \hfill}
126 \DUprovidelength{\DUoptionlistindent}{3cm
}
127 \ifthenelse{\isundefined{\DUoptionlist}}{
128 \newenvironment{DUoptionlist
}{%
129 \list{}{\setlength{\labelwidth}{\DUoptionlistindent}
130 \setlength{\rightmargin}{1cm
}
131 \setlength{\leftmargin}{\rightmargin}
132 \addtolength{\leftmargin}{\labelwidth}
133 \addtolength{\leftmargin}{\labelsep}
134 \renewcommand{\makelabel}{\DUoptionlistlabel}}
139 % rubric (informal heading)
140 \providecommand*
{\DUrubric}[2][class-arg
]{%
141 \subsubsection*
{\centering\textit{\textmd{#2}}}}
143 % sidebar (text outside the main text flow)
144 \providecommand{\DUsidebar}[2][class-arg
]{%
146 \colorbox[gray
]{0.80}{\parbox{0.9\textwidth}{#2}}
150 % subtitle (for topic/sidebar)
151 \providecommand*
{\DUsubtitle}[2][class-arg
]{\par\emph{#2}\smallskip}
153 % title for topics, admonitions, unsupported section levels, and sidebar
154 \providecommand*
{\DUtitle}[2][class-arg
]{%
155 % call \DUtitle#1{#2} if it exists:
156 \ifcsname DUtitle
#1\endcsname%
157 \csname DUtitle
#1\endcsname{#2}%
159 \smallskip\noindent\textbf{#2}\smallskip%
163 % titlereference role
164 \providecommand*
{\DUroletitlereference}[1]{\textsl{#1}}
166 % topic (quote with heading)
167 \providecommand{\DUtopic}[2][class-arg
]{%
168 \ifcsname DUtopic
#1\endcsname%
169 \csname DUtopic
#1\endcsname{#2}%
171 \begin{quote
}#2\end{quote
}
175 % transition (break, fancybreak, anonymous section)
176 \providecommand*
{\DUtransition}[1][class-arg
]{%
177 \hspace*
{\fill}\hrulefill\hspace*
{\fill}
178 \vskip 0.5\baselineskip
182 \ifthenelse{\isundefined{\hypersetup}}{
183 \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue
]{hyperref
}
184 \urlstyle{same
} % normal text font (alternatives: tt, rm, sf)
187 pdftitle=
{reStructuredText Test Document
},
188 pdfauthor=
{David Goodger;Me;Myself;I
}
192 \title{\phantomsection%
193 reStructuredText Test Document
%
194 \label{restructuredtext-test-
document}%
197 \large{Examples of Syntax Constructs
}%
198 \label{examples-of-syntax-constructs
}%
209 \begin{tabularx
}{\DUdocinfowidth}{lX
}
218 \href{mailto:goodger@python.org
}{goodger@python.org
} \\
225 \textbf{Organization
}: &
228 Now, or yesterday. Or maybe even
\emph{before
} yesterday. \\
230 This is a ``work in progress'' \\
232 is managed by a version control system. \\
235 \textbf{Copyright
}: &
236 This
document has been placed in the public domain. You
237 may do with it as you wish. You may copy, modify,
238 redistribute, reattribute, sell, buy, rent, lease,
239 destroy, or improve it, quote it at length, excerpt,
240 incorporate, collate, fold, staple, or mutilate it, or do
241 anything else to it that your or anyone else's heart
243 \textbf{field name
}: &
244 This is a ``generic bibliographic field''.
246 \textbf{field name ``
2''
}: &
247 Generic bibliographic fields may contain multiple body elements.
254 \DUtopic[dedication
]{
255 \DUtitle[dedication
]{Dedication
}
257 For Docutils users \& co-developers.
261 \DUtitle[abstract
]{Abstract
}
263 This is a test
document, containing at least one example of each
264 reStructuredText construct.
267 % This is a comment. Note how any initial comments are moved by
268 % transforms to after the document title, subtitle, and docinfo.
270 % Above is the document title, and below is the subtitle.
271 % They are transformed from section titles after parsing.
273 % bibliographic fields (which also require a transform):
275 \pagebreak[4] % start ToC on new page
277 \phantomsection\label{table-of-contents
}
278 \pdfbookmark[1]{Table of Contents
}{table-of-contents
}
279 \renewcommand{\contentsname}{Table of Contents
}
284 \section{1~~~Structural Elements
%
285 \label{structural-elements
}%
289 \subsection{1.1~~~Section Title
%
290 \label{section-title
}%
292 \subsubsection*
{Section Subtitle
}
294 Lone subsections are converted to a section subtitle by a transform
295 activated with the
\texttt{-
{}-section-subtitles
} command line option or the
296 \texttt{sectsubtitle-xform
} configuration value.
299 \subsection{1.2~~~Empty Section
%
300 \label{empty-section
}%
304 \subsection{1.3~~~Transitions
%
311 %___________________________________________________________________________
315 It divides the section. Transitions may also occur between sections:
318 %___________________________________________________________________________
323 \section{2~~~Body Elements
%
324 \label{body-elements
}%
328 \subsection{2.1~~~Paragraphs
%
335 \subsubsection{2.1.1~~~Inline Markup
%
336 \label{inline-markup
}%
339 Paragraphs contain text and may contain inline markup:
\emph{emphasis
},
340 \textbf{strong emphasis
},
\texttt{inline literals
}, standalone hyperlinks
341 (
\url{http://www.python.org
}), external hyperlinks (
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id30
}{id29
}{5}), internal
342 cross-references (
\hyperref[example
]{example
}), external hyperlinks with embedded URIs
343 (
\href{http://www.python.org
}{Python web site
}),
\href{http://www.python.org/
}{anonymous hyperlink
344 references
}\DUfootnotemark{id38
}{id29
}{5} (
\href{http://docutils.sourceforge.net/
}{a second reference
}\DUfootnotemark{id40
}{id39
}{8}), footnote references (manually
345 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
]}),
346 substitution references (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}), and
%
347 \phantomsection\label{inline-hyperlink-targets
}inline hyperlink targets
348 (see
\hyperref[targets
]{Targets
} below for a reference back to here). Character-level
349 inline markup is also possible (although exceedingly ugly!) in
\emph{re
}\texttt{Structured
}\emph{Text
}. Problems are indicated by
%
350 \raisebox{1em
}{\hypertarget{id28
}{}}\hyperlink{id27
}{\textbf{\color{red
}|problematic|
}} text
351 (generated by processing errors; this one is intentional). Here is a
352 reference to the
\hyperref[doctitle
]{doctitle
} and the
\hyperref[subtitle
]{subtitle
}.
354 The default role for interpreted text is
\DUroletitlereference{Title Reference
}. Here are
355 some explicit interpreted text roles: a PEP reference (
\href{http://www.python.org/dev/peps/pep-
0287}{PEP
287}); an
356 RFC reference (
\href{http://www.faqs.org/rfcs/rfc2822.html
}{RFC
2822}); an abbreviation (
\DUrole{abbreviation
}{abb.
}), an acronym
357 (
\DUrole{acronym
}{reST
}), code (
\texttt{\DUrole{code
}{print "hello world"
}}); a
\textsubscript{subscript
};
358 a
\textsuperscript{superscript
} and explicit roles for
\DUroletitlereference{Docutils
}'
359 \emph{standard
} \textbf{inline
} \texttt{markup
}.
361 % DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
363 Let's test wrapping and whitespace significance in inline literals:
364 \texttt{This is an example of -
{}-inline-literal -
{}-text, -
{}-including some-
{}-
365 strangely-
{}-hyphenated-words. ~Adjust-the-width-of-your-browser-window
366 to see how the text is wrapped. ~-
{}- -
{}-
{}-
{}- -
{}-
{}-
{}-
{}-
{}-
{}-
{}- ~Now note ~ ~the
367 spacing ~ ~between the ~ ~words of ~ ~this sentence ~ ~(words
368 should ~ ~be grouped ~ ~in pairs).
}
370 If the
\texttt{-
{}-pep-references
} option was supplied, there should be a
371 live link to PEP
258 here.
374 \subsection{2.2~~~Bullet Lists
%
375 \label{bullet-lists
}%
384 \item Nested bullet list.
392 Paragraph
2 of item
2.
396 \item Nested bullet list.
410 \item This nested list should be compacted by the HTML writer.
412 \phantomsection\label{target
}
413 % Even if this item contains a target and a comment.
420 \subsection{2.3~~~Enumerated Lists
%
421 \label{enumerated-lists
}%
423 \newcounter{listcnt0
}
424 \begin{list
}{\arabic{listcnt0
}.
}
426 \usecounter{listcnt0
}
427 \setlength{\rightmargin}{\leftmargin}
430 \item Arabic numerals.
431 \newcounter{listcnt1
}
432 \begin{list
}{\alph{listcnt1
})
}
434 \usecounter{listcnt1
}
435 \setlength{\rightmargin}{\leftmargin}
439 \newcounter{listcnt2
}
440 \begin{list
}{(
\roman{listcnt2
})
}
442 \usecounter{listcnt2
}
443 \setlength{\rightmargin}{\leftmargin}
447 \newcounter{listcnt3
}
448 \begin{list
}{\Alph{listcnt3
}.
}
450 \usecounter{listcnt3
}
451 \setlength{\rightmargin}{\leftmargin}
455 \newcounter{listcnt4
}
456 \begin{list
}{\Roman{listcnt4
})
}
458 \usecounter{listcnt4
}
459 \setlength{\rightmargin}{\leftmargin}
468 \item Lists that don't start at
1:
469 \setcounter{listcnt1
}{0}
470 \begin{list
}{\arabic{listcnt1
}.
}
472 \usecounter{listcnt1
}
473 \addtocounter{listcnt1
}{2}
474 \setlength{\rightmargin}{\leftmargin}
481 \setcounter{listcnt1
}{0}
482 \begin{list
}{\Alph{listcnt1
}.
}
484 \usecounter{listcnt1
}
485 \addtocounter{listcnt1
}{2}
486 \setlength{\rightmargin}{\leftmargin}
493 \setcounter{listcnt1
}{0}
494 \begin{list
}{\roman{listcnt1
}.
}
496 \usecounter{listcnt1
}
497 \addtocounter{listcnt1
}{2}
498 \setlength{\rightmargin}{\leftmargin}
508 \subsection{2.4~~~Definition Lists
%
509 \label{definition-lists
}%
513 \item[{Term
}] \leavevmode
516 \item[{Term
}] \leavevmode (
\textbf{classifier
})
518 Definition paragraph
1.
520 Definition paragraph
2.
522 \item[{Term
}] \leavevmode
525 \item[{Term
}] \leavevmode (
\textbf{classifier one
})
526 (
\textbf{classifier two
})
533 \subsection{2.5~~~Field Lists
%
539 Field lists map field names to field bodies, like database
540 records. They are often part of an extension syntax. They are
541 an unambiguous variant of RFC
2822 fields.
543 \item[{how arg1 arg2:
}]
544 The field marker is a colon, the field name, and a colon.
546 The field body may contain one or more body elements, indented
547 relative to the field marker.
550 \DUrole{credits
}{This paragraph has the
\DUroletitlereference{credits
} class set. (This is actually not
551 about credits but just for ensuring that the class attribute
552 doesn't get stripped away.)
}
557 \subsection{2.6~~~Option Lists
%
558 \label{option-lists
}%
561 For listing command-line options:
565 \item[-a
] command-line option ``a''
567 \item[-b file
] options can have arguments
568 and long descriptions
570 \item[-
{}-long
] options can be long also
572 \item[-
{}-input=file
] long options can also have
575 \item[-
{}-very-long-option
] The description can also start on the next line.
577 The description may contain multiple body elements,
578 regardless of where it starts.
580 \item[-x, -y, -z
] Multiple options are an ``option group''.
582 \item[-v, -
{}-verbose
] Commonly-seen: short \& long options.
584 \item[-
1 file, -
{}-one=file, -
{}-two file
] Multiple options with arguments.
586 \item[/V
] DOS/VMS-style options too
590 There must be at least two spaces between the option and the
594 \subsection{2.7~~~Literal Blocks
%
595 \label{literal-blocks
}%
598 Literal blocks are indicated with a double-colon (``::'') at the end of
599 the preceding paragraph (over there
\texttt{-
{}->
}). They can be indented:
601 \begin{quote
}{\ttfamily \raggedright \noindent
603 ~~~~text~=~'is~left~as-is'\\
604 ~~~~spaces
\_and\_linebreaks~=~'are~preserved'\\
605 ~~~~markup
\_processing~=~None
609 Or they can be quoted without indentation:
611 \begin{quote
}{\ttfamily \raggedright \noindent
614 >~Why~didn't~I~think~of~that?
619 \subsection{2.8~~~Line Blocks
%
623 This section tests line blocks. Line blocks are body elements which
624 consist of lines and other line blocks. Nested line blocks cause
627 \begin{DUlineblock
}{0em
}
628 \item[] This is a line block. It ends with a blank line.
630 \begin{DUlineblock
}{\DUlineblockindent}
631 \item[] New lines begin with a vertical bar (``|'').
632 \item[] Line breaks and initial indent are significant, and preserved.
634 \begin{DUlineblock
}{\DUlineblockindent}
635 \item[] Continuation lines are also possible. A long line that is intended
636 to wrap should begin with a space in place of the vertical bar.
638 \item[] The left edge of a continuation line need not be aligned with
639 the left edge of the text above it.
643 \begin{DUlineblock
}{0em
}
644 \item[] This is a second line block.
646 \item[] Blank lines are permitted internally, but they must begin with a ``|''.
649 Another line block, surrounded by paragraphs:
651 \begin{DUlineblock
}{0em
}
652 \item[] And it's no good waiting by the window
653 \item[] It's no good waiting for the sun
654 \item[] Please believe me, the things you dream of
655 \item[] They don't fall in the lap of no-one
658 Take it away, Eric the Orchestra Leader!
662 \begin{DUlineblock
}{0em
}
663 \item[] A one, two, a one two three four
665 \item[] Half a bee, philosophically,
667 \begin{DUlineblock
}{\DUlineblockindent}
668 \item[] must,
\emph{ipso facto
}, half not be.
670 \item[] But half the bee has got to be,
672 \begin{DUlineblock
}{\DUlineblockindent}
673 \item[] \emph{vis a vis
} its entity. D'you see?
676 \item[] But can a bee be said to be
678 \begin{DUlineblock
}{\DUlineblockindent}
679 \item[] or not to be an entire bee,
681 \begin{DUlineblock
}{\DUlineblockindent}
682 \item[] when half the bee is not a bee,
684 \begin{DUlineblock
}{\DUlineblockindent}
685 \item[] due to some ancient injury?
695 A line block, like the following poem by Christian Morgenstern, can
696 also be centre-aligned:
698 \begin{DUlineblock
}{0em
}
699 \otherlanguage{ngerman}{\DUrole{align-center
}{
700 \item[] \textbf{Die Trichter
}
702 \item[] Zwei Trichter wandeln durch die Nacht.
703 \item[] Durch ihres Rumpfs verengten Schacht
704 \item[] fließt weißes Mondlicht
705 \item[] still und heiter
715 \subsection{2.9~~~Block Quotes
%
716 \label{block-quotes
}%
719 Block quotes consist of indented body elements:
723 My theory by A. Elk. Brackets Miss, brackets. This theory goes
724 as follows and begins now. All brontosauruses are thin at one
725 end, much much thicker in the middle and then thin again at the
726 far end. That is my theory, it is mine, and belongs to me and I
727 own it, and what it is too.
730 \raggedleft —Anne Elk (Miss)
734 The language of a quote (like any other object) can be specified by
740 \otherlanguage{french
}{
741 ReStructuredText est un langage de balisage léger utilisé
742 notamment dans la documentation du langage Python.
747 \subsection{2.10~~~Doctest Blocks
%
748 \label{doctest-blocks
}%
751 \begin{quote
}{\ttfamily \raggedright \noindent
752 >
{}>
{}>~print~'Python-specific~usage~examples;~begun~with~">
{}>
{}>"'\\
753 Python-specific~usage~examples;~begun~with~">
{}>
{}>"\\
754 >
{}>
{}>~print~'(cut~and~pasted~from~interactive~Python~sessions)'\\
755 (cut~and~pasted~from~interactive~Python~sessions)
760 \subsection{2.11~~~Footnotes
%
764 \DUfootnotetext{id8
}{id1
}{1}{%
765 A footnote contains body elements, consistently indented by at
768 This is the footnote's second paragraph.
771 \DUfootnotetext{label
}{id3
}{2}{\phantomsection\label{label
}%
772 Footnotes may be numbered, either manually (as in
\DUfootnotemark{id9
}{id8
}{1}) or
773 automatically using a ``\#''-prefixed label. This footnote has a
774 label so it can be referred to from multiple places, both as a
775 footnote reference (
\DUfootnotemark{id10
}{label
}{2}) and as a
\hyperref[label
]{hyperlink reference
}.
778 \DUfootnotetext{id12
}{id2
}{3}{%
779 This footnote is numbered automatically and anonymously using a
780 label of ``\#'' only.
782 This is the second paragraph.
784 And this is the third paragraph.
787 \DUfootnotetext{id13
}{id4
}{*
}{%
788 Footnotes may also use symbols, specified with a ``*'' label.
789 Here's a reference to the next footnote:
\DUfootnotemark{id14
}{id15
}{†
}.
792 \DUfootnotetext{id15
}{id14
}{†
}{%
793 This footnote shows the next symbol in the sequence.
796 \DUfootnotetext{id16
}{id16
}{4}{%
797 Here's an unreferenced footnote, with a reference to a
798 nonexistent footnote:
%
799 \raisebox{1em
}{\hypertarget{id46
}{}}%
800 \raisebox{1em
}{\hypertarget{id17
}{}}\hyperlink{id45
}{\textbf{\color{red
}{[}5{]}\_}}.
804 \subsection{2.12~~~Citations
%
807 \begin{figure
}[b
]\raisebox{1em
}{\hypertarget{cit2002
}{}}[CIT2002
]
808 Citations are text-labeled footnotes. They may be
809 rendered separately and differently from footnotes.
812 Here's a reference to the above,
\hyperlink{cit2002
}{[CIT2002
]}, and a
%
813 \raisebox{1em
}{\hypertarget{id48
}{}}%
814 \raisebox{1em
}{\hypertarget{id19
}{}}\hyperlink{id47
}{\textbf{\color{red
}{[}nonexistent
{]}\_}}
818 \subsection{2.13~~~Targets
%
820 \label{another-target
}%
823 \phantomsection\label{example
}
824 This paragraph is pointed to by the explicit ``example'' target. A
825 reference can be found under
\hyperref[inline-markup
]{Inline Markup
}, above.
\hyperref[inline-hyperlink-targets
]{Inline
826 hyperlink targets
} are also possible.
828 Section headers are implicit targets, referred to by name. See
829 \hyperref[targets
]{Targets
}, which is a subsection of
\hyperref[body-elements
]{Body Elements
}.
831 Explicit external targets are interpolated into references such as
832 ``
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id31
}{id29
}{5}''.
834 Targets may be indirect and anonymous. Thus
\hyperref[targets
]{this phrase
} may also
835 refer to the
\hyperref[targets
]{Targets
} section.
838 \raisebox{1em
}{\hypertarget{id50
}{}}\hyperlink{id49
}{\textbf{\color{red
}`hyperlink reference without a target`
\_}}, which generates an
842 \subsubsection{2.13.1~~~Duplicate Target Names
%
843 \label{duplicate-target-names
}%
846 Duplicate names in section headers or other implicit targets will
847 generate ``info'' (level-
1) system messages. Duplicate names in
848 explicit targets will generate ``warning'' (level-
2) system messages.
851 \subsubsection{2.13.2~~~Duplicate Target Names
%
855 Since there are two ``Duplicate Target Names'' section headers, we
856 cannot uniquely refer to either of them by name. If we try to (like
858 \raisebox{1em
}{\hypertarget{id52
}{}}\hyperlink{id51
}{\textbf{\color{red
}`Duplicate Target Names`
\_}}), an error is generated.
861 \subsection{2.14~~~Directives
%
865 \phantomsection\label{contents
}
866 These are just a sample of the many reStructuredText Directives. For
868 \url{http://docutils.sourceforge.net/docs/ref/rst/directives.html
}.
871 \subsubsection{2.14.1~~~Document Parts
%
872 \label{document-parts
}%
875 An example of the ``contents'' directive can be seen above this section
876 (a local, untitled table of
\hyperref[contents
]{contents
}) and at the beginning of the
877 document (a
document-wide
\hyperref[table-of-contents
]{table of contents
}).
880 \subsubsection{2.14.2~~~Images and Figures
%
881 \label{images-and-figures
}%
884 An image directive (also clickable -
{}- a hyperlink reference):
886 \hyperref[directives
]{\includegraphics{../../../docs/user/rst/images/title.png
}}
888 Image with multiple IDs:
890 \includegraphics{../../../docs/user/rst/images/title.png
}
891 \phantomsection\label{image-target-
3}\label{image-target-
2}\label{image-target-
1}
895 \noindent\makebox[\textwidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
897 A left-aligned image:
899 \noindent{\includegraphics{../../../docs/user/rst/images/biohazard.png
}\hfill}
901 This paragraph might flow around the image.
902 The specific behavior depends upon the style sheet and
903 the browser or rendering software used.
905 A right-aligned image:
907 \noindent{\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
909 This paragraph might flow around the image.
910 The specific behavior depends upon the style sheet and
911 the browser or rendering software used.
913 For inline images see
\hyperref[substitution-definitions
]{Substitution Definitions
}.
919 \includegraphics[width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
921 An image
2 em wide and
15 pixel high:
923 \includegraphics[height=
15px,width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
925 An image occupying
50\% of the line width:
927 \includegraphics[width=
0.500\linewidth]{../../../docs/user/rst/images/title.png
}
931 \includegraphics[height=
2cm
]{../../../docs/user/rst/images/biohazard.png
}
933 A
\emph{figure
} is an image with a caption and/or a legend. With page-based output
934 media, figures might float to a different position if this helps the page
937 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
258bp
]{../../../docs/user/rst/images/title.png
}}
938 \caption{Plaintext markup syntax and parser system.
}
940 \setlength{\DUtablewidth}{\linewidth}
941 \begin{longtable*
}[c
]{|p
{0.156\DUtablewidth}|p
{0.563\DUtablewidth}|
}
946 Revised, revisited, based on 're' module.
952 Structure-enhanced text, structuredtext.
958 Well it is, isn't it?
963 This paragraph is also part of the legend.
967 A left-aligned figure:
969 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
970 \caption{This is the caption.
}
974 The legend may consist of several paragraphs.
978 This paragraph might flow around the figure.
980 The specific behavior depends upon the style sheet and the browser or
981 rendering software used.
985 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
986 \caption{This is the caption.
}
990 The legend may consist of several paragraphs.
994 This paragraph might flow around the figure.
996 The specific behavior depends upon the style sheet and the browser or
997 rendering software used.
999 A right-aligned figure:
1001 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
1002 \caption{This is the caption.
}
1006 The legend may consist of several paragraphs.
1010 This paragraph might flow around the figure. The specific behavior depends
1011 upon the style sheet and the browser or rendering software used.
1014 \subsubsection{2.14.3~~~Admonitions
%
1015 \label{admonitions
}%
1018 \DUadmonition[attention
]{
1019 \DUtitle[attention
]{Attention!
}
1021 Directives at large.
1024 \DUadmonition[caution
]{
1025 \DUtitle[caution
]{Caution!
}
1027 Don't take any wooden nickels.
1030 \DUadmonition[danger
]{
1031 \DUtitle[danger
]{!DANGER!
}
1033 Mad scientist at work!
1036 \DUadmonition[error
]{
1037 \DUtitle[error
]{Error
}
1042 \DUadmonition[hint
]{
1043 \DUtitle[hint
]{Hint
}
1045 It's bigger than a bread box.
1048 \DUadmonition[important
]{
1049 \DUtitle[important
]{Important
}
1053 \item Wash behind your ears.
1055 \item Clean up your room.
1057 \item Call your mother.
1059 \item Back up your data.
1064 \DUadmonition[note
]{
1065 \DUtitle[note
]{Note
}
1073 15\% if the service is good.
1076 \DUadmonition[warning
]{
1077 \DUtitle[warning
]{Warning
}
1079 Strong prose may provoke extreme mental exertion.
1080 Reader discretion is strongly advised.
1083 \DUadmonition[admonition-and-by-the-way
]{
1084 \DUtitle[admonition-and-by-the-way
]{And, by the way...
}
1086 You can make up your own admonition too.
1090 \subsubsection{2.14.4~~~Topics, Sidebars, and Rubrics
%
1091 \label{topics-sidebars-and-rubrics
}%
1094 \emph{Sidebars
} are like miniature, parallel documents.
1097 \DUtitle[title
]{Sidebar Title
}
1099 \DUsubtitle[sidebar
]{Optional Subtitle
}
1101 This is a sidebar. It is for text outside the flow of the main
1104 \DUrubric{This is a rubric inside a sidebar
}
1106 Sidebars often appear beside the main text with a border and a different
1107 background or font
color.
1110 A
\emph{topic
} is like a block quote with a title, or a self-contained section
1111 with no subsections.
1114 \DUtitle[title
]{Topic Title
}
1119 A
\emph{rubric
} is like an informal heading that doesn't correspond to the
1120 document's structure. It is typically highlighted in red (hence the name).
1122 \DUrubric{This is a rubric
}
1124 Topics and rubrics can be used at places where a
\hyperref[section-title
]{section title
} is not
1125 allowed (e.g. inside a directive).
1128 \subsubsection{2.14.5~~~Target Footnotes
%
1129 \label{target-footnotes
}%
1132 \DUfootnotetext{id29
}{id30
}{5}{%
1133 \url{http://www.python.org/
}
1136 \DUfootnotetext{id33
}{id34
}{6}{%
1137 \url{http://pygments.org/
}
1140 \DUfootnotetext{id35
}{id36
}{7}{%
1141 \url{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
}
1144 \DUfootnotetext{id39
}{id40
}{8}{%
1145 \url{http://docutils.sourceforge.net/
}
1148 \DUfootnotetext{id41
}{id42
}{9}{%
1153 \subsubsection{2.14.6~~~Replacement Text
%
1154 \label{replacement-text
}%
1157 I recommend you try
\href{http://www.python.org/
}{Python,
\emph{the
} best language around
}\DUfootnotemark{id32
}{id29
}{5}.
1160 \subsubsection{2.14.7~~~Compound Paragraph
%
1161 \label{compound-paragraph
}%
1164 Compound
1, paragraph
1.
1166 Compound
1, paragraph
2.
1170 \item Compound
1, list item one.
1172 \item Compound
1, list item two.
1176 Another compound statement:
1178 Compound
2, a literal block:
1180 \begin{quote
}{\ttfamily \raggedright \noindent
1181 Compound~
2,~literal.
1184 Compound
2, this is a test.
1186 Compound
3, only consisting of one paragraph.
1188 \begin{quote
}{\ttfamily \raggedright \noindent
1190 This~one~starts~with~a~literal~block.
1193 Compound
4, a paragraph.
1195 Now something
\emph{really
} perverted -
{}- a nested compound block. This is
1196 just to test that it works at all; the results don't have to be
1199 Compound
5, block
1 (a paragraph).
1201 Compound
6, block
2 in compound
5.
1203 Compound
6, another paragraph.
1205 Compound
5, block
3 (a paragraph).
1207 Compound
7, with a table inside:
1209 \setlength{\DUtablewidth}{\linewidth}
1210 \begin{longtable*
}[c
]{|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|
}
1232 Compound
7, a paragraph after the table.
1234 Compound
7, another paragraph.
1237 \subsubsection{2.14.8~~~Parsed Literal Blocks
%
1238 \label{parsed-literal-blocks
}%
1241 \begin{quote
}{\ttfamily \raggedright \noindent
1242 This~is~a~parsed~literal~block.\\
1243 ~~~~This~line~is~indented.~~The~next~line~is~blank.\\
1245 Inline~markup~is~supported,~e.g.~
\emph{emphasis
},~
\textbf{strong
},~
\texttt{literal\\
1246 text
},~footnotes
\DUfootnotemark{id22
}{id8
}{1},~
%
1247 \phantomsection\label{hyperlink-targets
}hyperlink~targets,~and~
\href{http://www.python.org/
}{references
}.
1252 \subsubsection{2.14.9~~~Code
%
1256 Blocks of source code can be set with the
\DUroletitlereference{code
} directive. If the code
1257 language is specified, the content is parsed and tagged by the
\href{http://pygments.org/
}{Pygments
}\DUfootnotemark{id34
}{id33
}{6}
1258 syntax highlighter and can be formatted with a style sheet. (Code parsing
1259 is turned off using the
\texttt{syntax-highlight
} config setting in the test
1260 conversions in order to get identical results with/without installed
1261 Pygments highlighter.)
1263 \begin{quote
}{\ttfamily \raggedright \noindent
1264 print~'This~is~Python~code.'
1268 The
\texttt{:number-lines:
} option (with optional start value) generates line
1271 \begin{quote
}{\ttfamily \raggedright \noindent
1272 \DUrole{ln
}{~
8~
}\#~print~integers~from~
0~to~
9:\\
1273 \DUrole{ln
}{~
9~
}for~i~in~range(
10):\\
1274 \DUrole{ln
}{10~
}~~~~print~i
1278 For inline code snippets, there is the
\DUroletitlereference{code
} role, which can be used
1279 directly (the code will not be parsed/tagged, as the language is not
1280 known) or as base for special code roles, e.g.,
1286 Docutils uses LaTeX syntax for math directives and roles:
1287 \texttt{\DUrole{code
}{\DUrole{latex
}{\DUrole{tex
}{\textbackslash{}alpha = f(x)
}}}} prints $
\alpha = f(x)$.
1291 The
\texttt{:code:
} option of the
\DUroletitlereference{include
} directive sets the included content
1292 as a code block, here the rst file
\texttt{header
\_footer.txt
} with line numbers:
1294 \begin{quote
}{\ttfamily \raggedright \noindent
1295 \DUrole{ln
}{1~
}..~header::~Document~header\\
1296 \DUrole{ln
}{2~
}..~footer::~Document~footer
1301 \subsection{2.15~~~Substitution Definitions
%
1302 \label{substitution-definitions
}%
1305 An inline image (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}) example:
1307 (Substitution definitions are not visible in the HTML source.)
1310 \subsection{2.16~~~Comments
%
1316 % Comments begin with two dots and a space. Anything may
1317 % follow, except for the syntax of footnotes, hyperlink
1318 % targets, directives, or substitution definitions.
1320 % Double-dashes -- "--" -- must be escaped somehow in HTML output.
1322 % Comments may contain non-ASCII characters: ä ö ü æ ø å
1324 (View the HTML source to see the comment.)
1327 \subsection{2.17~~~Raw text
%
1331 This does not necessarily look nice, because there may be missing white space.
1333 It's just there to freeze the behavior.
1339 \DUrole{myclass
}{Another test with myclass set.
}
1341 This is the
\DUrole{myrawroleclass
}{fourth test
} with myrawroleclass set.
1343 Fifth test in LaTeX.\
\Line two.
1346 \subsection{2.18~~~Container
%
1354 % currently not implemented in LaTeX:
1355 % .. include:: data/header_footer.txt
1358 \subsection{2.19~~~Colspanning tables
%
1359 \label{colspanning-tables
}%
1362 This table has a cell spanning two columns:
1364 \setlength{\DUtablewidth}{\linewidth}
1365 \begin{longtable*
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.086\DUtablewidth}|
}
1367 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1383 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1398 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1436 \subsection{2.20~~~Rowspanning tables
%
1437 \label{rowspanning-tables
}%
1440 Here's a table with cells spanning several rows:
1442 \setlength{\DUtablewidth}{\linewidth}
1443 \begin{longtable*
}[c
]{|p
{0.296\DUtablewidth}|p
{0.156\DUtablewidth}|p
{0.226\DUtablewidth}|
}
1446 Header row, column
1
1447 (header rows optional)
1457 Header row, column
1
1458 (header rows optional)
1466 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1470 body row
1, column
1
1479 &
\multirow{2}{0.16\DUtablewidth}{%
1482 } &
\multirow{2}{0.23\DUtablewidth}{%
1495 \subsection{2.21~~~Custom Roles
%
1496 \label{custom-roles
}%
1501 \item A role based on an existing role.
1503 \texttt{\DUrole{custom
}{one
}} \texttt{\DUrole{custom
}{two
}} \texttt{\DUrole{custom
}{three
}}
1507 \DUrole{customnew
}{one two three
}
1509 \item A role with class attribute.
1511 \DUrole{special
}{interpreted text
}
1513 \item A language-switching role:
1515 Let's count in German
\otherlanguage{ngerman}{eins zwei drei
}.
1517 \item A role with multiple class attributes, styled with raw directives:
1519 \newcommand{\DUrolegreen}[1]{\textcolor{green
}{#1}}
1520 \newcommand{\DUrolesc}[1]{\textsc{#1}}
1522 The following works in most browsers but does not validate
1523 (
\texttt{<style>
} is only allowed in the
document head):
1525 \begin{quote
}{\ttfamily \raggedright \noindent
1528 ~~<style~type="text/css"><!-
{}-\\
1529 ~~~.green~\
{color:~green;\
}\\
1530 ~~~.sc~\
{font-variant:~small-caps;\
}\\
1535 \otherlanguage{british
}{\DUrole{green
}{\DUrole{sc
}{British colourful text in small-caps
}}}.
1540 \subsection{2.22~~~Mathematics
%
1541 \label{mathematics
}%
1544 Docutils supports inline math with the prefix or postfix
\texttt{:math:
}
1545 role specificator, $n! +
\sin(x_n^
2)$ and $A_
\text{c
} =
1546 \frac{\pi}{4} d^
2$, as well as displayed math via the
1547 \DUroletitlereference{math
} directive:
1550 f(
\epsilon) =
\frac{1}{1 +
\exp\left(
\frac{\varepsilon}{k_
\text{B
}T
}\right)
}
1552 Content may start on the first line of the directive, e.g.
1555 N =
\frac{\text{number of apples
}}{7}
1557 Equations can be labeled with a reference name using the
\texttt{:name:
} option.
1558 See
\hyperref[eq-m
]{eq:M
} and
\hyperref[eq-schrodinger
]{eq:schrödinger
} below.
1560 The determinant of the matrix
1563 \mathbf{M
} =
\left(
\begin{matrix
}a&b\
\c&d
\end{matrix
}\right)
1567 is $|
\mathbf{M
}| = ad - bc$.
1569 More than one display math block can be put in one math directive.
1570 For example, the following sum and integral with limits:
1573 \int_0^
1 x^n dx =
\frac{1}{n +
1}
1576 \sum_{n=
1}^m n =
\frac{m(m+
1)
}{2}
1578 LaTeX-supported Unicode math symbols can be used in math roles and
1581 The Schrödinger equation
1584 i
\hbar \frac{\partial }{\partial t
}\Psi =
\hat{H
}\Psi ,
1586 \label{eq-schrodinger
}
1588 with the
\emph{wave function
} $
\Psi $, describes how the quantum state of a
1589 physical system changes in time.
1592 \item[{Math-Accents:
}] \leavevmode
1593 \setlength{\DUtablewidth}{\linewidth}
1594 \begin{longtable*
}[c
]{p
{0.315\DUtablewidth}p
{0.315\DUtablewidth}p
{0.315\DUtablewidth}}
1596 $
\acute{a
}$
\texttt{\textbackslash{}acute\
{a\
}}
1598 $
\dot{t
}$
\texttt{\textbackslash{}dot\
{t\
}}
1600 $
\hat{\gamma}$
\texttt{\textbackslash{}hat\
{\textbackslash{}gamma\
}}
1603 $
\grave{a
}$
\texttt{\textbackslash{}grave\
{a\
}}
1605 $
\ddot{t
}$
\texttt{\textbackslash{}ddot\
{t\
}}
1607 $
\tilde{\alpha}$
\texttt{\textbackslash{}tilde\
{\textbackslash{}alpha\
}}
1610 $
\breve{x
}$
\texttt{\textbackslash{}breve\
{x\
}}
1612 $
\dddot{t
}$
\texttt{\textbackslash{}dddot\
{t\
}}
1614 $
\vec{\imath}$
\texttt{\textbackslash{}vec\
{\textbackslash{}imath\
}}
1617 $
\check{a
}$
\texttt{\textbackslash{}check\
{a\
}}
1619 $
\bar{a
}$
\texttt{\textbackslash{}bar\
{a\
}}
1621 $
\vec{R
}$
\texttt{\textbackslash{}vec\
{R\
}}
1630 Modulation Transfer Function:
1633 \text{MTF
} =
\left|
\frac{\mathcal{F
}\
{s(x)\
}}
1634 {\mathcal{F
}\
{ s(x)\
} |_
{\omega _
{x
}=
0}}\right|
1635 =
\mathrm{abs
}\left(
\frac
1636 {\int _
{-
\infty }^
{\infty }s(x)
\mathrm{e
}^
{\mathrm{i
}\omega _
{x
}x
}\mathrm{d
}{x
}}
1637 {\int _
{-
\infty }^
{\infty }s(x)
\mathrm{d
}{x
}}
1640 Math split over two lines: If a double backslash is detected outside a
1641 \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}
1642 \texttt{align
} environment:
1645 s_
{\mathrm{out
}}(x) & = s_
{\mathrm{in
}}(x') * s_
\delta (x-x') \\
1646 & =
\int s_
{\mathrm{in
}}(x')s_
\delta (x-x')
\mathrm{d
}x'
1648 Cases (``manually'', with
\texttt{matrix
} environment):
1651 \mathrm{sgn
}(x) =
\left\
{\begin{matrix
}
1656 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
1657 HTML writers with
\texttt{-
{}-math-output=MathML
}):
1660 \mathrm{sgn
}(x) =
\begin{cases
}
1666 \section{3~~~Tests for the LaTeX writer
%
1667 \label{tests-for-the-latex-writer
}%
1670 Test syntax elements which may cause trouble for the LaTeX writer but might
1671 not need to be tested with other writers (e.g. the HTML writer).
1674 \subsection{3.1~~~Custom Roles in LaTeX
%
1675 \label{custom-roles-in-latex
}%
1680 \item Role names and class arguments are converted to conform to the
1681 regular expression
\texttt{{[}a-z
{]}{[}-a-z0-
9{]}*
} (letters are downcased,
1682 accents and similar decoration is stripped, non-conforming
1683 characters are replaced by a hyphen).
1685 Class arguments may contain numbers and hyphens, which need special
1686 treatment in LaTeX command names.
1688 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}}
1690 \item With LaTeX, roles can be styled within the
document using the
\DUroletitlereference{raw
}
1693 \newcommand{\DUrolelarge}[1]{{\large #1}}
1695 \@namedef
{DUrolesmall-caps
}{\textsc}
1696 \@namedef
{DUrolecustom4
}{\textbf}
1699 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}} in large, bold, small-caps.
1701 \item Custom roles can be based on standard roles:
1703 This is a
\emph{\DUrole{custom-emphasis
}{customized emphasis text role
}}
1705 This is a
\texttt{\DUrole{custom-literal
}{customized literal text role
}}
1707 This is a
\textbf{\DUrole{custom-strong
}{customized strong text role
}}
1709 This is a
\textsubscript{\DUrole{custom-subscript
}{customized subscript text role
}}
1711 This is a
\textsuperscript{\DUrole{custom-superscript
}{customized superscript text role
}}
1713 This is a
\DUroletitlereference{\DUrole{custom-title-reference
}{customized title-reference text role
}}
1718 \subsection{3.2~~~More Tables
%
1719 \label{more-tables
}%
1722 A multicolumn table with multi-paragraph rowspanning cells:
1724 \setlength{\DUtablewidth}{\linewidth}
1725 \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}|
}
1731 &
\multicolumn{3}{p
{0.41\DUtablewidth}|
}{
1734 With a second paragraph
1739 \multicolumn{2}{|p
{0.31\DUtablewidth}|
}{
1742 With a second paragraph
1755 &
\multicolumn{2}{p
{0.36\DUtablewidth}|
}{
1756 multicolumn
3 (one line,
1757 but very very very very
1773 &
\multicolumn{3}{p
{0.38\DUtablewidth}|
}{
1779 % This file is used by the standalone_rst_latex test.
1782 \subsection{3.3~~~Option lists
%
1786 The LaTeX-
2e description environment is used for definition lists.
1787 The definition is continued on the same line as the term, this should
1788 not happen if a option-list is at the top of the definition.
1790 If the option list is not at the first element in the definition, it
1791 is contained in a quote
1795 \begin{DUoptionlist
}
1797 \item[-
{}-help
] show help
1806 \item[{In a definition list:
}] \leavevmode %
1807 \begin{DUoptionlist
}
1809 \item[-
{}-help
] show help
1818 \subsection{3.4~~~Monospaced non-alphanumeric characters
%
1819 \label{monospaced-non-alphanumeric-characters
}%
1822 These are all ASCII characters except a-zA-Z0-
9 and space:
1824 \texttt{!!!"
{}"
{}"\#\#\#\$\$\$\%\%\%\&\&\&'
{}'
{}'((()))***+++,
{},
{},-
{}-
{}-...///:::
}
1826 \texttt{;;;<
{}<
{}<===>
{}>
{}>???@@@
{[}{[}{[}\textbackslash{}\textbackslash{}\textbackslash{}{]}{]}{]}\textasciicircum{}\textasciicircum{}\textasciicircum{}\_\_\_`
{}`
{}`\
{\
{\
{|||\
}\
}\
}\textasciitilde{}\textasciitilde{}\textasciitilde{}}
1828 \texttt{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
1830 The two lines of non-alphanumeric characters should both have the same
1831 width as the third line.
1834 \subsection{3.5~~~Non-ASCII characters
%
1835 \label{non-ascii-characters
}%
1838 Punctuation and footnote symbols
1840 \setlength{\DUtablewidth}{\linewidth}
1841 \begin{longtable*
}[c
]{|p
{0.028\DUtablewidth}|p
{0.424\DUtablewidth}|
}
1858 single turned comma quotation mark
1864 single comma quotation mark
1870 low single comma quotation mark
1876 double turned comma quotation mark
1882 double comma quotation mark
1888 low double comma quotation mark
1942 left-right double arrow
1947 The
\DUroletitlereference{Latin-
1 extended
} Unicode block
1949 \setlength{\DUtablewidth}{\linewidth}
1950 \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}|
}
2208 \item The following line should not be wrapped, because it uses
2209 no-break spaces (
\textbackslash{}u00a0):
2211 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
2213 \item Line wrapping with/without breakpoints marked by soft hyphens
2214 (
\textbackslash{}u00ad):
2216 pdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-sch
2218 pdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrisch
2220 \item The currency sign (
\textbackslash{}u00a4) is not supported by all fonts
2221 (some have an Euro sign at its place). You might see an error
2224 \begin{quote
}{\ttfamily \raggedright \noindent
2225 !~Package~textcomp~Error:~Symbol~
\textbackslash{}textcurrency~not~provided~by\\
2226 (textcomp)~~~~~~~~~~~~~~~~font~family~ptm~in~TS1~encoding.\\
2227 (textcomp)~~~~~~~~~~~~~~~~Default~family~used~instead.
2231 (which in case of font family ptm is a false positive). Add either
2235 turn the error in a warning, use the default symbol (bitmap), or
2237 \item[{force,almostfull:
}]
2238 use the symbol provided by the font at the users
2243 to the
document options or use a different font package.
2248 \subsection{3.6~~~Encoding special chars
%
2249 \label{encoding-special-chars
}%
2252 The LaTeX Info pages lists under ``
2.18 Special Characters''
2256 The following characters play a special role in LaTeX and are called
2257 ``special printing characters'', or simply ``special characters''.
2261 \# \$ \% \&
\textasciitilde{} \_ \textasciicircum{} \textbackslash{} \
{ \
}
2267 The special chars verbatim:
2269 \begin{quote
}{\ttfamily \raggedright \noindent
2270 \#~\$~\%~\&~
\textasciitilde{}~
\_~
\textasciicircum{}~
\textbackslash{}~\
{~\
}
2274 However also
\emph{square brackets
} {[}{]} need special care.
2278 item and all the other commands with optional arguments check
2279 if the token right after the macro name is an opening bracket.
2280 In that case the contents between that bracket and the following
2281 closing bracket on the same grouping level are taken as the
2282 optional argument. What makes this unintuitive is the fact that
2283 the square brackets aren't grouping characters themselves, so in
2284 your last example item
{[}{[}...
{]}{]} the optional argument consists of
2285 {[}... (without the closing bracket).
2289 Compare the items in the following lists:
2295 \item {[}bracketed
{]} item
2300 \item[{simple
}] \leavevmode
2303 \item[{{[}bracketed
{]}}] \leavevmode
2308 The OT1 font-encoding has different characters for the less-than,
2309 greater-than and bar, < | >, except for typewriter font
\DUroletitlereference{cmtt
}:
2311 \begin{quote
}{\ttfamily \raggedright \noindent
2317 \subsection{3.7~~~Hyperlinks and -targets
%
2318 \label{hyperlinks-and-targets
}%
2321 In LaTeX, we must set an explicit anchor (
\texttt{\textbackslash{}phantomsection
}) for a
2323 \phantomsection\label{hypertarget-in-plain-text
}hypertarget in plain text or in a figure but not in a longtable or
2326 \setlength{\DUtablewidth}{\linewidth}
2327 \begin{longtable
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
2328 \caption{Table with
%
2329 \label{hypertarget-in-table-title
}hypertarget in table title.
}\\
2342 \phantomsection\label{figure-label
}
2343 \noindent\makebox[\textwidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
2344 \caption{Figure with
%
2345 \label{hypertarget-in-figure-caption
}hypertarget in figure caption.
}
2348 \phantomsection\label{hypertarget-in-figure-legend
}hypertarget in figure legend.
2352 \includegraphics{../../../docs/user/rst/images/biohazard.png
}
2353 \phantomsection\label{image-label
}
2355 See
\hyperref[hypertarget-in-plain-text
]{hypertarget in plain text
},
2356 \hyperref[table-label
]{table label
},
\hyperref[hypertarget-in-table-title
]{hypertarget in table title
},
2357 \hyperref[figure-label
]{figure label
},
\hyperref[hypertarget-in-figure-caption
]{hypertarget in figure caption
},
2358 \hyperref[hypertarget-in-figure-legend
]{hypertarget in figure legend
}, and
2359 \hyperref[image-label
]{image label
}.
2362 \subsection{3.8~~~External references
%
2363 \label{external-references
}%
2366 Long URLs should be wrapped in the PDF.
2367 This can be achieved with the url command which is used by the LaTeX writer
2368 whenever the content (name) of a reference node equals the link URL.
2371 \item[{Example:
}] \leavevmode
2372 a long URL that should wrap in the output
2373 \url{http://docutils.sourceforge.net/docs/user/latex.html\#id79
}
2377 If the argument contains any ``\%'', ``\#'', or ``
\textasciicircum{}\textasciicircum{}'', or ends with
\texttt{\textbackslash{}}, it can't
2378 be used in the argument to another command. The argument must not contain
2381 The characters
\textasciicircum{}, \
{, \
}, and
\texttt{\textbackslash{}} are invalid in a ``http:'' or ``ftp:'' URL
2382 and not recognized as part of it:
2384 \begin{DUlineblock
}{0em
}
2385 \item[] \url{http://www.example.org
}/strange
\textasciicircum{}\textasciicircum{}name
2386 \item[] \url{http://www.example.org
}\textbackslash{}using
\textbackslash{}DOS
\textbackslash{}paths
\textbackslash{}
2387 \item[] \url{http://www.example.org/XML
}/strange\
{n\
}ame
2390 They can, however be used in paths and/or filenames.
2392 Handling by the LaTeX writer:
2396 \item \texttt{\#
},
\texttt{\textbackslash{}} and
\texttt{\%
} are escaped:
2398 \begin{DUlineblock
}{0em
}
2399 \item[] \href{http://www.w3.org/XML/Schema\#dev
}{URL with \#
}
2400 \url{http://www.w3.org/XML/Schema\#dev
}
2401 \item[] \href{http://www.w3.org/XML/Schema\%dev
}{URL with \%
}
2402 \url{http://example.org/Schema\%dev
}
2403 \item[] \href{A:DOS\
\path\\
}{file with DOS path
}\DUfootnotemark{id42
}{id41
}{9} \url{A:DOS\
\path\\
}\DUfootnotemark{id43
}{id41
}{9}
2406 \DUadmonition[note
]{
2407 \DUtitle[note
]{Note
}
2409 These URLs are typeset inside a LaTeX command without error.
2411 \begin{DUlineblock
}{0em
}
2412 \item[] \url{http://www.w3.org/XML/Schema\#dev
}
2413 \item[] \url{http://example.org/Schema\%dev
}
2414 \item[] \url{A:DOS\
\path\\
}\DUfootnotemark{id44
}{id41
}{9}
2422 \item \textasciicircum{}\textasciicircum{} LaTeX's special syntax for characters results in ``strange'' replacements
2423 (both with href and url). A warning is given.
2425 \href{../strange^^name
}{file with
\textasciicircum{}\textasciicircum{}}:
2426 \url{../strange^^name
}
2428 \item Unbalanced braces, \
{ or \
}, will fail (both with href and url):
2430 \begin{quote
}{\ttfamily \raggedright \noindent
2431 `file~with~\
{~<../strange\
{name>`
\_\_\\
2432 `<../strange\
{name>`
\_\_
2436 while balanced braces are suported:
2438 \begin{DUlineblock
}{0em
}
2439 \item[] \url{../strange
{n
}ame
}
2440 \item[] \url{../st
{r
}ange
{n
}ame
}
2441 \item[] \url{../
{st
{r
}ange
{n
}ame
}}
2447 \subsection{3.9~~~Section titles with
\hyperref[inline-markup
]{inline markup
}%
2448 \label{section-titles-with-inline-markup
}%
2452 \subsubsection{3.9.1~~~
\emph{emphasized
}, H
\textsubscript{2}O and $x^
2$
%
2453 \label{emphasized-h2o-and-x-
2}%
2457 \subsubsection{3.9.2~~~Substitutions work
%
2458 \label{substitutions-fail
}%
2462 \subsection{3.10~~~Deeply nested sections
%
2463 \label{deeply-nested-sections
}%
2469 \subsubsection{3.10.1~~~Level
3%
2476 \paragraph{3.10.1.1~~~level
4%
2483 \subparagraph{3.10.1.1.1~~~level
5%
2487 (depending on the
document class)
2490 \DUtitle[sectionVI
]{3.10.1.1.1.1~~~level
6%
2494 an unsupported level.
2496 % unusual combinations (from newlatex, for interactive testing)
2497 % .. include:: data/latex.txt
2499 % Preface for System Messages:
2502 \section{4~~~Error Handling
%
2503 \label{error-handling
}%
2506 Any errors caught during processing will generate system messages.
2508 There should be five messages in the following, auto-generated
2509 section, ``Docutils System Messages'':
2511 % section should be added by Docutils automatically
2514 \section[Docutils System Messages
]{\color{red
}Docutils System Messages
%
2517 \DUadmonition[system-message
]{
2518 \DUtitle[system-message
]{system-message
}
2519 \raisebox{1em
}{\hypertarget{id27
}{}}
2521 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
104
2524 Undefined substitution referenced: ``problematic''.
2527 \DUadmonition[system-message
]{
2528 \DUtitle[system-message
]{system-message
}
2529 \raisebox{1em
}{\hypertarget{id45
}{}}
2531 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
391
2534 Unknown target name: ``
5''.
2537 \DUadmonition[system-message
]{
2538 \DUtitle[system-message
]{system-message
}
2539 \raisebox{1em
}{\hypertarget{id47
}{}}
2541 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
400
2544 Unknown target name: ``nonexistent''.
2547 \DUadmonition[system-message
]{
2548 \DUtitle[system-message
]{system-message
}
2549 \raisebox{1em
}{\hypertarget{id49
}{}}
2551 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
427
2554 Unknown target name: ``hyperlink reference without a target''.
2557 \DUadmonition[system-message
]{
2558 \DUtitle[system-message
]{system-message
}
2559 \raisebox{1em
}{\hypertarget{id51
}{}}
2561 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
440
2564 Duplicate target name, cannot be used as a unique reference: ``duplicate target names''.