1 \documentclass[a4paper]{article
}
2 % generated by Docutils <http://docutils.sourceforge.net/>
3 \usepackage{fixltx2e
} % LaTeX patches, \textsubscript
4 \usepackage{cmap
} % fix search and cut-and-paste in Acrobat
5 \usepackage[T1]{fontenc}
6 \usepackage[utf8
]{inputenc}
9 \usepackage{float
} % float configuration
10 \floatplacement{figure
}{H
} % place figures here definitely
14 \usepackage{longtable
}
16 \setlength{\extrarowheight}{2pt
}
17 \newlength{\DUtablewidth} % internal use in tables
19 \usepackage{textcomp
} % text symbol macros
21 %%% Custom LaTeX preamble
23 \usepackage{mathptmx
} % Times
24 \usepackage[scaled=
.90]{helvet
}
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 \providecommand{\DUtopicdedication}[1]{\begin{center
}#1\end{center
}}
54 % docinfo (width of docinfo table)
55 \DUprovidelength{\DUdocinfowidth}{0.9\textwidth}
57 % error admonition title
58 \providecommand*
{\DUtitleerror}[1]{\DUtitle{\color{red
}#1}}
60 % fieldlist environment
61 \ifthenelse{\isundefined{\DUfieldlist}}{
62 \newenvironment{DUfieldlist
}%
64 {\enddescription\endquote}
66 % numeric or symbol footnotes with hyperlinks
67 \providecommand*
{\DUfootnotemark}[3]{%
68 \raisebox{1em
}{\hypertarget{#1}{}}%
69 \hyperlink{#2}{\textsuperscript{#3}}%
71 \providecommand{\DUfootnotetext}[4]{%
73 \renewcommand{\thefootnote}{%
74 \protect\raisebox{1em
}{\protect\hypertarget{#1}{}}%
75 \protect\hyperlink{#2}{#3}}%
80 % inline markup (custom roles)
81 % \DUrole{#1}{#2} tries \DUrole#1{#2}
82 \providecommand*
{\DUrole}[2]{%
83 \ifcsname DUrole
#1\endcsname%
84 \csname DUrole
#1\endcsname{#2}%
85 \else% backwards compatibility: try \docutilsrole#1{#2}
86 \ifcsname docutilsrole
#1\endcsname%
87 \csname docutilsrole
#1\endcsname{#2}%
95 \ifthenelse{\isundefined{\DUlegend}}{
96 \newenvironment{DUlegend
}{\small}{}
99 % lineblock environment
100 \DUprovidelength{\DUlineblockindent}{2.5em
}
101 \ifthenelse{\isundefined{\DUlineblock}}{
102 \newenvironment{DUlineblock
}[1]{%
103 \list{}{\setlength{\partopsep}{\parskip}
104 \addtolength{\partopsep}{\baselineskip}
105 \setlength{\topsep}{0pt
}
106 \setlength{\itemsep}{0.15\baselineskip}
107 \setlength{\parsep}{0pt
}
108 \setlength{\leftmargin}{#1}}
114 % optionlist environment
115 \providecommand*
{\DUoptionlistlabel}[1]{\bf #1 \hfill}
116 \DUprovidelength{\DUoptionlistindent}{3cm
}
117 \ifthenelse{\isundefined{\DUoptionlist}}{
118 \newenvironment{DUoptionlist
}{%
119 \list{}{\setlength{\labelwidth}{\DUoptionlistindent}
120 \setlength{\rightmargin}{1cm
}
121 \setlength{\leftmargin}{\rightmargin}
122 \addtolength{\leftmargin}{\labelwidth}
123 \addtolength{\leftmargin}{\labelsep}
124 \renewcommand{\makelabel}{\DUoptionlistlabel}}
129 % rubric (informal heading)
130 \providecommand*
{\DUrubric}[2][class-arg
]{%
131 \subsubsection*
{\centering\textit{\textmd{#2}}}}
133 % sidebar (text outside the main text flow)
134 \providecommand{\DUsidebar}[2][class-arg
]{%
136 \colorbox[gray
]{0.80}{\parbox{0.9\textwidth}{#2}}
140 % subtitle (for topic/sidebar)
141 \providecommand*
{\DUsubtitle}[2][class-arg
]{\par\emph{#2}\smallskip}
143 % title for topics, admonitions and sidebar
144 \providecommand*
{\DUtitle}[2][class-arg
]{%
145 % call \DUtitle#1{#2} if it exists:
146 \ifcsname DUtitle
#1\endcsname%
147 \csname DUtitle
#1\endcsname{#2}%
149 \smallskip\noindent\textbf{#2}\smallskip%
153 % titlereference role
154 \providecommand*
{\DUroletitlereference}[1]{\textsl{#1}}
156 % topic (quote with heading)
157 \providecommand{\DUtopic}[2][class-arg
]{%
158 \ifcsname DUtopic
#1\endcsname%
159 \csname DUtopic
#1\endcsname{#2}%
161 \begin{quote
}#2\end{quote
}
165 % transition (break, fancybreak, anonymous section)
166 \providecommand*
{\DUtransition}[1][class-arg
]{%
167 \hspace*
{\fill}\hrulefill\hspace*
{\fill}
168 \vskip 0.5\baselineskip
172 \ifthenelse{\isundefined{\hypersetup}}{
173 \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue
]{hyperref
}
174 \urlstyle{same
} % normal text font (alternatives: tt, rm, sf)
177 pdftitle=
{reStructuredText Test Document
},
178 pdfauthor=
{David Goodger;Me;Myself;I
}
182 \title{reStructuredText Test Document
%
184 \label{restructuredtext-test-
document}%
187 \large{Examples of Syntax Constructs
}%
188 \label{examples-of-syntax-constructs
}%
199 \begin{tabularx
}{\DUdocinfowidth}{lX
}
208 \href{mailto:goodger@python.org
}{goodger@python.org
} \\
215 \textbf{Organization
}: &
218 Now, or yesterday. Or maybe even
\emph{before
} yesterday. \\
220 This is a ``work in progress'' \\
222 is managed by a version control system. \\
225 \textbf{Copyright
}: &
226 This
document has been placed in the public domain. You
227 may do with it as you wish. You may copy, modify,
228 redistribute, reattribute, sell, buy, rent, lease,
229 destroy, or improve it, quote it at length, excerpt,
230 incorporate, collate, fold, staple, or mutilate it, or do
231 anything else to it that your or anyone else's heart
233 \textbf{field name
}: &
234 This is a ``generic bibliographic field''.
236 \textbf{field name ``
2''
}: &
237 Generic bibliographic fields may contain multiple body elements.
244 \DUtopic[dedication
]{
245 \DUtitle[dedication
]{Dedication
}
247 For Docutils users \& co-developers.
251 \DUtitle[abstract
]{Abstract
}
253 This is a test
document, containing at least one example of each
254 reStructuredText construct.
257 % This is a comment. Note how any initial comments are moved by
258 % transforms to after the document title, subtitle, and docinfo.
260 % Above is the document title, and below is the subtitle.
261 % They are transformed from section titles after parsing.
263 % bibliographic fields (which also require a transform):
264 \pagebreak[4] % start ToC on new page
265 \phantomsection\label{table-of-contents
}
266 \pdfbookmark[1]{Table of Contents
}{table-of-contents
}
267 \renewcommand{\contentsname}{Table of Contents
}
272 %___________________________________________________________________________
274 \section*
{1~~~Structural Elements
%
276 \addcontentsline{toc
}{section
}{1~~~Structural Elements
}%
277 \label{structural-elements
}%
281 %___________________________________________________________________________
283 \subsection*
{1.1~~~Section Title
%
285 \addcontentsline{toc
}{subsection
}{1.1~~~Section Title
}%
286 \label{section-title
}%
288 \subsubsection*
{Section Subtitle
}
290 That's it, the text just above this line.
293 %___________________________________________________________________________
295 \subsection*
{1.2~~~Empty Section
%
297 \addcontentsline{toc
}{subsection
}{1.2~~~Empty Section
}%
298 \label{empty-section
}%
302 %___________________________________________________________________________
304 \subsection*
{1.3~~~Transitions
%
306 \addcontentsline{toc
}{subsection
}{1.3~~~Transitions
}%
313 %___________________________________________________________________________
317 It divides the section. Transitions may also occur between sections:
320 %___________________________________________________________________________
325 %___________________________________________________________________________
327 \section*
{2~~~Body Elements
%
329 \addcontentsline{toc
}{section
}{2~~~Body Elements
}%
330 \label{body-elements
}%
334 %___________________________________________________________________________
336 \subsection*
{2.1~~~Paragraphs
%
338 \addcontentsline{toc
}{subsection
}{2.1~~~Paragraphs
}%
345 %___________________________________________________________________________
347 \subsubsection*
{2.1.1~~~Inline Markup
%
349 \addcontentsline{toc
}{subsubsection
}{2.1.1~~~Inline Markup
}%
350 \label{inline-markup
}%
353 Paragraphs contain text and may contain inline markup:
\emph{emphasis
},
354 \textbf{strong emphasis
},
\texttt{inline literals
}, standalone hyperlinks
355 (
\url{http://www.python.org
}), external hyperlinks (
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id30
}{id29
}{5}), internal
356 cross-references (
\hyperref[example
]{example
}), external hyperlinks with embedded URIs
357 (
\href{http://www.python.org
}{Python web site
}),
\href{http://www.python.org/
}{anonymous hyperlink
358 references
}\DUfootnotemark{id33
}{id29
}{5} (
\href{http://docutils.sourceforge.net/
}{a second reference
}\DUfootnotemark{id35
}{id34
}{6}), footnote references (manually
359 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
}]),
360 substitution references (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}), and
%
361 \phantomsection\label{inline-hyperlink-targets
}inline hyperlink targets
362 (see
\hyperref[targets
]{Targets
} below for a reference back to here). Character-level
363 inline markup is also possible (although exceedingly ugly!) in
\emph{re
}\texttt{Structured
}\emph{Text
}. Problems are indicated by
%
364 \raisebox{1em
}{\hypertarget{id28
}{}}\hyperlink{id27
}{\textbf{\color{red
}|problematic|
}} text
365 (generated by processing errors; this one is intentional). Here is a
366 reference to the
\hyperref[doctitle
]{doctitle
} and the
\hyperref[subtitle
]{subtitle
}.
368 The default role for interpreted text is
\DUroletitlereference{Title Reference
}. Here are
369 some explicit interpreted text roles: a PEP reference (
\href{http://www.python.org/dev/peps/pep-
0287}{PEP
287}); an
370 RFC reference (
\href{http://www.faqs.org/rfcs/rfc2822.html
}{RFC
2822}); a
\textsubscript{subscript
}; a
\textsuperscript{superscript
};
371 and explicit roles for
\emph{standard
} \textbf{inline
}
374 % DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
376 Let's test wrapping and whitespace significance in inline literals:
377 \texttt{This is an example of -
{}-inline-literal -
{}-text, -
{}-including some-
{}-
378 strangely-
{}-hyphenated-words. ~Adjust-the-width-of-your-browser-window
379 to see how the text is wrapped. ~-
{}- -
{}-
{}-
{}- -
{}-
{}-
{}-
{}-
{}-
{}-
{}- ~Now note ~ ~the
380 spacing ~ ~between the ~ ~words of ~ ~this sentence ~ ~(words
381 should ~ ~be grouped ~ ~in pairs).
}
383 If the
\texttt{-
{}-pep-references
} option was supplied, there should be a
384 live link to PEP
258 here.
387 %___________________________________________________________________________
389 \subsection*
{2.2~~~Bullet Lists
%
391 \addcontentsline{toc
}{subsection
}{2.2~~~Bullet Lists
}%
392 \label{bullet-lists
}%
401 \item Nested bullet list.
409 Paragraph
2 of item
2.
413 \item Nested bullet list.
427 \item This nested list should be compacted by the HTML writer.
429 \phantomsection\label{target
}
430 % Even if this item contains a target and a comment.
437 %___________________________________________________________________________
439 \subsection*
{2.3~~~Enumerated Lists
%
441 \addcontentsline{toc
}{subsection
}{2.3~~~Enumerated Lists
}%
442 \label{enumerated-lists
}%
444 \newcounter{listcnt0
}
445 \begin{list
}{\arabic{listcnt0
}.
}
447 \usecounter{listcnt0
}
448 \setlength{\rightmargin}{\leftmargin}
451 \item Arabic numerals.
452 \newcounter{listcnt1
}
453 \begin{list
}{\alph{listcnt1
})
}
455 \usecounter{listcnt1
}
456 \setlength{\rightmargin}{\leftmargin}
460 \newcounter{listcnt2
}
461 \begin{list
}{(
\roman{listcnt2
})
}
463 \usecounter{listcnt2
}
464 \setlength{\rightmargin}{\leftmargin}
468 \newcounter{listcnt3
}
469 \begin{list
}{\Alph{listcnt3
}.
}
471 \usecounter{listcnt3
}
472 \setlength{\rightmargin}{\leftmargin}
476 \newcounter{listcnt4
}
477 \begin{list
}{\Roman{listcnt4
})
}
479 \usecounter{listcnt4
}
480 \setlength{\rightmargin}{\leftmargin}
489 \item Lists that don't start at
1:
490 \setcounter{listcnt1
}{0}
491 \begin{list
}{\arabic{listcnt1
}.
}
493 \usecounter{listcnt1
}
494 \addtocounter{listcnt1
}{2}
495 \setlength{\rightmargin}{\leftmargin}
502 \setcounter{listcnt1
}{0}
503 \begin{list
}{\Alph{listcnt1
}.
}
505 \usecounter{listcnt1
}
506 \addtocounter{listcnt1
}{2}
507 \setlength{\rightmargin}{\leftmargin}
514 \setcounter{listcnt1
}{0}
515 \begin{list
}{\roman{listcnt1
}.
}
517 \usecounter{listcnt1
}
518 \addtocounter{listcnt1
}{2}
519 \setlength{\rightmargin}{\leftmargin}
529 %___________________________________________________________________________
531 \subsection*
{2.4~~~Definition Lists
%
533 \addcontentsline{toc
}{subsection
}{2.4~~~Definition Lists
}%
534 \label{definition-lists
}%
538 \item[{Term
}] \leavevmode
541 \item[{Term
}] \leavevmode (
\textbf{classifier
})
543 Definition paragraph
1.
545 Definition paragraph
2.
547 \item[{Term
}] \leavevmode
550 \item[{Term
}] \leavevmode (
\textbf{classifier one
})
551 (
\textbf{classifier two
})
558 %___________________________________________________________________________
560 \subsection*
{2.5~~~Field Lists
%
562 \addcontentsline{toc
}{subsection
}{2.5~~~Field Lists
}%
568 Field lists map field names to field bodies, like database
569 records. They are often part of an extension syntax. They are
570 an unambiguous variant of RFC
2822 fields.
572 \item[{how arg1 arg2:
}]
573 The field marker is a colon, the field name, and a colon.
575 The field body may contain one or more body elements, indented
576 relative to the field marker.
579 This paragraph has the
\DUroletitlereference{credits
} class set. (This is actually not
580 about credits but just for ensuring that the class attribute
581 doesn't get stripped away.)
586 %___________________________________________________________________________
588 \subsection*
{2.6~~~Option Lists
%
590 \addcontentsline{toc
}{subsection
}{2.6~~~Option Lists
}%
591 \label{option-lists
}%
594 For listing command-line options:
598 \item[-a
] command-line option ``a''
600 \item[-b file
] options can have arguments
601 and long descriptions
603 \item[-
{}-long
] options can be long also
605 \item[-
{}-input=file
] long options can also have
608 \item[-
{}-very-long-option
] The description can also start on the next line.
610 The description may contain multiple body elements,
611 regardless of where it starts.
613 \item[-x, -y, -z
] Multiple options are an ``option group''.
615 \item[-v, -
{}-verbose
] Commonly-seen: short \& long options.
617 \item[-
1 file, -
{}-one=file, -
{}-two file
] Multiple options with arguments.
619 \item[/V
] DOS/VMS-style options too
623 There must be at least two spaces between the option and the
627 %___________________________________________________________________________
629 \subsection*
{2.7~~~Literal Blocks
%
631 \addcontentsline{toc
}{subsection
}{2.7~~~Literal Blocks
}%
632 \label{literal-blocks
}%
635 Literal blocks are indicated with a double-colon (``::'') at the end of
636 the preceding paragraph (over there
\texttt{-
{}->
}). They can be indented:
638 \begin{quote
}{\ttfamily \raggedright \noindent
640 ~~~~text~=~'is~left~as-is'\\
641 ~~~~spaces
\_and\_linebreaks~=~'are~preserved'\\
642 ~~~~markup
\_processing~=~None
646 Or they can be quoted without indentation:
648 \begin{quote
}{\ttfamily \raggedright \noindent
651 >~Why~didn't~I~think~of~that?
656 %___________________________________________________________________________
658 \subsection*
{2.8~~~Line Blocks
%
660 \addcontentsline{toc
}{subsection
}{2.8~~~Line Blocks
}%
664 This section tests line blocks. Line blocks are body elements which
665 consist of lines and other line blocks. Nested line blocks cause
668 \begin{DUlineblock
}{0em
}
669 \item[] This is a line block. It ends with a blank line.
671 \begin{DUlineblock
}{\DUlineblockindent}
672 \item[] New lines begin with a vertical bar (``|'').
673 \item[] Line breaks and initial indent are significant, and preserved.
675 \begin{DUlineblock
}{\DUlineblockindent}
676 \item[] Continuation lines are also possible. A long line that is intended
677 to wrap should begin with a space in place of the vertical bar.
679 \item[] The left edge of a continuation line need not be aligned with
680 the left edge of the text above it.
684 \begin{DUlineblock
}{0em
}
685 \item[] This is a second line block.
687 \item[] Blank lines are permitted internally, but they must begin with a ``|''.
690 Another line block, surrounded by paragraphs:
692 \begin{DUlineblock
}{0em
}
693 \item[] And it's no good waiting by the window
694 \item[] It's no good waiting for the sun
695 \item[] Please believe me, the things you dream of
696 \item[] They don't fall in the lap of no-one
699 Take it away, Eric the Orchestra Leader!
703 \begin{DUlineblock
}{0em
}
704 \item[] A one, two, a one two three four
706 \item[] Half a bee, philosophically,
708 \begin{DUlineblock
}{\DUlineblockindent}
709 \item[] must,
\emph{ipso facto
}, half not be.
711 \item[] But half the bee has got to be,
713 \begin{DUlineblock
}{\DUlineblockindent}
714 \item[] \emph{vis a vis
} its entity. D'you see?
717 \item[] But can a bee be said to be
719 \begin{DUlineblock
}{\DUlineblockindent}
720 \item[] or not to be an entire bee,
722 \begin{DUlineblock
}{\DUlineblockindent}
723 \item[] when half the bee is not a bee,
725 \begin{DUlineblock
}{\DUlineblockindent}
726 \item[] due to some ancient injury?
737 %___________________________________________________________________________
739 \subsection*
{2.9~~~Block Quotes
%
741 \addcontentsline{toc
}{subsection
}{2.9~~~Block Quotes
}%
742 \label{block-quotes
}%
745 Block quotes consist of indented body elements:
749 My theory by A. Elk. Brackets Miss, brackets. This theory goes
750 as follows and begins now. All brontosauruses are thin at one
751 end, much much thicker in the middle and then thin again at the
752 far end. That is my theory, it is mine, and belongs to me and I
753 own it, and what it is too.
756 \raggedleft —Anne Elk (Miss)
761 %___________________________________________________________________________
763 \subsection*
{2.10~~~Doctest Blocks
%
765 \addcontentsline{toc
}{subsection
}{2.10~~~Doctest Blocks
}%
766 \label{doctest-blocks
}%
769 \begin{quote
}{\ttfamily \raggedright \noindent
770 >
{}>
{}>~print~'Python-specific~usage~examples;~begun~with~">
{}>
{}>"'\\
771 Python-specific~usage~examples;~begun~with~">
{}>
{}>"\\
772 >
{}>
{}>~print~'(cut~and~pasted~from~interactive~Python~sessions)'\\
773 (cut~and~pasted~from~interactive~Python~sessions)
778 %___________________________________________________________________________
780 \subsection*
{2.11~~~Footnotes
%
782 \addcontentsline{toc
}{subsection
}{2.11~~~Footnotes
}%
786 \DUfootnotetext{id8
}{id1
}{1}{%
787 A footnote contains body elements, consistently indented by at
790 This is the footnote's second paragraph.
793 \DUfootnotetext{label
}{id3
}{2}{\phantomsection\label{label
}%
794 Footnotes may be numbered, either manually (as in
\DUfootnotemark{id9
}{id8
}{1}) or
795 automatically using a ``\#''-prefixed label. This footnote has a
796 label so it can be referred to from multiple places, both as a
797 footnote reference (
\DUfootnotemark{id10
}{label
}{2}) and as a
\hyperref[label
]{hyperlink reference
}.
800 \DUfootnotetext{id12
}{id2
}{3}{%
801 This footnote is numbered automatically and anonymously using a
802 label of ``\#'' only.
804 This is the second paragraph.
806 And this is the third paragraph.
809 \DUfootnotetext{id13
}{id4
}{*
}{%
810 Footnotes may also use symbols, specified with a ``*'' label.
811 Here's a reference to the next footnote:
\DUfootnotemark{id14
}{id15
}{†
}.
814 \DUfootnotetext{id15
}{id14
}{†
}{%
815 This footnote shows the next symbol in the sequence.
818 \DUfootnotetext{id16
}{id16
}{4}{%
819 Here's an unreferenced footnote, with a reference to a
820 nonexistent footnote:
%
821 \raisebox{1em
}{\hypertarget{id41
}{}}%
822 \raisebox{1em
}{\hypertarget{id17
}{}}\hyperlink{id40
}{\textbf{\color{red
}{[}5{]}\_}}.
826 %___________________________________________________________________________
828 \subsection*
{2.12~~~Citations
%
830 \addcontentsline{toc
}{subsection
}{2.12~~~Citations
}%
833 \begin{figure
}[b
]\raisebox{1em
}{\hypertarget{cit2002
}{}}[CIT2002
]
834 Citations are text-labeled footnotes. They may be
835 rendered separately and differently from footnotes.
838 Here's a reference to the above,
[\hyperlink{cit2002
}{CIT2002
}], and a
%
839 \raisebox{1em
}{\hypertarget{id43
}{}}%
840 \raisebox{1em
}{\hypertarget{id19
}{}}\hyperlink{id42
}{\textbf{\color{red
}{[}nonexistent
{]}\_}}
844 %___________________________________________________________________________
846 \subsection*
{2.13~~~Targets
%
848 \addcontentsline{toc
}{subsection
}{2.13~~~Targets
}%
850 \label{another-target
}%
853 \phantomsection\label{example
}
854 This paragraph is pointed to by the explicit ``example'' target. A
855 reference can be found under
\hyperref[inline-markup
]{Inline Markup
}, above.
\hyperref[inline-hyperlink-targets
]{Inline
856 hyperlink targets
} are also possible.
858 Section headers are implicit targets, referred to by name. See
859 \hyperref[targets
]{Targets
}, which is a subsection of
\hyperref[body-elements
]{Body Elements
}.
861 Explicit external targets are interpolated into references such as
862 ``
\href{http://www.python.org/
}{Python
}\DUfootnotemark{id31
}{id29
}{5}''.
864 Targets may be indirect and anonymous. Thus
\hyperref[targets
]{this phrase
} may also
865 refer to the
\hyperref[targets
]{Targets
} section.
868 \raisebox{1em
}{\hypertarget{id45
}{}}\hyperlink{id44
}{\textbf{\color{red
}`hyperlink reference without a target`
\_}}, which generates an
872 %___________________________________________________________________________
874 \subsubsection*
{2.13.1~~~Duplicate Target Names
%
876 \addcontentsline{toc
}{subsubsection
}{2.13.1~~~Duplicate Target Names
}%
877 \label{duplicate-target-names
}%
880 Duplicate names in section headers or other implicit targets will
881 generate ``info'' (level-
1) system messages. Duplicate names in
882 explicit targets will generate ``warning'' (level-
2) system messages.
885 %___________________________________________________________________________
887 \subsubsection*
{2.13.2~~~Duplicate Target Names
%
889 \addcontentsline{toc
}{subsubsection
}{2.13.2~~~Duplicate Target Names
}%
893 Since there are two ``Duplicate Target Names'' section headers, we
894 cannot uniquely refer to either of them by name. If we try to (like
896 \raisebox{1em
}{\hypertarget{id47
}{}}\hyperlink{id46
}{\textbf{\color{red
}`Duplicate Target Names`
\_}}), an error is generated.
899 %___________________________________________________________________________
901 \subsection*
{2.14~~~Directives
%
903 \addcontentsline{toc
}{subsection
}{2.14~~~Directives
}%
907 \phantomsection\label{contents
}
908 These are just a sample of the many reStructuredText Directives. For
910 \url{http://docutils.sourceforge.net/docs/ref/rst/directives.html
}.
913 %___________________________________________________________________________
915 \subsubsection*
{2.14.1~~~Document Parts
%
917 \addcontentsline{toc
}{subsubsection
}{2.14.1~~~Document Parts
}%
918 \label{document-parts
}%
921 An example of the ``contents'' directive can be seen above this section
922 (a local, untitled table of
\hyperref[contents
]{contents
}) and at the beginning of the
923 document (a
document-wide
\hyperref[table-of-contents
]{table of contents
}).
926 %___________________________________________________________________________
928 \subsubsection*
{2.14.2~~~Images and Figures
%
930 \addcontentsline{toc
}{subsubsection
}{2.14.2~~~Images and Figures
}%
931 \label{images-and-figures
}%
934 An image directive (also clickable -
{}- a hyperlink reference):
936 \hyperref[directives
]{\includegraphics{../../../docs/user/rst/images/title.png
}}
938 Image with multiple IDs:
940 \includegraphics{../../../docs/user/rst/images/title.png
}
941 \phantomsection\label{image-target-
3}\label{image-target-
2}\label{image-target-
1}
945 \noindent\makebox[\textwidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
947 A left-aligned image:
949 \noindent{\includegraphics{../../../docs/user/rst/images/biohazard.png
}\hfill}
951 This paragraph might flow around the image.
952 The specific behavior depends upon the style sheet and
953 the browser or rendering software used.
955 A right-aligned image:
957 \noindent{\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
959 This paragraph might flow around the image.
960 The specific behavior depends upon the style sheet and
961 the browser or rendering software used.
963 For inline images see
\hyperref[substitution-definitions
]{Substitution Definitions
}.
969 \includegraphics[width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
971 An image
2 em wide and
15 pixel high:
973 \includegraphics[height=
15px,width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
975 An image occupying
50\% of the line width:
977 \includegraphics[width=
0.500\linewidth]{../../../docs/user/rst/images/title.png
}
981 \includegraphics[height=
2cm
]{../../../docs/user/rst/images/biohazard.png
}
983 A
\emph{figure
} is an image with a caption and/or a legend. With page-based output
984 media, figures might float to a different position if this helps the page
987 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
258bp
]{../../../docs/user/rst/images/title.png
}}
988 \caption{Plaintext markup syntax and parser system.
}
991 \setlength{\DUtablewidth}{\linewidth}
992 \begin{longtable
}[c
]{|p
{0.156\DUtablewidth}|p
{0.563\DUtablewidth}|
}
997 Revised, revisited, based on 're' module.
1003 Structure-enhanced text, structuredtext.
1009 Well it is, isn't it?
1014 This paragraph is also part of the legend.
1018 A left-aligned figure:
1020 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
1021 \caption{This is the caption.
}
1025 The legend may consist of several paragraphs.
1029 This paragraph might flow around the figure.
1031 The specific behavior depends upon the style sheet and the browser or
1032 rendering software used.
1036 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
1037 \caption{This is the caption.
}
1041 The legend may consist of several paragraphs.
1045 This paragraph might flow around the figure.
1047 The specific behavior depends upon the style sheet and the browser or
1048 rendering software used.
1050 A right-aligned figure:
1052 \noindent\makebox[\textwidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
1053 \caption{This is the caption.
}
1057 The legend may consist of several paragraphs.
1061 This paragraph might flow around the figure. The specific behavior depends
1062 upon the style sheet and the browser or rendering software used.
1065 %___________________________________________________________________________
1067 \subsubsection*
{2.14.3~~~Admonitions
%
1069 \addcontentsline{toc
}{subsubsection
}{2.14.3~~~Admonitions
}%
1070 \label{admonitions
}%
1073 \DUadmonition[attention
]{
1074 \DUtitle[attention
]{Attention!
}
1076 Directives at large.
1079 \DUadmonition[caution
]{
1080 \DUtitle[caution
]{Caution!
}
1082 Don't take any wooden nickels.
1085 \DUadmonition[danger
]{
1086 \DUtitle[danger
]{!DANGER!
}
1088 Mad scientist at work!
1091 \DUadmonition[error
]{
1092 \DUtitle[error
]{Error
}
1097 \DUadmonition[hint
]{
1098 \DUtitle[hint
]{Hint
}
1100 It's bigger than a bread box.
1103 \DUadmonition[important
]{
1104 \DUtitle[important
]{Important
}
1108 \item Wash behind your ears.
1110 \item Clean up your room.
1112 \item Call your mother.
1114 \item Back up your data.
1119 \DUadmonition[note
]{
1120 \DUtitle[note
]{Note
}
1128 15\% if the service is good.
1131 \DUadmonition[warning
]{
1132 \DUtitle[warning
]{Warning
}
1134 Strong prose may provoke extreme mental exertion.
1135 Reader discretion is strongly advised.
1138 \DUadmonition[admonition-and-by-the-way
]{
1139 \DUtitle[admonition-and-by-the-way
]{And, by the way...
}
1141 You can make up your own admonition too.
1145 %___________________________________________________________________________
1147 \subsubsection*
{2.14.4~~~Topics, Sidebars, and Rubrics
%
1149 \addcontentsline{toc
}{subsubsection
}{2.14.4~~~Topics, Sidebars, and Rubrics
}%
1150 \label{topics-sidebars-and-rubrics
}%
1153 \emph{Sidebars
} are like miniature, parallel documents.
1156 \DUtitle[title
]{Sidebar Title
}
1158 \DUsubtitle[sidebar
]{Optional Subtitle
}
1160 This is a sidebar. It is for text outside the flow of the main
1163 \DUrubric{This is a rubric inside a sidebar
}
1165 Sidebars often appear beside the main text with a border and a different
1166 background or font
color.
1169 A
\emph{topic
} is like a block quote with a title, or a self-contained section
1170 with no subsections.
1173 \DUtitle[title
]{Topic Title
}
1178 A
\emph{rubric
} is like an informal heading that doesn't correspond to the
1179 document's structure. It is typically highlighted in red (hence the name).
1181 \DUrubric{This is a rubric
}
1183 Topics and rubrics can be used at places where a
\hyperref[section-title
]{section title
} is not
1184 allowed (e.g. inside a directive).
1187 %___________________________________________________________________________
1189 \subsubsection*
{2.14.5~~~Target Footnotes
%
1191 \addcontentsline{toc
}{subsubsection
}{2.14.5~~~Target Footnotes
}%
1192 \label{target-footnotes
}%
1195 \DUfootnotetext{id29
}{id30
}{5}{%
1196 \url{http://www.python.org/
}
1199 \DUfootnotetext{id34
}{id35
}{6}{%
1200 \url{http://docutils.sourceforge.net/
}
1203 \DUfootnotetext{id36
}{id37
}{7}{%
1208 %___________________________________________________________________________
1210 \subsubsection*
{2.14.6~~~Replacement Text
%
1212 \addcontentsline{toc
}{subsubsection
}{2.14.6~~~Replacement Text
}%
1213 \label{replacement-text
}%
1216 I recommend you try
\href{http://www.python.org/
}{Python,
\emph{the
} best language around
}\DUfootnotemark{id32
}{id29
}{5}.
1219 %___________________________________________________________________________
1221 \subsubsection*
{2.14.7~~~Compound Paragraph
%
1223 \addcontentsline{toc
}{subsubsection
}{2.14.7~~~Compound Paragraph
}%
1224 \label{compound-paragraph
}%
1227 Compound
1, paragraph
1.
1229 Compound
1, paragraph
2.
1233 \item Compound
1, list item one.
1235 \item Compound
1, list item two.
1239 Another compound statement:
1241 Compound
2, a literal block:
1243 \begin{quote
}{\ttfamily \raggedright \noindent
1244 Compound~
2,~literal.
1247 Compound
2, this is a test.
1249 Compound
3, only consisting of one paragraph.
1251 \begin{quote
}{\ttfamily \raggedright \noindent
1253 This~one~starts~with~a~literal~block.
1256 Compound
4, a paragraph.
1258 Now something
\emph{really
} perverted -
{}- a nested compound block. This is
1259 just to test that it works at all; the results don't have to be
1262 Compound
5, block
1 (a paragraph).
1264 Compound
6, block
2 in compound
5.
1266 Compound
6, another paragraph.
1268 Compound
5, block
3 (a paragraph).
1270 Compound
7, with a table inside:
1273 \setlength{\DUtablewidth}{\linewidth}
1274 \begin{longtable
}[c
]{|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|
}
1296 Compound
7, a paragraph after the table.
1298 Compound
7, another paragraph.
1301 %___________________________________________________________________________
1303 \subsubsection*
{2.14.8~~~Parsed Literal Blocks
%
1305 \addcontentsline{toc
}{subsubsection
}{2.14.8~~~Parsed Literal Blocks
}%
1306 \label{parsed-literal-blocks
}%
1309 \begin{quote
}{\ttfamily \raggedright \noindent
1310 This~is~a~parsed~literal~block.\\
1311 ~~~~This~line~is~indented.~~The~next~line~is~blank.\\
1313 Inline~markup~is~supported,~e.g.~
\emph{emphasis
},~
\textbf{strong
},~
\texttt{literal\\
1314 text
},~footnotes
\DUfootnotemark{id22
}{id8
}{1},~
%
1315 \phantomsection\label{hyperlink-targets
}hyperlink~targets,~and~
\href{http://www.python.org/
}{references
}.
1320 %___________________________________________________________________________
1322 \subsection*
{2.15~~~Substitution Definitions
%
1324 \addcontentsline{toc
}{subsection
}{2.15~~~Substitution Definitions
}%
1325 \label{substitution-definitions
}%
1328 An inline image (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}) example:
1330 (Substitution definitions are not visible in the HTML source.)
1333 %___________________________________________________________________________
1335 \subsection*
{2.16~~~Comments
%
1337 \addcontentsline{toc
}{subsection
}{2.16~~~Comments
}%
1343 % Comments begin with two dots and a space. Anything may
1344 % follow, except for the syntax of footnotes, hyperlink
1345 % targets, directives, or substitution definitions.
1347 % Double-dashes -- "--" -- must be escaped somehow in HTML output.
1349 % Comments may contain non-ASCII characters: ä ö ü æ ø å
1351 (View the HTML source to see the comment.)
1354 %___________________________________________________________________________
1356 \subsection*
{2.17~~~Raw text
%
1358 \addcontentsline{toc
}{subsection
}{2.17~~~Raw text
}%
1362 This does not necessarily look nice, because there may be missing white space.
1364 It's just there to freeze the behavior.
1365 A test.Second test.
\DUrole{myclass
}{Another test with myclass set.
}
1366 This is the
\DUrole{myrawroleclass
}{fourth test
} with myrawroleclass set.
1367 Fifth test in LaTeX.\
\Line two.
1369 %___________________________________________________________________________
1371 \subsection*
{2.18~~~Container
%
1373 \addcontentsline{toc
}{subsection
}{2.18~~~Container
}%
1381 % currently not implemented in LaTeX:
1382 % .. include:: data/header_footer.txt
1385 %___________________________________________________________________________
1387 \subsection*
{2.19~~~Colspanning tables
%
1389 \addcontentsline{toc
}{subsection
}{2.19~~~Colspanning tables
}%
1390 \label{colspanning-tables
}%
1393 This table has a cell spanning two columns:
1396 \setlength{\DUtablewidth}{\linewidth}
1397 \begin{longtable
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.086\DUtablewidth}|
}
1399 \multicolumn{2}{|l|
}{\textbf{%
1415 \multicolumn{2}{|l|
}{\textbf{%
1430 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1468 %___________________________________________________________________________
1470 \subsection*
{2.20~~~Rowspanning tables
%
1472 \addcontentsline{toc
}{subsection
}{2.20~~~Rowspanning tables
}%
1473 \label{rowspanning-tables
}%
1476 Here's a table with cells spanning several rows:
1479 \setlength{\DUtablewidth}{\linewidth}
1480 \begin{longtable
}[c
]{|p
{0.296\DUtablewidth}|p
{0.156\DUtablewidth}|p
{0.226\DUtablewidth}|
}
1483 Header row, column
1
1484 (header rows optional)
1494 Header row, column
1
1495 (header rows optional)
1503 \multicolumn{3}{c
}{\hfill ... continued on next page
} \\
1507 body row
1, column
1
1516 &
\multirow{2}{0.16\DUtablewidth}{%
1519 } &
\multirow{2}{0.23\DUtablewidth}{%
1532 %___________________________________________________________________________
1534 \subsection*
{2.21~~~Custom Roles
%
1536 \addcontentsline{toc
}{subsection
}{2.21~~~Custom Roles
}%
1537 \label{custom-roles
}%
1542 \item A role based on an existing role.
1544 \texttt{\DUrole{custom
}{one
}} \texttt{\DUrole{custom
}{two
}} \texttt{\DUrole{custom
}{three
}}
1548 \DUrole{customnew
}{one two three
}
1550 \item A role with class attribute.
1552 \DUrole{special
}{interpreted text
}
1554 \item A role with class attribute.
1556 \DUrole{very
}{\DUrole{special
}{interpreted text
}}
1561 %___________________________________________________________________________
1563 \section*
{3~~~Tests for the LaTeX writer
%
1565 \addcontentsline{toc
}{section
}{3~~~Tests for the LaTeX writer
}%
1566 \label{tests-for-the-latex-writer
}%
1569 Test syntax elements which may cause trouble for the LaTeX writer but might
1570 not need to be tested with other writers (e.g. the HTML writer).
1573 %___________________________________________________________________________
1575 \subsection*
{3.1~~~Custom Roles in LaTeX
%
1577 \addcontentsline{toc
}{subsection
}{3.1~~~Custom Roles in LaTeX
}%
1578 \label{custom-roles-in-latex
}%
1583 \item Role names and class arguments are converted to conform to the regular
1584 expression
\texttt{{[}a-z
{]}{[}-a-z0-
9{]}*
} (all non-conforming characters are replaced
1585 by a hyphen, all letters are downcased).
1587 Class arguments may contain numbers and hyphens, which need special
1588 treatment in LaTeX command names.
1590 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}}
1592 \item With LaTeX, roles can be styled within the
document using the
\DUroletitlereference{raw
}
1594 \newcommand{\docutilsrolelarge}[1]{{\large #1}}
1596 \@namedef
{docutilsrolesmall-caps
}{\textsc}
1597 \@namedef
{docutilsrolecustom4
}{\textbf}
1599 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Interpreted Text
}}}}} in large, bold, small-caps.
1601 \item Custom roles can be based on standard roles:
1603 This is a
\emph{\DUrole{custom-emphasis
}{customized emphasis text role
}}
1605 This is a
\texttt{\DUrole{custom-literal
}{customized literal text role
}}
1607 This is a
\textbf{\DUrole{custom-strong
}{customized strong text role
}}
1609 This is a
\textsubscript{\DUrole{custom-subscript
}{customized subscript text role
}}
1611 This is a
\textsuperscript{\DUrole{custom-superscript
}{customized superscript text role
}}
1613 This is a
\DUroletitlereference{\DUrole{custom-title-reference
}{customized title-reference text role
}}
1617 % This file is used by the standalone_rst_latex test.
1620 %___________________________________________________________________________
1622 \subsection*
{3.2~~~Option lists
%
1624 \addcontentsline{toc
}{subsection
}{3.2~~~Option lists
}%
1628 The LaTeX-
2e description environment is used for definition lists.
1629 The definition is continued on the same line as the term, this should
1630 not happen if a option-list is at the top of the definition.
1632 If the option list is not at the first element in the definition, it
1633 is contained in a quote
1637 \begin{DUoptionlist
}
1639 \item[-
{}-help
] show help
1648 \item[{In a definition list:
}] \leavevmode %
1649 \begin{DUoptionlist
}
1651 \item[-
{}-help
] show help
1660 %___________________________________________________________________________
1662 \subsection*
{3.3~~~Monospaced non-alphanumeric characters
%
1664 \addcontentsline{toc
}{subsection
}{3.3~~~Monospaced non-alphanumeric characters
}%
1665 \label{monospaced-non-alphanumeric-characters
}%
1668 These are all ASCII characters except a-zA-Z0-
9 and space:
1670 \texttt{!!!"
{}"
{}"\#\#\#\$\$\$\%\%\%\&\&\&'
{}'
{}'((()))***+++,
{},
{},-
{}-
{}-...///:::
}
1672 \texttt{;;;<
{}<
{}<===>
{}>
{}>???@@@
{[}{[}{[}\textbackslash{}\textbackslash{}\textbackslash{}{]}{]}{]}\textasciicircum{}\textasciicircum{}\textasciicircum{}\_\_\_`
{}`
{}`\
{\
{\
{|||\
}\
}\
}\textasciitilde{}\textasciitilde{}\textasciitilde{}}
1674 \texttt{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
}
1676 The two lines of non-alphanumeric characters should both have the same
1677 width as the third line.
1680 %___________________________________________________________________________
1682 \subsection*
{3.4~~~Non-ASCII characters
%
1684 \addcontentsline{toc
}{subsection
}{3.4~~~Non-ASCII characters
}%
1685 \label{non-ascii-characters
}%
1688 Punctuation and footnote symbols
1691 \setlength{\DUtablewidth}{\linewidth}
1692 \begin{longtable
}[c
]{|p
{0.028\DUtablewidth}|p
{0.424\DUtablewidth}|
}
1709 single turned comma quotation mark
1715 single comma quotation mark
1721 low single comma quotation mark
1727 double turned comma quotation mark
1733 double comma quotation mark
1739 low double comma quotation mark
1793 left-right double arrow
1798 The
\DUroletitlereference{Latin-
1 extended
} Unicode block
1801 \setlength{\DUtablewidth}{\linewidth}
1802 \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}|
}
2060 \item The following line should not be wrapped, because it uses
2061 no-break spaces (
\textbackslash{}u00a0):
2063 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
2065 \item Line wrapping with/without breakpoints marked by soft hyphens
2066 (
\textbackslash{}u00ad):
2068 pdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-sch
2070 pdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrisch
2072 \item The currency sign (
\textbackslash{}u00a4) is not supported by all fonts
2073 (some have an Euro sign at its place). You might see an error
2076 \begin{quote
}{\ttfamily \raggedright \noindent
2077 !~Package~textcomp~Error:~Symbol~
\textbackslash{}textcurrency~not~provided~by\\
2078 (textcomp)~~~~~~~~~~~~~~~~font~family~ptm~in~TS1~encoding.\\
2079 (textcomp)~~~~~~~~~~~~~~~~Default~family~used~instead.
2083 (which in case of font family ptm is a false positive). Add either
2087 turn the error in a warning, use the default symbol (bitmap), or
2089 \item[{force,almostfull:
}]
2090 use the symbol provided by the font at the users
2095 to the
document options or use a different font package.
2100 %___________________________________________________________________________
2102 \subsection*
{3.5~~~Encoding special chars
%
2104 \addcontentsline{toc
}{subsection
}{3.5~~~Encoding special chars
}%
2105 \label{encoding-special-chars
}%
2108 The LaTeX Info pages lists under ``
2.18 Special Characters''
2112 The following characters play a special role in LaTeX and are called
2113 ``special printing characters'', or simply ``special characters''.
2117 \# \$ \% \&
\textasciitilde{} \_ \textasciicircum{} \textbackslash{} \
{ \
}
2123 The special chars verbatim:
2125 \begin{quote
}{\ttfamily \raggedright \noindent
2126 \#~\$~\%~\&~
\textasciitilde{}~
\_~
\textasciicircum{}~
\textbackslash{}~\
{~\
}
2130 However also
\emph{square brackets
} {[}{]} need special care.
2134 item and all the other commands with optional arguments check
2135 if the token right after the macro name is an opening bracket.
2136 In that case the contents between that bracket and the following
2137 closing bracket on the same grouping level are taken as the
2138 optional argument. What makes this unintuitive is the fact that
2139 the square brackets aren't grouping characters themselves, so in
2140 your last example item
{[}{[}...
{]}{]} the optional argument consists of
2141 {[}... (without the closing bracket).
2145 Compare the items in the following lists:
2151 \item {[}bracketed
{]} item
2156 \item[{simple
}] \leavevmode
2159 \item[{{[}bracketed
{]}}] \leavevmode
2164 The OT1 font-encoding has different characters for the less-than,
2165 greater-than and bar, < | >, except for typewriter font
\DUroletitlereference{cmtt
}:
2167 \begin{quote
}{\ttfamily \raggedright \noindent
2173 %___________________________________________________________________________
2175 \subsection*
{3.6~~~Hyperlinks and -targets
%
2177 \addcontentsline{toc
}{subsection
}{3.6~~~Hyperlinks and -targets
}%
2178 \label{hyperlinks-and-targets
}%
2181 In LaTeX, we must set an explicit anchor (
\texttt{\textbackslash{}phantomsection
}) for a
2183 \phantomsection\label{hypertarget-in-plain-text
}hypertarget in plain text or in a figure but not in a longtable or
2187 \setlength{\DUtablewidth}{\linewidth}
2188 \begin{longtable
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
2189 \caption{Table with
%
2190 \label{hypertarget-in-table-title
}hypertarget in table title.
}\\
2203 \phantomsection\label{figure-label
}
2204 \noindent\makebox[\textwidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
2205 \caption{Figure with
%
2206 \label{hypertarget-in-figure-caption
}hypertarget in figure caption.
}
2209 \phantomsection\label{hypertarget-in-figure-legend
}hypertarget in figure legend.
2213 \includegraphics{../../../docs/user/rst/images/biohazard.png
}
2214 \phantomsection\label{image-label
}
2216 See
\hyperref[hypertarget-in-plain-text
]{hypertarget in plain text
},
2217 \hyperref[table-label
]{table label
},
\hyperref[hypertarget-in-table-title
]{hypertarget in table title
},
2218 \hyperref[figure-label
]{figure label
},
\hyperref[hypertarget-in-figure-caption
]{hypertarget in figure caption
},
2219 \hyperref[hypertarget-in-figure-legend
]{hypertarget in figure legend
}, and
2220 \hyperref[image-label
]{image label
}.
2223 %___________________________________________________________________________
2225 \subsection*
{3.7~~~External references
%
2227 \addcontentsline{toc
}{subsection
}{3.7~~~External references
}%
2228 \label{external-references
}%
2231 Long URLs should be wrapped in the PDF.
2232 This can be achieved with the url command which is used by the LaTeX writer
2233 wheneve the content (name) of a reference node equals the link URL.
2236 \item[{Example:
}] \leavevmode
2237 a long URL that should wrap in the output
2238 \url{http://docutils.sourceforge.net/docs/user/latex.html\#id79
}
2242 If the argument contains any ``\%'', ``\#'', or ``
\textasciicircum{}\textasciicircum{}'', or ends with
\texttt{\textbackslash{}}, it can't
2243 be used in the argument to another command. The argument must not contain
2246 The characters
\textasciicircum{}, \
{, \
}, and
\texttt{\textbackslash{}} are invalid in a ``http:'' or ``ftp:'' URL
2247 and not recognized as part of it:
2249 \begin{DUlineblock
}{0em
}
2250 \item[] \url{http://www.example.org
}/strange
\textasciicircum{}\textasciicircum{}name
2251 \item[] \url{http://www.example.org
}\textbackslash{}using
\textbackslash{}DOS
\textbackslash{}paths
\textbackslash{}
2252 \item[] \url{http://www.example.org/XML
}/strange\
{n\
}ame
2255 They can, however be used in paths and/or filenames.
2257 Handling by the LaTeX writer:
2261 \item \texttt{\#
},
\texttt{\textbackslash{}} and
\texttt{\%
} are escaped:
2263 \begin{DUlineblock
}{0em
}
2264 \item[] \href{http://www.w3.org/XML/Schema\#dev
}{URL with \#
}
2265 \url{http://www.w3.org/XML/Schema\#dev
}
2266 \item[] \href{http://www.w3.org/XML/Schema\%dev
}{URL with \%
}
2267 \url{http://example.org/Schema\%dev
}
2268 \item[] \href{A:DOS\
\path\\
}{file with DOS path
}\DUfootnotemark{id37
}{id36
}{7} \url{A:DOS\
\path\\
}\DUfootnotemark{id38
}{id36
}{7}
2271 \DUadmonition[note
]{
2272 \DUtitle[note
]{Note
}
2274 These URLs are typeset inside a LaTeX command without error.
2276 \begin{DUlineblock
}{0em
}
2277 \item[] \url{http://www.w3.org/XML/Schema\#dev
}
2278 \item[] \url{http://example.org/Schema\%dev
}
2279 \item[] \url{A:DOS\
\path\\
}\DUfootnotemark{id39
}{id36
}{7}
2287 \item \textasciicircum{}\textasciicircum{} LaTeX's special syntax for characters results in ``strange'' replacements
2288 (both with href and url). A warning is given.
2290 \href{../strange^^name
}{file with
\textasciicircum{}\textasciicircum{}}:
2291 \url{../strange^^name
}
2293 \item Unbalanced braces, \
{ or \
}, will fail (both with href and url):
2295 \begin{quote
}{\ttfamily \raggedright \noindent
2296 `file~with~\
{~<../strange\
{name>`
\_\_\\
2297 `<../strange\
{name>`
\_\_
2301 while balanced braces are suported:
2303 \begin{DUlineblock
}{0em
}
2304 \item[] \url{../strange
{n
}ame
}
2305 \item[] \url{../st
{r
}ange
{n
}ame
}
2306 \item[] \url{../
{st
{r
}ange
{n
}ame
}}
2311 % unusual combinations (from newlatex, for interactive testing)
2312 % .. include:: data/latex.txt
2314 % Preface for System Messages:
2317 %___________________________________________________________________________
2319 \section*
{4~~~Error Handling
%
2321 \addcontentsline{toc
}{section
}{4~~~Error Handling
}%
2322 \label{error-handling
}%
2325 Any errors caught during processing will generate system messages.
2327 There should be five messages in the following, auto-generated
2328 section, ``Docutils System Messages'':
2330 % section should be added by Docutils automatically
2333 %___________________________________________________________________________
2335 \section*
{\color{red
}Docutils System Messages
%
2337 \addcontentsline{toc
}{section
}{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~
102
2347 Undefined substitution referenced: ``problematic''.
2350 \DUadmonition[system-message
]{
2351 \DUtitle[system-message
]{system-message
}
2352 \raisebox{1em
}{\hypertarget{id40
}{}}
2354 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
361
2357 Unknown target name: ``
5''.
2360 \DUadmonition[system-message
]{
2361 \DUtitle[system-message
]{system-message
}
2362 \raisebox{1em
}{\hypertarget{id42
}{}}
2364 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
370
2367 Unknown target name: ``nonexistent''.
2370 \DUadmonition[system-message
]{
2371 \DUtitle[system-message
]{system-message
}
2372 \raisebox{1em
}{\hypertarget{id44
}{}}
2374 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
397
2377 Unknown target name: ``hyperlink reference without a target''.
2380 \DUadmonition[system-message
]{
2381 \DUtitle[system-message
]{system-message
}
2382 \raisebox{1em
}{\hypertarget{id46
}{}}
2384 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
410
2387 Duplicate target name, cannot be used as a unique reference: ``duplicate target names''.