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 Lone subsections are converted to a section subtitle by a transform
301 activated with the
\texttt{--section-subtitles
} command line option or the
302 \texttt{sectsubtitle-xform
} configuration value.
305 %___________________________________________________________________________
307 \subsection*
{\phantomsection%
309 \addcontentsline{toc
}{subsection
}{1.2 Empty Section
}%
310 \label{empty-section
}%
314 %___________________________________________________________________________
316 \subsection*
{\phantomsection%
318 \addcontentsline{toc
}{subsection
}{1.3 Transitions
}%
325 %___________________________________________________________________________
329 It divides the section. Transitions may also occur between sections:
332 %___________________________________________________________________________
337 %___________________________________________________________________________
339 \section*
{\phantomsection%
341 \addcontentsline{toc
}{section
}{2 Body Elements
}%
342 \label{body-elements
}%
346 %___________________________________________________________________________
348 \subsection*
{\phantomsection%
350 \addcontentsline{toc
}{subsection
}{2.1 Paragraphs
}%
357 %___________________________________________________________________________
359 \subsubsection*
{\phantomsection%
361 \addcontentsline{toc
}{subsubsection
}{2.1.1 Inline Markup
}%
362 \label{inline-markup
}%
365 Paragraphs contain text and may contain inline markup:
\emph{emphasis
},
366 \textbf{strong emphasis
},
\texttt{inline literals
}, standalone hyperlinks
367 (
\url{http://www.python.org
}), external hyperlinks (
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id30
}{id29
}{5}), internal
368 cross-references (
\hyperref[example
]{example
}), external hyperlinks with embedded URIs
369 (
\href{http://www.python.org
}{Python web site
}),
\href{http://www.python.org/
}{anonymous hyperlink
370 references
}\DUfootnotemark{id35
}{id29
}{5} (
\href{http://docutils.sourceforge.net/
}{a second reference
}\DUfootnotemark{id37
}{id36
}{7}), footnote references (manually
371 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
}]),
372 substitution references (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}), and
%
373 \phantomsection\label{inline-hyperlink-targets
}inline hyperlink targets
374 (see
\hyperref[targets
]{Targets
} below for a reference back to here). Character-level
375 inline markup is also possible (although exceedingly ugly!) in
\emph{re
}\texttt{Structured
}\emph{Text
}. Problems are indicated by
%
376 \raisebox{1em
}{\hypertarget{id28
}{}}\hyperlink{id27
}{\textbf{\color{red
}|problematic|
}} text
377 (generated by processing errors; this one is intentional). Here is a
378 reference to the
\hyperref[doctitle
]{doctitle
} and the
\hyperref[subtitle
]{subtitle
}.
380 The default role for interpreted text is
\DUroletitlereference{Title Reference
}. Here are
381 some explicit interpreted text roles: a PEP reference (
\href{http://www.python.org/dev/peps/pep-
0287}{PEP
287}); an
382 RFC reference (
\href{http://www.faqs.org/rfcs/rfc2822.html
}{RFC
2822}); a
\textsubscript{subscript
}; a
\textsuperscript{superscript
};
383 and explicit roles for
\emph{standard
} \textbf{inline
}
386 % DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
388 Let's test wrapping and whitespace significance in inline literals:
389 \texttt{This is an example of --inline-literal --text, --including some--
390 strangely--hyphenated-words. ~Adjust-the-width-of-your-browser-window
391 to see how the text is wrapped. ~-- ---- -------- ~Now note ~ ~the
392 spacing ~ ~between the ~ ~words of ~ ~this sentence ~ ~(words
393 should ~ ~be grouped ~ ~in pairs).
}
395 If the
\texttt{--pep-references
} option was supplied, there should be a
396 live link to PEP
258 here.
399 %___________________________________________________________________________
401 \subsection*
{\phantomsection%
403 \addcontentsline{toc
}{subsection
}{2.2 Bullet Lists
}%
404 \label{bullet-lists
}%
413 \item Nested bullet list.
421 Paragraph
2 of item
2.
425 \item Nested bullet list.
439 \item This nested list should be compacted by the HTML writer.
441 \phantomsection\label{target
}
442 % Even if this item contains a target and a comment.
449 %___________________________________________________________________________
451 \subsection*
{\phantomsection%
452 2.3 Enumerated Lists
%
453 \addcontentsline{toc
}{subsection
}{2.3 Enumerated Lists
}%
454 \label{enumerated-lists
}%
456 \newcounter{listcnt0
}
457 \begin{list
}{\arabic{listcnt0
}.
}
459 \usecounter{listcnt0
}
460 \setlength{\rightmargin}{\leftmargin}
463 \item Arabic numerals.
464 \newcounter{listcnt1
}
465 \begin{list
}{\alph{listcnt1
})
}
467 \usecounter{listcnt1
}
468 \setlength{\rightmargin}{\leftmargin}
472 \newcounter{listcnt2
}
473 \begin{list
}{(
\roman{listcnt2
})
}
475 \usecounter{listcnt2
}
476 \setlength{\rightmargin}{\leftmargin}
480 \newcounter{listcnt3
}
481 \begin{list
}{\Alph{listcnt3
}.
}
483 \usecounter{listcnt3
}
484 \setlength{\rightmargin}{\leftmargin}
488 \newcounter{listcnt4
}
489 \begin{list
}{\Roman{listcnt4
})
}
491 \usecounter{listcnt4
}
492 \setlength{\rightmargin}{\leftmargin}
501 \item Lists that don't start at
1:
502 \setcounter{listcnt1
}{0}
503 \begin{list
}{\arabic{listcnt1
}.
}
505 \usecounter{listcnt1
}
506 \addtocounter{listcnt1
}{2}
507 \setlength{\rightmargin}{\leftmargin}
514 \setcounter{listcnt1
}{0}
515 \begin{list
}{\Alph{listcnt1
}.
}
517 \usecounter{listcnt1
}
518 \addtocounter{listcnt1
}{2}
519 \setlength{\rightmargin}{\leftmargin}
526 \setcounter{listcnt1
}{0}
527 \begin{list
}{\roman{listcnt1
}.
}
529 \usecounter{listcnt1
}
530 \addtocounter{listcnt1
}{2}
531 \setlength{\rightmargin}{\leftmargin}
541 %___________________________________________________________________________
543 \subsection*
{\phantomsection%
544 2.4 Definition Lists
%
545 \addcontentsline{toc
}{subsection
}{2.4 Definition Lists
}%
546 \label{definition-lists
}%
550 \item[{Term
}] \leavevmode
553 \item[{Term
}] \leavevmode (
\textbf{classifier
})
555 Definition paragraph
1.
557 Definition paragraph
2.
559 \item[{Term
}] \leavevmode
562 \item[{Term
}] \leavevmode (
\textbf{classifier one
})
563 (
\textbf{classifier two
})
570 %___________________________________________________________________________
572 \subsection*
{\phantomsection%
574 \addcontentsline{toc
}{subsection
}{2.5 Field Lists
}%
580 Field lists map field names to field bodies, like database
581 records. They are often part of an extension syntax. They are
582 an unambiguous variant of RFC
2822 fields.
584 \item[{how arg1 arg2:
}]
585 The field marker is a colon, the field name, and a colon.
587 The field body may contain one or more body elements, indented
588 relative to the field marker.
591 \DUrole{credits
}{This paragraph has the
\DUroletitlereference{credits
} class set. (This is actually not
592 about credits but just for ensuring that the class attribute
593 doesn't get stripped away.)
}
598 %___________________________________________________________________________
600 \subsection*
{\phantomsection%
602 \addcontentsline{toc
}{subsection
}{2.6 Option Lists
}%
603 \label{option-lists
}%
606 For listing command-line options:
610 \item[-a
] command-line option "a"
612 \item[-b file
] options can have arguments
613 and long descriptions
615 \item[--long
] options can be long also
617 \item[--input=file
] long options can also have
620 \item[--very-long-option
] The description can also start on the next line.
622 The description may contain multiple body elements,
623 regardless of where it starts.
625 \item[-x, -y, -z
] Multiple options are an "option group".
627 \item[-v, --verbose
] Commonly-seen: short \& long options.
629 \item[-
1 file, --one=file, --two file
] Multiple options with arguments.
631 \item[/V
] DOS/VMS-style options too
635 There must be at least two spaces between the option and the
639 %___________________________________________________________________________
641 \subsection*
{\phantomsection%
643 \addcontentsline{toc
}{subsection
}{2.7 Literal Blocks
}%
644 \label{literal-blocks
}%
647 Literal blocks are indicated with a double-colon ("::") at the end of
648 the preceding paragraph (over there
\texttt{-->
}). They can be indented:
650 \begin{quote
}{\ttfamily \raggedright \noindent
652 ~~~~text~=~'is~left~as-is'\\
653 ~~~~spaces
\_and\_linebreaks~=~'are~preserved'\\
654 ~~~~markup
\_processing~=~None
658 Or they can be quoted without indentation:
660 \begin{quote
}{\ttfamily \raggedright \noindent
663 >~Why~didn't~I~think~of~that?
668 %___________________________________________________________________________
670 \subsection*
{\phantomsection%
672 \addcontentsline{toc
}{subsection
}{2.8 Line Blocks
}%
676 This section tests line blocks. Line blocks are body elements which
677 consist of lines and other line blocks. Nested line blocks cause
680 \begin{DUlineblock
}{0em
}
681 \item[] This is a line block. It ends with a blank line.
683 \begin{DUlineblock
}{\DUlineblockindent}
684 \item[] New lines begin with a vertical bar ("|").
685 \item[] Line breaks and initial indent are significant, and preserved.
687 \begin{DUlineblock
}{\DUlineblockindent}
688 \item[] Continuation lines are also possible. A long line that is intended
689 to wrap should begin with a space in place of the vertical bar.
691 \item[] The left edge of a continuation line need not be aligned with
692 the left edge of the text above it.
696 \begin{DUlineblock
}{0em
}
697 \item[] This is a second line block.
699 \item[] Blank lines are permitted internally, but they must begin with a "|".
702 Another line block, surrounded by paragraphs:
704 \begin{DUlineblock
}{0em
}
705 \item[] And it's no good waiting by the window
706 \item[] It's no good waiting for the sun
707 \item[] Please believe me, the things you dream of
708 \item[] They don't fall in the lap of no-one
711 Take it away, Eric the Orchestra Leader!
715 \begin{DUlineblock
}{0em
}
716 \item[] A one, two, a one two three four
718 \item[] Half a bee, philosophically,
720 \begin{DUlineblock
}{\DUlineblockindent}
721 \item[] must,
\emph{ipso facto
}, half not be.
723 \item[] But half the bee has got to be,
725 \begin{DUlineblock
}{\DUlineblockindent}
726 \item[] \emph{vis a vis
} its entity. D'you see?
729 \item[] But can a bee be said to be
731 \begin{DUlineblock
}{\DUlineblockindent}
732 \item[] or not to be an entire bee,
734 \begin{DUlineblock
}{\DUlineblockindent}
735 \item[] when half the bee is not a bee,
737 \begin{DUlineblock
}{\DUlineblockindent}
738 \item[] due to some ancient injury?
748 A line block, like the following poem by Christian Morgenstern, can
749 also be centre-aligned:
751 \begin{DUlineblock
}{0em
}
752 \otherlanguage{german
}{\DUrole{align-center
}{
753 \item[] \textbf{Die Trichter
}
755 \item[] Zwei Trichter wandeln durch die Nacht.
756 \item[] Durch ihres Rumpfs verengten Schacht
757 \item[] fließt weißes Mondlicht
758 \item[] still und heiter
768 %___________________________________________________________________________
770 \subsection*
{\phantomsection%
772 \addcontentsline{toc
}{subsection
}{2.9 Block Quotes
}%
773 \label{block-quotes
}%
776 Block quotes consist of indented body elements:
780 My theory by A. Elk. Brackets Miss, brackets. This theory goes
781 as follows and begins now. All brontosauruses are thin at one
782 end, much much thicker in the middle and then thin again at the
783 far end. That is my theory, it is mine, and belongs to me and I
784 own it, and what it is too.
787 \raggedleft —Anne Elk (Miss)
791 The language of a quote (like any other object) can be specified by
797 \otherlanguage{french
}{
798 ReStructuredText est un langage de balisage léger utilisé
799 notamment dans la documentation du langage Python.
804 %___________________________________________________________________________
806 \subsection*
{\phantomsection%
808 \addcontentsline{toc
}{subsection
}{2.10 Doctest Blocks
}%
809 \label{doctest-blocks
}%
812 \begin{quote
}{\ttfamily \raggedright \noindent
813 >>>~print~'Python-specific~usage~examples;~begun~with~">>>"'\\
814 Python-specific~usage~examples;~begun~with~">>>"\\
815 >>>~print~'(cut~and~pasted~from~interactive~Python~sessions)'\\
816 (cut~and~pasted~from~interactive~Python~sessions)
821 %___________________________________________________________________________
823 \subsection*
{\phantomsection%
825 \addcontentsline{toc
}{subsection
}{2.11 Footnotes
}%
829 \DUfootnotetext{id8
}{id1
}{1}{%
830 A footnote contains body elements, consistently indented by at
833 This is the footnote's second paragraph.
836 \DUfootnotetext{label
}{id3
}{2}{\phantomsection\label{label
}%
837 Footnotes may be numbered, either manually (as in
\DUfootnotemark{id9
}{id8
}{1}) or
838 automatically using a "\#"-prefixed label. This footnote has a
839 label so it can be referred to from multiple places, both as a
840 footnote reference (
\DUfootnotemark{id10
}{label
}{2}) and as a
\hyperref[label
]{hyperlink reference
}.
843 \DUfootnotetext{id12
}{id2
}{3}{%
844 This footnote is numbered automatically and anonymously using a
847 This is the second paragraph.
849 And this is the third paragraph.
852 \DUfootnotetext{id13
}{id4
}{*
}{%
853 Footnotes may also use symbols, specified with a "*" label.
854 Here's a reference to the next footnote:
\DUfootnotemark{id14
}{id15
}{†
}.
857 \DUfootnotetext{id15
}{id14
}{†
}{%
858 This footnote shows the next symbol in the sequence.
861 \DUfootnotetext{id16
}{id16
}{4}{%
862 Here's an unreferenced footnote, with a reference to a
863 nonexistent footnote:
%
864 \raisebox{1em
}{\hypertarget{id43
}{}}%
865 \raisebox{1em
}{\hypertarget{id17
}{}}\hyperlink{id42
}{\textbf{\color{red
}{[}5{]}\_}}.
869 %___________________________________________________________________________
871 \subsection*
{\phantomsection%
873 \addcontentsline{toc
}{subsection
}{2.12 Citations
}%
876 \begin{figure
}[b
]\raisebox{1em
}{\hypertarget{cit2002
}{}}[CIT2002
]
877 Citations are text-labeled footnotes. They may be
878 rendered separately and differently from footnotes.
881 Here's a reference to the above,
[\hyperlink{cit2002
}{CIT2002
}], and a
%
882 \raisebox{1em
}{\hypertarget{id45
}{}}%
883 \raisebox{1em
}{\hypertarget{id19
}{}}\hyperlink{id44
}{\textbf{\color{red
}{[}nonexistent
{]}\_}}
887 %___________________________________________________________________________
889 \subsection*
{\phantomsection%
891 \addcontentsline{toc
}{subsection
}{2.13 Targets
}%
893 \label{another-target
}%
896 \phantomsection\label{example
}
897 This paragraph is pointed to by the explicit "example" target. A
898 reference can be found under
\hyperref[inline-markup
]{Inline Markup
}, above.
\hyperref[inline-hyperlink-targets
]{Inline
899 hyperlink targets
} are also possible.
901 Section headers are implicit targets, referred to by name. See
902 \hyperref[targets
]{Targets
}, which is a subsection of
\hyperref[body-elements
]{Body Elements
}.
904 Explicit external targets are interpolated into references such as
905 "
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id31
}{id29
}{5}".
907 Targets may be indirect and anonymous. Thus
\hyperref[targets
]{this phrase
} may also
908 refer to the
\hyperref[targets
]{Targets
} section.
911 \raisebox{1em
}{\hypertarget{id47
}{}}\hyperlink{id46
}{\textbf{\color{red
}`hyperlink reference without a target`
\_}}, which generates an
915 %___________________________________________________________________________
917 \subsubsection*
{\phantomsection%
918 2.13.1 Duplicate Target Names
%
919 \addcontentsline{toc
}{subsubsection
}{2.13.1 Duplicate Target Names
}%
920 \label{duplicate-target-names
}%
923 Duplicate names in section headers or other implicit targets will
924 generate "info" (level-
1) system messages. Duplicate names in
925 explicit targets will generate "warning" (level-
2) system messages.
928 %___________________________________________________________________________
930 \subsubsection*
{\phantomsection%
931 2.13.2 Duplicate Target Names
%
932 \addcontentsline{toc
}{subsubsection
}{2.13.2 Duplicate Target Names
}%
936 Since there are two "Duplicate Target Names" section headers, we
937 cannot uniquely refer to either of them by name. If we try to (like
939 \raisebox{1em
}{\hypertarget{id49
}{}}\hyperlink{id48
}{\textbf{\color{red
}`Duplicate Target Names`
\_}}), an error is generated.
942 %___________________________________________________________________________
944 \subsection*
{\phantomsection%
946 \addcontentsline{toc
}{subsection
}{2.14 Directives
}%
950 \phantomsection\label{contents
}
951 These are just a sample of the many reStructuredText Directives. For
953 \url{http://docutils.sourceforge.net/docs/ref/rst/directives.html
}.
956 %___________________________________________________________________________
958 \subsubsection*
{\phantomsection%
959 2.14.1 Document Parts
%
960 \addcontentsline{toc
}{subsubsection
}{2.14.1 Document Parts
}%
961 \label{document-parts
}%
964 An example of the "contents" directive can be seen above this section
965 (a local, untitled table of
\hyperref[contents
]{contents
}) and at the beginning of the
966 document (a
document-wide
\hyperref[table-of-contents
]{table of contents
}).
969 %___________________________________________________________________________
971 \subsubsection*
{\phantomsection%
972 2.14.2 Images and Figures
%
973 \addcontentsline{toc
}{subsubsection
}{2.14.2 Images and Figures
}%
974 \label{images-and-figures
}%
977 An image directive (also clickable -- a hyperlink reference):
979 \hyperref[directives
]{\includegraphics{../../../docs/user/rst/images/title.png
}}
981 Image with multiple IDs:
983 \includegraphics{../../../docs/user/rst/images/title.png
}
984 \phantomsection\label{image-target-
3}\label{image-target-
2}\label{image-target-
1}
988 \noindent\makebox[\textwidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
990 A left-aligned image:
992 \noindent{\includegraphics{../../../docs/user/rst/images/biohazard.png
}\hfill}
994 This paragraph might flow around the image.
995 The specific behavior depends upon the style sheet and
996 the browser or rendering software used.
998 A right-aligned image:
1000 \noindent{\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
1002 This paragraph might flow around the image.
1003 The specific behavior depends upon the style sheet and
1004 the browser or rendering software used.
1006 For inline images see
\hyperref[substitution-definitions
]{Substitution Definitions
}.
1012 \includegraphics[width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
1014 An image
2 em wide and
15 pixel high:
1016 \includegraphics[height=
15\pdfpxdimen,width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
1018 An image occupying
50\% of the line width:
1020 \includegraphics[width=
0.500\linewidth]{../../../docs/user/rst/images/title.png
}
1024 \includegraphics[height=
2cm
]{../../../docs/user/rst/images/biohazard.png
}
1026 A
\emph{figure
} is an image with a caption and/or a legend. With page-based output
1027 media, figures might float to a different position if this helps the page
1030 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
258bp
]{../../../docs/user/rst/images/title.png
}}
1031 \caption{Plaintext markup syntax and parser system.
}
1034 \setlength{\DUtablewidth}{\linewidth}
1035 \begin{longtable
}[c
]{|p
{0.156\DUtablewidth}|p
{0.563\DUtablewidth}|
}
1040 Revised, revisited, based on 're' module.
1046 Structure-enhanced text, structuredtext.
1052 Well it is, isn't it?
1057 This paragraph is also part of the legend.
1061 A left-aligned figure:
1063 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40\pdfpxdimen]{../../../docs/user/rst/images/biohazard.png
}}
1064 \caption{This is the caption.
}
1068 The legend may consist of several paragraphs.
1072 This paragraph might flow around the figure.
1074 The specific behavior depends upon the style sheet and the browser or
1075 rendering software used.
1079 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40\pdfpxdimen]{../../../docs/user/rst/images/biohazard.png
}}
1080 \caption{This is the caption.
}
1084 The legend may consist of several paragraphs.
1088 This paragraph might flow around the figure.
1090 The specific behavior depends upon the style sheet and the browser or
1091 rendering software used.
1093 A right-aligned figure:
1095 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40\pdfpxdimen]{../../../docs/user/rst/images/biohazard.png
}}
1096 \caption{This is the caption.
}
1100 The legend may consist of several paragraphs.
1104 This paragraph might flow around the figure. The specific behavior depends
1105 upon the style sheet and the browser or rendering software used.
1108 %___________________________________________________________________________
1110 \subsubsection*
{\phantomsection%
1112 \addcontentsline{toc
}{subsubsection
}{2.14.3 Admonitions
}%
1113 \label{admonitions
}%
1116 \DUadmonition[attention
]{
1117 \DUtitle[attention
]{Attention!
}
1119 Directives at large.
1122 \DUadmonition[caution
]{
1123 \DUtitle[caution
]{Caution!
}
1125 Don't take any wooden nickels.
1128 \DUadmonition[danger
]{
1129 \DUtitle[danger
]{!DANGER!
}
1131 Mad scientist at work!
1134 \DUadmonition[error
]{
1135 \DUtitle[error
]{Error
}
1140 \DUadmonition[hint
]{
1141 \DUtitle[hint
]{Hint
}
1143 It's bigger than a bread box.
1146 \DUadmonition[important
]{
1147 \DUtitle[important
]{Important
}
1151 \item Wash behind your ears.
1153 \item Clean up your room.
1155 \item Call your mother.
1157 \item Back up your data.
1162 \DUadmonition[note
]{
1163 \DUtitle[note
]{Note
}
1171 15\% if the service is good.
1174 \DUadmonition[warning
]{
1175 \DUtitle[warning
]{Warning
}
1177 Strong prose may provoke extreme mental exertion.
1178 Reader discretion is strongly advised.
1181 \DUadmonition[admonition-and-by-the-way
]{
1182 \DUtitle[admonition-and-by-the-way
]{And, by the way...
}
1184 You can make up your own admonition too.
1188 %___________________________________________________________________________
1190 \subsubsection*
{\phantomsection%
1191 2.14.4 Topics, Sidebars, and Rubrics
%
1192 \addcontentsline{toc
}{subsubsection
}{2.14.4 Topics, Sidebars, and Rubrics
}%
1193 \label{topics-sidebars-and-rubrics
}%
1196 \emph{Sidebars
} are like miniature, parallel documents.
1199 \DUtitle[title
]{Sidebar Title
}
1201 \DUsubtitle[sidebar
]{Optional Subtitle
}
1203 This is a sidebar. It is for text outside the flow of the main
1206 \DUrubric{This is a rubric inside a sidebar
}
1208 Sidebars often appear beside the main text with a border and a different
1209 background or font
color.
1212 A
\emph{topic
} is like a block quote with a title, or a self-contained section
1213 with no subsections.
1216 \DUtitle[title
]{Topic Title
}
1221 A
\emph{rubric
} is like an informal heading that doesn't correspond to the
1222 document's structure. It is typically highlighted in red (hence the name).
1224 \DUrubric{This is a rubric
}
1226 Topics and rubrics can be used at places where a
\hyperref[section-title
]{section title
} is not
1227 allowed (e.g. inside a directive).
1230 %___________________________________________________________________________
1232 \subsubsection*
{\phantomsection%
1233 2.14.5 Target Footnotes
%
1234 \addcontentsline{toc
}{subsubsection
}{2.14.5 Target Footnotes
}%
1235 \label{target-footnotes
}%
1238 \DUfootnotetext{id29
}{id30
}{5}{%
1239 \url{http://www.python.org/
}
1242 \DUfootnotetext{id33
}{id34
}{6}{%
1243 \url{http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=polyglossia
}
1246 \DUfootnotetext{id36
}{id37
}{7}{%
1247 \url{http://docutils.sourceforge.net/
}
1250 \DUfootnotetext{id38
}{id39
}{8}{%
1255 %___________________________________________________________________________
1257 \subsubsection*
{\phantomsection%
1258 2.14.6 Replacement Text
%
1259 \addcontentsline{toc
}{subsubsection
}{2.14.6 Replacement Text
}%
1260 \label{replacement-text
}%
1263 I recommend you try
\href{http://www.python.org/
}{Python,
\emph{the
} best language around
}\DUfootnotemark{id32
}{id29
}{5}.
1266 %___________________________________________________________________________
1268 \subsubsection*
{\phantomsection%
1269 2.14.7 Compound Paragraph
%
1270 \addcontentsline{toc
}{subsubsection
}{2.14.7 Compound Paragraph
}%
1271 \label{compound-paragraph
}%
1274 Compound
1, paragraph
1.
1276 Compound
1, paragraph
2.
1280 \item Compound
1, list item one.
1282 \item Compound
1, list item two.
1286 Another compound statement:
1288 Compound
2, a literal block:
1290 \begin{quote
}{\ttfamily \raggedright \noindent
1291 Compound~
2,~literal.
1294 Compound
2, this is a test.
1296 Compound
3, only consisting of one paragraph.
1298 \begin{quote
}{\ttfamily \raggedright \noindent
1300 This~one~starts~with~a~literal~block.
1303 Compound
4, a paragraph.
1305 Now something
\emph{really
} perverted -- a nested compound block. This is
1306 just to test that it works at all; the results don't have to be
1309 Compound
5, block
1 (a paragraph).
1311 Compound
6, block
2 in compound
5.
1313 Compound
6, another paragraph.
1315 Compound
5, block
3 (a paragraph).
1317 Compound
7, with a table inside:
1320 \setlength{\DUtablewidth}{\linewidth}
1321 \begin{longtable
}[c
]{|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|
}
1343 Compound
7, a paragraph after the table.
1345 Compound
7, another paragraph.
1348 %___________________________________________________________________________
1350 \subsubsection*
{\phantomsection%
1351 2.14.8 Parsed Literal Blocks
%
1352 \addcontentsline{toc
}{subsubsection
}{2.14.8 Parsed Literal Blocks
}%
1353 \label{parsed-literal-blocks
}%
1356 \begin{quote
}{\ttfamily \raggedright \noindent
1357 This~is~a~parsed~literal~block.\\
1358 ~~~~This~line~is~indented.~~The~next~line~is~blank.\\
1360 Inline~markup~is~supported,~e.g.~
\emph{emphasis
},~
\textbf{strong
},~
\texttt{literal\\
1361 text
},~footnotes
\DUfootnotemark{id22
}{id8
}{1},~
%
1362 \phantomsection\label{hyperlink-targets
}hyperlink~targets,~and~
\href{http://www.python.org/
}{references
}.
1367 %___________________________________________________________________________
1369 \subsection*
{\phantomsection%
1370 2.15 Substitution Definitions
%
1371 \addcontentsline{toc
}{subsection
}{2.15 Substitution Definitions
}%
1372 \label{substitution-definitions
}%
1375 An inline image (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}) example:
1377 (Substitution definitions are not visible in the HTML source.)
1380 %___________________________________________________________________________
1382 \subsection*
{\phantomsection%
1384 \addcontentsline{toc
}{subsection
}{2.16 Comments
}%
1390 % Comments begin with two dots and a space. Anything may
1391 % follow, except for the syntax of footnotes, hyperlink
1392 % targets, directives, or substitution definitions.
1394 % Double-dashes -- "--" -- must be escaped somehow in HTML output.
1396 % Comments may contain non-ASCII characters: ä ö ü æ ø å
1398 (View the HTML source to see the comment.)
1401 %___________________________________________________________________________
1403 \subsection*
{\phantomsection%
1405 \addcontentsline{toc
}{subsection
}{2.17 Raw text
}%
1409 This does not necessarily look nice, because there may be missing white space.
1411 It's just there to freeze the behavior.
1417 \DUrole{myclass
}{Another test with myclass set.
}
1419 This is the
\DUrole{myrawroleclass
}{fourth test
} with myrawroleclass set.
1421 Fifth test in LaTeX.\
\Line two.
1424 %___________________________________________________________________________
1426 \subsection*
{\phantomsection%
1428 \addcontentsline{toc
}{subsection
}{2.18 Container
}%
1436 % currently not implemented in LaTeX:
1437 % .. include:: data/header_footer.txt
1440 %___________________________________________________________________________
1442 \subsection*
{\phantomsection%
1443 2.19 Colspanning tables
%
1444 \addcontentsline{toc
}{subsection
}{2.19 Colspanning tables
}%
1445 \label{colspanning-tables
}%
1448 This table has a cell spanning two columns:
1451 \setlength{\DUtablewidth}{\linewidth}
1452 \begin{longtable
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.086\DUtablewidth}|
}
1454 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1470 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1485 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1523 %___________________________________________________________________________
1525 \subsection*
{\phantomsection%
1526 2.20 Rowspanning tables
%
1527 \addcontentsline{toc
}{subsection
}{2.20 Rowspanning tables
}%
1528 \label{rowspanning-tables
}%
1531 Here's a table with cells spanning several rows:
1534 \setlength{\DUtablewidth}{\linewidth}
1535 \begin{longtable
}[c
]{|p
{0.296\DUtablewidth}|p
{0.156\DUtablewidth}|p
{0.226\DUtablewidth}|
}
1538 Header row, column
1
1539 (header rows optional)
1549 Header row, column
1
1550 (header rows optional)
1558 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1562 body row
1, column
1
1571 &
\multirow{2}{0.16\DUtablewidth}{%
1574 } &
\multirow{2}{0.23\DUtablewidth}{%
1587 %___________________________________________________________________________
1589 \subsection*
{\phantomsection%
1591 \addcontentsline{toc
}{subsection
}{2.21 Custom Roles
}%
1592 \label{custom-roles
}%
1597 \item A role based on an existing role.
1599 \texttt{\DUrole{custom
}{one
}} \texttt{\DUrole{custom
}{two
}} \texttt{\DUrole{custom
}{three
}}
1603 \DUrole{customnew
}{one two three
}
1605 \item A role with class attribute.
1607 \DUrole{special
}{interpreted text
}
1609 \item A language-switching role:
1611 Let's count in German
\otherlanguage{german
}{eins zwei drei
}.
1613 \item A role with multiple class attributes, styled with raw directives:
1615 \newcommand{\DUrolegreen}[1]{\textcolor{green
}{#1}}
1616 \newcommand{\DUrolesc}[1]{\textsc{#1}}
1618 The following works in most browsers but does not validate
1619 (
\texttt{<style>
} is only allowed in the
document head):
1621 \begin{quote
}{\ttfamily \raggedright \noindent
1624 ~~<style~type="text/css"><!--\\
1625 ~~~.green~\
{color:~green;\
}\\
1626 ~~~.sc~\
{font-variant:~small-caps;\
}\\
1631 \otherlanguage{british
}{\DUrole{green
}{\DUrole{sc
}{British colourful text in small-caps
}}}.
1636 %___________________________________________________________________________
1638 \section*
{\phantomsection%
1639 3 Tests for the LaTeX writer
%
1640 \addcontentsline{toc
}{section
}{3 Tests for the LaTeX writer
}%
1641 \label{tests-for-the-latex-writer
}%
1644 Test syntax elements which may cause trouble for the LaTeX writer but might
1645 not need to be tested with other writers (e.g. the HTML writer).
1648 %___________________________________________________________________________
1650 \subsection*
{\phantomsection%
1651 3.1 Custom Roles in LaTeX
%
1652 \addcontentsline{toc
}{subsection
}{3.1 Custom Roles in LaTeX
}%
1653 \label{custom-roles-in-latex
}%
1658 \item Role names and class arguments are converted to conform to the
1659 regular expression
\texttt{{[}a-z
{]}{[}-a-z0-
9{]}*
} (letters are downcased,
1660 accents and similar decoration is stripped, non-conforming
1661 characters are replaced by a hyphen).
1663 Class arguments may contain numbers and hyphens, which need special
1664 treatment in LaTeX command names.
1666 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}}
1668 \item With LaTeX, roles can be styled within the
document using the
\DUroletitlereference{raw
}
1671 \newcommand{\DUrolelarge}[1]{{\large #1}}
1673 \@namedef
{DUrolesmall-caps
}{\textsc}
1674 \@namedef
{DUrolecustom4
}{\textbf}
1677 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}} in large, bold, small-caps.
1679 \item Custom roles can be based on standard roles:
1681 This is a
\emph{\DUrole{custom-emphasis
}{customized emphasis text role
}}
1683 This is a
\texttt{\DUrole{custom-literal
}{customized literal text role
}}
1685 This is a
\textbf{\DUrole{custom-strong
}{customized strong text role
}}
1687 This is a
\textsubscript{\DUrole{custom-subscript
}{customized subscript text role
}}
1689 This is a
\textsuperscript{\DUrole{custom-superscript
}{customized superscript text role
}}
1691 This is a
\DUroletitlereference{\DUrole{custom-title-reference
}{customized title-reference text role
}}
1695 % This file is used by the standalone_rst_latex test.
1698 %___________________________________________________________________________
1700 \subsection*
{\phantomsection%
1702 \addcontentsline{toc
}{subsection
}{3.2 Option lists
}%
1706 The LaTeX-
2e description environment is used for definition lists.
1707 The definition is continued on the same line as the term, this should
1708 not happen if a option-list is at the top of the definition.
1710 If the option list is not at the first element in the definition, it
1711 is contained in a quote
1715 \begin{DUoptionlist
}
1717 \item[--help
] show help
1726 \item[{In a definition list:
}] \leavevmode %
1727 \begin{DUoptionlist
}
1729 \item[--help
] show help
1738 %___________________________________________________________________________
1740 \subsection*
{\phantomsection%
1741 3.3 Monospaced non-alphanumeric characters
%
1742 \addcontentsline{toc
}{subsection
}{3.3 Monospaced non-alphanumeric characters
}%
1743 \label{monospaced-non-alphanumeric-characters
}%
1746 These are all ASCII characters except a-zA-Z0-
9 and space:
1748 \texttt{!!!"""\#\#\#\$\$\$\%\%\%\&\&\&'''((()))***+++,,,---...///:::
}
1750 \texttt{;;;<<<===>>>???@@@
{[}{[}{[}\textbackslash{}\textbackslash{}\textbackslash{}{]}{]}{]}\textasciicircum{}\textasciicircum{}\textasciicircum{}\_\_\_```\
{\
{\
{|||\
}\
}\
}\textasciitilde{}\textasciitilde{}\textasciitilde{}}
1752 \texttt{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
1754 The two lines of non-alphanumeric characters should both have the same
1755 width as the third line.
1758 %___________________________________________________________________________
1760 \subsection*
{\phantomsection%
1761 3.4 Non-ASCII characters
%
1762 \addcontentsline{toc
}{subsection
}{3.4 Non-ASCII characters
}%
1763 \label{non-ascii-characters
}%
1766 Punctuation and footnote symbols
1769 \setlength{\DUtablewidth}{\linewidth}
1770 \begin{longtable
}[c
]{|p
{0.028\DUtablewidth}|p
{0.424\DUtablewidth}|
}
1787 single turned comma quotation mark
1793 single comma quotation mark
1799 low single comma quotation mark
1805 double turned comma quotation mark
1811 double comma quotation mark
1817 low double comma quotation mark
1871 left-right double arrow
1876 The
\DUroletitlereference{Latin-
1 extended
} Unicode block
1879 \setlength{\DUtablewidth}{\linewidth}
1880 \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}|
}
2138 \item The following line should not be wrapped, because it uses
2139 no-break spaces (
\textbackslash{}u00a0):
2141 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
2143 \item Line wrapping with/without breakpoints marked by soft hyphens
2144 (
\textbackslash{}u00ad):
2146 pdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-sch
2148 pdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrisch
2150 \item The currency sign (
\textbackslash{}u00a4) is not supported by all fonts
2151 (some have an Euro sign at its place). You might see an error
2154 \begin{quote
}{\ttfamily \raggedright \noindent
2155 !~Package~textcomp~Error:~Symbol~
\textbackslash{}textcurrency~not~provided~by\\
2156 (textcomp)~~~~~~~~~~~~~~~~font~family~ptm~in~TS1~encoding.\\
2157 (textcomp)~~~~~~~~~~~~~~~~Default~family~used~instead.
2161 (which in case of font family ptm is a false positive). Add either
2165 turn the error in a warning, use the default symbol (bitmap), or
2167 \item[{force,almostfull:
}]
2168 use the symbol provided by the font at the users
2173 to the
document options or use a different font package.
2178 %___________________________________________________________________________
2180 \subsection*
{\phantomsection%
2181 3.5 Encoding special chars
%
2182 \addcontentsline{toc
}{subsection
}{3.5 Encoding special chars
}%
2183 \label{encoding-special-chars
}%
2186 The LaTeX Info pages lists under "
2.18 Special Characters"
2190 The following characters play a special role in LaTeX and are called
2191 "special printing characters", or simply "special characters".
2195 \# \$ \% \&
\textasciitilde{} \_ \textasciicircum{} \textbackslash{} \
{ \
}
2201 The special chars verbatim:
2203 \begin{quote
}{\ttfamily \raggedright \noindent
2204 \#~\$~\%~\&~
\textasciitilde{}~
\_~
\textasciicircum{}~
\textbackslash{}~\
{~\
}
2208 However also
\emph{square brackets
} {[}{]} need special care.
2212 item and all the other commands with optional arguments check
2213 if the token right after the macro name is an opening bracket.
2214 In that case the contents between that bracket and the following
2215 closing bracket on the same grouping level are taken as the
2216 optional argument. What makes this unintuitive is the fact that
2217 the square brackets aren't grouping characters themselves, so in
2218 your last example item
{[}{[}...
{]}{]} the optional argument consists of
2219 {[}... (without the closing bracket).
2223 Compare the items in the following lists:
2229 \item {[}bracketed
{]} item
2234 \item[{simple
}] \leavevmode
2237 \item[{{[}bracketed
{]}}] \leavevmode
2242 The OT1 font-encoding has different characters for the less-than,
2243 greater-than and bar, < | >, except for typewriter font
\DUroletitlereference{cmtt
}:
2245 \begin{quote
}{\ttfamily \raggedright \noindent
2251 %___________________________________________________________________________
2253 \subsection*
{\phantomsection%
2254 3.6 Hyperlinks and -targets
%
2255 \addcontentsline{toc
}{subsection
}{3.6 Hyperlinks and -targets
}%
2256 \label{hyperlinks-and-targets
}%
2259 In LaTeX, we must set an explicit anchor (
\texttt{\textbackslash{}phantomsection
}) for a
2261 \phantomsection\label{hypertarget-in-plain-text
}hypertarget in plain text or in a figure but not in a longtable or
2265 \setlength{\DUtablewidth}{\linewidth}
2266 \begin{longtable
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
2267 \caption{Table with
%
2268 \label{hypertarget-in-table-title
}hypertarget in table title.
}\\
2281 \phantomsection\label{figure-label
}
2282 \noindent\makebox[\textwidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
2283 \caption{Figure with
%
2284 \label{hypertarget-in-figure-caption
}hypertarget in figure caption.
}
2287 \phantomsection\label{hypertarget-in-figure-legend
}hypertarget in figure legend.
2291 \includegraphics{../../../docs/user/rst/images/biohazard.png
}
2292 \phantomsection\label{image-label
}
2294 See
\hyperref[hypertarget-in-plain-text
]{hypertarget in plain text
},
2295 \hyperref[table-label
]{table label
},
\hyperref[hypertarget-in-table-title
]{hypertarget in table title
},
2296 \hyperref[figure-label
]{figure label
},
\hyperref[hypertarget-in-figure-caption
]{hypertarget in figure caption
},
2297 \hyperref[hypertarget-in-figure-legend
]{hypertarget in figure legend
}, and
2298 \hyperref[image-label
]{image label
}.
2301 %___________________________________________________________________________
2303 \subsection*
{\phantomsection%
2304 3.7 External references
%
2305 \addcontentsline{toc
}{subsection
}{3.7 External references
}%
2306 \label{external-references
}%
2309 Long URLs should be wrapped in the PDF.
2310 This can be achieved with the url command which is used by the LaTeX writer
2311 wheneve the content (name) of a reference node equals the link URL.
2314 \item[{Example:
}] \leavevmode
2315 a long URL that should wrap in the output
2316 \url{http://docutils.sourceforge.net/docs/user/latex.html\#id79
}
2320 If the argument contains any "\%", "\#", or "
\textasciicircum{}\textasciicircum{}", or ends with
\texttt{\textbackslash{}}, it can't
2321 be used in the argument to another command. The argument must not contain
2324 The characters
\textasciicircum{}, \
{, \
}, and
\texttt{\textbackslash{}} are invalid in a "http:" or "ftp:" URL
2325 and not recognized as part of it:
2327 \begin{DUlineblock
}{0em
}
2328 \item[] \url{http://www.example.org
}/strange
\textasciicircum{}\textasciicircum{}name
2329 \item[] \url{http://www.example.org
}\textbackslash{}using
\textbackslash{}DOS
\textbackslash{}paths
\textbackslash{}
2330 \item[] \url{http://www.example.org/XML
}/strange\
{n\
}ame
2333 They can, however be used in paths and/or filenames.
2335 Handling by the LaTeX writer:
2339 \item \texttt{\#
},
\texttt{\textbackslash{}} and
\texttt{\%
} are escaped:
2341 \begin{DUlineblock
}{0em
}
2342 \item[] \href{http://www.w3.org/XML/Schema\#dev
}{URL with \#
}
2343 \url{http://www.w3.org/XML/Schema\#dev
}
2344 \item[] \href{http://www.w3.org/XML/Schema\%dev
}{URL with \%
}
2345 \url{http://example.org/Schema\%dev
}
2346 \item[] \href{A:DOS\
\path\\
}{file with DOS path
}\DUfootnotemark{id39
}{id38
}{8} \url{A:DOS\
\path\\
}\DUfootnotemark{id40
}{id38
}{8}
2349 \DUadmonition[note
]{
2350 \DUtitle[note
]{Note
}
2352 These URLs are typeset inside a LaTeX command without error.
2354 \begin{DUlineblock
}{0em
}
2355 \item[] \url{http://www.w3.org/XML/Schema\#dev
}
2356 \item[] \url{http://example.org/Schema\%dev
}
2357 \item[] \url{A:DOS\
\path\\
}\DUfootnotemark{id41
}{id38
}{8}
2365 \item \textasciicircum{}\textasciicircum{} LaTeX's special syntax for characters results in "strange" replacements
2366 (both with href and url). A warning is given.
2368 \href{../strange^^name
}{file with
\textasciicircum{}\textasciicircum{}}:
2369 \url{../strange^^name
}
2371 \item Unbalanced braces, \
{ or \
}, will fail (both with href and url):
2373 \begin{quote
}{\ttfamily \raggedright \noindent
2374 `file~with~\
{~<../strange\
{name>`
\_\_\\
2375 `<../strange\
{name>`
\_\_
2379 while balanced braces are suported:
2381 \begin{DUlineblock
}{0em
}
2382 \item[] \url{../strange
{n
}ame
}
2383 \item[] \url{../st
{r
}ange
{n
}ame
}
2384 \item[] \url{../
{st
{r
}ange
{n
}ame
}}
2390 %___________________________________________________________________________
2392 \section*
{\phantomsection%
2393 4 Tests for the XeTeX writer
%
2394 \addcontentsline{toc
}{section
}{4 Tests for the XeTeX writer
}%
2395 \label{tests-for-the-xetex-writer
}%
2398 With XeTeX, you can typeset text in any language/script supported by
2399 Unicode and the selected font, e.g. Azərbaycanca, Bân-lâm-gú, Башҡорт
2400 Беларуская, Български, Català, Чӑвашла, Česky, Ελληνικά, Español,
2401 Français, Føroyskt, Хальмг, Íslenska, עברית , Қазақша, Kurdî,
2402 Latviešu, Lietuvių, Македонски, Монгол, Nāhuatl, Português, Română,
2403 Русский, Slovenščina, Српски, Türkçe, Українська, Tiếng Việt, Volapük,
2404 Võro, ייִדיש , Žemaitėška.
2405 Currently, there is extended support for
28 languages in the
2406 \href{http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=polyglossia
}{polyglossia
}\DUfootnotemark{id34
}{id33
}{6} package.
2411 %___________________________________________________________________________
2413 \section*
{\phantomsection%
2415 \addcontentsline{toc
}{section
}{5 Error Handling
}%
2416 \label{error-handling
}%
2419 Any errors caught during processing will generate system messages.
2421 There should be five messages in the following, auto-generated
2422 section, "Docutils System Messages":
2424 % section should be added by Docutils automatically
2427 %___________________________________________________________________________
2429 \section*
{\phantomsection%
2430 \color{red
}Docutils System Messages
%
2431 \addcontentsline{toc
}{section
}{Docutils System Messages
}%
2434 \DUadmonition[system-message
]{
2435 \DUtitle[system-message
]{system-message
}
2436 \raisebox{1em
}{\hypertarget{id27
}{}}
2438 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
104
2441 Undefined substitution referenced: "problematic".
2444 \DUadmonition[system-message
]{
2445 \DUtitle[system-message
]{system-message
}
2446 \raisebox{1em
}{\hypertarget{id42
}{}}
2448 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
390
2451 Unknown target name: "
5".
2454 \DUadmonition[system-message
]{
2455 \DUtitle[system-message
]{system-message
}
2456 \raisebox{1em
}{\hypertarget{id44
}{}}
2458 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
399
2461 Unknown target name: "nonexistent".
2464 \DUadmonition[system-message
]{
2465 \DUtitle[system-message
]{system-message
}
2466 \raisebox{1em
}{\hypertarget{id46
}{}}
2468 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
426
2471 Unknown target name: "hyperlink reference without a target".
2474 \DUadmonition[system-message
]{
2475 \DUtitle[system-message
]{system-message
}
2476 \raisebox{1em
}{\hypertarget{id48
}{}}
2478 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
439
2481 Duplicate target name, cannot be used as a unique reference: "duplicate target names".