1 \documentclass[a4paper]{article
}
2 % generated by Docutils <http://docutils.sourceforge.net/>
3 % rubber: set program xelatex
4 \usepackage[no-sscript
]{xltxtra
} % loads fixltx2e, metalogo, xunicode, fontspec
5 \defaultfontfeatures{Scale=MatchLowercase
}
7 \usepackage{polyglossia
}
8 \setdefaultlanguage{english
}
9 \setotherlanguages{german,british,french
}
11 \usepackage{float
} % float configuration
12 \floatplacement{figure
}{H
} % place figures here definitely
15 \usepackage{longtable
}
17 \setlength{\extrarowheight}{2pt
}
18 \newlength{\DUtablewidth} % internal use in tables
21 %%% Custom LaTeX preamble
22 % Linux Libertine (free, wide coverage, not only for Linux)
23 \setmainfont{Linux Libertine O
}
24 \setsansfont{Linux Biolinum O
}
25 \setmonofont[HyphenChar=None
]{DejaVu Sans Mono
}
27 %%% User specified packages and stylesheets
29 %%% Fallback definitions for Docutils-specific commands
31 % providelength (provide a length variable and set default, if it is new)
32 \providecommand*
{\DUprovidelength}[2]{
33 \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{}
37 \providecommand*
{\DUtitleabstract}[1]{\centerline{\textbf{#1}}}
39 % admonition (specially marked topic)
40 \providecommand{\DUadmonition}[2][class-arg
]{%
41 % try \DUadmonition#1{#2}:
42 \ifcsname DUadmonition
#1\endcsname%
43 \csname DUadmonition
#1\endcsname{#2}%
46 \fbox{\parbox{0.9\textwidth}{#2}}
52 \@namedef
{DUrolealign-center
}{\centering}
57 \providecommand{\DUtopicdedication}[1]{\begin{center
}#1\end{center
}}
59 % docinfo (width of docinfo table)
60 \DUprovidelength{\DUdocinfowidth}{0.9\textwidth}
62 % error admonition title
63 \providecommand*
{\DUtitleerror}[1]{\DUtitle{\color{red
}#1}}
65 % fieldlist environment
66 \ifthenelse{\isundefined{\DUfieldlist}}{
67 \newenvironment{DUfieldlist
}%
69 {\enddescription\endquote}
71 % numeric or symbol footnotes with hyperlinks
72 \providecommand*
{\DUfootnotemark}[3]{%
73 \raisebox{1em
}{\hypertarget{#1}{}}%
74 \hyperlink{#2}{\textsuperscript{#3}}%
76 \providecommand{\DUfootnotetext}[4]{%
78 \renewcommand{\thefootnote}{%
79 \protect\raisebox{1em
}{\protect\hypertarget{#1}{}}%
80 \protect\hyperlink{#2}{#3}}%
85 % inline markup (custom roles)
86 % \DUrole{#1}{#2} tries \DUrole#1{#2}
87 \providecommand*
{\DUrole}[2]{%
88 \ifcsname DUrole
#1\endcsname%
89 \csname DUrole
#1\endcsname{#2}%
90 \else% backwards compatibility: try \docutilsrole#1{#2}
91 \ifcsname docutilsrole
#1\endcsname%
92 \csname docutilsrole
#1\endcsname{#2}%
100 \ifthenelse{\isundefined{\DUlegend}}{
101 \newenvironment{DUlegend
}{\small}{}
104 % lineblock environment
105 \DUprovidelength{\DUlineblockindent}{2.5em
}
106 \ifthenelse{\isundefined{\DUlineblock}}{
107 \newenvironment{DUlineblock
}[1]{%
108 \list{}{\setlength{\partopsep}{\parskip}
109 \addtolength{\partopsep}{\baselineskip}
110 \setlength{\topsep}{0pt
}
111 \setlength{\itemsep}{0.15\baselineskip}
112 \setlength{\parsep}{0pt
}
113 \setlength{\leftmargin}{#1}}
119 % optionlist environment
120 \providecommand*
{\DUoptionlistlabel}[1]{\bf #1 \hfill}
121 \DUprovidelength{\DUoptionlistindent}{3cm
}
122 \ifthenelse{\isundefined{\DUoptionlist}}{
123 \newenvironment{DUoptionlist
}{%
124 \list{}{\setlength{\labelwidth}{\DUoptionlistindent}
125 \setlength{\rightmargin}{1cm
}
126 \setlength{\leftmargin}{\rightmargin}
127 \addtolength{\leftmargin}{\labelwidth}
128 \addtolength{\leftmargin}{\labelsep}
129 \renewcommand{\makelabel}{\DUoptionlistlabel}}
134 \DUprovidelength{\pdfpxdimen}{1bp
}
137 % rubric (informal heading)
138 \providecommand*
{\DUrubric}[2][class-arg
]{%
139 \subsubsection*
{\centering\textit{\textmd{#2}}}}
141 % sidebar (text outside the main text flow)
142 \providecommand{\DUsidebar}[2][class-arg
]{%
144 \colorbox[gray
]{0.80}{\parbox{0.9\textwidth}{#2}}
148 % subtitle (for topic/sidebar)
149 \providecommand*
{\DUsubtitle}[2][class-arg
]{\par\emph{#2}\smallskip}
151 % title for topics, admonitions and sidebar
152 \providecommand*
{\DUtitle}[2][class-arg
]{%
153 % call \DUtitle#1{#2} if it exists:
154 \ifcsname DUtitle
#1\endcsname%
155 \csname DUtitle
#1\endcsname{#2}%
157 \smallskip\noindent\textbf{#2}\smallskip%
161 % titlereference role
162 \providecommand*
{\DUroletitlereference}[1]{\textsl{#1}}
164 % topic (quote with heading)
165 \providecommand{\DUtopic}[2][class-arg
]{%
166 \ifcsname DUtopic
#1\endcsname%
167 \csname DUtopic
#1\endcsname{#2}%
169 \begin{quote
}#2\end{quote
}
173 % transition (break, fancybreak, anonymous section)
174 \providecommand*
{\DUtransition}[1][class-arg
]{%
175 \hspace*
{\fill}\hrulefill\hspace*
{\fill}
176 \vskip 0.5\baselineskip
180 \ifthenelse{\isundefined{\hypersetup}}{
181 \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue
]{hyperref
}
182 \urlstyle{same
} % normal text font (alternatives: tt, rm, sf)
185 pdftitle=
{reStructuredText Test Document
},
186 pdfauthor=
{David Goodger;Me;Myself;I
}
190 \title{\phantomsection%
191 reStructuredText Test Document
%
192 \label{restructuredtext-test-
document}%
195 \large{Examples of Syntax Constructs
}%
196 \label{examples-of-syntax-constructs
}%
207 \begin{tabularx
}{\DUdocinfowidth}{lX
}
216 \href{mailto:goodger@python.org
}{goodger@python.org
} \\
223 \textbf{Organization
}: &
226 Now, or yesterday. Or maybe even
\emph{before
} yesterday. \\
228 This is a "work in progress" \\
230 is managed by a version control system. \\
233 \textbf{Copyright
}: &
234 This
document has been placed in the public domain. You
235 may do with it as you wish. You may copy, modify,
236 redistribute, reattribute, sell, buy, rent, lease,
237 destroy, or improve it, quote it at length, excerpt,
238 incorporate, collate, fold, staple, or mutilate it, or do
239 anything else to it that your or anyone else's heart
241 \textbf{field name
}: &
242 This is a "generic bibliographic field".
244 \textbf{field name "
2"
}: &
245 Generic bibliographic fields may contain multiple body elements.
252 \DUtopic[dedication
]{
253 \DUtitle[dedication
]{Dedication
}
255 For Docutils users \& co-developers.
259 \DUtitle[abstract
]{Abstract
}
261 This is a test
document, containing at least one example of each
262 reStructuredText construct.
265 % This is a comment. Note how any initial comments are moved by
266 % transforms to after the document title, subtitle, and docinfo.
268 % Above is the document title, and below is the subtitle.
269 % They are transformed from section titles after parsing.
271 % bibliographic fields (which also require a transform):
273 \pagebreak[4] % start ToC on new page
275 \phantomsection\label{table-of-contents
}
276 \pdfbookmark[1]{Table of Contents
}{table-of-contents
}
277 \renewcommand{\contentsname}{Table of Contents
}
282 %___________________________________________________________________________
284 \section*
{\phantomsection%
285 1 Structural Elements
%
286 \addcontentsline{toc
}{section
}{1 Structural Elements
}%
287 \label{structural-elements
}%
291 %___________________________________________________________________________
293 \subsection*
{\phantomsection%
295 \addcontentsline{toc
}{subsection
}{1.1 Section Title
}%
296 \label{section-title
}%
298 \subsubsection*
{Section Subtitle
}
300 That's it, the text just above this line.
303 %___________________________________________________________________________
305 \subsection*
{\phantomsection%
307 \addcontentsline{toc
}{subsection
}{1.2 Empty Section
}%
308 \label{empty-section
}%
312 %___________________________________________________________________________
314 \subsection*
{\phantomsection%
316 \addcontentsline{toc
}{subsection
}{1.3 Transitions
}%
323 %___________________________________________________________________________
327 It divides the section. Transitions may also occur between sections:
330 %___________________________________________________________________________
335 %___________________________________________________________________________
337 \section*
{\phantomsection%
339 \addcontentsline{toc
}{section
}{2 Body Elements
}%
340 \label{body-elements
}%
344 %___________________________________________________________________________
346 \subsection*
{\phantomsection%
348 \addcontentsline{toc
}{subsection
}{2.1 Paragraphs
}%
355 %___________________________________________________________________________
357 \subsubsection*
{\phantomsection%
359 \addcontentsline{toc
}{subsubsection
}{2.1.1 Inline Markup
}%
360 \label{inline-markup
}%
363 Paragraphs contain text and may contain inline markup:
\emph{emphasis
},
364 \textbf{strong emphasis
},
\texttt{inline literals
}, standalone hyperlinks
365 (
\url{http://www.python.org
}), external hyperlinks (
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id30
}{id29
}{5}), internal
366 cross-references (
\hyperref[example
]{example
}), external hyperlinks with embedded URIs
367 (
\href{http://www.python.org
}{Python web site
}),
\href{http://www.python.org/
}{anonymous hyperlink
368 references
}\DUfootnotemark{id35
}{id29
}{5} (
\href{http://docutils.sourceforge.net/
}{a second reference
}\DUfootnotemark{id37
}{id36
}{7}), footnote references (manually
369 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
}]),
370 substitution references (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}), and
%
371 \phantomsection\label{inline-hyperlink-targets
}inline hyperlink targets
372 (see
\hyperref[targets
]{Targets
} below for a reference back to here). Character-level
373 inline markup is also possible (although exceedingly ugly!) in
\emph{re
}\texttt{Structured
}\emph{Text
}. Problems are indicated by
%
374 \raisebox{1em
}{\hypertarget{id28
}{}}\hyperlink{id27
}{\textbf{\color{red
}|problematic|
}} text
375 (generated by processing errors; this one is intentional). Here is a
376 reference to the
\hyperref[doctitle
]{doctitle
} and the
\hyperref[subtitle
]{subtitle
}.
378 The default role for interpreted text is
\DUroletitlereference{Title Reference
}. Here are
379 some explicit interpreted text roles: a PEP reference (
\href{http://www.python.org/dev/peps/pep-
0287}{PEP
287}); an
380 RFC reference (
\href{http://www.faqs.org/rfcs/rfc2822.html
}{RFC
2822}); a
\textsubscript{subscript
}; a
\textsuperscript{superscript
};
381 and explicit roles for
\emph{standard
} \textbf{inline
}
384 % DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
386 Let's test wrapping and whitespace significance in inline literals:
387 \texttt{This is an example of --inline-literal --text, --including some--
388 strangely--hyphenated-words. ~Adjust-the-width-of-your-browser-window
389 to see how the text is wrapped. ~-- ---- -------- ~Now note ~ ~the
390 spacing ~ ~between the ~ ~words of ~ ~this sentence ~ ~(words
391 should ~ ~be grouped ~ ~in pairs).
}
393 If the
\texttt{--pep-references
} option was supplied, there should be a
394 live link to PEP
258 here.
397 %___________________________________________________________________________
399 \subsection*
{\phantomsection%
401 \addcontentsline{toc
}{subsection
}{2.2 Bullet Lists
}%
402 \label{bullet-lists
}%
411 \item Nested bullet list.
419 Paragraph
2 of item
2.
423 \item Nested bullet list.
437 \item This nested list should be compacted by the HTML writer.
439 \phantomsection\label{target
}
440 % Even if this item contains a target and a comment.
447 %___________________________________________________________________________
449 \subsection*
{\phantomsection%
450 2.3 Enumerated Lists
%
451 \addcontentsline{toc
}{subsection
}{2.3 Enumerated Lists
}%
452 \label{enumerated-lists
}%
454 \newcounter{listcnt0
}
455 \begin{list
}{\arabic{listcnt0
}.
}
457 \usecounter{listcnt0
}
458 \setlength{\rightmargin}{\leftmargin}
461 \item Arabic numerals.
462 \newcounter{listcnt1
}
463 \begin{list
}{\alph{listcnt1
})
}
465 \usecounter{listcnt1
}
466 \setlength{\rightmargin}{\leftmargin}
470 \newcounter{listcnt2
}
471 \begin{list
}{(
\roman{listcnt2
})
}
473 \usecounter{listcnt2
}
474 \setlength{\rightmargin}{\leftmargin}
478 \newcounter{listcnt3
}
479 \begin{list
}{\Alph{listcnt3
}.
}
481 \usecounter{listcnt3
}
482 \setlength{\rightmargin}{\leftmargin}
486 \newcounter{listcnt4
}
487 \begin{list
}{\Roman{listcnt4
})
}
489 \usecounter{listcnt4
}
490 \setlength{\rightmargin}{\leftmargin}
499 \item Lists that don't start at
1:
500 \setcounter{listcnt1
}{0}
501 \begin{list
}{\arabic{listcnt1
}.
}
503 \usecounter{listcnt1
}
504 \addtocounter{listcnt1
}{2}
505 \setlength{\rightmargin}{\leftmargin}
512 \setcounter{listcnt1
}{0}
513 \begin{list
}{\Alph{listcnt1
}.
}
515 \usecounter{listcnt1
}
516 \addtocounter{listcnt1
}{2}
517 \setlength{\rightmargin}{\leftmargin}
524 \setcounter{listcnt1
}{0}
525 \begin{list
}{\roman{listcnt1
}.
}
527 \usecounter{listcnt1
}
528 \addtocounter{listcnt1
}{2}
529 \setlength{\rightmargin}{\leftmargin}
539 %___________________________________________________________________________
541 \subsection*
{\phantomsection%
542 2.4 Definition Lists
%
543 \addcontentsline{toc
}{subsection
}{2.4 Definition Lists
}%
544 \label{definition-lists
}%
548 \item[{Term
}] \leavevmode
551 \item[{Term
}] \leavevmode (
\textbf{classifier
})
553 Definition paragraph
1.
555 Definition paragraph
2.
557 \item[{Term
}] \leavevmode
560 \item[{Term
}] \leavevmode (
\textbf{classifier one
})
561 (
\textbf{classifier two
})
568 %___________________________________________________________________________
570 \subsection*
{\phantomsection%
572 \addcontentsline{toc
}{subsection
}{2.5 Field Lists
}%
578 Field lists map field names to field bodies, like database
579 records. They are often part of an extension syntax. They are
580 an unambiguous variant of RFC
2822 fields.
582 \item[{how arg1 arg2:
}]
583 The field marker is a colon, the field name, and a colon.
585 The field body may contain one or more body elements, indented
586 relative to the field marker.
589 \DUrole{credits
}{This paragraph has the
\DUroletitlereference{credits
} class set. (This is actually not
590 about credits but just for ensuring that the class attribute
591 doesn't get stripped away.)
}
596 %___________________________________________________________________________
598 \subsection*
{\phantomsection%
600 \addcontentsline{toc
}{subsection
}{2.6 Option Lists
}%
601 \label{option-lists
}%
604 For listing command-line options:
608 \item[-a
] command-line option "a"
610 \item[-b file
] options can have arguments
611 and long descriptions
613 \item[--long
] options can be long also
615 \item[--input=file
] long options can also have
618 \item[--very-long-option
] The description can also start on the next line.
620 The description may contain multiple body elements,
621 regardless of where it starts.
623 \item[-x, -y, -z
] Multiple options are an "option group".
625 \item[-v, --verbose
] Commonly-seen: short \& long options.
627 \item[-
1 file, --one=file, --two file
] Multiple options with arguments.
629 \item[/V
] DOS/VMS-style options too
633 There must be at least two spaces between the option and the
637 %___________________________________________________________________________
639 \subsection*
{\phantomsection%
641 \addcontentsline{toc
}{subsection
}{2.7 Literal Blocks
}%
642 \label{literal-blocks
}%
645 Literal blocks are indicated with a double-colon ("::") at the end of
646 the preceding paragraph (over there
\texttt{-->
}). They can be indented:
648 \begin{quote
}{\ttfamily \raggedright \noindent
650 ~~~~text~=~'is~left~as-is'\\
651 ~~~~spaces
\_and\_linebreaks~=~'are~preserved'\\
652 ~~~~markup
\_processing~=~None
656 Or they can be quoted without indentation:
658 \begin{quote
}{\ttfamily \raggedright \noindent
661 >~Why~didn't~I~think~of~that?
666 %___________________________________________________________________________
668 \subsection*
{\phantomsection%
670 \addcontentsline{toc
}{subsection
}{2.8 Line Blocks
}%
674 This section tests line blocks. Line blocks are body elements which
675 consist of lines and other line blocks. Nested line blocks cause
678 \begin{DUlineblock
}{0em
}
679 \item[] This is a line block. It ends with a blank line.
681 \begin{DUlineblock
}{\DUlineblockindent}
682 \item[] New lines begin with a vertical bar ("|").
683 \item[] Line breaks and initial indent are significant, and preserved.
685 \begin{DUlineblock
}{\DUlineblockindent}
686 \item[] Continuation lines are also possible. A long line that is intended
687 to wrap should begin with a space in place of the vertical bar.
689 \item[] The left edge of a continuation line need not be aligned with
690 the left edge of the text above it.
694 \begin{DUlineblock
}{0em
}
695 \item[] This is a second line block.
697 \item[] Blank lines are permitted internally, but they must begin with a "|".
700 Another line block, surrounded by paragraphs:
702 \begin{DUlineblock
}{0em
}
703 \item[] And it's no good waiting by the window
704 \item[] It's no good waiting for the sun
705 \item[] Please believe me, the things you dream of
706 \item[] They don't fall in the lap of no-one
709 Take it away, Eric the Orchestra Leader!
713 \begin{DUlineblock
}{0em
}
714 \item[] A one, two, a one two three four
716 \item[] Half a bee, philosophically,
718 \begin{DUlineblock
}{\DUlineblockindent}
719 \item[] must,
\emph{ipso facto
}, half not be.
721 \item[] But half the bee has got to be,
723 \begin{DUlineblock
}{\DUlineblockindent}
724 \item[] \emph{vis a vis
} its entity. D'you see?
727 \item[] But can a bee be said to be
729 \begin{DUlineblock
}{\DUlineblockindent}
730 \item[] or not to be an entire bee,
732 \begin{DUlineblock
}{\DUlineblockindent}
733 \item[] when half the bee is not a bee,
735 \begin{DUlineblock
}{\DUlineblockindent}
736 \item[] due to some ancient injury?
746 A line block, like the following poem by Christian Morgenstern, can
747 also be centre-aligned:
749 \begin{DUlineblock
}{0em
}
750 \otherlanguage{german
}{\DUrole{align-center
}{
751 \item[] \textbf{Die Trichter
}
753 \item[] Zwei Trichter wandeln durch die Nacht.
754 \item[] Durch ihres Rumpfs verengten Schacht
755 \item[] fließt weißes Mondlicht
756 \item[] still und heiter
766 %___________________________________________________________________________
768 \subsection*
{\phantomsection%
770 \addcontentsline{toc
}{subsection
}{2.9 Block Quotes
}%
771 \label{block-quotes
}%
774 Block quotes consist of indented body elements:
778 My theory by A. Elk. Brackets Miss, brackets. This theory goes
779 as follows and begins now. All brontosauruses are thin at one
780 end, much much thicker in the middle and then thin again at the
781 far end. That is my theory, it is mine, and belongs to me and I
782 own it, and what it is too.
785 \raggedleft —Anne Elk (Miss)
789 The language of a quote (like any other object) can be specified by
795 \otherlanguage{french
}{
796 ReStructuredText est un langage de balisage léger utilisé
797 notamment dans la documentation du langage Python.
802 %___________________________________________________________________________
804 \subsection*
{\phantomsection%
806 \addcontentsline{toc
}{subsection
}{2.10 Doctest Blocks
}%
807 \label{doctest-blocks
}%
810 \begin{quote
}{\ttfamily \raggedright \noindent
811 >>>~print~'Python-specific~usage~examples;~begun~with~">>>"'\\
812 Python-specific~usage~examples;~begun~with~">>>"\\
813 >>>~print~'(cut~and~pasted~from~interactive~Python~sessions)'\\
814 (cut~and~pasted~from~interactive~Python~sessions)
819 %___________________________________________________________________________
821 \subsection*
{\phantomsection%
823 \addcontentsline{toc
}{subsection
}{2.11 Footnotes
}%
827 \DUfootnotetext{id8
}{id1
}{1}{%
828 A footnote contains body elements, consistently indented by at
831 This is the footnote's second paragraph.
834 \DUfootnotetext{label
}{id3
}{2}{\phantomsection\label{label
}%
835 Footnotes may be numbered, either manually (as in
\DUfootnotemark{id9
}{id8
}{1}) or
836 automatically using a "\#"-prefixed label. This footnote has a
837 label so it can be referred to from multiple places, both as a
838 footnote reference (
\DUfootnotemark{id10
}{label
}{2}) and as a
\hyperref[label
]{hyperlink reference
}.
841 \DUfootnotetext{id12
}{id2
}{3}{%
842 This footnote is numbered automatically and anonymously using a
845 This is the second paragraph.
847 And this is the third paragraph.
850 \DUfootnotetext{id13
}{id4
}{*
}{%
851 Footnotes may also use symbols, specified with a "*" label.
852 Here's a reference to the next footnote:
\DUfootnotemark{id14
}{id15
}{†
}.
855 \DUfootnotetext{id15
}{id14
}{†
}{%
856 This footnote shows the next symbol in the sequence.
859 \DUfootnotetext{id16
}{id16
}{4}{%
860 Here's an unreferenced footnote, with a reference to a
861 nonexistent footnote:
%
862 \raisebox{1em
}{\hypertarget{id43
}{}}%
863 \raisebox{1em
}{\hypertarget{id17
}{}}\hyperlink{id42
}{\textbf{\color{red
}{[}5{]}\_}}.
867 %___________________________________________________________________________
869 \subsection*
{\phantomsection%
871 \addcontentsline{toc
}{subsection
}{2.12 Citations
}%
874 \begin{figure
}[b
]\raisebox{1em
}{\hypertarget{cit2002
}{}}[CIT2002
]
875 Citations are text-labeled footnotes. They may be
876 rendered separately and differently from footnotes.
879 Here's a reference to the above,
[\hyperlink{cit2002
}{CIT2002
}], and a
%
880 \raisebox{1em
}{\hypertarget{id45
}{}}%
881 \raisebox{1em
}{\hypertarget{id19
}{}}\hyperlink{id44
}{\textbf{\color{red
}{[}nonexistent
{]}\_}}
885 %___________________________________________________________________________
887 \subsection*
{\phantomsection%
889 \addcontentsline{toc
}{subsection
}{2.13 Targets
}%
891 \label{another-target
}%
894 \phantomsection\label{example
}
895 This paragraph is pointed to by the explicit "example" target. A
896 reference can be found under
\hyperref[inline-markup
]{Inline Markup
}, above.
\hyperref[inline-hyperlink-targets
]{Inline
897 hyperlink targets
} are also possible.
899 Section headers are implicit targets, referred to by name. See
900 \hyperref[targets
]{Targets
}, which is a subsection of
\hyperref[body-elements
]{Body Elements
}.
902 Explicit external targets are interpolated into references such as
903 "
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id31
}{id29
}{5}".
905 Targets may be indirect and anonymous. Thus
\hyperref[targets
]{this phrase
} may also
906 refer to the
\hyperref[targets
]{Targets
} section.
909 \raisebox{1em
}{\hypertarget{id47
}{}}\hyperlink{id46
}{\textbf{\color{red
}`hyperlink reference without a target`
\_}}, which generates an
913 %___________________________________________________________________________
915 \subsubsection*
{\phantomsection%
916 2.13.1 Duplicate Target Names
%
917 \addcontentsline{toc
}{subsubsection
}{2.13.1 Duplicate Target Names
}%
918 \label{duplicate-target-names
}%
921 Duplicate names in section headers or other implicit targets will
922 generate "info" (level-
1) system messages. Duplicate names in
923 explicit targets will generate "warning" (level-
2) system messages.
926 %___________________________________________________________________________
928 \subsubsection*
{\phantomsection%
929 2.13.2 Duplicate Target Names
%
930 \addcontentsline{toc
}{subsubsection
}{2.13.2 Duplicate Target Names
}%
934 Since there are two "Duplicate Target Names" section headers, we
935 cannot uniquely refer to either of them by name. If we try to (like
937 \raisebox{1em
}{\hypertarget{id49
}{}}\hyperlink{id48
}{\textbf{\color{red
}`Duplicate Target Names`
\_}}), an error is generated.
940 %___________________________________________________________________________
942 \subsection*
{\phantomsection%
944 \addcontentsline{toc
}{subsection
}{2.14 Directives
}%
948 \phantomsection\label{contents
}
949 These are just a sample of the many reStructuredText Directives. For
951 \url{http://docutils.sourceforge.net/docs/ref/rst/directives.html
}.
954 %___________________________________________________________________________
956 \subsubsection*
{\phantomsection%
957 2.14.1 Document Parts
%
958 \addcontentsline{toc
}{subsubsection
}{2.14.1 Document Parts
}%
959 \label{document-parts
}%
962 An example of the "contents" directive can be seen above this section
963 (a local, untitled table of
\hyperref[contents
]{contents
}) and at the beginning of the
964 document (a
document-wide
\hyperref[table-of-contents
]{table of contents
}).
967 %___________________________________________________________________________
969 \subsubsection*
{\phantomsection%
970 2.14.2 Images and Figures
%
971 \addcontentsline{toc
}{subsubsection
}{2.14.2 Images and Figures
}%
972 \label{images-and-figures
}%
975 An image directive (also clickable -- a hyperlink reference):
977 \hyperref[directives
]{\includegraphics{../../../docs/user/rst/images/title.png
}}
979 Image with multiple IDs:
981 \includegraphics{../../../docs/user/rst/images/title.png
}
982 \phantomsection\label{image-target-
3}\label{image-target-
2}\label{image-target-
1}
986 \noindent\makebox[\textwidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
988 A left-aligned image:
990 \noindent{\includegraphics{../../../docs/user/rst/images/biohazard.png
}\hfill}
992 This paragraph might flow around the image.
993 The specific behavior depends upon the style sheet and
994 the browser or rendering software used.
996 A right-aligned image:
998 \noindent{\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
1000 This paragraph might flow around the image.
1001 The specific behavior depends upon the style sheet and
1002 the browser or rendering software used.
1004 For inline images see
\hyperref[substitution-definitions
]{Substitution Definitions
}.
1010 \includegraphics[width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
1012 An image
2 em wide and
15 pixel high:
1014 \includegraphics[height=
15\pdfpxdimen,width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
1016 An image occupying
50\% of the line width:
1018 \includegraphics[width=
0.500\linewidth]{../../../docs/user/rst/images/title.png
}
1022 \includegraphics[height=
2cm
]{../../../docs/user/rst/images/biohazard.png
}
1024 A
\emph{figure
} is an image with a caption and/or a legend. With page-based output
1025 media, figures might float to a different position if this helps the page
1028 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
258bp
]{../../../docs/user/rst/images/title.png
}}
1029 \caption{Plaintext markup syntax and parser system.
}
1032 \setlength{\DUtablewidth}{\linewidth}
1033 \begin{longtable
}[c
]{|p
{0.156\DUtablewidth}|p
{0.563\DUtablewidth}|
}
1038 Revised, revisited, based on 're' module.
1044 Structure-enhanced text, structuredtext.
1050 Well it is, isn't it?
1055 This paragraph is also part of the legend.
1059 A left-aligned figure:
1061 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40\pdfpxdimen]{../../../docs/user/rst/images/biohazard.png
}}
1062 \caption{This is the caption.
}
1066 The legend may consist of several paragraphs.
1070 This paragraph might flow around the figure.
1072 The specific behavior depends upon the style sheet and the browser or
1073 rendering software used.
1077 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40\pdfpxdimen]{../../../docs/user/rst/images/biohazard.png
}}
1078 \caption{This is the caption.
}
1082 The legend may consist of several paragraphs.
1086 This paragraph might flow around the figure.
1088 The specific behavior depends upon the style sheet and the browser or
1089 rendering software used.
1091 A right-aligned figure:
1093 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40\pdfpxdimen]{../../../docs/user/rst/images/biohazard.png
}}
1094 \caption{This is the caption.
}
1098 The legend may consist of several paragraphs.
1102 This paragraph might flow around the figure. The specific behavior depends
1103 upon the style sheet and the browser or rendering software used.
1106 %___________________________________________________________________________
1108 \subsubsection*
{\phantomsection%
1110 \addcontentsline{toc
}{subsubsection
}{2.14.3 Admonitions
}%
1111 \label{admonitions
}%
1114 \DUadmonition[attention
]{
1115 \DUtitle[attention
]{Attention!
}
1117 Directives at large.
1120 \DUadmonition[caution
]{
1121 \DUtitle[caution
]{Caution!
}
1123 Don't take any wooden nickels.
1126 \DUadmonition[danger
]{
1127 \DUtitle[danger
]{!DANGER!
}
1129 Mad scientist at work!
1132 \DUadmonition[error
]{
1133 \DUtitle[error
]{Error
}
1138 \DUadmonition[hint
]{
1139 \DUtitle[hint
]{Hint
}
1141 It's bigger than a bread box.
1144 \DUadmonition[important
]{
1145 \DUtitle[important
]{Important
}
1149 \item Wash behind your ears.
1151 \item Clean up your room.
1153 \item Call your mother.
1155 \item Back up your data.
1160 \DUadmonition[note
]{
1161 \DUtitle[note
]{Note
}
1169 15\% if the service is good.
1172 \DUadmonition[warning
]{
1173 \DUtitle[warning
]{Warning
}
1175 Strong prose may provoke extreme mental exertion.
1176 Reader discretion is strongly advised.
1179 \DUadmonition[admonition-and-by-the-way
]{
1180 \DUtitle[admonition-and-by-the-way
]{And, by the way...
}
1182 You can make up your own admonition too.
1186 %___________________________________________________________________________
1188 \subsubsection*
{\phantomsection%
1189 2.14.4 Topics, Sidebars, and Rubrics
%
1190 \addcontentsline{toc
}{subsubsection
}{2.14.4 Topics, Sidebars, and Rubrics
}%
1191 \label{topics-sidebars-and-rubrics
}%
1194 \emph{Sidebars
} are like miniature, parallel documents.
1197 \DUtitle[title
]{Sidebar Title
}
1199 \DUsubtitle[sidebar
]{Optional Subtitle
}
1201 This is a sidebar. It is for text outside the flow of the main
1204 \DUrubric{This is a rubric inside a sidebar
}
1206 Sidebars often appear beside the main text with a border and a different
1207 background or font
color.
1210 A
\emph{topic
} is like a block quote with a title, or a self-contained section
1211 with no subsections.
1214 \DUtitle[title
]{Topic Title
}
1219 A
\emph{rubric
} is like an informal heading that doesn't correspond to the
1220 document's structure. It is typically highlighted in red (hence the name).
1222 \DUrubric{This is a rubric
}
1224 Topics and rubrics can be used at places where a
\hyperref[section-title
]{section title
} is not
1225 allowed (e.g. inside a directive).
1228 %___________________________________________________________________________
1230 \subsubsection*
{\phantomsection%
1231 2.14.5 Target Footnotes
%
1232 \addcontentsline{toc
}{subsubsection
}{2.14.5 Target Footnotes
}%
1233 \label{target-footnotes
}%
1236 \DUfootnotetext{id29
}{id30
}{5}{%
1237 \url{http://www.python.org/
}
1240 \DUfootnotetext{id33
}{id34
}{6}{%
1241 \url{http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=polyglossia
}
1244 \DUfootnotetext{id36
}{id37
}{7}{%
1245 \url{http://docutils.sourceforge.net/
}
1248 \DUfootnotetext{id38
}{id39
}{8}{%
1253 %___________________________________________________________________________
1255 \subsubsection*
{\phantomsection%
1256 2.14.6 Replacement Text
%
1257 \addcontentsline{toc
}{subsubsection
}{2.14.6 Replacement Text
}%
1258 \label{replacement-text
}%
1261 I recommend you try
\href{http://www.python.org/
}{Python,
\emph{the
} best language around
}\DUfootnotemark{id32
}{id29
}{5}.
1264 %___________________________________________________________________________
1266 \subsubsection*
{\phantomsection%
1267 2.14.7 Compound Paragraph
%
1268 \addcontentsline{toc
}{subsubsection
}{2.14.7 Compound Paragraph
}%
1269 \label{compound-paragraph
}%
1272 Compound
1, paragraph
1.
1274 Compound
1, paragraph
2.
1278 \item Compound
1, list item one.
1280 \item Compound
1, list item two.
1284 Another compound statement:
1286 Compound
2, a literal block:
1288 \begin{quote
}{\ttfamily \raggedright \noindent
1289 Compound~
2,~literal.
1292 Compound
2, this is a test.
1294 Compound
3, only consisting of one paragraph.
1296 \begin{quote
}{\ttfamily \raggedright \noindent
1298 This~one~starts~with~a~literal~block.
1301 Compound
4, a paragraph.
1303 Now something
\emph{really
} perverted -- a nested compound block. This is
1304 just to test that it works at all; the results don't have to be
1307 Compound
5, block
1 (a paragraph).
1309 Compound
6, block
2 in compound
5.
1311 Compound
6, another paragraph.
1313 Compound
5, block
3 (a paragraph).
1315 Compound
7, with a table inside:
1318 \setlength{\DUtablewidth}{\linewidth}
1319 \begin{longtable
}[c
]{|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|
}
1341 Compound
7, a paragraph after the table.
1343 Compound
7, another paragraph.
1346 %___________________________________________________________________________
1348 \subsubsection*
{\phantomsection%
1349 2.14.8 Parsed Literal Blocks
%
1350 \addcontentsline{toc
}{subsubsection
}{2.14.8 Parsed Literal Blocks
}%
1351 \label{parsed-literal-blocks
}%
1354 \begin{quote
}{\ttfamily \raggedright \noindent
1355 This~is~a~parsed~literal~block.\\
1356 ~~~~This~line~is~indented.~~The~next~line~is~blank.\\
1358 Inline~markup~is~supported,~e.g.~
\emph{emphasis
},~
\textbf{strong
},~
\texttt{literal\\
1359 text
},~footnotes
\DUfootnotemark{id22
}{id8
}{1},~
%
1360 \phantomsection\label{hyperlink-targets
}hyperlink~targets,~and~
\href{http://www.python.org/
}{references
}.
1365 %___________________________________________________________________________
1367 \subsection*
{\phantomsection%
1368 2.15 Substitution Definitions
%
1369 \addcontentsline{toc
}{subsection
}{2.15 Substitution Definitions
}%
1370 \label{substitution-definitions
}%
1373 An inline image (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}) example:
1375 (Substitution definitions are not visible in the HTML source.)
1378 %___________________________________________________________________________
1380 \subsection*
{\phantomsection%
1382 \addcontentsline{toc
}{subsection
}{2.16 Comments
}%
1388 % Comments begin with two dots and a space. Anything may
1389 % follow, except for the syntax of footnotes, hyperlink
1390 % targets, directives, or substitution definitions.
1392 % Double-dashes -- "--" -- must be escaped somehow in HTML output.
1394 % Comments may contain non-ASCII characters: ä ö ü æ ø å
1396 (View the HTML source to see the comment.)
1399 %___________________________________________________________________________
1401 \subsection*
{\phantomsection%
1403 \addcontentsline{toc
}{subsection
}{2.17 Raw text
}%
1407 This does not necessarily look nice, because there may be missing white space.
1409 It's just there to freeze the behavior.
1415 \DUrole{myclass
}{Another test with myclass set.
}
1417 This is the
\DUrole{myrawroleclass
}{fourth test
} with myrawroleclass set.
1419 Fifth test in LaTeX.\
\Line two.
1422 %___________________________________________________________________________
1424 \subsection*
{\phantomsection%
1426 \addcontentsline{toc
}{subsection
}{2.18 Container
}%
1434 % currently not implemented in LaTeX:
1435 % .. include:: data/header_footer.txt
1438 %___________________________________________________________________________
1440 \subsection*
{\phantomsection%
1441 2.19 Colspanning tables
%
1442 \addcontentsline{toc
}{subsection
}{2.19 Colspanning tables
}%
1443 \label{colspanning-tables
}%
1446 This table has a cell spanning two columns:
1449 \setlength{\DUtablewidth}{\linewidth}
1450 \begin{longtable
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.086\DUtablewidth}|
}
1452 \multicolumn{2}{|l|
}{\textbf{%
1468 \multicolumn{2}{|l|
}{\textbf{%
1483 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1521 %___________________________________________________________________________
1523 \subsection*
{\phantomsection%
1524 2.20 Rowspanning tables
%
1525 \addcontentsline{toc
}{subsection
}{2.20 Rowspanning tables
}%
1526 \label{rowspanning-tables
}%
1529 Here's a table with cells spanning several rows:
1532 \setlength{\DUtablewidth}{\linewidth}
1533 \begin{longtable
}[c
]{|p
{0.296\DUtablewidth}|p
{0.156\DUtablewidth}|p
{0.226\DUtablewidth}|
}
1536 Header row, column
1
1537 (header rows optional)
1547 Header row, column
1
1548 (header rows optional)
1556 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1560 body row
1, column
1
1569 &
\multirow{2}{0.16\DUtablewidth}{%
1572 } &
\multirow{2}{0.23\DUtablewidth}{%
1585 %___________________________________________________________________________
1587 \subsection*
{\phantomsection%
1589 \addcontentsline{toc
}{subsection
}{2.21 Custom Roles
}%
1590 \label{custom-roles
}%
1595 \item A role based on an existing role.
1597 \texttt{\DUrole{custom
}{one
}} \texttt{\DUrole{custom
}{two
}} \texttt{\DUrole{custom
}{three
}}
1601 \DUrole{customnew
}{one two three
}
1603 \item A role with class attribute.
1605 \DUrole{special
}{interpreted text
}
1607 \item A language-switching role:
1609 Let's count in German
\otherlanguage{german
}{eins zwei drei
}.
1611 \item A role with multiple class attributes, styled with raw directives:
1613 \newcommand{\DUrolegreen}[1]{\textcolor{green
}{#1}}
1614 \newcommand{\DUrolesc}[1]{\textsc{#1}}
1616 The following works in most browsers but does not validate
1617 (
\texttt{<style>
} is only allowed in the
document head):
1619 \begin{quote
}{\ttfamily \raggedright \noindent
1622 ~~<style~type="text/css"><!--\\
1623 ~~~.green~\
{color:~green;\
}\\
1624 ~~~.sc~\
{font-variant:~small-caps;\
}\\
1629 \otherlanguage{british
}{\DUrole{green
}{\DUrole{sc
}{British colourful text in small-caps
}}}.
1634 %___________________________________________________________________________
1636 \section*
{\phantomsection%
1637 3 Tests for the LaTeX writer
%
1638 \addcontentsline{toc
}{section
}{3 Tests for the LaTeX writer
}%
1639 \label{tests-for-the-latex-writer
}%
1642 Test syntax elements which may cause trouble for the LaTeX writer but might
1643 not need to be tested with other writers (e.g. the HTML writer).
1646 %___________________________________________________________________________
1648 \subsection*
{\phantomsection%
1649 3.1 Custom Roles in LaTeX
%
1650 \addcontentsline{toc
}{subsection
}{3.1 Custom Roles in LaTeX
}%
1651 \label{custom-roles-in-latex
}%
1656 \item Role names and class arguments are converted to conform to the
1657 regular expression
\texttt{{[}a-z
{]}{[}-a-z0-
9{]}*
} (letters are downcased,
1658 accents and similar decoration is stripped, non-conforming
1659 characters are replaced by a hyphen).
1661 Class arguments may contain numbers and hyphens, which need special
1662 treatment in LaTeX command names.
1664 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}}
1666 \item With LaTeX, roles can be styled within the
document using the
\DUroletitlereference{raw
}
1669 \newcommand{\DUrolelarge}[1]{{\large #1}}
1671 \@namedef
{DUrolesmall-caps
}{\textsc}
1672 \@namedef
{DUrolecustom4
}{\textbf}
1675 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}} in large, bold, small-caps.
1677 \item Custom roles can be based on standard roles:
1679 This is a
\emph{\DUrole{custom-emphasis
}{customized emphasis text role
}}
1681 This is a
\texttt{\DUrole{custom-literal
}{customized literal text role
}}
1683 This is a
\textbf{\DUrole{custom-strong
}{customized strong text role
}}
1685 This is a
\textsubscript{\DUrole{custom-subscript
}{customized subscript text role
}}
1687 This is a
\textsuperscript{\DUrole{custom-superscript
}{customized superscript text role
}}
1689 This is a
\DUroletitlereference{\DUrole{custom-title-reference
}{customized title-reference text role
}}
1693 % This file is used by the standalone_rst_latex test.
1696 %___________________________________________________________________________
1698 \subsection*
{\phantomsection%
1700 \addcontentsline{toc
}{subsection
}{3.2 Option lists
}%
1704 The LaTeX-
2e description environment is used for definition lists.
1705 The definition is continued on the same line as the term, this should
1706 not happen if a option-list is at the top of the definition.
1708 If the option list is not at the first element in the definition, it
1709 is contained in a quote
1713 \begin{DUoptionlist
}
1715 \item[--help
] show help
1724 \item[{In a definition list:
}] \leavevmode %
1725 \begin{DUoptionlist
}
1727 \item[--help
] show help
1736 %___________________________________________________________________________
1738 \subsection*
{\phantomsection%
1739 3.3 Monospaced non-alphanumeric characters
%
1740 \addcontentsline{toc
}{subsection
}{3.3 Monospaced non-alphanumeric characters
}%
1741 \label{monospaced-non-alphanumeric-characters
}%
1744 These are all ASCII characters except a-zA-Z0-
9 and space:
1746 \texttt{!!!"""\#\#\#\$\$\$\%\%\%\&\&\&'''((()))***+++,,,---...///:::
}
1748 \texttt{;;;<<<===>>>???@@@
{[}{[}{[}\textbackslash{}\textbackslash{}\textbackslash{}{]}{]}{]}\textasciicircum{}\textasciicircum{}\textasciicircum{}\_\_\_```\
{\
{\
{|||\
}\
}\
}\textasciitilde{}\textasciitilde{}\textasciitilde{}}
1750 \texttt{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
1752 The two lines of non-alphanumeric characters should both have the same
1753 width as the third line.
1756 %___________________________________________________________________________
1758 \subsection*
{\phantomsection%
1759 3.4 Non-ASCII characters
%
1760 \addcontentsline{toc
}{subsection
}{3.4 Non-ASCII characters
}%
1761 \label{non-ascii-characters
}%
1764 Punctuation and footnote symbols
1767 \setlength{\DUtablewidth}{\linewidth}
1768 \begin{longtable
}[c
]{|p
{0.028\DUtablewidth}|p
{0.424\DUtablewidth}|
}
1785 single turned comma quotation mark
1791 single comma quotation mark
1797 low single comma quotation mark
1803 double turned comma quotation mark
1809 double comma quotation mark
1815 low double comma quotation mark
1869 left-right double arrow
1874 The
\DUroletitlereference{Latin-
1 extended
} Unicode block
1877 \setlength{\DUtablewidth}{\linewidth}
1878 \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}|
}
2136 \item The following line should not be wrapped, because it uses
2137 no-break spaces (
\textbackslash{}u00a0):
2139 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
2141 \item Line wrapping with/without breakpoints marked by soft hyphens
2142 (
\textbackslash{}u00ad):
2144 pdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-sch
2146 pdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrisch
2148 \item The currency sign (
\textbackslash{}u00a4) is not supported by all fonts
2149 (some have an Euro sign at its place). You might see an error
2152 \begin{quote
}{\ttfamily \raggedright \noindent
2153 !~Package~textcomp~Error:~Symbol~
\textbackslash{}textcurrency~not~provided~by\\
2154 (textcomp)~~~~~~~~~~~~~~~~font~family~ptm~in~TS1~encoding.\\
2155 (textcomp)~~~~~~~~~~~~~~~~Default~family~used~instead.
2159 (which in case of font family ptm is a false positive). Add either
2163 turn the error in a warning, use the default symbol (bitmap), or
2165 \item[{force,almostfull:
}]
2166 use the symbol provided by the font at the users
2171 to the
document options or use a different font package.
2176 %___________________________________________________________________________
2178 \subsection*
{\phantomsection%
2179 3.5 Encoding special chars
%
2180 \addcontentsline{toc
}{subsection
}{3.5 Encoding special chars
}%
2181 \label{encoding-special-chars
}%
2184 The LaTeX Info pages lists under "
2.18 Special Characters"
2188 The following characters play a special role in LaTeX and are called
2189 "special printing characters", or simply "special characters".
2193 \# \$ \% \&
\textasciitilde{} \_ \textasciicircum{} \textbackslash{} \
{ \
}
2199 The special chars verbatim:
2201 \begin{quote
}{\ttfamily \raggedright \noindent
2202 \#~\$~\%~\&~
\textasciitilde{}~
\_~
\textasciicircum{}~
\textbackslash{}~\
{~\
}
2206 However also
\emph{square brackets
} {[}{]} need special care.
2210 item and all the other commands with optional arguments check
2211 if the token right after the macro name is an opening bracket.
2212 In that case the contents between that bracket and the following
2213 closing bracket on the same grouping level are taken as the
2214 optional argument. What makes this unintuitive is the fact that
2215 the square brackets aren't grouping characters themselves, so in
2216 your last example item
{[}{[}...
{]}{]} the optional argument consists of
2217 {[}... (without the closing bracket).
2221 Compare the items in the following lists:
2227 \item {[}bracketed
{]} item
2232 \item[{simple
}] \leavevmode
2235 \item[{{[}bracketed
{]}}] \leavevmode
2240 The OT1 font-encoding has different characters for the less-than,
2241 greater-than and bar, < | >, except for typewriter font
\DUroletitlereference{cmtt
}:
2243 \begin{quote
}{\ttfamily \raggedright \noindent
2249 %___________________________________________________________________________
2251 \subsection*
{\phantomsection%
2252 3.6 Hyperlinks and -targets
%
2253 \addcontentsline{toc
}{subsection
}{3.6 Hyperlinks and -targets
}%
2254 \label{hyperlinks-and-targets
}%
2257 In LaTeX, we must set an explicit anchor (
\texttt{\textbackslash{}phantomsection
}) for a
2259 \phantomsection\label{hypertarget-in-plain-text
}hypertarget in plain text or in a figure but not in a longtable or
2263 \setlength{\DUtablewidth}{\linewidth}
2264 \begin{longtable
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
2265 \caption{Table with
%
2266 \label{hypertarget-in-table-title
}hypertarget in table title.
}\\
2279 \phantomsection\label{figure-label
}
2280 \noindent\makebox[\textwidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
2281 \caption{Figure with
%
2282 \label{hypertarget-in-figure-caption
}hypertarget in figure caption.
}
2285 \phantomsection\label{hypertarget-in-figure-legend
}hypertarget in figure legend.
2289 \includegraphics{../../../docs/user/rst/images/biohazard.png
}
2290 \phantomsection\label{image-label
}
2292 See
\hyperref[hypertarget-in-plain-text
]{hypertarget in plain text
},
2293 \hyperref[table-label
]{table label
},
\hyperref[hypertarget-in-table-title
]{hypertarget in table title
},
2294 \hyperref[figure-label
]{figure label
},
\hyperref[hypertarget-in-figure-caption
]{hypertarget in figure caption
},
2295 \hyperref[hypertarget-in-figure-legend
]{hypertarget in figure legend
}, and
2296 \hyperref[image-label
]{image label
}.
2299 %___________________________________________________________________________
2301 \subsection*
{\phantomsection%
2302 3.7 External references
%
2303 \addcontentsline{toc
}{subsection
}{3.7 External references
}%
2304 \label{external-references
}%
2307 Long URLs should be wrapped in the PDF.
2308 This can be achieved with the url command which is used by the LaTeX writer
2309 wheneve the content (name) of a reference node equals the link URL.
2312 \item[{Example:
}] \leavevmode
2313 a long URL that should wrap in the output
2314 \url{http://docutils.sourceforge.net/docs/user/latex.html\#id79
}
2318 If the argument contains any "\%", "\#", or "
\textasciicircum{}\textasciicircum{}", or ends with
\texttt{\textbackslash{}}, it can't
2319 be used in the argument to another command. The argument must not contain
2322 The characters
\textasciicircum{}, \
{, \
}, and
\texttt{\textbackslash{}} are invalid in a "http:" or "ftp:" URL
2323 and not recognized as part of it:
2325 \begin{DUlineblock
}{0em
}
2326 \item[] \url{http://www.example.org
}/strange
\textasciicircum{}\textasciicircum{}name
2327 \item[] \url{http://www.example.org
}\textbackslash{}using
\textbackslash{}DOS
\textbackslash{}paths
\textbackslash{}
2328 \item[] \url{http://www.example.org/XML
}/strange\
{n\
}ame
2331 They can, however be used in paths and/or filenames.
2333 Handling by the LaTeX writer:
2337 \item \texttt{\#
},
\texttt{\textbackslash{}} and
\texttt{\%
} are escaped:
2339 \begin{DUlineblock
}{0em
}
2340 \item[] \href{http://www.w3.org/XML/Schema\#dev
}{URL with \#
}
2341 \url{http://www.w3.org/XML/Schema\#dev
}
2342 \item[] \href{http://www.w3.org/XML/Schema\%dev
}{URL with \%
}
2343 \url{http://example.org/Schema\%dev
}
2344 \item[] \href{A:DOS\
\path\\
}{file with DOS path
}\DUfootnotemark{id39
}{id38
}{8} \url{A:DOS\
\path\\
}\DUfootnotemark{id40
}{id38
}{8}
2347 \DUadmonition[note
]{
2348 \DUtitle[note
]{Note
}
2350 These URLs are typeset inside a LaTeX command without error.
2352 \begin{DUlineblock
}{0em
}
2353 \item[] \url{http://www.w3.org/XML/Schema\#dev
}
2354 \item[] \url{http://example.org/Schema\%dev
}
2355 \item[] \url{A:DOS\
\path\\
}\DUfootnotemark{id41
}{id38
}{8}
2363 \item \textasciicircum{}\textasciicircum{} LaTeX's special syntax for characters results in "strange" replacements
2364 (both with href and url). A warning is given.
2366 \href{../strange^^name
}{file with
\textasciicircum{}\textasciicircum{}}:
2367 \url{../strange^^name
}
2369 \item Unbalanced braces, \
{ or \
}, will fail (both with href and url):
2371 \begin{quote
}{\ttfamily \raggedright \noindent
2372 `file~with~\
{~<../strange\
{name>`
\_\_\\
2373 `<../strange\
{name>`
\_\_
2377 while balanced braces are suported:
2379 \begin{DUlineblock
}{0em
}
2380 \item[] \url{../strange
{n
}ame
}
2381 \item[] \url{../st
{r
}ange
{n
}ame
}
2382 \item[] \url{../
{st
{r
}ange
{n
}ame
}}
2388 %___________________________________________________________________________
2390 \section*
{\phantomsection%
2391 4 Tests for the XeTeX writer
%
2392 \addcontentsline{toc
}{section
}{4 Tests for the XeTeX writer
}%
2393 \label{tests-for-the-xetex-writer
}%
2396 With XeTeX, you can typeset text in any language/script supported by
2397 Unicode and the selected font, e.g. Azərbaycanca, Bân-lâm-gú, Башҡорт
2398 Беларуская, Български, Català, Чӑвашла, Česky, Ελληνικά, Español,
2399 Français, Føroyskt, Хальмг, Íslenska, עברית , Қазақша, Kurdî,
2400 Latviešu, Lietuvių, Македонски, Монгол, Nāhuatl, Português, Română,
2401 Русский, Slovenščina, Српски, Türkçe, Українська, Tiếng Việt, Volapük,
2402 Võro, ייִדיש , Žemaitėška.
2403 Currently, there is extended support for
28 languages in the
2404 \href{http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=polyglossia
}{polyglossia
}\DUfootnotemark{id34
}{id33
}{6} package.
2409 %___________________________________________________________________________
2411 \section*
{\phantomsection%
2413 \addcontentsline{toc
}{section
}{5 Error Handling
}%
2414 \label{error-handling
}%
2417 Any errors caught during processing will generate system messages.
2419 There should be five messages in the following, auto-generated
2420 section, "Docutils System Messages":
2422 % section should be added by Docutils automatically
2425 %___________________________________________________________________________
2427 \section*
{\phantomsection%
2428 \color{red
}Docutils System Messages
%
2429 \addcontentsline{toc
}{section
}{Docutils System Messages
}%
2432 \DUadmonition[system-message
]{
2433 \DUtitle[system-message
]{system-message
}
2434 \raisebox{1em
}{\hypertarget{id27
}{}}
2436 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
102
2439 Undefined substitution referenced: "problematic".
2442 \DUadmonition[system-message
]{
2443 \DUtitle[system-message
]{system-message
}
2444 \raisebox{1em
}{\hypertarget{id42
}{}}
2446 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
388
2449 Unknown target name: "
5".
2452 \DUadmonition[system-message
]{
2453 \DUtitle[system-message
]{system-message
}
2454 \raisebox{1em
}{\hypertarget{id44
}{}}
2456 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
397
2459 Unknown target name: "nonexistent".
2462 \DUadmonition[system-message
]{
2463 \DUtitle[system-message
]{system-message
}
2464 \raisebox{1em
}{\hypertarget{id46
}{}}
2466 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
424
2469 Unknown target name: "hyperlink reference without a target".
2472 \DUadmonition[system-message
]{
2473 \DUtitle[system-message
]{system-message
}
2474 \raisebox{1em
}{\hypertarget{id48
}{}}
2476 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
437
2479 Duplicate target name, cannot be used as a unique reference: "duplicate target names".