1 \documentclass[a4paper]{article
}
2 % generated by Docutils <https://docutils.sourceforge.io/>
3 \usepackage{cmap
} % fix search and cut-and-paste in Acrobat
5 \usepackage[T1]{fontenc}
8 \usepackage[british,french,
ngerman,english
]{babel
}
9 % Prevent side-effects if French hyphenation patterns are not loaded:
10 \frenchbsetup{StandardLayout
}
11 \AtBeginDocument{\selectlanguage{english
}\noextrasfrench}
13 \usepackage{float
} % extended float configuration
14 \floatplacement{figure
}{H
} % place figures here definitely
18 \setcounter{secnumdepth
}{0}
19 \usepackage{longtable,ltcaption,array
}
20 \setlength{\extrarowheight}{2pt
}
21 \newlength{\DUtablewidth} % internal use in tables
24 %%% Custom LaTeX preamble
26 \usepackage{mathptmx
} % Times
27 \usepackage[scaled=
.90]{helvet
}
30 %%% User specified packages and stylesheets
32 %%% Fallback definitions for Docutils-specific commands
34 % class handling for environments (block-level elements)
35 % \begin{DUclass}{spam} tries \DUCLASSspam and
36 % \end{DUclass}{spam} tries \endDUCLASSspam
37 \ifx\DUclass\undefined % poor man's "provideenvironment"
38 \newenvironment{DUclass
}[1]%
39 {% "#1" does not work in end-part of environment.
40 \def\DocutilsClassFunctionName{DUCLASS
#1}
41 \csname \DocutilsClassFunctionName \endcsname}%
42 {\csname end
\DocutilsClassFunctionName \endcsname}%
45 % Provide a length variable and set default, if it is new
46 \providecommand*
{\DUprovidelength}[2]{
47 \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{}
50 \providecommand*
{\DUCLASSabstract}{
51 \renewcommand{\DUtitle}[1]{\centerline{\textbf{#
#1}}}
54 % admonition environment (specially marked topic)
55 \ifx\DUadmonition\undefined % poor man's "provideenvironment"
56 \newbox{\DUadmonitionbox}
57 \newenvironment{DUadmonition
}%
59 \begin{lrbox
}{\DUadmonitionbox}
60 \begin{minipage
}{0.9\linewidth}
64 \fbox{\usebox{\DUadmonitionbox}}
69 % special topic for dedications
70 \providecommand*
{\DUCLASSdedication}{%
71 \renewenvironment{quote
}{\begin{center
}}{\end{center
}}%
74 % width of docinfo table
75 \DUprovidelength{\DUdocinfowidth}{0.9\linewidth}
77 % subtitle (in document title)
78 \providecommand*
{\DUdocumentsubtitle}[1]{{\large #1}}
81 \providecommand*
{\DUCLASSerror}{\color{red
}}
83 % field list environment (for separate configuration of `field lists`)
84 \ifthenelse{\isundefined{\DUfieldlist}}{
85 \newenvironment{DUfieldlist
}%
87 {\enddescription\endquote}
90 % numerical or symbol footnotes with hyperlinks and backlinks
91 \providecommand*
{\DUfootnotemark}[3]{%
92 \raisebox{1em
}{\hypertarget{#1}{}}%
93 \hyperlink{#2}{\textsuperscript{#3}}%
95 \providecommand{\DUfootnotetext}[4]{%
97 \renewcommand{\thefootnote}{%
98 \protect\raisebox{1em
}{\protect\hypertarget{#1}{}}%
99 \protect\hyperlink{#2}{#3}}%
104 % custom inline roles: \DUrole{#1}{#2} tries \DUrole#1{#2}
105 \providecommand*
{\DUrole}[2]{%
106 \ifcsname DUrole
#1\endcsname%
107 \csname DUrole
#1\endcsname{#2}%
113 % legend environment (in figures and formal tables)
114 \ifthenelse{\isundefined{\DUlegend}}{
115 \newenvironment{DUlegend
}{\small}{}
118 % line block environment
119 \DUprovidelength{\DUlineblockindent}{2.5em
}
120 \ifthenelse{\isundefined{\DUlineblock}}{
121 \newenvironment{DUlineblock
}[1]{%
122 \list{}{\setlength{\partopsep}{\parskip}
123 \addtolength{\partopsep}{\baselineskip}
124 \setlength{\topsep}{0pt
}
125 \setlength{\itemsep}{0.15\baselineskip}
126 \setlength{\parsep}{0pt
}
127 \setlength{\leftmargin}{#1}}
133 % list of command line options
134 \providecommand*
{\DUoptionlistlabel}[1]{\bfseries #1 \hfill}
135 \DUprovidelength{\DUoptionlistindent}{3cm
}
136 \ifthenelse{\isundefined{\DUoptionlist}}{
137 \newenvironment{DUoptionlist
}{%
138 \list{}{\setlength{\labelwidth}{\DUoptionlistindent}
139 \setlength{\rightmargin}{1cm
}
140 \setlength{\leftmargin}{\rightmargin}
141 \addtolength{\leftmargin}{\labelwidth}
142 \addtolength{\leftmargin}{\labelsep}
143 \renewcommand{\makelabel}{\DUoptionlistlabel}}
149 \providecommand*
{\DUrubric}[1]{\subsubsection*
{\emph{#1}}}
151 % text outside the main text flow
152 \providecommand{\DUsidebar}[1]{%
154 \colorbox[gray
]{0.80}{\parbox{0.9\linewidth}{#1}}
158 % subtitle (for sidebar)
159 \providecommand*
{\DUsubtitle}[1]{\par\emph{#1}\smallskip}
161 % title for topics, admonitions, unsupported section levels, and sidebar
162 \providecommand*
{\DUtitle}[1]{%
163 \smallskip\noindent\textbf{#1}\smallskip}
165 % titlereference standard role
166 \providecommand*
{\DUroletitlereference}[1]{\textsl{#1}}
168 % transition (break / fancybreak / anonymous section)
169 \providecommand*
{\DUtransition}{%
170 \hspace*
{\fill}\hrulefill\hspace*
{\fill}
171 \vskip 0.5\baselineskip
175 \ifthenelse{\isundefined{\hypersetup}}{
176 \usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue
]{hyperref
}
177 \usepackage{bookmark
}
178 \urlstyle{same
} % normal text font (alternatives: tt, rm, sf)
181 pdftitle=
{reStructuredText Test Document
},
182 pdfkeywords=
{reStructuredText, test, parser
},
183 pdfinfo=
{description=
{A test
document, containing at least one example of each reStructuredText construct.
}},
184 pdfauthor=
{David Goodger;Me;Myself;I
}
189 \title{reStructuredText Test Document
%
190 \label{restructuredtext-test-
document}%
193 \DUdocumentsubtitle{Examples of Syntax Constructs
}%
194 \label{examples-of-syntax-constructs
}%
202 \begin{tabularx
}{\DUdocinfowidth}{lX
}
211 \href{mailto:goodger@python.org
}{goodger@python.org
} \\
218 \textbf{Organization
}: &
221 Now, or yesterday. Or maybe even
\emph{before
} yesterday. \\
223 This is a “work in progress” \\
225 is managed by a version control system. \\
228 \textbf{Copyright
}: &
229 This
document has been placed in the public domain. You
230 may do with it as you wish. You may copy, modify,
231 redistribute, reattribute, sell, buy, rent, lease,
232 destroy, or improve it, quote it at length, excerpt,
233 incorporate, collate, fold, staple, or mutilate it, or do
234 anything else to it that your or anyone else’s heart
236 \textbf{field name
}: &
237 This is a “generic bibliographic field”.
239 \textbf{field name “
2”
}: &
240 Generic bibliographic fields may contain multiple body elements.
247 \begin{DUclass
}{dedication
}
251 For Docutils users \& co-developers.
255 \begin{DUclass
}{abstract
}
259 This is a test
document, containing at least one example of each
260 reStructuredText construct.
264 % This is a comment. Note how any initial comments are moved by
265 % transforms to after the document title, subtitle, and docinfo.
267 % Above is the document title, and below is the subtitle.
268 % They are transformed from section titles after parsing.
270 % bibliographic fields (which also require a transform):
272 \pagebreak[4] % start ToC on new page
274 \phantomsection\label{table-of-contents
}
275 \pdfbookmark[1]{Table of Contents
}{table-of-contents
}
276 \renewcommand{\contentsname}{Table of Contents
}
280 \section{1 Structural Elements
%
281 \label{structural-elements
}%
285 \subsection{1.1 Section Title
%
286 \label{section-title
}%
288 \subsubsection*
{Section Subtitle
}
290 Lone subsections are converted to a section subtitle by a transform
291 activated with the
\texttt{-
{}-section-subtitles
} command line option or the
292 \texttt{sectsubtitle-xform
} configuration value.
295 \subsection{1.2 Empty Section
%
296 \label{empty-section
}%
300 \subsection{1.3 Transitions
%
306 %___________________________________________________________________________
309 It divides the section. Transitions may also occur between sections:
311 %___________________________________________________________________________
315 \section{2 Body Elements
%
316 \label{body-elements
}%
320 \subsection{2.1 Paragraphs
%
327 \subsubsection{2.1.1 Inline Markup
%
328 \label{inline-markup
}%
331 Paragraphs contain text and may contain inline markup:
\emph{emphasis
},
332 \textbf{strong emphasis
},
\texttt{inline literals
}, standalone hyperlinks
333 (
\url{http://www.python.org
}), external hyperlinks (
\href{http://www.python.org/
}{Python
}\DUfootnotemark{footnote-reference-
10}{footnote-
6}{5}), internal
334 cross-references (
\hyperref[example
]{example
}), external hyperlinks with embedded URIs
335 (
\href{http://www.python.org
}{Python web site
}),
\href{http://www.python.org/
}{anonymous hyperlink
336 references
}\DUfootnotemark{footnote-reference-
16}{footnote-
6}{5} (
\href{https://docutils.sourceforge.io/
}{a second reference
}\DUfootnotemark{footnote-reference-
17}{footnote-
9}{8}), footnote references (manually
337 numbered
\DUfootnotemark{footnote-reference-
1}{footnote-
1}{1}, anonymous auto-numbered
\DUfootnotemark{footnote-reference-
2}{footnote-
2}{3}, labeled auto-numbered
\DUfootnotemark{footnote-reference-
3}{label
}{2}, or symbolic
\DUfootnotemark{footnote-reference-
4}{footnote-
3}{*
}), citation references (see
\hyperlink{cit2002
}{[CIT2002
]}),
338 substitution references (
\includegraphics{../../../docs/user/rst/images/biohazard.png
} \&
339 a
\emph{trimmed heart
} \texttt{(U+
2665):
}\ding{170}), and
%
340 \phantomsection\label{inline-hyperlink-targets
}inline hyperlink targets
341 (see
\hyperref[targets
]{Targets
} below for a reference back to here). Character-level
342 inline markup is also possible (although exceedingly ugly!) in
\emph{re
}\texttt{Structured
}\emph{Text
}. Problems are indicated by
%
343 \raisebox{1em
}{\hypertarget{problematic-
1}{}}\hyperlink{system-message-
1}{\textbf{\color{red
}|problematic|
}} text
344 (generated by processing errors; this one is intentional). Here is a
345 reference to the
\hyperref[doctitle
]{doctitle
} and the
\hyperref[subtitle
]{subtitle
}.
347 The default role for interpreted text is
\DUroletitlereference{Title Reference
}. Here are
348 some explicit interpreted text roles: a PEP reference (
\href{https://peps.python.org/pep-
0287}{PEP
287}); an
349 RFC reference (
\href{https://tools.ietf.org/html/rfc2822.html
}{RFC
2822}); an abbreviation (
\DUrole{abbreviation
}{abb.
}), an acronym
350 (
\DUrole{acronym
}{reST
}), code (
\texttt{\DUrole{code
}{print
\textquotedbl{}hello world
\textquotedbl{}}}); a
\textsubscript{subscript
};
351 a
\textsuperscript{superscript
} and explicit roles for
\DUroletitlereference{Docutils
}’
352 \emph{standard
} \textbf{inline
} \texttt{markup
}.
354 % DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
356 Let’s test wrapping and whitespace significance in inline literals:
357 \texttt{This is an example of -
{}-inline-literal -
{}-text, -
{}-including some-
{}-
358 strangely-
{}-hyphenated-words. ~Adjust-the-width-of-your-browser-window
359 to see how the text is wrapped. ~-
{}- -
{}-
{}-
{}- -
{}-
{}-
{}-
{}-
{}-
{}-
{}- ~Now note ~ ~the
360 spacing ~ ~between the ~ ~words of ~ ~this sentence ~ ~(words
361 should ~ ~be grouped ~ ~in pairs).
}
363 If the
\texttt{-
{}-pep-references
} option was supplied, there should be a
364 live link to PEP
258 here.
367 \subsection{2.2 Bullet Lists
%
368 \label{bullet-lists
}%
375 \item Nested bullet list.
382 Paragraph
2 of item
2.
385 \item Nested bullet list.
397 \item This nested list should be compacted by the HTML writer.
399 \phantomsection\label{target
}
400 % Even if this item contains a target and a comment.
405 \subsection{2.3 Enumerated Lists
%
406 \label{enumerated-lists
}%
410 \item Arabic numerals.
413 \renewcommand{\labelenumii}{\alph{enumii
})
}
417 \renewcommand{\labelenumiii}{(
\roman{enumiii
})
}
423 \begin{list
}{\Roman{enumv
})
}{\usecounter{enumv
}}
430 \item Lists that don’t start at
1:
433 \renewcommand{\labelenumii}{\arabic{enumii
}.
}
434 \setcounter{enumii
}{2}
441 \renewcommand{\labelenumii}{\Alph{enumii
}.
}
442 \setcounter{enumii
}{2}
449 \renewcommand{\labelenumii}{\roman{enumii
}.
}
450 \setcounter{enumii
}{2}
458 \subsection{2.4 Definition Lists
%
459 \label{definition-lists
}%
466 \item[{Term
}] (
\textbf{classifier
})
467 Definition paragraph
1.
469 Definition paragraph
2.
474 \item[{Term
}] (
\textbf{classifier one
})(
\textbf{classifier two
})
479 \subsection{2.5 Field Lists
%
485 Field lists map field names to field bodies, like database
486 records. They are often part of an extension syntax. They are
487 an unambiguous variant of RFC
2822 fields.
489 \item[{how arg1 arg2:
}]
490 The field marker is a colon, the field name, and a colon.
492 The field body may contain one or more body elements, indented
493 relative to the field marker.
496 \DUrole{credits
}{This paragraph has the
\DUroletitlereference{credits
} class set. (This is actually not
497 about credits but just for ensuring that the class attribute
498 doesn’t get stripped away.)
}
502 \subsection{2.6 Option Lists
%
503 \label{option-lists
}%
506 For listing command-line options:
509 \item[-a
] command-line option “a”
510 \item[-b file
] options can have arguments
511 and long descriptions
512 \item[-
{}-long
] options can be long, too
513 \item[-
{}-input=file
] long options can also have arguments
514 \item[/V
] DOS/VMS-style option
515 \item[-
{}-very-long-option
] The description can also start on the next line.
517 The description may contain multiple body elements,
518 regardless of where it starts.
519 \item[-x, -y, -z
] Multiple options are an “option group”.
520 \item[-v, -
{}-verbose
] Commonly-seen: short \& long options.
521 \item[-
1 file, -
{}-one=file, -
{}-two file
] Multiple options with arguments.
522 \item[-f <
{[}path
{]}file>
] Option argumens must start with a letter
523 or be wrapped in angle brackets.
524 \item[-d <src dest>
] Angle brackets are also required if an
525 option expects more than one argument.
528 There must be at least two spaces between the option and the
532 \subsection{2.7 Literal Blocks
%
533 \label{literal-blocks
}%
536 Literal blocks are indicated with a double-colon (“::”) at the end of
537 the preceding paragraph (over there
\texttt{-
{}->
}). They can be indented:
542 text = 'is left as-is'
543 spaces_and_linebreaks = 'are preserved'
544 markup_processing = None
548 Or they can be quoted without indentation:
554 > Why didn't I think of that?
559 \subsection{2.8 Line Blocks
%
563 This section tests line blocks. Line blocks are body elements which
564 consist of lines and other line blocks. Nested line blocks cause
567 \begin{DUlineblock
}{0em
}
568 \item[] This is a line block. It ends with a blank line.
570 \begin{DUlineblock
}{\DUlineblockindent}
571 \item[] New lines begin with a vertical bar (“|”).
572 \item[] Line breaks and initial indent are significant, and preserved.
574 \begin{DUlineblock
}{\DUlineblockindent}
575 \item[] Continuation lines are also possible. A long line that is intended
576 to wrap should begin with a space in place of the vertical bar.
578 \item[] The left edge of a continuation line need not be aligned with
579 the left edge of the text above it.
583 \begin{DUlineblock
}{0em
}
584 \item[] This is a second line block.
586 \item[] Blank lines are permitted internally, but they must begin with a “|”.
589 Another line block, surrounded by paragraphs:
591 \begin{DUlineblock
}{0em
}
592 \item[] And it’s no good waiting by the window
593 \item[] It’s no good waiting for the sun
594 \item[] Please believe me, the things you dream of
595 \item[] They don’t fall in the lap of no-one
598 Take it away, Eric the Orchestra Leader!
601 \begin{DUlineblock
}{0em
}
602 \item[] A one, two, a one two three four
604 \item[] Half a bee, philosophically,
606 \begin{DUlineblock
}{\DUlineblockindent}
607 \item[] must,
\emph{ipso facto
}, half not be.
609 \item[] But half the bee has got to be,
611 \begin{DUlineblock
}{\DUlineblockindent}
612 \item[] \emph{vis a vis
} its entity. D’you see?
615 \item[] But can a bee be said to be
617 \begin{DUlineblock
}{\DUlineblockindent}
618 \item[] or not to be an entire bee,
620 \begin{DUlineblock
}{\DUlineblockindent}
621 \item[] when half the bee is not a bee,
623 \begin{DUlineblock
}{\DUlineblockindent}
624 \item[] due to some ancient injury?
633 A line block, like the following poem by Christian Morgenstern, can
634 also be centre-aligned:
636 \begin{selectlanguage
}{ngerman}
637 \begin{DUlineblock
}{0em
}
639 \item[] \textbf{Die Trichter
}
641 \item[] Zwei Trichter wandeln durch die Nacht.
642 \item[] Durch ihres Rumpfs verengten Schacht
643 \item[] fließt weißes Mondlicht
644 \item[] still und heiter
654 \subsection{2.9 Block Quotes
%
655 \label{block-quotes
}%
658 Block quotes consist of indented body elements:
661 My theory by A. Elk. Brackets Miss, brackets. This theory goes
662 as follows and begins now. All brontosauruses are thin at one
663 end, much much thicker in the middle and then thin again at the
664 far end. That is my theory, it is mine, and belongs to me and I
665 own it, and what it is too.
668 \raggedleft —Anne Elk (Miss)
671 The language of a quote (like any other object) can be specified by
676 \begin{selectlanguage
}{french
}
678 ReStructuredText est un langage de balisage léger utilisé
679 notamment dans la documentation du langage Python.
684 \subsection{2.10 Doctest Blocks
%
685 \label{doctest-blocks
}%
690 >>> print 'Python-specific usage examples; begun with ">>>"'
691 Python-specific usage examples; begun with ">>>"
692 >>> print '(cut and pasted from interactive Python sessions)'
693 (cut and pasted from interactive Python sessions)
698 \subsection{2.11 Footnotes
%
702 \DUfootnotetext{footnote-
1}{footnote-reference-
1}{1}{%
703 A footnote contains body elements, consistently indented by at
706 This is the footnote’s second paragraph.
709 \DUfootnotetext{label
}{footnote-reference-
3}{2}{\phantomsection\label{label
}%
710 Footnotes may be numbered, either manually (as in
\DUfootnotemark{footnote-reference-
5}{footnote-
1}{1}) or
711 automatically using a “\#”-prefixed label. This footnote has a
712 label so it can be referred to from multiple places, both as a
713 footnote reference (
\DUfootnotemark{footnote-reference-
6}{label
}{2}) and as a
\hyperref[label
]{hyperlink reference
}.
716 \DUfootnotetext{footnote-
2}{footnote-reference-
2}{3}{%
717 This footnote is numbered automatically and anonymously using a
720 This is the second paragraph.
722 And this is the third paragraph.
725 \DUfootnotetext{footnote-
3}{footnote-reference-
4}{*
}{%
726 Footnotes may also use symbols, specified with a “*” label.
727 Here’s a reference to the next footnote:
\DUfootnotemark{footnote-reference-
7}{footnote-
4}{†
}.
730 \DUfootnotetext{footnote-
4}{footnote-reference-
7}{†
}{%
731 This footnote shows the next symbol in the sequence.
734 \DUfootnotetext{footnote-
5}{footnote-
5}{4}{%
735 Here’s an unreferenced footnote, with a reference to a
736 nonexistent footnote:
%
737 \raisebox{1em
}{\hypertarget{footnote-reference-
8}{}}\hyperlink{system-message-
2}{\textbf{\color{red
}{[}5{]}\_}}.
741 \subsection{2.12 Citations
%
744 \begin{figure
}[b
]\raisebox{1em
}{\hypertarget{cit2002
}{}}[CIT2002
]
745 Citations are text-labeled footnotes. They may be
746 rendered separately and differently from footnotes.
749 Here’s a reference to the above,
\hyperlink{cit2002
}{[CIT2002
]}, and a
%
750 \raisebox{1em
}{\hypertarget{citation-reference-
3}{}}\hyperlink{system-message-
3}{\textbf{\color{red
}{[}nonexistent
{]}\_}}
754 \subsection{2.13 Targets
%
756 \label{another-target
}%
759 \phantomsection\label{example
}
760 This paragraph is pointed to by the explicit “example” target. A
761 reference can be found under
\hyperref[inline-markup
]{Inline Markup
}, above.
\hyperref[inline-hyperlink-targets
]{Inline
762 hyperlink targets
} are also possible.
764 Section headers are implicit targets, referred to by name. See
765 \hyperref[targets
]{Targets
}, which is a subsection of
\hyperref[body-elements
]{Body Elements
}.
767 Explicit external targets are interpolated into references such as
768 “
\href{http://www.python.org/
}{Python
}\DUfootnotemark{footnote-reference-
11}{footnote-
6}{5}”.
770 Targets may be indirect and anonymous. Thus
\hyperref[targets
]{this phrase
} may also
771 refer to the
\hyperref[targets
]{Targets
} section.
774 \raisebox{1em
}{\hypertarget{problematic-
2}{}}\hyperlink{system-message-
4}{\textbf{\color{red
}`hyperlink reference without a target`
\_}}, which generates an
778 \subsubsection{2.13.1 Duplicate Target Names
%
779 \label{duplicate-target-names
}%
782 Duplicate names in section headers or other implicit targets will
783 generate “info” (level-
1) system messages. Duplicate names in
784 explicit targets will generate “warning” (level-
2) system messages.
787 \subsubsection{2.13.2 Duplicate Target Names
%
788 \label{duplicate-target-names-
1}%
791 Since there are two “Duplicate Target Names” section headers, we
792 cannot uniquely refer to either of them by name. If we try to (like
794 \raisebox{1em
}{\hypertarget{problematic-
3}{}}\hyperlink{system-message-
5}{\textbf{\color{red
}`Duplicate Target Names`
\_}}), an error is generated.
797 \subsection{2.14 Directives
%
801 These are just a sample of the many reStructuredText Directives. For
802 others, please see
\href{https://docutils.sourceforge.io/docs/ref/rst/directives.html
}{reStructuredText Directives
}\DUfootnotemark{footnote-reference-
18}{footnote-
10}{9}.
805 \subsubsection{2.14.1 Document Parts
%
806 \label{document-parts
}%
809 An example of the “contents” directive can be seen above this section
810 (a local, untitled table of
\hyperref[contents
]{contents
}) and at the beginning of the
811 document (a
document-wide
\hyperref[table-of-contents
]{table of contents
}).
814 \subsubsection{2.14.2 Images and Figures
%
815 \label{images-and-figures
}%
818 An image directive (also clickable – a hyperlink reference):
820 \hyperref[directives
]{\includegraphics[width=
0.700\linewidth]{../../../docs/user/rst/images/title.png
}}
822 Image with multiple IDs:
824 \includegraphics{../../../docs/user/rst/images/biohazard.png
}
825 \phantomsection\label{image-target-
3}\label{image-target-
2}\label{image-target-
1}
829 \noindent\makebox[\linewidth][c
]{\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
831 A left-aligned image:
833 \noindent{\includegraphics{../../../docs/user/rst/images/biohazard.png
}\hfill}
835 This paragraph might flow around the image.
836 The specific behavior depends upon the style sheet and
837 the browser or rendering software used.
839 A right-aligned image:
841 \noindent{\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png
}}
843 This paragraph might flow around the image.
844 The specific behavior depends upon the style sheet and
845 the browser or rendering software used.
847 For inline images see
\hyperref[substitution-definitions
]{Substitution Definitions
}.
853 \includegraphics[width=
2em
]{../../../docs/user/rst/images/biohazard.png
}
855 An image
2 cm wide and
15 pixel high:
857 \includegraphics[height=
15px,width=
2cm
]{../../../docs/user/rst/images/biohazard.png
}
859 Relative units allow adaption of the image to the screen or paper size.
860 An image occupying
50\% of the line width:
862 \includegraphics[width=
0.500\linewidth]{../../../docs/user/rst/images/title.png
}
864 A
\emph{figure
} is an image with a caption and/or a legend. With page-based output
865 media, figures might float to a different position if this helps the page
868 \begin{DUclass
}{figclass1
}
869 \begin{DUclass
}{figclass2
}
871 \noindent\makebox[\linewidth][c
]{\includegraphics[width=
258bp
]{../../../docs/user/rst/images/title.png
}}
872 \caption{Plaintext markup syntax and parser system.
}
874 \setlength{\DUtablewidth}{\linewidth}%
875 \begin{longtable*
}{|p
{0.156\DUtablewidth}|p
{0.563\DUtablewidth}|
}
880 Revised, revisited, based on ‘re’ module.
886 Structure-enhanced text, structuredtext.
892 Well it is, isn’t it?
897 This paragraph is also part of the legend.
903 A left-aligned figure,
70\% wide:
905 \begin{DUclass
}{figclass1
}
906 \begin{DUclass
}{figclass2
}
907 \begin{figure
} % align = "left"
908 \noindent\makebox[\linewidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
909 \caption{This is the caption.
}
913 The legend may consist of several paragraphs.
919 This paragraph might flow around the figure.
921 The specific behavior depends upon the style sheet and the browser or
922 rendering software used.
924 A centred figure,
40\% wide:
927 \noindent\makebox[\linewidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
928 \caption{This is the caption.
}
932 The legend may consist of several paragraphs.
936 This paragraph might flow around the figure.
938 The specific behavior depends upon the style sheet and the browser or
939 rendering software used.
941 A right-aligned figure:
943 \begin{figure
} % align = "right"
944 \noindent\makebox[\linewidth][c
]{\includegraphics[width=
40px
]{../../../docs/user/rst/images/biohazard.png
}}
945 \caption{This is the caption.
}
949 The legend may consist of several paragraphs.
953 This paragraph might flow around the figure. The specific behavior depends
954 upon the style sheet and the browser or rendering software used.
957 \subsubsection{2.14.3 Tables
%
961 Tables may be given titles and additional arguments with the
\emph{table
}
964 \setlength{\DUtablewidth}{\linewidth}%
965 \begin{longtable
}[l
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
966 \caption{left-aligned table
}\\
975 \caption[]{left-aligned table (... continued)
}\\
984 \multicolumn{2}{p
{0.15\DUtablewidth}}{\raggedleft\ldots continued on next page
}\\
1001 \setlength{\DUtablewidth}{\linewidth}%
1002 \begin{longtable
}[c
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
1003 \caption{center-aligned table
}\\
1012 \caption[]{center-aligned table (... continued)
}\\
1021 \multicolumn{2}{p
{0.15\DUtablewidth}}{\raggedleft\ldots continued on next page
}\\
1038 \setlength{\DUtablewidth}{\linewidth}%
1039 \begin{longtable
}[r
]{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|
}
1040 \caption{right-aligned table
}\\
1049 \caption[]{right-aligned table (... continued)
}\\
1058 \multicolumn{2}{p
{0.15\DUtablewidth}}{\raggedleft\ldots continued on next page
}\\
1075 With the “widths” argument “auto” (or “class” value “colwidths-auto”),
1076 column widths are determined by the backend (if supported by the
1079 \phantomsection\label{target2
}\label{target1
}
1080 \begin{longtable*
}{|l|l|l|
}
1082 \textbf{A
} &
\textbf{B
} &
\textbf{A or B
} \\
1086 \textbf{A
} &
\textbf{B
} &
\textbf{A or B
} \\
1091 False & False & False \\
1093 True & False & True \\
1095 False & True & True \\
1097 True & True & True \\
1102 \subsubsection{2.14.4 Admonitions
%
1103 \label{admonitions
}%
1106 \begin{DUclass
}{attention
}
1107 \begin{DUadmonition
}
1108 \DUtitle{Attention!
}
1110 Directives at large.
1114 \begin{DUclass
}{caution
}
1115 \begin{DUadmonition
}
1118 Don’t take any wooden nickels.
1122 \begin{DUclass
}{danger
}
1123 \begin{DUadmonition
}
1126 Mad scientist at work!
1130 \begin{DUclass
}{error
}
1131 \begin{DUadmonition
}
1138 \begin{DUclass
}{hint
}
1139 \begin{DUadmonition
}
1142 It’s bigger than a bread box.
1146 \begin{DUclass
}{important
}
1147 \begin{DUadmonition
}
1151 \item Wash behind your ears.
1153 \item Clean up your room.
1155 \item Call your mother.
1157 \item Back up your data.
1162 \begin{DUclass
}{note
}
1163 \begin{DUadmonition
}
1170 \begin{DUclass
}{tip
}
1171 \begin{DUadmonition
}
1174 15\% if the service is good.
1178 \begin{DUclass
}{warning
}
1179 \begin{DUadmonition
}
1182 Strong prose may provoke extreme mental exertion.
1183 Reader discretion is strongly advised.
1187 \begin{DUclass
}{admonition-and-by-the-way
}
1188 \begin{DUadmonition
}
1189 \DUtitle{And, by the way…
}
1191 You can make up your own admonition too.
1196 \subsubsection{2.14.5 Topics, Sidebars, and Rubrics
%
1197 \label{topics-sidebars-and-rubrics
}%
1200 \emph{Sidebars
} are like miniature, parallel documents.
1203 \DUtitle{Optional Sidebar Title
}
1205 \DUsubtitle{Optional Subtitle
}
1207 This is a sidebar. It is for text outside the flow of the main
1210 \DUrubric{This is a rubric inside a sidebar
}
1212 Sidebars often appear beside the main text with a border and a different
1213 background or font
color.
1216 A
\emph{topic
} is like a block quote with a title, or a self-contained section
1217 with no subsections.
1219 \begin{DUclass
}{topic
}
1221 \DUtitle{Topic Title
}
1227 A
\emph{rubric
} is like an informal heading that doesn’t correspond to the
1228 document’s structure. It is typically highlighted in red (hence the name).
1230 \DUrubric{This is a rubric
}
1232 Topics and rubrics can be used at places where a
\hyperref[section-title
]{section title
} is not
1233 allowed (e.g. inside a directive).
1236 \subsubsection{2.14.6 Target Footnotes
%
1237 \label{target-footnotes
}%
1240 \DUfootnotetext{footnote-
6}{footnote-reference-
10}{5}{%
1241 \url{http://www.python.org/
}
1244 \DUfootnotetext{footnote-
7}{footnote-reference-
13}{6}{%
1245 \url{http://pygments.org/
}
1248 \DUfootnotetext{footnote-
8}{footnote-reference-
14}{7}{%
1249 \url{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
}
1252 \DUfootnotetext{footnote-
9}{footnote-reference-
17}{8}{%
1253 \url{https://docutils.sourceforge.io/
}
1256 \DUfootnotetext{footnote-
10}{footnote-reference-
18}{9}{%
1257 \url{https://docutils.sourceforge.io/docs/ref/rst/directives.html
}
1260 \DUfootnotetext{footnote-
11}{footnote-reference-
19}{10}{%
1261 \url{https://docutils.sourceforge.io/docs/ref/rst/directives.html\#metadata
}
1265 \subsubsection{2.14.7 Replacement Text
%
1266 \label{replacement-text
}%
1269 I recommend you try
\href{http://www.python.org/
}{Python,
\emph{the
} best language around
}\DUfootnotemark{footnote-reference-
12}{footnote-
6}{5}.
1272 \subsubsection{2.14.8 Compound Paragraph
%
1273 \label{compound-paragraph
}%
1276 The
\emph{compound
} directive is used to create a “compound paragraph”, which
1277 is a single logical paragraph containing multiple physical body
1278 elements. For example:
1280 \begin{DUclass
}{compound
}
1281 The ‘rm’ command is very dangerous. If you are logged
1282 in as root and enter
1289 you will erase the entire contents of your file system.
1292 Test the handling and display of compound paragraphs:
1294 \begin{DUclass
}{compound
}
1295 \begin{DUclass
}{some-class
}
1296 Compound
2, paragraph
1,
1298 compound
2, paragraph
2,
1304 compound
2, paragraph
3.
1308 \begin{DUclass
}{compound
}
1309 Compound
3, only consisting of one paragraph.
1312 \begin{DUclass
}{compound
}
1316 This one starts with a literal block.
1319 Compound
4, paragraph following the literal block.
1322 Now something
\emph{really
} perverted – a nested compound block. This is
1323 just to test that it works at all; the results don’t have to be
1326 \begin{DUclass
}{compound
}
1327 Compound
5, block
1 (a paragraph).
1329 \begin{DUclass
}{compound
}
1330 Compound
6 is block
2 in compound
5.
1332 Compound
6, another paragraph.
1335 Compound
5, block
3 (a paragraph).
1338 \begin{DUclass
}{compound
}
1339 Compound
7, tests the inclusion of various block-level
1340 elements in one logical paragraph. First a table,
1341 \setlength{\DUtablewidth}{\linewidth}%
1342 \begin{longtable*
}{|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|p
{0.249\DUtablewidth}|
}
1364 followed by a paragraph. This physical paragraph is
1365 actually a continuation of the paragraph before the table. It is followed
1371 \item an enumerated list,
1374 \begin{DUoptionlist
}
1375 \item[-
{}-an
] option list,
1384 \item[{a definition
}]
1387 a paragraph, an image:
1388 \includegraphics{../../../docs/user/rst/images/biohazard.png
}
1390 \begin{DUlineblock
}{0em
}
1394 a paragraph followed by a comment,
1397 \begin{DUclass
}{note
}
1398 \begin{DUadmonition
}
1404 and the final paragraph of the compound
7.
1408 \subsubsection{2.14.9 Parsed Literal Blocks
%
1409 \label{parsed-literal-blocks
}%
1413 \ttfamily\raggedright
1414 This~is~a~parsed~literal~block.\\
1415 ~~~~This~line~is~indented.~~The~next~line~is~blank.\\
1417 Inline~markup~is~supported,~e.g.~
\emph{emphasis
},~
\textbf{strong
},~
\texttt{literal\\
1418 text
},~
\textsubscript{sub-
}~and~
\textsuperscript{super
}scripts,\\
1419 inline~formulas:~$A =
2 \pi r^
2$,\\
1420 footnotes
\DUfootnotemark{footnote-reference-
9}{footnote-
1}{1},~
%
1421 \phantomsection\label{hyperlink-targets
}hyperlink~targets,~and~
\href{http://www.python.org/
}{references
}.
1425 \subsubsection{2.14.10 Code
%
1429 Blocks of source code can be set with the
\DUroletitlereference{code
} directive. If the code
1430 language is specified, the content is parsed and tagged by the
\href{http://pygments.org/
}{Pygments
}\DUfootnotemark{footnote-reference-
13}{footnote-
7}{6}
1431 syntax highlighter and can be formatted with a style sheet. (Code parsing
1432 is turned off using the
\texttt{syntax-highlight
} config setting in the test
1433 conversions in order to get identical results with/without installed
1434 Pygments highlighter.)
1436 \begin{DUclass
}{code
}
1437 \begin{DUclass
}{python
}
1440 print 'This is Python code.'
1446 The
\texttt{:number-lines:
} option (with optional start value) generates line
1449 \begin{DUclass
}{code
}
1450 \begin{DUclass
}{python
}
1452 \ttfamily\raggedright
1453 \DUrole{ln
}{~
8~
}\#~print~integers~from~
0~to~
9:\\
1454 \DUrole{ln
}{~
9~
}for~i~in~range(
10):\\
1455 \DUrole{ln
}{10~
}~~~~print~i
1460 For inline code snippets, there is the
\DUroletitlereference{code
} role, which can be used
1461 directly (the code will not be parsed/tagged, as the language is not known)
1462 or as base for special code roles, e.g. the LaTeX code in the next
1465 Docutils uses LaTeX syntax for math directives and roles:
1466 \texttt{\DUrole{code
}{\DUrole{tex
}{\textbackslash{}alpha = f(x)
}}} prints $
\alpha = f(x)$.
1468 The
\texttt{:code:
} option of the
\DUroletitlereference{include
} directive sets the included content
1469 as a code block, here the rst file
\texttt{header
\_footer.txt
} with line numbers:
1471 \begin{DUclass
}{code
}
1472 \begin{DUclass
}{rst
}
1474 \ttfamily\raggedright
1475 \DUrole{ln
}{1~
}..~header::~Document~header\\
1476 \DUrole{ln
}{2~
}..~footer::~Document~footer
1482 \subsubsection{2.14.11 Meta
%
1486 The
\href{https://docutils.sourceforge.io/docs/ref/rst/directives.html\#metadata
}{“meta” directive
}\DUfootnotemark{footnote-reference-
19}{footnote-
11}{10} is used to specify metadata to be stored in,
1487 e.g., HTML META tags or ODT file properties.
1490 \subsection{2.15 Substitution Definitions
%
1491 \label{substitution-definitions
}%
1494 An inline image (
\includegraphics{../../../docs/user/rst/images/biohazard.png
}) example:
1498 (Substitution definitions are not visible in the HTML source.)
1501 \subsection{2.16 Comments
%
1507 % Comments begin with two dots and a space. Anything may
1508 % follow, except for the syntax of footnotes, hyperlink
1509 % targets, directives, or substitution definitions.
1511 % Double-dashes -- "--" -- must be escaped somehow in HTML output.
1513 % Comments may contain non-ASCII characters: ä ö ü æ ø å
1515 (View the HTML source to see the comment.)
1518 \subsection{2.17 Raw text
%
1522 This does not necessarily look nice, because there may be missing white space.
1524 It’s just there to freeze the behavior.
1530 \DUrole{myclass
}{Another test with myclass set.
}
1532 This is the
\DUrole{myrawroleclass
}{fourth test
} with myrawroleclass set.
1534 Fifth test in LaTeX.\
\Line two.
1537 \subsection{2.18 Container
%
1541 \begin{DUclass
}{custom
}
1547 % currently not implemented in LaTeX:
1548 % .. include:: data/header_footer.txt
1551 \subsection{2.19 Colspanning tables
%
1552 \label{colspanning-tables
}%
1555 This table has a cell spanning two columns:
1557 \setlength{\DUtablewidth}{\linewidth}%
1558 \begin{longtable*
}{|p
{0.075\DUtablewidth}|p
{0.075\DUtablewidth}|p
{0.086\DUtablewidth}|
}
1560 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1576 \multicolumn{2}{|p
{0.15\DUtablewidth}|
}{\textbf{%
1591 \multicolumn{3}{p
{0.24\DUtablewidth}}{\raggedleft\ldots continued on next page
}\\
1629 \subsection{2.20 Rowspanning tables
%
1630 \label{rowspanning-tables
}%
1633 Here’s a table with cells spanning several rows:
1635 \setlength{\DUtablewidth}{\linewidth}%
1636 \begin{longtable*
}{|p
{0.296\DUtablewidth}|p
{0.156\DUtablewidth}|p
{0.226\DUtablewidth}|
}
1639 Header row, column
1
1640 (header rows optional)
1650 Header row, column
1
1651 (header rows optional)
1659 \multicolumn{3}{p
{0.68\DUtablewidth}}{\raggedleft\ldots continued on next page
}\\
1663 body row
1, column
1
1672 &
\multirow{2}{0.16\DUtablewidth}{%
1675 } &
\multirow{2}{0.23\DUtablewidth}{%
1688 \subsection{2.21 List Tables
%
1689 \label{list-tables
}%
1692 Here’s a list table exercising all features:
1694 \begin{DUclass
}{test
}
1695 \setlength{\DUtablewidth}{0.950\linewidth}%
1696 \begin{longtable
}{|p
{0.133\DUtablewidth}|p
{0.110\DUtablewidth}|p
{0.249\DUtablewidth}|
}
1697 \caption{list table with integral header
}\\
1708 \caption[]{list table with integral header (... continued)
}\\
1719 \multicolumn{3}{p
{0.49\DUtablewidth}}{\raggedleft\ldots continued on next page
}\\
1735 If we took the bones out, it wouldn’t be
1736 crunchy, now would it?
1750 \begin{longtable
}[c
]{|l|l|
}
1751 \caption{center aligned list table
}\\
1755 Crunchy Frog &
1.49 \\
1757 Gannet Ripple &
1.99 \\
1762 \subsection{2.22 Custom Roles
%
1763 \label{custom-roles
}%
1767 \item A role based on an existing role.
1769 \texttt{\DUrole{custom
}{one
}} \texttt{\DUrole{custom
}{two
}} \texttt{\DUrole{custom
}{three
}}
1773 \DUrole{customnew
}{one two three
}
1775 \item A role with class attribute.
1777 \DUrole{special
}{interpreted text
}
1779 \item A language-switching role:
1781 Let’s count in German
\foreignlanguage{ngerman}{eins zwei drei
}.
1783 \item A role with multiple class attributes, styled with raw directives:
1785 \newcommand{\DUrolegreen}[1]{\textcolor{green
}{#1}}
1786 \newcommand{\DUrolesc}[1]{\textsc{#1}}
1788 The following works in most browsers but does not validate
1789 (
\texttt{<style>
} is only allowed in the
document head):
1795 <style type="text/css"><!-
{}-
1796 .green \
{color: green;\
}
1797 .sc \
{font-variant: small-caps;\
}
1802 \DUrole{green
}{\DUrole{sc
}{\foreignlanguage{british
}{British colourful text in small-caps
}}}.
1806 \subsection{2.23 Mathematics
%
1807 \label{mathematics
}%
1810 Docutils supports inline math with the prefix or postfix
\texttt{:math:
}
1811 role specificator, $n! +
\sin(x_n^
2)$ and $A_
\text{c
} =
1812 \frac{\pi}{4} d^
2$, as well as displayed math via the
1813 \DUroletitlereference{math
} directive:
1816 f(
\epsilon) =
\frac{1}{1 +
\exp\left(
\frac{\varepsilon}{k_
\text{B
}T
}\right)
}
1818 Content may start on the first line of the directive, e.g.
1821 N =
\frac{\text{number of apples
}}{7}
1823 Equations can be labeled with a reference name using the
\texttt{:name:
} option.
1824 See
\hyperref[eq-m
]{eq:M
} and
\hyperref[eq-schrodinger
]{eq:schrödinger
} below.
1826 The determinant of the matrix
1829 \mathbf{M
} =
\left(
\begin{matrix
}a&b\
\c&d
\end{matrix
}\right)
1832 is $|
\mathbf{M
}| = ad - bc$.
1834 More than one display math block can be put in one math directive.
1835 For example, the following sum and integral with limits:
1838 \int_0^
1 x^n dx =
\frac{1}{n +
1}
1841 \sum_{n=
1}^m n =
\frac{m(m+
1)
}{2}
1843 LaTeX-supported Unicode math symbols can be used in math roles and
1846 The Schrödinger equation
1849 i
\hbar \frac{\partial }{\partial t
}\Psi =
\hat{H
}\Psi ,
1850 \label{eq-schrodinger
}
1852 with the
\emph{wave function
} $
\Psi $, describes how the quantum state of a
1853 physical system changes in time.
1856 \item[{Math-Accents:
}] \leavevmode
1857 \setlength{\DUtablewidth}{1.000\linewidth}%
1858 \begin{longtable*
}{p
{0.315\DUtablewidth}p
{0.315\DUtablewidth}p
{0.315\DUtablewidth}}
1860 $
\acute{a
}$
\texttt{\textbackslash{}acute\
{a\
}}
1862 $
\dot{t
}$
\texttt{\textbackslash{}dot\
{t\
}}
1864 $
\hat{\gamma}$
\texttt{\textbackslash{}hat\
{\textbackslash{}gamma\
}}
1867 $
\grave{a
}$
\texttt{\textbackslash{}grave\
{a\
}}
1869 $
\ddot{t
}$
\texttt{\textbackslash{}ddot\
{t\
}}
1871 $
\tilde{\alpha}$
\texttt{\textbackslash{}tilde\
{\textbackslash{}alpha\
}}
1874 $
\breve{x
}$
\texttt{\textbackslash{}breve\
{x\
}}
1876 $
\dddot{t
}$
\texttt{\textbackslash{}dddot\
{t\
}}
1878 $
\vec{\imath}$
\texttt{\textbackslash{}vec\
{\textbackslash{}imath\
}}
1881 $
\check{a
}$
\texttt{\textbackslash{}check\
{a\
}}
1883 $
\bar{a
}$
\texttt{\textbackslash{}bar\
{a\
}}
1885 $
\vec{R
}$
\texttt{\textbackslash{}vec\
{R\
}}
1893 Modulation Transfer Function:
1896 \text{MTF
} =
\left|
\frac{\mathcal{F
}\
{s(x)\
}}
1897 {\mathcal{F
}\
{ s(x)\
} |_
{\omega _
{x
}=
0}}\right|
1898 =
\mathrm{abs
}\left(
\frac
1899 {\int _
{-
\infty }^
{\infty }s(x)
\mathrm{e
}^
{\mathrm{i
}\omega _
{x
}x
}\mathrm{d
}{x
}}
1900 {\int _
{-
\infty }^
{\infty }s(x)
\mathrm{d
}{x
}}
1903 Math split over two lines: If a double backslash is detected outside a
1904 \texttt{\textbackslash{}begin\
{...\
} \textbackslash{}end\
{...\
}} pair, the math code is wrapped in an
\href{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
}{AMSmath
}\DUfootnotemark{footnote-reference-
14}{footnote-
8}{7}
1905 \texttt{align
} environment:
1908 s_
{\mathrm{out
}}(x) & = s_
{\mathrm{in
}}(x') * s_
\delta (x-x') \\
1909 & =
\int s_
{\mathrm{in
}}(x')s_
\delta (x-x')
\mathrm{d
}x'
1911 Cases with the
\href{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
}{AMSmath
}\DUfootnotemark{footnote-reference-
15}{footnote-
8}{7} \texttt{cases
} environment:
1914 \mathrm{sgn
}(x) =
\begin{cases
}
1920 \section{3 Tests for the LaTeX writer
%
1921 \label{tests-for-the-latex-writer
}%
1924 Test syntax elements which may cause trouble for the LaTeX writer but might
1925 not need to be tested with other writers. See also the
1926 “latex
\_cornercases” test.
1929 \subsection{3.1 Custom Roles in LaTeX
%
1930 \label{custom-roles-in-latex
}%
1934 \item Role names and class arguments are converted to conform to the
1935 regular expression
\texttt{{[}a-z
{]}{[}-a-z0-
9{]}*
} (letters are downcased,
1936 accents and similar decoration is stripped, non-conforming
1937 characters are replaced by a hyphen).
1939 Class arguments may contain numbers and hyphens, which need special
1940 treatment in LaTeX command names.
1942 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{Text with role “custom4”
}}}}} (but without styling by
\texttt{DUrole*
}
1945 \item With LaTeX, roles can be styled within the
document using the
\DUroletitlereference{raw
}
1948 \newcommand{\DUrolelarge}[1]{{\large #1}}
1950 \@namedef
{DUrolesmall-caps
}{\textsc}
1951 \@namedef
{DUrolecustom4
}{\textbf}
1954 \DUrole{large
}{\DUrole{custom4
}{\DUrole{small-caps
}{\DUrole{custom-role
}{\DUrole{custom-role
}{inline text
}}}}} in large, bold, small-caps.
1956 \item Custom roles can be based on standard roles:
1958 This is a
\emph{\DUrole{custom-emphasis
}{customized emphasis text role
}}
1960 This is a
\texttt{\DUrole{custom-literal
}{customized literal text role
}}
1962 This is a
\textbf{\DUrole{custom-strong
}{customized strong text role
}}
1964 This is a
\textsubscript{\DUrole{custom-subscript
}{customized subscript text role
}}
1966 This is a
\textsuperscript{\DUrole{custom-superscript
}{customized superscript text role
}}
1968 This is a
\DUroletitlereference{\DUrole{custom-title-reference
}{customized title-reference text role
}}
1972 \subsection{3.2 class handling
%
1973 \label{class-handling
}%
1976 This section tests class handling for block level elements by the LaTeX
1977 writer. See the input file
\texttt{classes
\_latex.txt
} for the raw LaTeX code used
1978 to style the examples.
1980 An “epigraph” directive is exported as “quote” wrapped in a “DUclass”
1981 environment. Here, it is styled by a “DUCLASSepigraph” environment
1982 redefining the “quote” environment as “minipage”:
1984 \newcommand*
{\DUCLASSepigraph}{%
1985 \renewenvironment{quote
}{\vspace{1em
}
1986 \footnotesize\hfill{}%
1987 \begin{minipage
}{0.4\columnwidth}}%
1988 {\end{minipage
}\vskip\baselineskip}}
1990 \begin{DUclass
}{epigraph
}
1992 Do not play this piece fast. It is never right to play
\emph{Ragtime
} fast.
1995 \raggedleft —Scott Joplin
1999 Raw latex is also used to style the following lists: “DUCLASSenumerateitems”
2000 redefines “itemize” as “enumerate”, “DUCLASSrules” draws horizontal lines
2003 \newcommand*
{\DUCLASSenumerateitems}{%
2004 \renewenvironment{itemize
}{\begin{enumerate
}}%
2008 \newenvironment{DUCLASSrules
}%
2009 {\noindent\rule[0.5ex
]{1\columnwidth}{1pt
}}%
2010 {\noindent\rule[0.5ex
]{1\columnwidth}{1pt
}}
2012 An “enumerated” bullet list:
2014 \begin{DUclass
}{enumerateitems
}
2024 A list with lines above and below:
2026 \begin{DUclass
}{rules
}
2034 A normal bullet list is kept unchanged by the above redefinitions:
2044 A container wraps several elements in a common “class wrapper”. Here, we use
2045 it to set
2 paragraphs and a list in small caps:
2047 \newcommand*
{\DUCLASSscshape}{\scshape}
2049 \begin{DUclass
}{scshape
}
2057 \item still bullet list
2061 A right-aligned line-block. Alignment handling is built into the latex
2062 writer for image, table, and line block elements.
2064 \begin{DUlineblock
}{0em
}
2066 \item[] Max Mustermann
2068 \item[] D
01234 Testdorf
2069 \item[] Tel.:
0123/
456789
2072 % preface for System Messages:
2075 \section{4 Error Handling
%
2076 \label{error-handling
}%
2079 Any errors caught during processing will generate system messages.
2081 There should be five messages in the following, auto-generated
2082 section, “Docutils System Messages”:
2084 % section should be added by Docutils automatically
2087 \section[Docutils System Messages
]{\color{red
}Docutils System Messages
%
2090 \begin{DUclass
}{system-message
}
2091 \begin{DUadmonition
}
2092 \DUtitle{system-message
2093 \raisebox{1em
}{\hypertarget{system-message-
1}{}}}
2095 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
99
2097 \hyperlink{problematic-
1}{
2098 Undefined substitution referenced:
\textquotedbl{}problematic
\textquotedbl{}.
2102 \begin{DUclass
}{system-message
}
2103 \begin{DUadmonition
}
2104 \DUtitle{system-message
2105 \raisebox{1em
}{\hypertarget{system-message-
2}{}}}
2107 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
390
2109 \hyperlink{footnote-reference-
8}{
2110 Unknown target name:
\textquotedbl{}5\textquotedbl{}.
2114 \begin{DUclass
}{system-message
}
2115 \begin{DUadmonition
}
2116 \DUtitle{system-message
2117 \raisebox{1em
}{\hypertarget{system-message-
3}{}}}
2119 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
399
2121 \hyperlink{citation-reference-
3}{
2122 Unknown target name:
\textquotedbl{}nonexistent
\textquotedbl{}.
2126 \begin{DUclass
}{system-message
}
2127 \begin{DUadmonition
}
2128 \DUtitle{system-message
2129 \raisebox{1em
}{\hypertarget{system-message-
4}{}}}
2131 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
426
2133 \hyperlink{problematic-
2}{
2134 Unknown target name:
\textquotedbl{}hyperlink reference without a target
\textquotedbl{}.
2138 \begin{DUclass
}{system-message
}
2139 \begin{DUadmonition
}
2140 \DUtitle{system-message
2141 \raisebox{1em
}{\hypertarget{system-message-
5}{}}}
2143 {\color{red
}ERROR/
3} in
\texttt{functional/input/data/standard.txt
}, line~
439
2145 \hyperlink{problematic-
3}{
2146 Duplicate target name, cannot be used as a unique reference:
\textquotedbl{}duplicate target names
\textquotedbl{}.