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
}
8 \usepackage{polyglossia
}
9 \setdefaultlanguage{english
}
10 \setotherlanguages{german,british,french
}
12 \usepackage{float
} % float configuration
13 \floatplacement{figure
}{H
} % place figures here definitely
16 \setcounter{secnumdepth
}{0}
17 \usepackage{longtable,ltcaption,array
}
18 \setlength{\extrarowheight}{2pt
}
19 \newlength{\DUtablewidth} % internal use in tables
22 %%% Custom LaTeX preamble
23 % Linux Libertine (free, wide coverage, not only for Linux)
24 \setmainfont{Linux Libertine O
}
25 \setsansfont{Linux Biolinum O
}
26 \setmonofont[HyphenChar=None
]{DejaVu Sans Mono
}
28 %%% User specified packages and stylesheets
30 %%% Fallback definitions for Docutils-specific commands
32 % providelength (provide a length variable and set default, if it is new)
33 \providecommand*
{\DUprovidelength}[2]{
34 \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{}
38 \providecommand*
{\DUtitleabstract}[1]{\centerline{\textbf{#1}}}
40 % admonition (specially marked topic)
41 \providecommand{\DUadmonition}[2][class-arg
]{%
42 % try \DUadmonition#1{#2}:
43 \ifcsname DUadmonition
#1\endcsname%
44 \csname DUadmonition
#1\endcsname{#2}%
47 \fbox{\parbox{0.9\textwidth}{#2}}
53 \@namedef
{DUrolealign-center
}{\centering}
58 \providecommand{\DUtopicdedication}[1]{\begin{center
}#1\end{center
}}
60 % docinfo (width of docinfo table)
61 \DUprovidelength{\DUdocinfowidth}{0.9\textwidth}
63 % error admonition title
64 \providecommand*
{\DUtitleerror}[1]{\DUtitle{\color{red
}#1}}
66 % fieldlist environment
67 \ifthenelse{\isundefined{\DUfieldlist}}{
68 \newenvironment{DUfieldlist
}%
70 {\enddescription\endquote}
72 % numeric or symbol footnotes with hyperlinks
73 \providecommand*
{\DUfootnotemark}[3]{%
74 \raisebox{1em
}{\hypertarget{#1}{}}%
75 \hyperlink{#2}{\textsuperscript{#3}}%
77 \providecommand{\DUfootnotetext}[4]{%
79 \renewcommand{\thefootnote}{%
80 \protect\raisebox{1em
}{\protect\hypertarget{#1}{}}%
81 \protect\hyperlink{#2}{#3}}%
86 % inline markup (custom roles)
87 % \DUrole{#1}{#2} tries \DUrole#1{#2}
88 \providecommand*
{\DUrole}[2]{%
89 \ifcsname DUrole
#1\endcsname%
90 \csname DUrole
#1\endcsname{#2}%
91 \else% backwards compatibility: try \docutilsrole#1{#2}
92 \ifcsname docutilsrole
#1\endcsname%
93 \csname docutilsrole
#1\endcsname{#2}%
101 \ifthenelse{\isundefined{\DUlegend}}{
102 \newenvironment{DUlegend
}{\small}{}
105 % lineblock environment
106 \DUprovidelength{\DUlineblockindent}{2.5em
}
107 \ifthenelse{\isundefined{\DUlineblock}}{
108 \newenvironment{DUlineblock
}[1]{%
109 \list{}{\setlength{\partopsep}{\parskip}
110 \addtolength{\partopsep}{\baselineskip}
111 \setlength{\topsep}{0pt
}
112 \setlength{\itemsep}{0.15\baselineskip}
113 \setlength{\parsep}{0pt
}
114 \setlength{\leftmargin}{#1}}
120 % optionlist environment
121 \providecommand*
{\DUoptionlistlabel}[1]{\bf #1 \hfill}
122 \DUprovidelength{\DUoptionlistindent}{3cm
}
123 \ifthenelse{\isundefined{\DUoptionlist}}{
124 \newenvironment{DUoptionlist
}{%
125 \list{}{\setlength{\labelwidth}{\DUoptionlistindent}
126 \setlength{\rightmargin}{1cm
}
127 \setlength{\leftmargin}{\rightmargin}
128 \addtolength{\leftmargin}{\labelwidth}
129 \addtolength{\leftmargin}{\labelsep}
130 \renewcommand{\makelabel}{\DUoptionlistlabel}}
135 \DUprovidelength{\pdfpxdimen}{1bp
}
138 % rubric (informal heading)
139 \providecommand*
{\DUrubric}[2][class-arg
]{%
140 \subsubsection*
{\centering\textit{\textmd{#2}}}}
142 % sidebar (text outside the main text flow)
143 \providecommand{\DUsidebar}[2][class-arg
]{%
145 \colorbox[gray
]{0.80}{\parbox{0.9\textwidth}{#2}}
149 % subtitle (for topic/sidebar)
150 \providecommand*
{\DUsubtitle}[2][class-arg
]{\par\emph{#2}\smallskip}
152 % title for topics, admonitions, unsupported section levels, and sidebar
153 \providecommand*
{\DUtitle}[2][class-arg
]{%
154 % call \DUtitle#1{#2} if it exists:
155 \ifcsname DUtitle
#1\endcsname%
156 \csname DUtitle
#1\endcsname{#2}%
158 \smallskip\noindent\textbf{#2}\smallskip%
162 % titlereference role
163 \providecommand*
{\DUroletitlereference}[1]{\textsl{#1}}
165 % topic (quote with heading)
166 \providecommand{\DUtopic}[2][class-arg
]{%
167 \ifcsname DUtopic
#1\endcsname%
168 \csname DUtopic
#1\endcsname{#2}%
170 \begin{quote
}#2\end{quote
}
174 % transition (break, fancybreak, anonymous section)
175 \providecommand*
{\DUtransition}[1][class-arg
]{%
176 \hspace*
{\fill}\hrulefill\hspace*
{\fill}
177 \vskip 0.5\baselineskip
181 \ifthenelse{\isundefined{\hypersetup}}{
182 \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue
]{hyperref
}
183 \urlstyle{same
} % normal text font (alternatives: tt, rm, sf)
186 pdftitle=
{reStructuredText Test Document
},
187 pdfauthor=
{David Goodger;Me;Myself;I
}
191 \title{\phantomsection%
192 reStructuredText Test Document
%
193 \label{restructuredtext-test-
document}%
196 \large{Examples of Syntax Constructs
}%
197 \label{examples-of-syntax-constructs
}%
208 \begin{tabularx
}{\DUdocinfowidth}{lX
}
217 \href{mailto:goodger@python.org
}{goodger@python.org
} \\
224 \textbf{Organization
}: &
227 Now, or yesterday. Or maybe even
\emph{before
} yesterday. \\
229 This is a "work in progress" \\
231 is managed by a version control system. \\
234 \textbf{Copyright
}: &
235 This
document has been placed in the public domain. You
236 may do with it as you wish. You may copy, modify,
237 redistribute, reattribute, sell, buy, rent, lease,
238 destroy, or improve it, quote it at length, excerpt,
239 incorporate, collate, fold, staple, or mutilate it, or do
240 anything else to it that your or anyone else's heart
242 \textbf{field name
}: &
243 This is a "generic bibliographic field".
245 \textbf{field name "
2"
}: &
246 Generic bibliographic fields may contain multiple body elements.
253 \DUtopic[dedication
]{
254 \DUtitle[dedication
]{Dedication
}
256 For Docutils users \& co-developers.
260 \DUtitle[abstract
]{Abstract
}
262 This is a test
document, containing at least one example of each
263 reStructuredText construct.
266 % This is a comment. Note how any initial comments are moved by
267 % transforms to after the document title, subtitle, and docinfo.
269 % Above is the document title, and below is the subtitle.
270 % They are transformed from section titles after parsing.
272 % bibliographic fields (which also require a transform):
274 \pagebreak[4] % start ToC on new page
276 \phantomsection\label{table-of-contents
}
277 \pdfbookmark[1]{Table of Contents
}{table-of-contents
}
278 \renewcommand{\contentsname}{Table of Contents
}
283 \section{1 Structural Elements
%
284 \label{structural-elements
}%
288 \subsection{1.1 Section Title
%
289 \label{section-title
}%
291 \subsubsection*
{Section Subtitle
}
293 Lone subsections are converted to a section subtitle by a transform
294 activated with the
\texttt{--section-subtitles
} command line option or the
295 \texttt{sectsubtitle-xform
} configuration value.
298 \subsection{1.2 Empty Section
%
299 \label{empty-section
}%
303 \subsection{1.3 Transitions
%
310 %___________________________________________________________________________
314 It divides the section. Transitions may also occur between sections:
317 %___________________________________________________________________________
322 \section{2 Body Elements
%
323 \label{body-elements
}%
327 \subsection{2.1 Paragraphs
%
334 \subsubsection{2.1.1 Inline Markup
%
335 \label{inline-markup
}%
338 Paragraphs contain text and may contain inline markup:
\emph{emphasis
},
339 \textbf{strong emphasis
},
\texttt{inline literals
}, standalone hyperlinks
340 (
\url{http://www.python.org
}), external hyperlinks (
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id30
}{id29
}{5}), internal
341 cross-references (
\hyperref[example
]{example
}), external hyperlinks with embedded URIs
342 (
\href{http://www.python.org
}{Python web site
}),
\href{http://www.python.org/
}{anonymous hyperlink
343 references
}\DUfootnotemark{id37
}{id29
}{5} (
\href{http://docutils.sourceforge.net/
}{a second reference
}\DUfootnotemark{id39
}{id38
}{8}), footnote references (manually
344 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
]}),
345 substitution references (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}), and
%
346 \phantomsection\label{inline-hyperlink-targets
}inline hyperlink targets
347 (see
\hyperref[targets
]{Targets
} below for a reference back to here). Character-level
348 inline markup is also possible (although exceedingly ugly!) in
\emph{re
}\texttt{Structured
}\emph{Text
}. Problems are indicated by
%
349 \raisebox{1em
}{\hypertarget{id28
}{}}\hyperlink{id27
}{\textbf{\color{red
}|problematic|
}} text
350 (generated by processing errors; this one is intentional). Here is a
351 reference to the
\hyperref[doctitle
]{doctitle
} and the
\hyperref[subtitle
]{subtitle
}.
353 The default role for interpreted text is
\DUroletitlereference{Title Reference
}. Here are
354 some explicit interpreted text roles: a PEP reference (
\href{http://www.python.org/dev/peps/pep-
0287}{PEP
287}); an
355 RFC reference (
\href{http://www.faqs.org/rfcs/rfc2822.html
}{RFC
2822}); an abbreviation (
\DUrole{abbreviation
}{abb.
}), an acronym
356 (
\DUrole{acronym
}{reST
}), code (
\texttt{\DUrole{code
}{print "hello world"
}}); a
\textsubscript{subscript
};
357 a
\textsuperscript{superscript
} and explicit roles for
\DUroletitlereference{Docutils
}'
358 \emph{standard
} \textbf{inline
} \texttt{markup
}.
360 % DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
362 Let's test wrapping and whitespace significance in inline literals:
363 \texttt{This is an example of --inline-literal --text, --including some--
364 strangely--hyphenated-words. ~Adjust-the-width-of-your-browser-window
365 to see how the text is wrapped. ~-- ---- -------- ~Now note ~ ~the
366 spacing ~ ~between the ~ ~words of ~ ~this sentence ~ ~(words
367 should ~ ~be grouped ~ ~in pairs).
}
369 If the
\texttt{--pep-references
} option was supplied, there should be a
370 live link to PEP
258 here.
373 \subsection{2.2 Bullet Lists
%
374 \label{bullet-lists
}%
383 \item Nested bullet list.
391 Paragraph
2 of item
2.
395 \item Nested bullet list.
409 \item This nested list should be compacted by the HTML writer.
411 \phantomsection\label{target
}
412 % Even if this item contains a target and a comment.
419 \subsection{2.3 Enumerated Lists
%
420 \label{enumerated-lists
}%
422 \newcounter{listcnt0
}
423 \begin{list
}{\arabic{listcnt0
}.
}
425 \usecounter{listcnt0
}
426 \setlength{\rightmargin}{\leftmargin}
429 \item Arabic numerals.
430 \newcounter{listcnt1
}
431 \begin{list
}{\alph{listcnt1
})
}
433 \usecounter{listcnt1
}
434 \setlength{\rightmargin}{\leftmargin}
438 \newcounter{listcnt2
}
439 \begin{list
}{(
\roman{listcnt2
})
}
441 \usecounter{listcnt2
}
442 \setlength{\rightmargin}{\leftmargin}
446 \newcounter{listcnt3
}
447 \begin{list
}{\Alph{listcnt3
}.
}
449 \usecounter{listcnt3
}
450 \setlength{\rightmargin}{\leftmargin}
454 \newcounter{listcnt4
}
455 \begin{list
}{\Roman{listcnt4
})
}
457 \usecounter{listcnt4
}
458 \setlength{\rightmargin}{\leftmargin}
467 \item Lists that don't start at
1:
468 \setcounter{listcnt1
}{0}
469 \begin{list
}{\arabic{listcnt1
}.
}
471 \usecounter{listcnt1
}
472 \addtocounter{listcnt1
}{2}
473 \setlength{\rightmargin}{\leftmargin}
480 \setcounter{listcnt1
}{0}
481 \begin{list
}{\Alph{listcnt1
}.
}
483 \usecounter{listcnt1
}
484 \addtocounter{listcnt1
}{2}
485 \setlength{\rightmargin}{\leftmargin}
492 \setcounter{listcnt1
}{0}
493 \begin{list
}{\roman{listcnt1
}.
}
495 \usecounter{listcnt1
}
496 \addtocounter{listcnt1
}{2}
497 \setlength{\rightmargin}{\leftmargin}
507 \subsection{2.4 Definition Lists
%
508 \label{definition-lists
}%
512 \item[{Term
}] \leavevmode
515 \item[{Term
}] \leavevmode (
\textbf{classifier
})
517 Definition paragraph
1.
519 Definition paragraph
2.
521 \item[{Term
}] \leavevmode
524 \item[{Term
}] \leavevmode (
\textbf{classifier one
})
525 (
\textbf{classifier two
})
532 \subsection{2.5 Field Lists
%
538 Field lists map field names to field bodies, like database
539 records. They are often part of an extension syntax. They are
540 an unambiguous variant of RFC
2822 fields.
542 \item[{how arg1 arg2:
}]
543 The field marker is a colon, the field name, and a colon.
545 The field body may contain one or more body elements, indented
546 relative to the field marker.
549 \DUrole{credits
}{This paragraph has the
\DUroletitlereference{credits
} class set. (This is actually not
550 about credits but just for ensuring that the class attribute
551 doesn't get stripped away.)
}
556 \subsection{2.6 Option Lists
%
557 \label{option-lists
}%
560 For listing command-line options:
564 \item[-a
] command-line option "a"
566 \item[-b file
] options can have arguments
567 and long descriptions
569 \item[--long
] options can be long also
571 \item[--input=file
] long options can also have
574 \item[--very-long-option
] The description can also start on the next line.
576 The description may contain multiple body elements,
577 regardless of where it starts.
579 \item[-x, -y, -z
] Multiple options are an "option group".
581 \item[-v, --verbose
] Commonly-seen: short \& long options.
583 \item[-
1 file, --one=file, --two file
] Multiple options with arguments.
585 \item[/V
] DOS/VMS-style options too
589 There must be at least two spaces between the option and the
593 \subsection{2.7 Literal Blocks
%
594 \label{literal-blocks
}%
597 Literal blocks are indicated with a double-colon ("::") at the end of
598 the preceding paragraph (over there
\texttt{-->
}). They can be indented:
600 \begin{quote
}{\ttfamily \raggedright \noindent
602 ~~~~text~=~'is~left~as-is'\\
603 ~~~~spaces
\_and\_linebreaks~=~'are~preserved'\\
604 ~~~~markup
\_processing~=~None
608 Or they can be quoted without indentation:
610 \begin{quote
}{\ttfamily \raggedright \noindent
613 >~Why~didn't~I~think~of~that?
618 \subsection{2.8 Line Blocks
%
622 This section tests line blocks. Line blocks are body elements which
623 consist of lines and other line blocks. Nested line blocks cause
626 \begin{DUlineblock
}{0em
}
627 \item[] This is a line block. It ends with a blank line.
629 \begin{DUlineblock
}{\DUlineblockindent}
630 \item[] New lines begin with a vertical bar ("|").
631 \item[] Line breaks and initial indent are significant, and preserved.
633 \begin{DUlineblock
}{\DUlineblockindent}
634 \item[] Continuation lines are also possible. A long line that is intended
635 to wrap should begin with a space in place of the vertical bar.
637 \item[] The left edge of a continuation line need not be aligned with
638 the left edge of the text above it.
642 \begin{DUlineblock
}{0em
}
643 \item[] This is a second line block.
645 \item[] Blank lines are permitted internally, but they must begin with a "|".
648 Another line block, surrounded by paragraphs:
650 \begin{DUlineblock
}{0em
}
651 \item[] And it's no good waiting by the window
652 \item[] It's no good waiting for the sun
653 \item[] Please believe me, the things you dream of
654 \item[] They don't fall in the lap of no-one
657 Take it away, Eric the Orchestra Leader!
661 \begin{DUlineblock
}{0em
}
662 \item[] A one, two, a one two three four
664 \item[] Half a bee, philosophically,
666 \begin{DUlineblock
}{\DUlineblockindent}
667 \item[] must,
\emph{ipso facto
}, half not be.
669 \item[] But half the bee has got to be,
671 \begin{DUlineblock
}{\DUlineblockindent}
672 \item[] \emph{vis a vis
} its entity. D'you see?
675 \item[] But can a bee be said to be
677 \begin{DUlineblock
}{\DUlineblockindent}
678 \item[] or not to be an entire bee,
680 \begin{DUlineblock
}{\DUlineblockindent}
681 \item[] when half the bee is not a bee,
683 \begin{DUlineblock
}{\DUlineblockindent}
684 \item[] due to some ancient injury?
694 A line block, like the following poem by Christian Morgenstern, can
695 also be centre-aligned:
697 \begin{DUlineblock
}{0em
}
698 \otherlanguage{german
}{\DUrole{align-center
}{
699 \item[] \textbf{Die Trichter
}
701 \item[] Zwei Trichter wandeln durch die Nacht.
702 \item[] Durch ihres Rumpfs verengten Schacht
703 \item[] fließt weißes Mondlicht
704 \item[] still und heiter
714 \subsection{2.9 Block Quotes
%
715 \label{block-quotes
}%
718 Block quotes consist of indented body elements:
722 My theory by A. Elk. Brackets Miss, brackets. This theory goes
723 as follows and begins now. All brontosauruses are thin at one
724 end, much much thicker in the middle and then thin again at the
725 far end. That is my theory, it is mine, and belongs to me and I
726 own it, and what it is too.
729 \raggedleft —Anne Elk (Miss)
733 The language of a quote (like any other object) can be specified by
739 \otherlanguage{french
}{
740 ReStructuredText est un langage de balisage léger utilisé
741 notamment dans la documentation du langage Python.
746 \subsection{2.10 Doctest Blocks
%
747 \label{doctest-blocks
}%
750 \begin{quote
}{\ttfamily \raggedright \noindent
751 >>>~print~'Python-specific~usage~examples;~begun~with~">>>"'\\
752 Python-specific~usage~examples;~begun~with~">>>"\\
753 >>>~print~'(cut~and~pasted~from~interactive~Python~sessions)'\\
754 (cut~and~pasted~from~interactive~Python~sessions)
759 \subsection{2.11 Footnotes
%
763 \DUfootnotetext{id8
}{id1
}{1}{%
764 A footnote contains body elements, consistently indented by at
767 This is the footnote's second paragraph.
770 \DUfootnotetext{label
}{id3
}{2}{\phantomsection\label{label
}%
771 Footnotes may be numbered, either manually (as in
\DUfootnotemark{id9
}{id8
}{1}) or
772 automatically using a "\#"-prefixed label. This footnote has a
773 label so it can be referred to from multiple places, both as a
774 footnote reference (
\DUfootnotemark{id10
}{label
}{2}) and as a
\hyperref[label
]{hyperlink reference
}.
777 \DUfootnotetext{id12
}{id2
}{3}{%
778 This footnote is numbered automatically and anonymously using a
781 This is the second paragraph.
783 And this is the third paragraph.
786 \DUfootnotetext{id13
}{id4
}{*
}{%
787 Footnotes may also use symbols, specified with a "*" label.
788 Here's a reference to the next footnote:
\DUfootnotemark{id14
}{id15
}{†
}.
791 \DUfootnotetext{id15
}{id14
}{†
}{%
792 This footnote shows the next symbol in the sequence.
795 \DUfootnotetext{id16
}{id16
}{4}{%
796 Here's an unreferenced footnote, with a reference to a
797 nonexistent footnote:
%
798 \raisebox{1em
}{\hypertarget{id45
}{}}%
799 \raisebox{1em
}{\hypertarget{id17
}{}}\hyperlink{id44
}{\textbf{\color{red
}{[}5{]}\_}}.
803 \subsection{2.12 Citations
%
806 \begin{figure
}[b
]\raisebox{1em
}{\hypertarget{cit2002
}{}}[CIT2002
]
807 Citations are text-labeled footnotes. They may be
808 rendered separately and differently from footnotes.
811 Here's a reference to the above,
\hyperlink{cit2002
}{[CIT2002
]}, and a
%
812 \raisebox{1em
}{\hypertarget{id47
}{}}%
813 \raisebox{1em
}{\hypertarget{id19
}{}}\hyperlink{id46
}{\textbf{\color{red
}{[}nonexistent
{]}\_}}
817 \subsection{2.13 Targets
%
819 \label{another-target
}%
822 \phantomsection\label{example
}
823 This paragraph is pointed to by the explicit "example" target. A
824 reference can be found under
\hyperref[inline-markup
]{Inline Markup
}, above.
\hyperref[inline-hyperlink-targets
]{Inline
825 hyperlink targets
} are also possible.
827 Section headers are implicit targets, referred to by name. See
828 \hyperref[targets
]{Targets
}, which is a subsection of
\hyperref[body-elements
]{Body Elements
}.
830 Explicit external targets are interpolated into references such as
831 "
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id31
}{id29
}{5}".
833 Targets may be indirect and anonymous. Thus
\hyperref[targets
]{this phrase
} may also
834 refer to the
\hyperref[targets
]{Targets
} section.
837 \raisebox{1em
}{\hypertarget{id49
}{}}\hyperlink{id48
}{\textbf{\color{red
}`hyperlink reference without a target`
\_}}, which generates an
841 \subsubsection{2.13.1 Duplicate Target Names
%
842 \label{duplicate-target-names
}%
845 Duplicate names in section headers or other implicit targets will
846 generate "info" (level-
1) system messages. Duplicate names in
847 explicit targets will generate "warning" (level-
2) system messages.
850 \subsubsection{2.13.2 Duplicate Target Names
%
854 Since there are two "Duplicate Target Names" section headers, we
855 cannot uniquely refer to either of them by name. If we try to (like
857 \raisebox{1em
}{\hypertarget{id51
}{}}\hyperlink{id50
}{\textbf{\color{red
}`Duplicate Target Names`
\_}}), an error is generated.
860 \subsection{2.14 Directives
%
864 \phantomsection\label{contents
}
865 These are just a sample of the many reStructuredText Directives. For
867 \url{http://docutils.sourceforge.net/docs/ref/rst/directives.html
}.
870 \subsubsection{2.14.1 Document Parts
%
871 \label{document-parts
}%
874 An example of the "contents" directive can be seen above this section
875 (a local, untitled table of
\hyperref[contents
]{contents
}) and at the beginning of the
876 document (a
document-wide
\hyperref[table-of-contents
]{table of contents
}).
879 \subsubsection{2.14.2 Images and Figures
%
880 \label{images-and-figures
}%
883 An image directive (also clickable -- a hyperlink reference):
885 \hyperref[directives
]{\includegraphics{../../../docs/user/rst/images/title.png
}}
887 Image with multiple IDs:
889 \includegraphics{../../../docs/user/rst/images/title.png
}
890 \phantomsection\label{image-target-
3}\label{image-target-
2}\label{image-target-
1}
894 \noindent\makebox[\textwidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
896 A left-aligned image:
898 \noindent{\includegraphics{../../../docs/user/rst/images/biohazard.png
}\hfill}
900 This paragraph might flow around the image.
901 The specific behavior depends upon the style sheet and
902 the browser or rendering software used.
904 A right-aligned image:
906 \noindent{\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
908 This paragraph might flow around the image.
909 The specific behavior depends upon the style sheet and
910 the browser or rendering software used.
912 For inline images see
\hyperref[substitution-definitions
]{Substitution Definitions
}.
918 \includegraphics[width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
920 An image
2 em wide and
15 pixel high:
922 \includegraphics[height=
15\pdfpxdimen,width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
924 An image occupying
50\% of the line width:
926 \includegraphics[width=
0.500\linewidth]{../../../docs/user/rst/images/title.png
}
930 \includegraphics[height=
2cm
]{../../../docs/user/rst/images/biohazard.png
}
932 A
\emph{figure
} is an image with a caption and/or a legend. With page-based output
933 media, figures might float to a different position if this helps the page
936 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
258bp
]{../../../docs/user/rst/images/title.png
}}
937 \caption{Plaintext markup syntax and parser system.
}
939 \setlength{\DUtablewidth}{\linewidth}
940 \begin{longtable*
}[c
]{|p
{0.156\DUtablewidth}|p
{0.563\DUtablewidth}|
}
945 Revised, revisited, based on 're' module.
951 Structure-enhanced text, structuredtext.
957 Well it is, isn't it?
962 This paragraph is also part of the legend.
966 A left-aligned figure:
968 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40\pdfpxdimen]{../../../docs/user/rst/images/biohazard.png
}}
969 \caption{This is the caption.
}
973 The legend may consist of several paragraphs.
977 This paragraph might flow around the figure.
979 The specific behavior depends upon the style sheet and the browser or
980 rendering software used.
984 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40\pdfpxdimen]{../../../docs/user/rst/images/biohazard.png
}}
985 \caption{This is the caption.
}
989 The legend may consist of several paragraphs.
993 This paragraph might flow around the figure.
995 The specific behavior depends upon the style sheet and the browser or
996 rendering software used.
998 A right-aligned figure:
1000 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40\pdfpxdimen]{../../../docs/user/rst/images/biohazard.png
}}
1001 \caption{This is the caption.
}
1005 The legend may consist of several paragraphs.
1009 This paragraph might flow around the figure. The specific behavior depends
1010 upon the style sheet and the browser or rendering software used.
1013 \subsubsection{2.14.3 Admonitions
%
1014 \label{admonitions
}%
1017 \DUadmonition[attention
]{
1018 \DUtitle[attention
]{Attention!
}
1020 Directives at large.
1023 \DUadmonition[caution
]{
1024 \DUtitle[caution
]{Caution!
}
1026 Don't take any wooden nickels.
1029 \DUadmonition[danger
]{
1030 \DUtitle[danger
]{!DANGER!
}
1032 Mad scientist at work!
1035 \DUadmonition[error
]{
1036 \DUtitle[error
]{Error
}
1041 \DUadmonition[hint
]{
1042 \DUtitle[hint
]{Hint
}
1044 It's bigger than a bread box.
1047 \DUadmonition[important
]{
1048 \DUtitle[important
]{Important
}
1052 \item Wash behind your ears.
1054 \item Clean up your room.
1056 \item Call your mother.
1058 \item Back up your data.
1063 \DUadmonition[note
]{
1064 \DUtitle[note
]{Note
}
1072 15\% if the service is good.
1075 \DUadmonition[warning
]{
1076 \DUtitle[warning
]{Warning
}
1078 Strong prose may provoke extreme mental exertion.
1079 Reader discretion is strongly advised.
1082 \DUadmonition[admonition-and-by-the-way
]{
1083 \DUtitle[admonition-and-by-the-way
]{And, by the way...
}
1085 You can make up your own admonition too.
1089 \subsubsection{2.14.4 Topics, Sidebars, and Rubrics
%
1090 \label{topics-sidebars-and-rubrics
}%
1093 \emph{Sidebars
} are like miniature, parallel documents.
1096 \DUtitle[title
]{Sidebar Title
}
1098 \DUsubtitle[sidebar
]{Optional Subtitle
}
1100 This is a sidebar. It is for text outside the flow of the main
1103 \DUrubric{This is a rubric inside a sidebar
}
1105 Sidebars often appear beside the main text with a border and a different
1106 background or font
color.
1109 A
\emph{topic
} is like a block quote with a title, or a self-contained section
1110 with no subsections.
1113 \DUtitle[title
]{Topic Title
}
1118 A
\emph{rubric
} is like an informal heading that doesn't correspond to the
1119 document's structure. It is typically highlighted in red (hence the name).
1121 \DUrubric{This is a rubric
}
1123 Topics and rubrics can be used at places where a
\hyperref[section-title
]{section title
} is not
1124 allowed (e.g. inside a directive).
1127 \subsubsection{2.14.5 Target Footnotes
%
1128 \label{target-footnotes
}%
1131 \DUfootnotetext{id29
}{id30
}{5}{%
1132 \url{http://www.python.org/
}
1135 \DUfootnotetext{id33
}{id34
}{6}{%
1136 \url{http://pygments.org/
}
1139 \DUfootnotetext{id35
}{id36
}{7}{%
1140 \url{http://ctan.org/pkg/polyglossia
}
1143 \DUfootnotetext{id38
}{id39
}{8}{%
1144 \url{http://docutils.sourceforge.net/
}
1147 \DUfootnotetext{id40
}{id41
}{9}{%
1152 \subsubsection{2.14.6 Replacement Text
%
1153 \label{replacement-text
}%
1156 I recommend you try
\href{http://www.python.org/
}{Python,
\emph{the
} best language around
}\DUfootnotemark{id32
}{id29
}{5}.
1159 \subsubsection{2.14.7 Compound Paragraph
%
1160 \label{compound-paragraph
}%
1163 Compound
1, paragraph
1.
1165 Compound
1, paragraph
2.
1169 \item Compound
1, list item one.
1171 \item Compound
1, list item two.
1175 Another compound statement:
1177 Compound
2, a literal block:
1179 \begin{quote
}{\ttfamily \raggedright \noindent
1180 Compound~
2,~literal.
1183 Compound
2, this is a test.
1185 Compound
3, only consisting of one paragraph.
1187 \begin{quote
}{\ttfamily \raggedright \noindent
1189 This~one~starts~with~a~literal~block.
1192 Compound
4, a paragraph.
1194 Now something
\emph{really
} perverted -- a nested compound block. This is
1195 just to test that it works at all; the results don't have to be
1198 Compound
5, block
1 (a paragraph).
1200 Compound
6, block
2 in compound
5.
1202 Compound
6, another paragraph.
1204 Compound
5, block
3 (a paragraph).
1206 Compound
7, with a table inside:
1208 \setlength{\DUtablewidth}{\linewidth}
1209 \begin{longtable*
}[c
]{|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|
}
1231 Compound
7, a paragraph after the table.
1233 Compound
7, another paragraph.
1236 \subsubsection{2.14.8 Parsed Literal Blocks
%
1237 \label{parsed-literal-blocks
}%
1240 \begin{quote
}{\ttfamily \raggedright \noindent
1241 This~is~a~parsed~literal~block.\\
1242 ~~~~This~line~is~indented.~~The~next~line~is~blank.\\
1244 Inline~markup~is~supported,~e.g.~
\emph{emphasis
},~
\textbf{strong
},~
\texttt{literal\\
1245 text
},~footnotes
\DUfootnotemark{id22
}{id8
}{1},~
%
1246 \phantomsection\label{hyperlink-targets
}hyperlink~targets,~and~
\href{http://www.python.org/
}{references
}.
1251 \subsubsection{2.14.9 Code
%
1255 Blocks of source code can be set with the
\DUroletitlereference{code
} directive. If the code
1256 language is specified, the content is parsed and tagged by the
\href{http://pygments.org/
}{Pygments
}\DUfootnotemark{id34
}{id33
}{6}
1257 syntax highlighter and can be formatted with a style sheet. (Code parsing
1258 is turned off using the
\texttt{syntax-highlight
} config setting in the test
1259 conversions in order to get identical results with/without installed
1260 Pygments highlighter.)
1262 \begin{quote
}{\ttfamily \raggedright \noindent
1263 print~'This~is~Python~code.'
1267 The
\texttt{:number-lines:
} option (with optional start value) generates line
1270 \begin{quote
}{\ttfamily \raggedright \noindent
1271 \DUrole{ln
}{~
8~
}\#~print~integers~from~
0~to~
9:\\
1272 \DUrole{ln
}{~
9~
}for~i~in~range(
10):\\
1273 \DUrole{ln
}{10~
}~~~~print~i
1277 For inline code snippets, there is the
\DUroletitlereference{code
} role, which can be used
1278 directly (the code will not be parsed/tagged, as the language is not
1279 known) or as base for special code roles, e.g.,
1285 Docutils uses LaTeX syntax for math directives and roles:
1286 \texttt{\DUrole{code
}{\DUrole{latex
}{\DUrole{tex
}{\textbackslash{}alpha = f(x)
}}}} prints $
\alpha = f(x)$.
1290 The
\texttt{:code:
} option of the
\DUroletitlereference{include
} directive sets the included content
1291 as a code block, here the rst file
\texttt{header
\_footer.txt
} with line numbers:
1293 \begin{quote
}{\ttfamily \raggedright \noindent
1294 \DUrole{ln
}{1~
}..~header::~Document~header\\
1295 \DUrole{ln
}{2~
}..~footer::~Document~footer
1300 \subsection{2.15 Substitution Definitions
%
1301 \label{substitution-definitions
}%
1304 An inline image (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}) example:
1306 (Substitution definitions are not visible in the HTML source.)
1309 \subsection{2.16 Comments
%
1315 % Comments begin with two dots and a space. Anything may
1316 % follow, except for the syntax of footnotes, hyperlink
1317 % targets, directives, or substitution definitions.
1319 % Double-dashes -- "--" -- must be escaped somehow in HTML output.
1321 % Comments may contain non-ASCII characters: ä ö ü æ ø å
1323 (View the HTML source to see the comment.)
1326 \subsection{2.17 Raw text
%
1330 This does not necessarily look nice, because there may be missing white space.
1332 It's just there to freeze the behavior.
1338 \DUrole{myclass
}{Another test with myclass set.
}
1340 This is the
\DUrole{myrawroleclass
}{fourth test
} with myrawroleclass set.
1342 Fifth test in LaTeX.\
\Line two.
1345 \subsection{2.18 Container
%
1353 % currently not implemented in LaTeX:
1354 % .. include:: data/header_footer.txt
1357 \subsection{2.19 Colspanning tables
%
1358 \label{colspanning-tables
}%
1361 This table has a cell spanning two columns:
1363 \setlength{\DUtablewidth}{\linewidth}
1364 \begin{longtable*
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.086\DUtablewidth}|
}
1366 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1382 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1397 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1435 \subsection{2.20 Rowspanning tables
%
1436 \label{rowspanning-tables
}%
1439 Here's a table with cells spanning several rows:
1441 \setlength{\DUtablewidth}{\linewidth}
1442 \begin{longtable*
}[c
]{|p
{0.296\DUtablewidth}|p
{0.156\DUtablewidth}|p
{0.226\DUtablewidth}|
}
1445 Header row, column
1
1446 (header rows optional)
1456 Header row, column
1
1457 (header rows optional)
1465 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1469 body row
1, column
1
1478 &
\multirow{2}{0.16\DUtablewidth}{%
1481 } &
\multirow{2}{0.23\DUtablewidth}{%
1494 \subsection{2.21 Custom Roles
%
1495 \label{custom-roles
}%
1500 \item A role based on an existing role.
1502 \texttt{\DUrole{custom
}{one
}} \texttt{\DUrole{custom
}{two
}} \texttt{\DUrole{custom
}{three
}}
1506 \DUrole{customnew
}{one two three
}
1508 \item A role with class attribute.
1510 \DUrole{special
}{interpreted text
}
1512 \item A language-switching role:
1514 Let's count in German
\otherlanguage{german
}{eins zwei drei
}.
1516 \item A role with multiple class attributes, styled with raw directives:
1518 \newcommand{\DUrolegreen}[1]{\textcolor{green
}{#1}}
1519 \newcommand{\DUrolesc}[1]{\textsc{#1}}
1521 The following works in most browsers but does not validate
1522 (
\texttt{<style>
} is only allowed in the
document head):
1524 \begin{quote
}{\ttfamily \raggedright \noindent
1527 ~~<style~type="text/css"><!--\\
1528 ~~~.green~\
{color:~green;\
}\\
1529 ~~~.sc~\
{font-variant:~small-caps;\
}\\
1534 \otherlanguage{british
}{\DUrole{green
}{\DUrole{sc
}{British colourful text in small-caps
}}}.
1539 \section{3 Tests for the LaTeX writer
%
1540 \label{tests-for-the-latex-writer
}%
1543 Test syntax elements which may cause trouble for the LaTeX writer but might
1544 not need to be tested with other writers (e.g. the HTML writer).
1547 \subsection{3.1 Custom Roles in LaTeX
%
1548 \label{custom-roles-in-latex
}%
1553 \item Role names and class arguments are converted to conform to the
1554 regular expression
\texttt{{[}a-z
{]}{[}-a-z0-
9{]}*
} (letters are downcased,
1555 accents and similar decoration is stripped, non-conforming
1556 characters are replaced by a hyphen).
1558 Class arguments may contain numbers and hyphens, which need special
1559 treatment in LaTeX command names.
1561 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}}
1563 \item With LaTeX, roles can be styled within the
document using the
\DUroletitlereference{raw
}
1566 \newcommand{\DUrolelarge}[1]{{\large #1}}
1568 \@namedef
{DUrolesmall-caps
}{\textsc}
1569 \@namedef
{DUrolecustom4
}{\textbf}
1572 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}} in large, bold, small-caps.
1574 \item Custom roles can be based on standard roles:
1576 This is a
\emph{\DUrole{custom-emphasis
}{customized emphasis text role
}}
1578 This is a
\texttt{\DUrole{custom-literal
}{customized literal text role
}}
1580 This is a
\textbf{\DUrole{custom-strong
}{customized strong text role
}}
1582 This is a
\textsubscript{\DUrole{custom-subscript
}{customized subscript text role
}}
1584 This is a
\textsuperscript{\DUrole{custom-superscript
}{customized superscript text role
}}
1586 This is a
\DUroletitlereference{\DUrole{custom-title-reference
}{customized title-reference text role
}}
1590 % This file is used by the standalone_rst_latex test.
1593 \subsection{3.2 Option lists
%
1597 The LaTeX-
2e description environment is used for definition lists.
1598 The definition is continued on the same line as the term, this should
1599 not happen if a option-list is at the top of the definition.
1601 If the option list is not at the first element in the definition, it
1602 is contained in a quote
1606 \begin{DUoptionlist
}
1608 \item[--help
] show help
1617 \item[{In a definition list:
}] \leavevmode %
1618 \begin{DUoptionlist
}
1620 \item[--help
] show help
1629 \subsection{3.3 Monospaced non-alphanumeric characters
%
1630 \label{monospaced-non-alphanumeric-characters
}%
1633 These are all ASCII characters except a-zA-Z0-
9 and space:
1635 \texttt{!!!"""\#\#\#\$\$\$\%\%\%\&\&\&'''((()))***+++,,,---...///:::
}
1637 \texttt{;;;<<<===>>>???@@@
{[}{[}{[}\textbackslash{}\textbackslash{}\textbackslash{}{]}{]}{]}\textasciicircum{}\textasciicircum{}\textasciicircum{}\_\_\_```\
{\
{\
{|||\
}\
}\
}\textasciitilde{}\textasciitilde{}\textasciitilde{}}
1639 \texttt{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
1641 The two lines of non-alphanumeric characters should both have the same
1642 width as the third line.
1645 \subsection{3.4 Non-ASCII characters
%
1646 \label{non-ascii-characters
}%
1649 Punctuation and footnote symbols
1651 \setlength{\DUtablewidth}{\linewidth}
1652 \begin{longtable*
}[c
]{|p
{0.028\DUtablewidth}|p
{0.424\DUtablewidth}|
}
1669 single turned comma quotation mark
1675 single comma quotation mark
1681 low single comma quotation mark
1687 double turned comma quotation mark
1693 double comma quotation mark
1699 low double comma quotation mark
1753 left-right double arrow
1758 The
\DUroletitlereference{Latin-
1 extended
} Unicode block
1760 \setlength{\DUtablewidth}{\linewidth}
1761 \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}|
}
2019 \item The following line should not be wrapped, because it uses
2020 no-break spaces (
\textbackslash{}u00a0):
2022 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
2024 \item Line wrapping with/without breakpoints marked by soft hyphens
2025 (
\textbackslash{}u00ad):
2027 pdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-sch
2029 pdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrisch
2031 \item The currency sign (
\textbackslash{}u00a4) is not supported by all fonts
2032 (some have an Euro sign at its place). You might see an error
2035 \begin{quote
}{\ttfamily \raggedright \noindent
2036 !~Package~textcomp~Error:~Symbol~
\textbackslash{}textcurrency~not~provided~by\\
2037 (textcomp)~~~~~~~~~~~~~~~~font~family~ptm~in~TS1~encoding.\\
2038 (textcomp)~~~~~~~~~~~~~~~~Default~family~used~instead.
2042 (which in case of font family ptm is a false positive). Add either
2046 turn the error in a warning, use the default symbol (bitmap), or
2048 \item[{force,almostfull:
}]
2049 use the symbol provided by the font at the users
2054 to the
document options or use a different font package.
2059 \subsection{3.5 Encoding special chars
%
2060 \label{encoding-special-chars
}%
2063 The LaTeX Info pages lists under "
2.18 Special Characters"
2067 The following characters play a special role in LaTeX and are called
2068 "special printing characters", or simply "special characters".
2072 \# \$ \% \&
\textasciitilde{} \_ \textasciicircum{} \textbackslash{} \
{ \
}
2078 The special chars verbatim:
2080 \begin{quote
}{\ttfamily \raggedright \noindent
2081 \#~\$~\%~\&~
\textasciitilde{}~
\_~
\textasciicircum{}~
\textbackslash{}~\
{~\
}
2085 However also
\emph{square brackets
} {[}{]} need special care.
2089 item and all the other commands with optional arguments check
2090 if the token right after the macro name is an opening bracket.
2091 In that case the contents between that bracket and the following
2092 closing bracket on the same grouping level are taken as the
2093 optional argument. What makes this unintuitive is the fact that
2094 the square brackets aren't grouping characters themselves, so in
2095 your last example item
{[}{[}...
{]}{]} the optional argument consists of
2096 {[}... (without the closing bracket).
2100 Compare the items in the following lists:
2106 \item {[}bracketed
{]} item
2111 \item[{simple
}] \leavevmode
2114 \item[{{[}bracketed
{]}}] \leavevmode
2119 The OT1 font-encoding has different characters for the less-than,
2120 greater-than and bar, < | >, except for typewriter font
\DUroletitlereference{cmtt
}:
2122 \begin{quote
}{\ttfamily \raggedright \noindent
2128 \subsection{3.6 Hyperlinks and -targets
%
2129 \label{hyperlinks-and-targets
}%
2132 In LaTeX, we must set an explicit anchor (
\texttt{\textbackslash{}phantomsection
}) for a
2134 \phantomsection\label{hypertarget-in-plain-text
}hypertarget in plain text or in a figure but not in a longtable or
2137 \setlength{\DUtablewidth}{\linewidth}
2138 \begin{longtable
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
2139 \caption{Table with
%
2140 \label{hypertarget-in-table-title
}hypertarget in table title.
}\\
2153 \phantomsection\label{figure-label
}
2154 \noindent\makebox[\textwidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
2155 \caption{Figure with
%
2156 \label{hypertarget-in-figure-caption
}hypertarget in figure caption.
}
2159 \phantomsection\label{hypertarget-in-figure-legend
}hypertarget in figure legend.
2163 \includegraphics{../../../docs/user/rst/images/biohazard.png
}
2164 \phantomsection\label{image-label
}
2166 See
\hyperref[hypertarget-in-plain-text
]{hypertarget in plain text
},
2167 \hyperref[table-label
]{table label
},
\hyperref[hypertarget-in-table-title
]{hypertarget in table title
},
2168 \hyperref[figure-label
]{figure label
},
\hyperref[hypertarget-in-figure-caption
]{hypertarget in figure caption
},
2169 \hyperref[hypertarget-in-figure-legend
]{hypertarget in figure legend
}, and
2170 \hyperref[image-label
]{image label
}.
2173 \subsection{3.7 External references
%
2174 \label{external-references
}%
2177 Long URLs should be wrapped in the PDF.
2178 This can be achieved with the url command which is used by the LaTeX writer
2179 whenever the content (name) of a reference node equals the link URL.
2182 \item[{Example:
}] \leavevmode
2183 a long URL that should wrap in the output
2184 \url{http://docutils.sourceforge.net/docs/user/latex.html\#id79
}
2188 If the argument contains any "\%", "\#", or "
\textasciicircum{}\textasciicircum{}", or ends with
\texttt{\textbackslash{}}, it can't
2189 be used in the argument to another command. The argument must not contain
2192 The characters
\textasciicircum{}, \
{, \
}, and
\texttt{\textbackslash{}} are invalid in a "http:" or "ftp:" URL
2193 and not recognized as part of it:
2195 \begin{DUlineblock
}{0em
}
2196 \item[] \url{http://www.example.org
}/strange
\textasciicircum{}\textasciicircum{}name
2197 \item[] \url{http://www.example.org
}\textbackslash{}using
\textbackslash{}DOS
\textbackslash{}paths
\textbackslash{}
2198 \item[] \url{http://www.example.org/XML
}/strange\
{n\
}ame
2201 They can, however be used in paths and/or filenames.
2203 Handling by the LaTeX writer:
2207 \item \texttt{\#
},
\texttt{\textbackslash{}} and
\texttt{\%
} are escaped:
2209 \begin{DUlineblock
}{0em
}
2210 \item[] \href{http://www.w3.org/XML/Schema\#dev
}{URL with \#
}
2211 \url{http://www.w3.org/XML/Schema\#dev
}
2212 \item[] \href{http://www.w3.org/XML/Schema\%dev
}{URL with \%
}
2213 \url{http://example.org/Schema\%dev
}
2214 \item[] \href{A:DOS\
\path\\
}{file with DOS path
}\DUfootnotemark{id41
}{id40
}{9} \url{A:DOS\
\path\\
}\DUfootnotemark{id42
}{id40
}{9}
2217 \DUadmonition[note
]{
2218 \DUtitle[note
]{Note
}
2220 These URLs are typeset inside a LaTeX command without error.
2222 \begin{DUlineblock
}{0em
}
2223 \item[] \url{http://www.w3.org/XML/Schema\#dev
}
2224 \item[] \url{http://example.org/Schema\%dev
}
2225 \item[] \url{A:DOS\
\path\\
}\DUfootnotemark{id43
}{id40
}{9}
2233 \item \textasciicircum{}\textasciicircum{} LaTeX's special syntax for characters results in "strange" replacements
2234 (both with href and url). A warning is given.
2236 \href{../strange^^name
}{file with
\textasciicircum{}\textasciicircum{}}:
2237 \url{../strange^^name
}
2239 \item Unbalanced braces, \
{ or \
}, will fail (both with href and url):
2241 \begin{quote
}{\ttfamily \raggedright \noindent
2242 `file~with~\
{~<../strange\
{name>`
\_\_\\
2243 `<../strange\
{name>`
\_\_
2247 while balanced braces are suported:
2249 \begin{DUlineblock
}{0em
}
2250 \item[] \url{../strange
{n
}ame
}
2251 \item[] \url{../st
{r
}ange
{n
}ame
}
2252 \item[] \url{../
{st
{r
}ange
{n
}ame
}}
2258 \subsection{3.8 Section titles with
\hyperref[inline-markup
]{inline markup
}%
2259 \label{section-titles-with-inline-markup
}%
2263 \subsubsection{3.8.1 \emph{emphasized
}, H
\textsubscript{2}O and $x^
2$
%
2264 \label{emphasized-h2o-and-x-
2}%
2268 \subsubsection{3.8.2 Substitutions work
%
2269 \label{substitutions-fail
}%
2273 \subsection{3.9 Deeply nested sections
%
2274 \label{deeply-nested-sections
}%
2280 \subsubsection{3.9.1 Level
3%
2287 \paragraph{3.9.1.1 level
4%
2294 \subparagraph{3.9.1.1.1 level
5%
2298 (depending on the
document class)
2301 \DUtitle[sectionVI
]{3.9.1.1.1.1 level
6%
2305 an unsupported level.
2308 \section{4 Tests for the XeTeX writer
%
2309 \label{tests-for-the-xetex-writer
}%
2312 With XeTeX, you can typeset text in any language/script supported by
2313 Unicode and the selected font, e.g. Azərbaycanca, Bân-lâm-gú, Башҡорт
2314 Беларуская, Български, Català, Чӑвашла, Česky, Ελληνικά, Español,
2315 Français, Føroyskt, Хальмг, Íslenska, עברית , Қазақша, Kurdî,
2316 Latviešu, Lietuvių, Македонски, Монгол, Nāhuatl, Português, Română,
2317 Русский, Slovenščina, Српски, Türkçe, Українська, Tiếng Việt, Volapük,
2318 Võro, ייִדיש , Žemaitėška.
2319 Currently, there is extended support for
28 languages in the
2320 \href{http://ctan.org/pkg/polyglossia
}{polyglossia
}\DUfootnotemark{id36
}{id35
}{7} package.
2325 \section{5 Error Handling
%
2326 \label{error-handling
}%
2329 Any errors caught during processing will generate system messages.
2331 There should be five messages in the following, auto-generated
2332 section, "Docutils System Messages":
2334 % section should be added by Docutils automatically
2337 \section[Docutils System Messages
]{\color{red
}Docutils System Messages
%
2340 \DUadmonition[system-message
]{
2341 \DUtitle[system-message
]{system-message
}
2342 \raisebox{1em
}{\hypertarget{id27
}{}}
2344 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
104
2347 Undefined substitution referenced: "problematic".
2350 \DUadmonition[system-message
]{
2351 \DUtitle[system-message
]{system-message
}
2352 \raisebox{1em
}{\hypertarget{id44
}{}}
2354 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
391
2357 Unknown target name: "
5".
2360 \DUadmonition[system-message
]{
2361 \DUtitle[system-message
]{system-message
}
2362 \raisebox{1em
}{\hypertarget{id46
}{}}
2364 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
400
2367 Unknown target name: "nonexistent".
2370 \DUadmonition[system-message
]{
2371 \DUtitle[system-message
]{system-message
}
2372 \raisebox{1em
}{\hypertarget{id48
}{}}
2374 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
427
2377 Unknown target name: "hyperlink reference without a target".
2380 \DUadmonition[system-message
]{
2381 \DUtitle[system-message
]{system-message
}
2382 \raisebox{1em
}{\hypertarget{id50
}{}}
2384 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
440
2387 Duplicate target name, cannot be used as a unique reference: "duplicate target names".