|
|
\documentclass[a4paper]{article} |
|
|
% generated by Docutils <http://docutils.sourceforge.net/> |
|
|
\usepackage{cmap} % fix search and cut-and-paste in Acrobat |
|
|
\usepackage{ifthen} |
|
|
\usepackage[T1]{fontenc} |
|
|
\usepackage[utf8]{inputenc} |
|
|
\DeclareUnicodeCharacter{21D4}{\ensuremath{\Leftrightarrow}} |
|
|
\DeclareUnicodeCharacter{2660}{\ensuremath{\spadesuit}} |
|
|
\DeclareUnicodeCharacter{2663}{\ensuremath{\clubsuit}} |
|
|
\usepackage{amsmath} |
|
|
\usepackage[british,french,ngerman,english]{babel} |
|
|
% Prevent side-effects if French hyphenation patterns are not loaded: |
|
|
\frenchbsetup{StandardLayout} |
|
|
\AtBeginDocument{\selectlanguage{english}\noextrasfrench} |
|
|
\usepackage{color} |
|
|
\usepackage{float} % float configuration |
|
|
\floatplacement{figure}{H} % place figures here definitely |
|
|
\usepackage{graphicx} |
|
|
\usepackage{alltt} |
|
|
\usepackage{multirow} |
|
|
\usepackage{pifont} |
|
|
\setcounter{secnumdepth}{0} |
|
|
\usepackage{longtable,ltcaption,array} |
|
|
\setlength{\extrarowheight}{2pt} |
|
|
\newlength{\DUtablewidth} % internal use in tables |
|
|
\usepackage{tabularx} |
|
|
\usepackage{textcomp} % text symbol macros |
|
|
|
|
|
%%% Custom LaTeX preamble |
|
|
% PDF Standard Fonts |
|
|
\usepackage{mathptmx} % Times |
|
|
\usepackage[scaled=.90]{helvet} |
|
|
\usepackage{courier} |
|
|
|
|
|
%%% User specified packages and stylesheets |
|
|
|
|
|
%%% Fallback definitions for Docutils-specific commands |
|
|
|
|
|
% class handling for environments (block-level elements) |
|
|
% \begin{DUclass}{spam} tries \DUCLASSspam and |
|
|
% \end{DUclass}{spam} tries \endDUCLASSspam |
|
|
\ifx\DUclass\undefined % poor man's "provideenvironment" |
|
|
\newenvironment{DUclass}[1]% |
|
|
{\def\DocutilsClassFunctionName{DUCLASS#1}% arg cannot be used in end-part of environment. |
|
|
\csname \DocutilsClassFunctionName \endcsname}% |
|
|
{\csname end\DocutilsClassFunctionName \endcsname}% |
|
|
\fi |
|
|
|
|
|
% providelength (provide a length variable and set default, if it is new) |
|
|
\providecommand*{\DUprovidelength}[2]{ |
|
|
\ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{} |
|
|
} |
|
|
|
|
|
% abstract title |
|
|
\providecommand*{\DUtitleabstract}[1]{\centerline{\textbf{#1}}} |
|
|
|
|
|
% admonition (specially marked topic) |
|
|
\providecommand{\DUadmonition}[2][class-arg]{% |
|
|
% try \DUadmonition#1{#2}: |
|
|
\ifcsname DUadmonition#1\endcsname% |
|
|
\csname DUadmonition#1\endcsname{#2}% |
|
|
\else |
|
|
\begin{center} |
|
|
\fbox{\parbox{0.9\linewidth}{#2}} |
|
|
\end{center} |
|
|
\fi |
|
|
} |
|
|
|
|
|
% dedication topic |
|
|
\providecommand*{\DUCLASSdedication}{% |
|
|
\renewenvironment{quote}{\begin{center}}{\end{center}}% |
|
|
} |
|
|
|
|
|
% docinfo (width of docinfo table) |
|
|
\DUprovidelength{\DUdocinfowidth}{0.9\linewidth} |
|
|
|
|
|
% subtitle (in document title) |
|
|
\providecommand*{\DUdocumentsubtitle}[1]{{\large #1}} |
|
|
\newcounter{enumv} |
|
|
|
|
|
% error admonition title |
|
|
\providecommand*{\DUtitleerror}[1]{\DUtitle{\color{red}#1}} |
|
|
|
|
|
% fieldlist environment |
|
|
\ifthenelse{\isundefined{\DUfieldlist}}{ |
|
|
\newenvironment{DUfieldlist}% |
|
|
{\quote\description} |
|
|
{\enddescription\endquote} |
|
|
}{} |
|
|
% numeric or symbol footnotes with hyperlinks |
|
|
\providecommand*{\DUfootnotemark}[3]{% |
|
|
\raisebox{1em}{\hypertarget{#1}{}}% |
|
|
\hyperlink{#2}{\textsuperscript{#3}}% |
|
|
} |
|
|
\providecommand{\DUfootnotetext}[4]{% |
|
|
\begingroup% |
|
|
\renewcommand{\thefootnote}{% |
|
|
\protect\raisebox{1em}{\protect\hypertarget{#1}{}}% |
|
|
\protect\hyperlink{#2}{#3}}% |
|
|
\footnotetext{#4}% |
|
|
\endgroup% |
|
|
} |
|
|
|
|
|
% inline markup (custom roles) |
|
|
% \DUrole{#1}{#2} tries \DUrole#1{#2} |
|
|
\providecommand*{\DUrole}[2]{% |
|
|
% backwards compatibility: try \docutilsrole#1{#2} |
|
|
\ifcsname docutilsrole#1\endcsname% |
|
|
\csname docutilsrole#1\endcsname{#2}% |
|
|
\else |
|
|
\csname DUrole#1\endcsname{#2}% |
|
|
\fi% |
|
|
} |
|
|
|
|
|
% legend environment |
|
|
\ifthenelse{\isundefined{\DUlegend}}{ |
|
|
\newenvironment{DUlegend}{\small}{} |
|
|
}{} |
|
|
|
|
|
% lineblock environment |
|
|
\DUprovidelength{\DUlineblockindent}{2.5em} |
|
|
\ifthenelse{\isundefined{\DUlineblock}}{ |
|
|
\newenvironment{DUlineblock}[1]{% |
|
|
\list{}{\setlength{\partopsep}{\parskip} |
|
|
\addtolength{\partopsep}{\baselineskip} |
|
|
\setlength{\topsep}{0pt} |
|
|
\setlength{\itemsep}{0.15\baselineskip} |
|
|
\setlength{\parsep}{0pt} |
|
|
\setlength{\leftmargin}{#1}} |
|
|
\raggedright |
|
|
} |
|
|
{\endlist} |
|
|
}{} |
|
|
|
|
|
% optionlist environment |
|
|
\providecommand*{\DUoptionlistlabel}[1]{\bf #1 \hfill} |
|
|
\DUprovidelength{\DUoptionlistindent}{3cm} |
|
|
\ifthenelse{\isundefined{\DUoptionlist}}{ |
|
|
\newenvironment{DUoptionlist}{% |
|
|
\list{}{\setlength{\labelwidth}{\DUoptionlistindent} |
|
|
\setlength{\rightmargin}{1cm} |
|
|
\setlength{\leftmargin}{\rightmargin} |
|
|
\addtolength{\leftmargin}{\labelwidth} |
|
|
\addtolength{\leftmargin}{\labelsep} |
|
|
\renewcommand{\makelabel}{\DUoptionlistlabel}} |
|
|
} |
|
|
{\endlist} |
|
|
}{} |
|
|
|
|
|
% rubric (informal heading) |
|
|
\providecommand*{\DUrubric}[1]{% |
|
|
\subsubsection*{\centering\textit{\textmd{#1}}}} |
|
|
|
|
|
% sidebar (text outside the main text flow) |
|
|
\providecommand{\DUsidebar}[1]{% |
|
|
\begin{center} |
|
|
\colorbox[gray]{0.80}{\parbox{0.9\linewidth}{#1}} |
|
|
\end{center} |
|
|
} |
|
|
|
|
|
% subtitle (for topic/sidebar) |
|
|
\providecommand*{\DUsubtitle}[1]{\par\emph{#1}\smallskip} |
|
|
|
|
|
% text mode subscript |
|
|
\ifx\textsubscript\undefined |
|
|
\usepackage{fixltx2e} % since 2015 loaded by default |
|
|
\fi |
|
|
|
|
|
% title for topics, admonitions, unsupported section levels, and sidebar |
|
|
\providecommand*{\DUtitle}[2][class-arg]{% |
|
|
% call \DUtitle#1{#2} if it exists: |
|
|
\ifcsname DUtitle#1\endcsname% |
|
|
\csname DUtitle#1\endcsname{#2}% |
|
|
\else |
|
|
\smallskip\noindent\textbf{#2}\smallskip% |
|
|
\fi |
|
|
} |
|
|
|
|
|
% titlereference role |
|
|
\providecommand*{\DUroletitlereference}[1]{\textsl{#1}} |
|
|
|
|
|
% transition (break, fancybreak, anonymous section) |
|
|
\providecommand*{\DUtransition}{% |
|
|
\hspace*{\fill}\hrulefill\hspace*{\fill} |
|
|
\vskip 0.5\baselineskip |
|
|
} |
|
|
|
|
|
% hyperlinks: |
|
|
\ifthenelse{\isundefined{\hypersetup}}{ |
|
|
\usepackage[colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref} |
|
|
\usepackage{bookmark} |
|
|
\urlstyle{same} % normal text font (alternatives: tt, rm, sf) |
|
|
}{} |
|
|
\hypersetup{ |
|
|
pdftitle={reStructuredText Test Document}, |
|
|
pdfauthor={David Goodger;Me;Myself;I} |
|
|
} |
|
|
|
|
|
%%% Title Data |
|
|
\title{\phantomsection% |
|
|
reStructuredText Test Document% |
|
|
\label{restructuredtext-test-document}% |
|
|
\label{doctitle}% |
|
|
\\ % subtitle% |
|
|
\DUdocumentsubtitle{Examples of Syntax Constructs}% |
|
|
\label{examples-of-syntax-constructs}% |
|
|
\label{subtitle}} |
|
|
\author{} |
|
|
\date{} |
|
|
|
|
|
%%% Body |
|
|
\begin{document} |
|
|
\maketitle |
|
|
|
|
|
% Docinfo |
|
|
\begin{center} |
|
|
\begin{tabularx}{\DUdocinfowidth}{lX} |
|
|
\textbf{Author}: & |
|
|
David Goodger \\ |
|
|
\textbf{Address}: & |
|
|
{\raggedright |
|
|
123 Example Street\\ |
|
|
Example, EX Canada\\ |
|
|
A1B 2C3 } \\ |
|
|
\textbf{Contact}: & |
|
|
\href{mailto:goodger@python.org}{goodger@python.org} \\ |
|
|
\textbf{Author}: & |
|
|
Me \\ |
|
|
\textbf{Author}: & |
|
|
Myself \\ |
|
|
\textbf{Author}: & |
|
|
I \\ |
|
|
\textbf{Organization}: & |
|
|
humankind \\ |
|
|
\textbf{Date}: & |
|
|
Now, or yesterday. Or maybe even \emph{before} yesterday. \\ |
|
|
\textbf{Status}: & |
|
|
This is a “work in progress” \\ |
|
|
\textbf{Revision}: & |
|
|
is managed by a version control system. \\ |
|
|
\textbf{Version}: & |
|
|
1 \\ |
|
|
\textbf{Copyright}: & |
|
|
This document has been placed in the public domain. You |
|
|
may do with it as you wish. You may copy, modify, |
|
|
redistribute, reattribute, sell, buy, rent, lease, |
|
|
destroy, or improve it, quote it at length, excerpt, |
|
|
incorporate, collate, fold, staple, or mutilate it, or do |
|
|
anything else to it that your or anyone else’s heart |
|
|
desires. \\ |
|
|
\textbf{field name}: & |
|
|
This is a “generic bibliographic field”. |
|
|
\\ |
|
|
\textbf{field name “2”}: & |
|
|
Generic bibliographic fields may contain multiple body elements. |
|
|
|
|
|
Like this. |
|
|
\\ |
|
|
\end{tabularx} |
|
|
\end{center} |
|
|
|
|
|
\begin{DUclass}{dedication} |
|
|
\begin{quote} |
|
|
\DUtitle[dedication]{Dedication} |
|
|
|
|
|
For Docutils users \& co-developers. |
|
|
\end{quote} |
|
|
\end{DUclass} |
|
|
|
|
|
\begin{DUclass}{abstract} |
|
|
\begin{quote} |
|
|
\DUtitle[abstract]{Abstract} |
|
|
|
|
|
This is a test document, containing at least one example of each |
|
|
reStructuredText construct. |
|
|
\end{quote} |
|
|
\end{DUclass} |
|
|
|
|
|
% This is a comment. Note how any initial comments are moved by |
|
|
% transforms to after the document title, subtitle, and docinfo. |
|
|
|
|
|
% Above is the document title, and below is the subtitle. |
|
|
% They are transformed from section titles after parsing. |
|
|
|
|
|
% bibliographic fields (which also require a transform): |
|
|
|
|
|
\pagebreak[4] % start ToC on new page |
|
|
|
|
|
\phantomsection\label{table-of-contents} |
|
|
\pdfbookmark[1]{Table of Contents}{table-of-contents} |
|
|
\renewcommand{\contentsname}{Table of Contents} |
|
|
\tableofcontents |
|
|
|
|
|
|
|
|
\section{1 Structural Elements% |
|
|
\label{structural-elements}% |
|
|
} |
|
|
|
|
|
|
|
|
\subsection{1.1 Section Title% |
|
|
\label{section-title}% |
|
|
} |
|
|
\subsubsection*{Section Subtitle} |
|
|
|
|
|
Lone subsections are converted to a section subtitle by a transform |
|
|
activated with the \texttt{-{}-section-subtitles} command line option or the |
|
|
\texttt{sectsubtitle-xform} configuration value. |
|
|
|
|
|
|
|
|
\subsection{1.2 Empty Section% |
|
|
\label{empty-section}% |
|
|
} |
|
|
|
|
|
|
|
|
\subsection{1.3 Transitions% |
|
|
\label{transitions}% |
|
|
} |
|
|
|
|
|
Here’s a transition: |
|
|
|
|
|
%___________________________________________________________________________ |
|
|
\DUtransition |
|
|
|
|
|
It divides the section. Transitions may also occur between sections: |
|
|
|
|
|
%___________________________________________________________________________ |
|
|
\DUtransition |
|
|
|
|
|
|
|
|
\section{2 Body Elements% |
|
|
\label{body-elements}% |
|
|
} |
|
|
|
|
|
|
|
|
\subsection{2.1 Paragraphs% |
|
|
\label{paragraphs}% |
|
|
} |
|
|
|
|
|
A paragraph. |
|
|
|
|
|
|
|
|
\subsubsection{2.1.1 Inline Markup% |
|
|
\label{inline-markup}% |
|
|
} |
|
|
|
|
|
Paragraphs contain text and may contain inline markup: \emph{emphasis}, |
|
|
\textbf{strong emphasis}, \texttt{inline literals}, standalone hyperlinks |
|
|
(\url{http://www.python.org}), external hyperlinks (\href{http://www.python.org/}{Python}\DUfootnotemark{id30}{id29}{5}), internal |
|
|
cross-references (\hyperref[example]{example}), external hyperlinks with embedded URIs |
|
|
(\href{http://www.python.org}{Python web site}), \href{http://www.python.org/}{anonymous hyperlink |
|
|
references}\DUfootnotemark{id38}{id29}{5} (\href{http://docutils.sourceforge.net/}{a second reference}\DUfootnotemark{id40}{id39}{8}), footnote references (manually |
|
|
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]}), |
|
|
substitution references (\includegraphics{../../../docs/user/rst/images/biohazard.png}), and % |
|
|
\phantomsection\label{inline-hyperlink-targets}inline hyperlink targets |
|
|
(see \hyperref[targets]{Targets} below for a reference back to here). Character-level |
|
|
inline markup is also possible (although exceedingly ugly!) in \emph{re}\texttt{Structured}\emph{Text}. Problems are indicated by % |
|
|
\raisebox{1em}{\hypertarget{id28}{}}\hyperlink{id27}{\textbf{\color{red}|problematic|}} text |
|
|
(generated by processing errors; this one is intentional). Here is a |
|
|
reference to the \hyperref[doctitle]{doctitle} and the \hyperref[subtitle]{subtitle}. |
|
|
|
|
|
The default role for interpreted text is \DUroletitlereference{Title Reference}. Here are |
|
|
some explicit interpreted text roles: a PEP reference (\href{http://www.python.org/dev/peps/pep-0287}{PEP 287}); an |
|
|
RFC reference (\href{http://tools.ietf.org/html/rfc2822.html}{RFC 2822}); an abbreviation (\DUrole{abbreviation}{abb.}), an acronym |
|
|
(\DUrole{acronym}{reST}), code (\texttt{\DUrole{code}{print \textquotedbl{}hello world\textquotedbl{}}}); a \textsubscript{subscript}; |
|
|
a \textsuperscript{superscript} and explicit roles for \DUroletitlereference{Docutils}’ |
|
|
\emph{standard} \textbf{inline} \texttt{markup}. |
|
|
|
|
|
% DO NOT RE-WRAP THE FOLLOWING PARAGRAPH! |
|
|
|
|
|
Let’s test wrapping and whitespace significance in inline literals: |
|
|
\texttt{This is an example of -{}-inline-literal -{}-text, -{}-including some-{}- |
|
|
strangely-{}-hyphenated-words. ~Adjust-the-width-of-your-browser-window |
|
|
to see how the text is wrapped. ~-{}- -{}-{}-{}- -{}-{}-{}-{}-{}-{}-{}- ~Now note ~ ~the |
|
|
spacing ~ ~between the ~ ~words of ~ ~this sentence ~ ~(words |
|
|
should ~ ~be grouped ~ ~in pairs).} |
|
|
|
|
|
If the \texttt{-{}-pep-references} option was supplied, there should be a |
|
|
live link to PEP 258 here. |
|
|
|
|
|
|
|
|
\subsection{2.2 Bullet Lists% |
|
|
\label{bullet-lists}% |
|
|
} |
|
|
|
|
|
\begin{itemize} |
|
|
\item A bullet list |
|
|
|
|
|
\begin{itemize} |
|
|
\item Nested bullet list. |
|
|
|
|
|
\item Nested item 2. |
|
|
\end{itemize} |
|
|
|
|
|
\item Item 2. |
|
|
|
|
|
Paragraph 2 of item 2. |
|
|
|
|
|
\begin{itemize} |
|
|
\item Nested bullet list. |
|
|
|
|
|
\item Nested item 2. |
|
|
|
|
|
\begin{itemize} |
|
|
\item Third level. |
|
|
|
|
|
\item Item 2. |
|
|
\end{itemize} |
|
|
|
|
|
\item Nested item 3. |
|
|
|
|
|
\item This nested list should be compacted by the HTML writer. |
|
|
% |
|
|
\phantomsection\label{target} |
|
|
% Even if this item contains a target and a comment. |
|
|
\end{itemize} |
|
|
\end{itemize} |
|
|
|
|
|
|
|
|
\subsection{2.3 Enumerated Lists% |
|
|
\label{enumerated-lists}% |
|
|
} |
|
|
|
|
|
\begin{enumerate} |
|
|
\item Arabic numerals. |
|
|
|
|
|
\begin{enumerate} |
|
|
\renewcommand{\labelenumii}{\alph{enumii})} |
|
|
\item lower alpha) |
|
|
|
|
|
\begin{enumerate} |
|
|
\renewcommand{\labelenumiii}{(\roman{enumiii})} |
|
|
\item (lower roman) |
|
|
|
|
|
\begin{enumerate} |
|
|
\item upper alpha. |
|
|
|
|
|
\begin{list}{\Roman{enumv})}{\usecounter{enumv}} |
|
|
\item upper roman) |
|
|
\end{list} |
|
|
\end{enumerate} |
|
|
\end{enumerate} |
|
|
\end{enumerate} |
|
|
|
|
|
\item Lists that don’t start at 1: |
|
|
|
|
|
\begin{enumerate} |
|
|
\renewcommand{\labelenumii}{\arabic{enumii}.} |
|
|
\setcounter{enumii}{2} |
|
|
\item Three |
|
|
|
|
|
\item Four |
|
|
\end{enumerate} |
|
|
|
|
|
\begin{enumerate} |
|
|
\renewcommand{\labelenumii}{\Alph{enumii}.} |
|
|
\setcounter{enumii}{2} |
|
|
\item C |
|
|
|
|
|
\item D |
|
|
\end{enumerate} |
|
|
|
|
|
\begin{enumerate} |
|
|
\renewcommand{\labelenumii}{\roman{enumii}.} |
|
|
\setcounter{enumii}{2} |
|
|
\item iii |
|
|
|
|
|
\item iv |
|
|
\end{enumerate} |
|
|
\end{enumerate} |
|
|
|
|
|
|
|
|
\subsection{2.4 Definition Lists% |
|
|
\label{definition-lists}% |
|
|
} |
|
|
|
|
|
\begin{description} |
|
|
\item[{Term}] \leavevmode |
|
|
Definition |
|
|
|
|
|
\item[{Term}] \leavevmode (\textbf{classifier}) |
|
|
Definition paragraph 1. |
|
|
|
|
|
Definition paragraph 2. |
|
|
|
|
|
\item[{Term}] \leavevmode |
|
|
Definition |
|
|
|
|
|
\item[{Term}] \leavevmode (\textbf{classifier one})(\textbf{classifier two}) |
|
|
Definition |
|
|
|
|
|
\end{description} |
|
|
|
|
|
|
|
|
\subsection{2.5 Field Lists% |
|
|
\label{field-lists}% |
|
|
} |
|
|
|
|
|
\begin{DUfieldlist} |
|
|
\item[{what:}] |
|
|
Field lists map field names to field bodies, like database |
|
|
records. They are often part of an extension syntax. They are |
|
|
an unambiguous variant of RFC 2822 fields. |
|
|
|
|
|
\item[{how arg1 arg2:}] |
|
|
The field marker is a colon, the field name, and a colon. |
|
|
|
|
|
The field body may contain one or more body elements, indented |
|
|
relative to the field marker. |
|
|
|
|
|
\item[{credits:}] |
|
|
\DUrole{credits}{This paragraph has the \DUroletitlereference{credits} class set. (This is actually not |
|
|
about credits but just for ensuring that the class attribute |
|
|
doesn’t get stripped away.)} |
|
|
\end{DUfieldlist} |
|
|
|
|
|
|
|
|
\subsection{2.6 Option Lists% |
|
|
\label{option-lists}% |
|
|
} |
|
|
|
|
|
For listing command-line options: |
|
|
|
|
|
\begin{DUoptionlist} |
|
|
\item[-a] command-line option “a” |
|
|
|
|
|
\item[-b file] options can have arguments |
|
|
and long descriptions |
|
|
|
|
|
\item[-{}-long] options can be long also |
|
|
|
|
|
\item[-{}-input=file] long options can also have |
|
|
arguments |
|
|
|
|
|
\item[-{}-very-long-option] The description can also start on the next line. |
|
|
|
|
|
The description may contain multiple body elements, |
|
|
regardless of where it starts. |
|
|
|
|
|
\item[-x, -y, -z] Multiple options are an “option group”. |
|
|
|
|
|
\item[-v, -{}-verbose] Commonly-seen: short \& long options. |
|
|
|
|
|
\item[-1 file, -{}-one=file, -{}-two file] Multiple options with arguments. |
|
|
|
|
|
\item[/V] DOS/VMS-style options too |
|
|
\end{DUoptionlist} |
|
|
|
|
|
There must be at least two spaces between the option and the |
|
|
description. |
|
|
|
|
|
|
|
|
\subsection{2.7 Literal Blocks% |
|
|
\label{literal-blocks}% |
|
|
} |
|
|
|
|
|
Literal blocks are indicated with a double-colon (“::”) at the end of |
|
|
the preceding paragraph (over there \texttt{-{}->}). They can be indented: |
|
|
|
|
|
\begin{quote} |
|
|
\begin{alltt} |
|
|
if literal_block: |
|
|
text = 'is left as-is' |
|
|
spaces_and_linebreaks = 'are preserved' |
|
|
markup_processing = None |
|
|
\end{alltt} |
|
|
\end{quote} |
|
|
|
|
|
Or they can be quoted without indentation: |
|
|
|
|
|
\begin{quote} |
|
|
\begin{alltt} |
|
|
>> Great idea! |
|
|
> |
|
|
> Why didn't I think of that? |
|
|
\end{alltt} |
|
|
\end{quote} |
|
|
|
|
|
|
|
|
\subsection{2.8 Line Blocks% |
|
|
\label{line-blocks}% |
|
|
} |
|
|
|
|
|
This section tests line blocks. Line blocks are body elements which |
|
|
consist of lines and other line blocks. Nested line blocks cause |
|
|
indentation. |
|
|
|
|
|
\begin{DUlineblock}{0em} |
|
|
\item[] This is a line block. It ends with a blank line. |
|
|
\item[] |
|
|
\begin{DUlineblock}{\DUlineblockindent} |
|
|
\item[] New lines begin with a vertical bar (“|”). |
|
|
\item[] Line breaks and initial indent are significant, and preserved. |
|
|
\item[] |
|
|
\begin{DUlineblock}{\DUlineblockindent} |
|
|
\item[] Continuation lines are also possible. A long line that is intended |
|
|
to wrap should begin with a space in place of the vertical bar. |
|
|
\end{DUlineblock} |
|
|
\item[] The left edge of a continuation line need not be aligned with |
|
|
the left edge of the text above it. |
|
|
\end{DUlineblock} |
|
|
\end{DUlineblock} |
|
|
|
|
|
\begin{DUlineblock}{0em} |
|
|
\item[] This is a second line block. |
|
|
\item[] |
|
|
\item[] Blank lines are permitted internally, but they must begin with a “|”. |
|
|
\end{DUlineblock} |
|
|
|
|
|
Another line block, surrounded by paragraphs: |
|
|
|
|
|
\begin{DUlineblock}{0em} |
|
|
\item[] And it’s no good waiting by the window |
|
|
\item[] It’s no good waiting for the sun |
|
|
\item[] Please believe me, the things you dream of |
|
|
\item[] They don’t fall in the lap of no-one |
|
|
\end{DUlineblock} |
|
|
|
|
|
Take it away, Eric the Orchestra Leader! |
|
|
|
|
|
\begin{quote} |
|
|
\begin{DUlineblock}{0em} |
|
|
\item[] A one, two, a one two three four |
|
|
\item[] |
|
|
\item[] Half a bee, philosophically, |
|
|
\item[] |
|
|
\begin{DUlineblock}{\DUlineblockindent} |
|
|
\item[] must, \emph{ipso facto}, half not be. |
|
|
\end{DUlineblock} |
|
|
\item[] But half the bee has got to be, |
|
|
\item[] |
|
|
\begin{DUlineblock}{\DUlineblockindent} |
|
|
\item[] \emph{vis a vis} its entity. D’you see? |
|
|
\item[] |
|
|
\end{DUlineblock} |
|
|
\item[] But can a bee be said to be |
|
|
\item[] |
|
|
\begin{DUlineblock}{\DUlineblockindent} |
|
|
\item[] or not to be an entire bee, |
|
|
\item[] |
|
|
\begin{DUlineblock}{\DUlineblockindent} |
|
|
\item[] when half the bee is not a bee, |
|
|
\item[] |
|
|
\begin{DUlineblock}{\DUlineblockindent} |
|
|
\item[] due to some ancient injury? |
|
|
\item[] |
|
|
\end{DUlineblock} |
|
|
\end{DUlineblock} |
|
|
\end{DUlineblock} |
|
|
\item[] Singing… |
|
|
\end{DUlineblock} |
|
|
\end{quote} |
|
|
|
|
|
A line block, like the following poem by Christian Morgenstern, can |
|
|
also be centre-aligned: |
|
|
|
|
|
\begin{selectlanguage}{ngerman} |
|
|
\begin{DUlineblock}{0em} |
|
|
\centering |
|
|
\item[] \textbf{Die Trichter} |
|
|
\item[] |
|
|
\item[] Zwei Trichter wandeln durch die Nacht. |
|
|
\item[] Durch ihres Rumpfs verengten Schacht |
|
|
\item[] fließt weißes Mondlicht |
|
|
\item[] still und heiter |
|
|
\item[] auf ihren |
|
|
\item[] Waldweg |
|
|
\item[] u. s. |
|
|
\item[] w. |
|
|
\item[] |
|
|
\end{DUlineblock} |
|
|
\end{selectlanguage} |
|
|
|
|
|
|
|
|
\subsection{2.9 Block Quotes% |
|
|
\label{block-quotes}% |
|
|
} |
|
|
|
|
|
Block quotes consist of indented body elements: |
|
|
|
|
|
\begin{quote} |
|
|
My theory by A. Elk. Brackets Miss, brackets. This theory goes |
|
|
as follows and begins now. All brontosauruses are thin at one |
|
|
end, much much thicker in the middle and then thin again at the |
|
|
far end. That is my theory, it is mine, and belongs to me and I |
|
|
own it, and what it is too. |
|
|
\nopagebreak |
|
|
|
|
|
\raggedleft —Anne Elk (Miss) |
|
|
\end{quote} |
|
|
|
|
|
The language of a quote (like any other object) can be specified by |
|
|
a class attribute: |
|
|
|
|
|
% |
|
|
|
|
|
\begin{selectlanguage}{french} |
|
|
\begin{quote} |
|
|
ReStructuredText est un langage de balisage léger utilisé |
|
|
notamment dans la documentation du langage Python. |
|
|
\end{quote} |
|
|
\end{selectlanguage} |
|
|
|
|
|
|
|
|
\subsection{2.10 Doctest Blocks% |
|
|
\label{doctest-blocks}% |
|
|
} |
|
|
|
|
|
\begin{quote} |
|
|
\begin{alltt} |
|
|
>>> print 'Python-specific usage examples; begun with ">>>"' |
|
|
Python-specific usage examples; begun with ">>>" |
|
|
>>> print '(cut and pasted from interactive Python sessions)' |
|
|
(cut and pasted from interactive Python sessions) |
|
|
\end{alltt} |
|
|
\end{quote} |
|
|
|
|
|
|
|
|
\subsection{2.11 Footnotes% |
|
|
\label{footnotes}% |
|
|
} |
|
|
% |
|
|
\DUfootnotetext{id8}{id1}{1}{% |
|
|
A footnote contains body elements, consistently indented by at |
|
|
least 3 spaces. |
|
|
|
|
|
This is the footnote’s second paragraph. |
|
|
} |
|
|
% |
|
|
\DUfootnotetext{label}{id3}{2}{\phantomsection\label{label}% |
|
|
Footnotes may be numbered, either manually (as in\DUfootnotemark{id9}{id8}{1}) or |
|
|
automatically using a “\#”-prefixed label. This footnote has a |
|
|
label so it can be referred to from multiple places, both as a |
|
|
footnote reference (\DUfootnotemark{id10}{label}{2}) and as a \hyperref[label]{hyperlink reference}. |
|
|
} |
|
|
% |
|
|
\DUfootnotetext{id12}{id2}{3}{% |
|
|
This footnote is numbered automatically and anonymously using a |
|
|
label of “\#” only. |
|
|
|
|
|
This is the second paragraph. |
|
|
|
|
|
And this is the third paragraph. |
|
|
} |
|
|
% |
|
|
\DUfootnotetext{id13}{id4}{*}{% |
|
|
Footnotes may also use symbols, specified with a “*” label. |
|
|
Here’s a reference to the next footnote:\DUfootnotemark{id14}{id15}{†}. |
|
|
} |
|
|
% |
|
|
\DUfootnotetext{id15}{id14}{†}{% |
|
|
This footnote shows the next symbol in the sequence. |
|
|
} |
|
|
% |
|
|
\DUfootnotetext{id16}{id16}{4}{% |
|
|
Here’s an unreferenced footnote, with a reference to a |
|
|
nonexistent footnote:% |
|
|
\raisebox{1em}{\hypertarget{id17}{}}\hyperlink{id45}{\textbf{\color{red}{[}5{]}\_}}. |
|
|
} |
|
|
|
|
|
|
|
|
\subsection{2.12 Citations% |
|
|
\label{citations}% |
|
|
} |
|
|
\begin{figure}[b]\raisebox{1em}{\hypertarget{cit2002}{}}[CIT2002] |
|
|
Citations are text-labeled footnotes. They may be |
|
|
rendered separately and differently from footnotes. |
|
|
\end{figure} |
|
|
|
|
|
Here’s a reference to the above, \hyperlink{cit2002}{[CIT2002]}, and a % |
|
|
\raisebox{1em}{\hypertarget{id19}{}}\hyperlink{id46}{\textbf{\color{red}{[}nonexistent{]}\_}} |
|
|
citation. |
|
|
|
|
|
|
|
|
\subsection{2.13 Targets% |
|
|
\label{targets}% |
|
|
\label{another-target}% |
|
|
} |
|
|
|
|
|
\phantomsection\label{example} |
|
|
This paragraph is pointed to by the explicit “example” target. A |
|
|
reference can be found under \hyperref[inline-markup]{Inline Markup}, above. \hyperref[inline-hyperlink-targets]{Inline |
|
|
hyperlink targets} are also possible. |
|
|
|
|
|
Section headers are implicit targets, referred to by name. See |
|
|
\hyperref[targets]{Targets}, which is a subsection of \hyperref[body-elements]{Body Elements}. |
|
|
|
|
|
Explicit external targets are interpolated into references such as |
|
|
“\href{http://www.python.org/}{Python}\DUfootnotemark{id31}{id29}{5}”. |
|
|
|
|
|
Targets may be indirect and anonymous. Thus \hyperref[targets]{this phrase} may also |
|
|
refer to the \hyperref[targets]{Targets} section. |
|
|
|
|
|
Here’s a % |
|
|
\raisebox{1em}{\hypertarget{id48}{}}\hyperlink{id47}{\textbf{\color{red}`hyperlink reference without a target`\_}}, which generates an |
|
|
error. |
|
|
|
|
|
|
|
|
\subsubsection{2.13.1 Duplicate Target Names% |
|
|
\label{duplicate-target-names}% |
|
|
} |
|
|
|
|
|
Duplicate names in section headers or other implicit targets will |
|
|
generate “info” (level-1) system messages. Duplicate names in |
|
|
explicit targets will generate “warning” (level-2) system messages. |
|
|
|
|
|
|
|
|
\subsubsection{2.13.2 Duplicate Target Names% |
|
|
\label{id21}% |
|
|
} |
|
|
|
|
|
Since there are two “Duplicate Target Names” section headers, we |
|
|
cannot uniquely refer to either of them by name. If we try to (like |
|
|
this: % |
|
|
\raisebox{1em}{\hypertarget{id50}{}}\hyperlink{id49}{\textbf{\color{red}`Duplicate Target Names`\_}}), an error is generated. |
|
|
|
|
|
|
|
|
\subsection{2.14 Directives% |
|
|
\label{directives}% |
|
|
} |
|
|
|
|
|
\phantomsection\label{contents} |
|
|
These are just a sample of the many reStructuredText Directives. For |
|
|
others, please see |
|
|
\url{http://docutils.sourceforge.net/docs/ref/rst/directives.html}. |
|
|
|
|
|
|
|
|
\subsubsection{2.14.1 Document Parts% |
|
|
\label{document-parts}% |
|
|
} |
|
|
|
|
|
An example of the “contents” directive can be seen above this section |
|
|
(a local, untitled table of \hyperref[contents]{contents}) and at the beginning of the |
|
|
document (a document-wide \hyperref[table-of-contents]{table of contents}). |
|
|
|
|
|
|
|
|
\subsubsection{2.14.2 Images and Figures% |
|
|
\label{images-and-figures}% |
|
|
} |
|
|
|
|
|
An image directive (also clickable – a hyperlink reference): |
|
|
|
|
|
\hyperref[directives]{\includegraphics{../../../docs/user/rst/images/title.png}} |
|
|
|
|
|
Image with multiple IDs: |
|
|
|
|
|
\includegraphics{../../../docs/user/rst/images/title.png} |
|
|
\phantomsection\label{image-target-3}\label{image-target-2}\label{image-target-1} |
|
|
|
|
|
A centered image: |
|
|
|
|
|
\noindent\makebox[\linewidth][c]{\includegraphics{../../../docs/user/rst/images/biohazard.png}} |
|
|
|
|
|
A left-aligned image: |
|
|
|
|
|
\noindent{\includegraphics{../../../docs/user/rst/images/biohazard.png}\hfill} |
|
|
|
|
|
This paragraph might flow around the image. |
|
|
The specific behavior depends upon the style sheet and |
|
|
the browser or rendering software used. |
|
|
|
|
|
A right-aligned image: |
|
|
|
|
|
\noindent{\hfill\includegraphics{../../../docs/user/rst/images/biohazard.png}} |
|
|
|
|
|
This paragraph might flow around the image. |
|
|
The specific behavior depends upon the style sheet and |
|
|
the browser or rendering software used. |
|
|
|
|
|
For inline images see \hyperref[substitution-definitions]{Substitution Definitions}. |
|
|
|
|
|
Image size: |
|
|
|
|
|
An image 2 em wide: |
|
|
|
|
|
\includegraphics[width=2em]{../../../docs/user/rst/images/biohazard.png} |
|
|
|
|
|
An image 2 em wide and 15 pixel high: |
|
|
|
|
|
\includegraphics[height=15px,width=2em]{../../../docs/user/rst/images/biohazard.png} |
|
|
|
|
|
An image occupying 50\% of the line width: |
|
|
|
|
|
\includegraphics[width=0.500\linewidth]{../../../docs/user/rst/images/title.png} |
|
|
|
|
|
An image 2 cm high: |
|
|
|
|
|
\includegraphics[height=2cm]{../../../docs/user/rst/images/biohazard.png} |
|
|
|
|
|
A \emph{figure} is an image with a caption and/or a legend. With page-based output |
|
|
media, figures might float to a different position if this helps the page |
|
|
layout. |
|
|
|
|
|
\begin{DUclass}{figclass1} |
|
|
\begin{DUclass}{figclass2} |
|
|
\begin{figure} |
|
|
\noindent\makebox[\linewidth][c]{\includegraphics[width=258bp]{../../../docs/user/rst/images/title.png}} |
|
|
\caption{Plaintext markup syntax and parser system.} |
|
|
\begin{DUlegend} |
|
|
\setlength{\DUtablewidth}{\linewidth} |
|
|
\begin{longtable*}[c]{|p{0.156\DUtablewidth}|p{0.563\DUtablewidth}|} |
|
|
\hline |
|
|
|
|
|
re |
|
|
& |
|
|
Revised, revisited, based on ‘re’ module. |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
Structured |
|
|
& |
|
|
Structure-enhanced text, structuredtext. |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
Text |
|
|
& |
|
|
Well it is, isn’t it? |
|
|
\\ |
|
|
\hline |
|
|
\end{longtable*} |
|
|
|
|
|
This paragraph is also part of the legend. |
|
|
\end{DUlegend} |
|
|
\end{figure} |
|
|
\end{DUclass} |
|
|
\end{DUclass} |
|
|
|
|
|
A left-aligned figure: |
|
|
|
|
|
\begin{DUclass}{figclass1} |
|
|
\begin{DUclass}{figclass2} |
|
|
\begin{figure} % align = "left" |
|
|
\noindent\makebox[\linewidth][c]{\includegraphics[width=40px]{../../../docs/user/rst/images/biohazard.png}} |
|
|
\caption{This is the caption.} |
|
|
\begin{DUlegend} |
|
|
This is the legend. |
|
|
|
|
|
The legend may consist of several paragraphs. |
|
|
\end{DUlegend} |
|
|
\end{figure} |
|
|
\end{DUclass} |
|
|
\end{DUclass} |
|
|
|
|
|
This paragraph might flow around the figure. |
|
|
|
|
|
The specific behavior depends upon the style sheet and the browser or |
|
|
rendering software used. |
|
|
|
|
|
A centered figure: |
|
|
|
|
|
\begin{figure} |
|
|
\noindent\makebox[\linewidth][c]{\includegraphics[width=40px]{../../../docs/user/rst/images/biohazard.png}} |
|
|
\caption{This is the caption.} |
|
|
\begin{DUlegend} |
|
|
This is the legend. |
|
|
|
|
|
The legend may consist of several paragraphs. |
|
|
\end{DUlegend} |
|
|
\end{figure} |
|
|
|
|
|
This paragraph might flow around the figure. |
|
|
|
|
|
The specific behavior depends upon the style sheet and the browser or |
|
|
rendering software used. |
|
|
|
|
|
A right-aligned figure: |
|
|
|
|
|
\begin{figure} % align = "right" |
|
|
\noindent\makebox[\linewidth][c]{\includegraphics[width=40px]{../../../docs/user/rst/images/biohazard.png}} |
|
|
\caption{This is the caption.} |
|
|
\begin{DUlegend} |
|
|
This is the legend. |
|
|
|
|
|
The legend may consist of several paragraphs. |
|
|
\end{DUlegend} |
|
|
\end{figure} |
|
|
|
|
|
This paragraph might flow around the figure. The specific behavior depends |
|
|
upon the style sheet and the browser or rendering software used. |
|
|
|
|
|
Tables may be given titles and additional arguments with the \emph{table} |
|
|
directive: |
|
|
|
|
|
\setlength{\DUtablewidth}{\linewidth} |
|
|
\begin{longtable}[l]{|p{0.075\DUtablewidth}|p{0.075\DUtablewidth}|} |
|
|
\caption{left-aligned table}\\ |
|
|
\hline |
|
|
\textbf{% |
|
|
A |
|
|
} & \textbf{% |
|
|
not A |
|
|
} \\ |
|
|
\hline |
|
|
\endfirsthead |
|
|
\caption[]{left-aligned table (... continued)}\\ |
|
|
\hline |
|
|
\textbf{% |
|
|
A |
|
|
} & \textbf{% |
|
|
not A |
|
|
} \\ |
|
|
\hline |
|
|
\endhead |
|
|
\multicolumn{2}{c}{\hfill ... continued on next page} \\ |
|
|
\endfoot |
|
|
\endlastfoot |
|
|
|
|
|
False |
|
|
& |
|
|
True |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
True |
|
|
& |
|
|
False |
|
|
\\ |
|
|
\hline |
|
|
\end{longtable} |
|
|
|
|
|
\setlength{\DUtablewidth}{\linewidth} |
|
|
\begin{longtable}[c]{|p{0.075\DUtablewidth}|p{0.075\DUtablewidth}|} |
|
|
\caption{center-aligned table}\\ |
|
|
\hline |
|
|
\textbf{% |
|
|
A |
|
|
} & \textbf{% |
|
|
not A |
|
|
} \\ |
|
|
\hline |
|
|
\endfirsthead |
|
|
\caption[]{center-aligned table (... continued)}\\ |
|
|
\hline |
|
|
\textbf{% |
|
|
A |
|
|
} & \textbf{% |
|
|
not A |
|
|
} \\ |
|
|
\hline |
|
|
\endhead |
|
|
\multicolumn{2}{c}{\hfill ... continued on next page} \\ |
|
|
\endfoot |
|
|
\endlastfoot |
|
|
|
|
|
False |
|
|
& |
|
|
True |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
True |
|
|
& |
|
|
False |
|
|
\\ |
|
|
\hline |
|
|
\end{longtable} |
|
|
|
|
|
\setlength{\DUtablewidth}{\linewidth} |
|
|
\begin{longtable}[r]{|p{0.075\DUtablewidth}|p{0.075\DUtablewidth}|} |
|
|
\caption{right-aligned table}\\ |
|
|
\hline |
|
|
\textbf{% |
|
|
A |
|
|
} & \textbf{% |
|
|
not A |
|
|
} \\ |
|
|
\hline |
|
|
\endfirsthead |
|
|
\caption[]{right-aligned table (... continued)}\\ |
|
|
\hline |
|
|
\textbf{% |
|
|
A |
|
|
} & \textbf{% |
|
|
not A |
|
|
} \\ |
|
|
\hline |
|
|
\endhead |
|
|
\multicolumn{2}{c}{\hfill ... continued on next page} \\ |
|
|
\endfoot |
|
|
\endlastfoot |
|
|
|
|
|
False |
|
|
& |
|
|
True |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
True |
|
|
& |
|
|
False |
|
|
\\ |
|
|
\hline |
|
|
\end{longtable} |
|
|
|
|
|
With the “widths” argument “auto” (or “class” value “colwidths-auto”), |
|
|
column widths are determined by the backend (if supported by the |
|
|
writer/backend). |
|
|
|
|
|
\begin{longtable*}[c]{|l|l|l|} |
|
|
\hline |
|
|
\textbf{A} & \textbf{B} & \textbf{A or B} \\ |
|
|
\hline |
|
|
\endfirsthead |
|
|
\hline |
|
|
\textbf{A} & \textbf{B} & \textbf{A or B} \\ |
|
|
\hline |
|
|
\endhead |
|
|
\multicolumn{3}{c}{\hfill ... continued on next page} \\ |
|
|
\endfoot |
|
|
\endlastfoot |
|
|
False & False & False \\ |
|
|
\hline |
|
|
True & False & True \\ |
|
|
\hline |
|
|
False & True & True \\ |
|
|
\hline |
|
|
True & True & True \\ |
|
|
\hline |
|
|
\end{longtable*} |
|
|
\label{target2}\label{target1} |
|
|
|
|
|
|
|
|
\subsubsection{2.14.3 Admonitions% |
|
|
\label{admonitions}% |
|
|
} |
|
|
|
|
|
\DUadmonition[attention]{ |
|
|
\DUtitle[attention]{Attention!} |
|
|
|
|
|
Directives at large. |
|
|
} |
|
|
|
|
|
\DUadmonition[caution]{ |
|
|
\DUtitle[caution]{Caution!} |
|
|
|
|
|
Don’t take any wooden nickels. |
|
|
} |
|
|
|
|
|
\DUadmonition[danger]{ |
|
|
\DUtitle[danger]{!DANGER!} |
|
|
|
|
|
Mad scientist at work! |
|
|
} |
|
|
|
|
|
\DUadmonition[error]{ |
|
|
\DUtitle[error]{Error} |
|
|
|
|
|
Does not compute. |
|
|
} |
|
|
|
|
|
\DUadmonition[hint]{ |
|
|
\DUtitle[hint]{Hint} |
|
|
|
|
|
It’s bigger than a bread box. |
|
|
} |
|
|
|
|
|
\DUadmonition[important]{ |
|
|
\DUtitle[important]{Important} |
|
|
|
|
|
\begin{itemize} |
|
|
\item Wash behind your ears. |
|
|
|
|
|
\item Clean up your room. |
|
|
|
|
|
\item Call your mother. |
|
|
|
|
|
\item Back up your data. |
|
|
\end{itemize} |
|
|
} |
|
|
|
|
|
\DUadmonition[note]{ |
|
|
\DUtitle[note]{Note} |
|
|
|
|
|
This is a note. |
|
|
} |
|
|
|
|
|
\DUadmonition[tip]{ |
|
|
\DUtitle[tip]{Tip} |
|
|
|
|
|
15\% if the service is good. |
|
|
} |
|
|
|
|
|
\DUadmonition[warning]{ |
|
|
\DUtitle[warning]{Warning} |
|
|
|
|
|
Strong prose may provoke extreme mental exertion. |
|
|
Reader discretion is strongly advised. |
|
|
} |
|
|
|
|
|
\DUadmonition[admonition-and-by-the-way]{ |
|
|
\DUtitle[admonition-and-by-the-way]{And, by the way…} |
|
|
|
|
|
You can make up your own admonition too. |
|
|
} |
|
|
|
|
|
|
|
|
\subsubsection{2.14.4 Topics, Sidebars, and Rubrics% |
|
|
\label{topics-sidebars-and-rubrics}% |
|
|
} |
|
|
|
|
|
\emph{Sidebars} are like miniature, parallel documents. |
|
|
|
|
|
\DUsidebar{ |
|
|
\DUtitle[title]{Sidebar Title} |
|
|
|
|
|
\DUsubtitle[sidebar]{Optional Subtitle} |
|
|
|
|
|
This is a sidebar. It is for text outside the flow of the main |
|
|
text. |
|
|
|
|
|
\DUrubric{This is a rubric inside a sidebar} |
|
|
|
|
|
Sidebars often appear beside the main text with a border and a different |
|
|
background or font color. |
|
|
} |
|
|
|
|
|
A \emph{topic} is like a block quote with a title, or a self-contained section |
|
|
with no subsections. |
|
|
|
|
|
\begin{DUclass}{topic} |
|
|
\begin{quote} |
|
|
\DUtitle[topic]{Topic Title} |
|
|
|
|
|
This is a topic. |
|
|
\end{quote} |
|
|
\end{DUclass} |
|
|
|
|
|
A \emph{rubric} is like an informal heading that doesn’t correspond to the |
|
|
document’s structure. It is typically highlighted in red (hence the name). |
|
|
|
|
|
\DUrubric{This is a rubric} |
|
|
|
|
|
Topics and rubrics can be used at places where a \hyperref[section-title]{section title} is not |
|
|
allowed (e.g. inside a directive). |
|
|
|
|
|
|
|
|
\subsubsection{2.14.5 Target Footnotes% |
|
|
\label{target-footnotes}% |
|
|
} |
|
|
% |
|
|
\DUfootnotetext{id29}{id30}{5}{% |
|
|
\url{http://www.python.org/} |
|
|
} |
|
|
% |
|
|
\DUfootnotetext{id33}{id34}{6}{% |
|
|
\url{http://pygments.org/} |
|
|
} |
|
|
% |
|
|
\DUfootnotetext{id35}{id36}{7}{% |
|
|
\url{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf} |
|
|
} |
|
|
% |
|
|
\DUfootnotetext{id39}{id40}{8}{% |
|
|
\url{http://docutils.sourceforge.net/} |
|
|
} |
|
|
% |
|
|
\DUfootnotetext{id41}{id42}{9}{% |
|
|
\url{A:DOS\\path\\} |
|
|
} |
|
|
|
|
|
|
|
|
\subsubsection{2.14.6 Replacement Text% |
|
|
\label{replacement-text}% |
|
|
} |
|
|
|
|
|
I recommend you try \href{http://www.python.org/}{Python, \emph{the} best language around}\DUfootnotemark{id32}{id29}{5}. |
|
|
|
|
|
|
|
|
\subsubsection{2.14.7 Compound Paragraph% |
|
|
\label{compound-paragraph}% |
|
|
} |
|
|
|
|
|
The \emph{compound} directive is used to create a “compound paragraph”, which |
|
|
is a single logical paragraph containing multiple physical body |
|
|
elements. For example: |
|
|
|
|
|
\begin{DUclass}{compound} |
|
|
The ‘rm’ command is very dangerous. If you are logged |
|
|
in as root and enter |
|
|
\begin{quote} |
|
|
\begin{alltt} |
|
|
cd / |
|
|
rm -rf * |
|
|
\end{alltt} |
|
|
\end{quote} |
|
|
you will erase the entire contents of your file system. |
|
|
\end{DUclass} |
|
|
|
|
|
Test the handling and display of compound paragraphs: |
|
|
|
|
|
\begin{DUclass}{compound} |
|
|
\begin{DUclass}{some-class} |
|
|
Compound 2, paragraph 1, |
|
|
|
|
|
compound 2, paragraph 2, |
|
|
\begin{itemize} |
|
|
\item list item 1, |
|
|
|
|
|
\item list item 2, |
|
|
\end{itemize} |
|
|
compound 2, paragraph 3. |
|
|
\end{DUclass} |
|
|
\end{DUclass} |
|
|
|
|
|
\begin{DUclass}{compound} |
|
|
Compound 3, only consisting of one paragraph. |
|
|
\end{DUclass} |
|
|
|
|
|
\begin{DUclass}{compound} |
|
|
\begin{quote} |
|
|
\begin{alltt} |
|
|
Compound 4. |
|
|
This one starts with a literal block. |
|
|
\end{alltt} |
|
|
\end{quote} |
|
|
Compound 4, paragraph following the literal block. |
|
|
\end{DUclass} |
|
|
|
|
|
Now something \emph{really} perverted – a nested compound block. This is |
|
|
just to test that it works at all; the results don’t have to be |
|
|
meaningful. |
|
|
|
|
|
\begin{DUclass}{compound} |
|
|
Compound 5, block 1 (a paragraph). |
|
|
|
|
|
\begin{DUclass}{compound} |
|
|
Compound 6 is block 2 in compound 5. |
|
|
|
|
|
Compound 6, another paragraph. |
|
|
\end{DUclass} |
|
|
|
|
|
Compound 5, block 3 (a paragraph). |
|
|
\end{DUclass} |
|
|
|
|
|
\begin{DUclass}{compound} |
|
|
Compound 7, tests the inclusion of various block-level |
|
|
elements in one logical paragraph. First a table, |
|
|
|
|
|
\setlength{\DUtablewidth}{\linewidth} |
|
|
\begin{longtable*}[c]{|p{0.249\DUtablewidth}|p{0.249\DUtablewidth}|p{0.249\DUtablewidth}|} |
|
|
\hline |
|
|
|
|
|
Left cell, first |
|
|
paragraph. |
|
|
|
|
|
Left cell, second |
|
|
paragraph. |
|
|
& |
|
|
Middle cell, |
|
|
consisting of |
|
|
exactly one |
|
|
paragraph. |
|
|
& |
|
|
Right cell. |
|
|
|
|
|
Paragraph 2. |
|
|
|
|
|
Paragraph 3. |
|
|
\\ |
|
|
\hline |
|
|
\end{longtable*} |
|
|
followed by a paragraph. This physical paragraph is |
|
|
actually a continuation of the paragraph before the table. It is followed |
|
|
by |
|
|
\begin{quote} |
|
|
a quote and |
|
|
\end{quote} |
|
|
\begin{enumerate} |
|
|
\item an enumerated list, |
|
|
\end{enumerate} |
|
|
a paragraph, |
|
|
\begin{DUoptionlist} |
|
|
\item[-{}-an] option list, |
|
|
\end{DUoptionlist} |
|
|
a paragraph, |
|
|
\begin{DUfieldlist} |
|
|
\item[{a field:}] |
|
|
list, |
|
|
\end{DUfieldlist} |
|
|
a paragraph, |
|
|
\begin{description} |
|
|
\item[{a definition}] \leavevmode |
|
|
list, |
|
|
|
|
|
\end{description} |
|
|
a paragraph, an image: |
|
|
\includegraphics{../../../docs/user/rst/images/biohazard.png} |
|
|
a paragraph, |
|
|
\begin{DUlineblock}{0em} |
|
|
\item[] a line |
|
|
\item[] block, |
|
|
\end{DUlineblock} |
|
|
a paragraph followed by a comment, |
|
|
% this is a comment |
|
|
a paragraph, a |
|
|
|
|
|
\DUadmonition[note]{ |
|
|
\DUtitle[note]{Note} |
|
|
|
|
|
with content |
|
|
} |
|
|
and the final paragraph of the compound 7. |
|
|
\end{DUclass} |
|
|
|
|
|
|
|
|
\subsubsection{2.14.8 Parsed Literal Blocks% |
|
|
\label{parsed-literal-blocks}% |
|
|
} |
|
|
|
|
|
\begin{quote} |
|
|
{\ttfamily \raggedright \noindent |
|
|
This~is~a~parsed~literal~block.\\ |
|
|
~~~~This~line~is~indented.~~The~next~line~is~blank.\\ |
|
|
~\\ |
|
|
Inline~markup~is~supported,~e.g.~\emph{emphasis},~\textbf{strong},~\texttt{literal\\ |
|
|
text},~\textsubscript{sub-}~and~\textsuperscript{super}scripts,\\ |
|
|
inline~formulas:~$A = 2 \pi r^2$,\\ |
|
|
footnotes\DUfootnotemark{id22}{id8}{1},~% |
|
|
\phantomsection\label{hyperlink-targets}hyperlink~targets,~and~\href{http://www.python.org/}{references}. |
|
|
} |
|
|
\end{quote} |
|
|
|
|
|
|
|
|
\subsubsection{2.14.9 Code% |
|
|
\label{code}% |
|
|
} |
|
|
|
|
|
Blocks of source code can be set with the \DUroletitlereference{code} directive. If the code |
|
|
language is specified, the content is parsed and tagged by the \href{http://pygments.org/}{Pygments}\DUfootnotemark{id34}{id33}{6} |
|
|
syntax highlighter and can be formatted with a style sheet. (Code parsing |
|
|
is turned off using the \texttt{syntax-highlight} config setting in the test |
|
|
conversions in order to get identical results with/without installed |
|
|
Pygments highlighter.) |
|
|
|
|
|
\begin{DUclass}{code} |
|
|
\begin{DUclass}{python} |
|
|
\begin{quote} |
|
|
\begin{alltt} |
|
|
print 'This is Python code.' |
|
|
\end{alltt} |
|
|
\end{quote} |
|
|
\end{DUclass} |
|
|
\end{DUclass} |
|
|
|
|
|
The \texttt{:number-lines:} option (with optional start value) generates line |
|
|
numbers: |
|
|
|
|
|
\begin{DUclass}{code} |
|
|
\begin{DUclass}{python} |
|
|
\begin{quote} |
|
|
{\ttfamily \raggedright \noindent |
|
|
\DUrole{ln}{~8~}\#~print~integers~from~0~to~9:\\ |
|
|
\DUrole{ln}{~9~}for~i~in~range(10):\\ |
|
|
\DUrole{ln}{10~}~~~~print~i |
|
|
} |
|
|
\end{quote} |
|
|
\end{DUclass} |
|
|
\end{DUclass} |
|
|
|
|
|
For inline code snippets, there is the \DUroletitlereference{code} role, which can be used |
|
|
directly (the code will not be parsed/tagged, as the language is not known) |
|
|
or as base for special code roles, e.g. the LaTeX code in the next |
|
|
paragraph. |
|
|
|
|
|
Docutils uses LaTeX syntax for math directives and roles: |
|
|
\texttt{\DUrole{code}{\DUrole{tex}{\textbackslash{}alpha = f(x)}}} prints $\alpha = f(x)$. |
|
|
|
|
|
The \texttt{:code:} option of the \DUroletitlereference{include} directive sets the included content |
|
|
as a code block, here the rst file \texttt{header\_footer.txt} with line numbers: |
|
|
|
|
|
\begin{DUclass}{code} |
|
|
\begin{DUclass}{rst} |
|
|
\begin{quote} |
|
|
{\ttfamily \raggedright \noindent |
|
|
\DUrole{ln}{1~}..~header::~Document~header\\ |
|
|
\DUrole{ln}{2~}..~footer::~Document~footer |
|
|
} |
|
|
\end{quote} |
|
|
\end{DUclass} |
|
|
\end{DUclass} |
|
|
|
|
|
|
|
|
\subsection{2.15 Substitution Definitions% |
|
|
\label{substitution-definitions}% |
|
|
} |
|
|
|
|
|
An inline image (\includegraphics{../../../docs/user/rst/images/biohazard.png}) example: |
|
|
|
|
|
(Substitution definitions are not visible in the HTML source.) |
|
|
|
|
|
|
|
|
\subsection{2.16 Comments% |
|
|
\label{comments}% |
|
|
} |
|
|
|
|
|
Here’s one: |
|
|
|
|
|
% Comments begin with two dots and a space. Anything may |
|
|
% follow, except for the syntax of footnotes, hyperlink |
|
|
% targets, directives, or substitution definitions. |
|
|
% |
|
|
% Double-dashes -- "--" -- must be escaped somehow in HTML output. |
|
|
% |
|
|
% Comments may contain non-ASCII characters: ä ö ü æ ø å |
|
|
|
|
|
(View the HTML source to see the comment.) |
|
|
|
|
|
|
|
|
\subsection{2.17 Raw text% |
|
|
\label{raw-text}% |
|
|
} |
|
|
|
|
|
This does not necessarily look nice, because there may be missing white space. |
|
|
|
|
|
It’s just there to freeze the behavior. |
|
|
|
|
|
A test. |
|
|
|
|
|
Second test. |
|
|
|
|
|
\DUrole{myclass}{Another test with myclass set.} |
|
|
|
|
|
This is the \DUrole{myrawroleclass}{fourth test} with myrawroleclass set. |
|
|
|
|
|
Fifth test in LaTeX.\\Line two. |
|
|
|
|
|
|
|
|
\subsection{2.18 Container% |
|
|
\label{container}% |
|
|
} |
|
|
|
|
|
\begin{DUclass}{custom} |
|
|
|
|
|
paragraph 1 |
|
|
|
|
|
paragraph 2 |
|
|
\end{DUclass} |
|
|
|
|
|
% currently not implemented in LaTeX: |
|
|
% .. include:: data/header_footer.txt |
|
|
|
|
|
|
|
|
\subsection{2.19 Colspanning tables% |
|
|
\label{colspanning-tables}% |
|
|
} |
|
|
|
|
|
This table has a cell spanning two columns: |
|
|
|
|
|
\setlength{\DUtablewidth}{\linewidth} |
|
|
\begin{longtable*}[c]{|p{0.075\DUtablewidth}|p{0.075\DUtablewidth}|p{0.086\DUtablewidth}|} |
|
|
\hline |
|
|
\multicolumn{2}{|p{0.15\DUtablewidth}|}{\textbf{% |
|
|
Inputs |
|
|
}} & \textbf{% |
|
|
Output |
|
|
} \\ |
|
|
\hline |
|
|
\textbf{% |
|
|
A |
|
|
} & \textbf{% |
|
|
B |
|
|
} & \textbf{% |
|
|
A or B |
|
|
} \\ |
|
|
\hline |
|
|
\endfirsthead |
|
|
\hline |
|
|
\multicolumn{2}{|p{0.15\DUtablewidth}|}{\textbf{% |
|
|
Inputs |
|
|
}} & \textbf{% |
|
|
Output |
|
|
} \\ |
|
|
\hline |
|
|
\textbf{% |
|
|
A |
|
|
} & \textbf{% |
|
|
B |
|
|
} & \textbf{% |
|
|
A or B |
|
|
} \\ |
|
|
\hline |
|
|
\endhead |
|
|
\multicolumn{3}{c}{\hfill ... continued on next page} \\ |
|
|
\endfoot |
|
|
\endlastfoot |
|
|
|
|
|
False |
|
|
& |
|
|
False |
|
|
& |
|
|
False |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
True |
|
|
& |
|
|
False |
|
|
& |
|
|
True |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
False |
|
|
& |
|
|
True |
|
|
& |
|
|
True |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
True |
|
|
& |
|
|
True |
|
|
& |
|
|
True |
|
|
\\ |
|
|
\hline |
|
|
\end{longtable*} |
|
|
|
|
|
|
|
|
\subsection{2.20 Rowspanning tables% |
|
|
\label{rowspanning-tables}% |
|
|
} |
|
|
|
|
|
Here’s a table with cells spanning several rows: |
|
|
|
|
|
\setlength{\DUtablewidth}{\linewidth} |
|
|
\begin{longtable*}[c]{|p{0.296\DUtablewidth}|p{0.156\DUtablewidth}|p{0.226\DUtablewidth}|} |
|
|
\hline |
|
|
\textbf{% |
|
|
Header row, column 1 |
|
|
(header rows optional) |
|
|
} & \textbf{% |
|
|
Header 2 |
|
|
} & \textbf{% |
|
|
Header 3 |
|
|
} \\ |
|
|
\hline |
|
|
\endfirsthead |
|
|
\hline |
|
|
\textbf{% |
|
|
Header row, column 1 |
|
|
(header rows optional) |
|
|
} & \textbf{% |
|
|
Header 2 |
|
|
} & \textbf{% |
|
|
Header 3 |
|
|
} \\ |
|
|
\hline |
|
|
\endhead |
|
|
\multicolumn{3}{c}{\hfill ... continued on next page} \\ |
|
|
\endfoot |
|
|
\endlastfoot |
|
|
|
|
|
body row 1, column 1 |
|
|
& |
|
|
column 2 |
|
|
& |
|
|
column 3 |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
body row 2 |
|
|
& \multirow{2}{0.16\DUtablewidth}{% |
|
|
Cells may |
|
|
span rows. |
|
|
} & \multirow{2}{0.23\DUtablewidth}{% |
|
|
Another |
|
|
rowspanning |
|
|
cell. |
|
|
} \\ |
|
|
\cline{1-1} |
|
|
|
|
|
body row 3 |
|
|
& & \\ |
|
|
\hline |
|
|
\end{longtable*} |
|
|
|
|
|
|
|
|
\subsection{2.21 Custom Roles% |
|
|
\label{custom-roles}% |
|
|
} |
|
|
|
|
|
\begin{itemize} |
|
|
\item A role based on an existing role. |
|
|
|
|
|
\texttt{\DUrole{custom}{one}} \texttt{\DUrole{custom}{two}} \texttt{\DUrole{custom}{three}} |
|
|
|
|
|
\item A new role. |
|
|
|
|
|
\DUrole{customnew}{one two three} |
|
|
|
|
|
\item A role with class attribute. |
|
|
|
|
|
\DUrole{special}{interpreted text} |
|
|
|
|
|
\item A language-switching role: |
|
|
|
|
|
Let’s count in German \foreignlanguage{ngerman}{eins zwei drei}. |
|
|
|
|
|
\item A role with multiple class attributes, styled with raw directives: |
|
|
|
|
|
\newcommand{\DUrolegreen}[1]{\textcolor{green}{#1}} |
|
|
\newcommand{\DUrolesc}[1]{\textsc{#1}} |
|
|
|
|
|
The following works in most browsers but does not validate |
|
|
(\texttt{<style>} is only allowed in the document head): |
|
|
|
|
|
\begin{quote} |
|
|
\begin{alltt} |
|
|
.. raw:: html |
|
|
|
|
|
<style type="text/css"><!-{}- |
|
|
.green \{color: green;\} |
|
|
.sc \{font-variant: small-caps;\} |
|
|
-{}-></style> |
|
|
\end{alltt} |
|
|
\end{quote} |
|
|
|
|
|
\DUrole{green}{\DUrole{sc}{\foreignlanguage{british}{British colourful text in small-caps}}}. |
|
|
\end{itemize} |
|
|
|
|
|
|
|
|
\subsection{2.22 Mathematics% |
|
|
\label{mathematics}% |
|
|
} |
|
|
|
|
|
Docutils supports inline math with the prefix or postfix \texttt{:math:} |
|
|
role specificator, $n! + \sin(x_n^2)$ and $A_\text{c} = |
|
|
\frac{\pi}{4} d^2$, as well as displayed math via the |
|
|
\DUroletitlereference{math} directive: |
|
|
% |
|
|
\begin{equation*} |
|
|
f(\epsilon) = \frac{1}{1 + \exp\left(\frac{\varepsilon}{k_\text{B}T}\right)} |
|
|
\end{equation*} |
|
|
Content may start on the first line of the directive, e.g. |
|
|
% |
|
|
\begin{equation*} |
|
|
N = \frac{\text{number of apples}}{7} |
|
|
\end{equation*} |
|
|
Equations can be labeled with a reference name using the \texttt{:name:} option. |
|
|
See \hyperref[eq-m]{eq:M} and \hyperref[eq-schrodinger]{eq:schrödinger} below. |
|
|
|
|
|
The determinant of the matrix |
|
|
% |
|
|
\begin{equation*} |
|
|
\mathbf{M} = \left(\begin{matrix}a&b\\c&d\end{matrix}\right) |
|
|
\phantomsection |
|
|
\label{eq-m} |
|
|
\end{equation*} |
|
|
is $|\mathbf{M}| = ad - bc$. |
|
|
|
|
|
More than one display math block can be put in one math directive. |
|
|
For example, the following sum and integral with limits: |
|
|
% |
|
|
\begin{equation*} |
|
|
\int_0^1 x^n dx = \frac{1}{n + 1} |
|
|
\end{equation*}% |
|
|
\begin{equation*} |
|
|
\sum_{n=1}^m n = \frac{m(m+1)}{2} |
|
|
\end{equation*} |
|
|
LaTeX-supported Unicode math symbols can be used in math roles and |
|
|
directives: |
|
|
|
|
|
The Schrödinger equation |
|
|
% |
|
|
\begin{equation*} |
|
|
i\hbar \frac{\partial }{\partial t}\Psi = \hat{H}\Psi , |
|
|
\phantomsection |
|
|
\label{eq-schrodinger} |
|
|
\end{equation*} |
|
|
with the \emph{wave function} $\Psi $, describes how the quantum state of a |
|
|
physical system changes in time. |
|
|
|
|
|
\begin{description} |
|
|
\item[{Math-Accents:}] \leavevmode |
|
|
\setlength{\DUtablewidth}{\linewidth} |
|
|
\begin{longtable*}[c]{p{0.315\DUtablewidth}p{0.315\DUtablewidth}p{0.315\DUtablewidth}} |
|
|
|
|
|
$\acute{a}$ \texttt{\textbackslash{}acute\{a\}} |
|
|
& |
|
|
$\dot{t}$ \texttt{\textbackslash{}dot\{t\}} |
|
|
& |
|
|
$\hat{\gamma}$ \texttt{\textbackslash{}hat\{\textbackslash{}gamma\}} |
|
|
\\ |
|
|
|
|
|
$\grave{a}$ \texttt{\textbackslash{}grave\{a\}} |
|
|
& |
|
|
$\ddot{t}$ \texttt{\textbackslash{}ddot\{t\}} |
|
|
& |
|
|
$\tilde{\alpha}$ \texttt{\textbackslash{}tilde\{\textbackslash{}alpha\}} |
|
|
\\ |
|
|
|
|
|
$\breve{x}$ \texttt{\textbackslash{}breve\{x\}} |
|
|
& |
|
|
$\dddot{t}$ \texttt{\textbackslash{}dddot\{t\}} |
|
|
& |
|
|
$\vec{\imath}$ \texttt{\textbackslash{}vec\{\textbackslash{}imath\}} |
|
|
\\ |
|
|
|
|
|
$\check{a}$ \texttt{\textbackslash{}check\{a\}} |
|
|
& |
|
|
$\bar{a}$ \texttt{\textbackslash{}bar\{a\}} |
|
|
& |
|
|
$\vec{R}$ \texttt{\textbackslash{}vec\{R\}} |
|
|
\\ |
|
|
\end{longtable*} |
|
|
|
|
|
\end{description} |
|
|
|
|
|
% \widetilde{xxx} |
|
|
% \widehat{xxx} |
|
|
|
|
|
Modulation Transfer Function: |
|
|
% |
|
|
\begin{equation*} |
|
|
\text{MTF} = \left|\frac{\mathcal{F}\{s(x)\}} |
|
|
{\mathcal{F}\{ s(x)\} |_{\omega _{x}=0}}\right| |
|
|
= \mathrm{abs}\left(\frac |
|
|
{\int _{-\infty }^{\infty }s(x) \mathrm{e}^{\mathrm{i}\omega _{x}x}\mathrm{d}{x}} |
|
|
{\int _{-\infty }^{\infty }s(x)\mathrm{d}{x}} |
|
|
\right). |
|
|
\end{equation*} |
|
|
Math split over two lines: If a double backslash is detected outside a |
|
|
\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{id36}{id35}{7} |
|
|
\texttt{align} environment: |
|
|
% |
|
|
\begin{align*} |
|
|
s_{\mathrm{out}}(x) & = s_{\mathrm{in}}(x') * s_\delta (x-x') \\ |
|
|
& = \int s_{\mathrm{in}}(x')s_\delta (x-x')\mathrm{d}x' |
|
|
\end{align*} |
|
|
Cases (“manually”, with \texttt{matrix} environment): |
|
|
% |
|
|
\begin{equation*} |
|
|
\mathrm{sgn}(x) = \left\{\begin{matrix} |
|
|
-1 & x<0\\ |
|
|
1 & x>0 |
|
|
\end{matrix}\right. |
|
|
\end{equation*} |
|
|
Cases with the \href{ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf}{AMSmath}\DUfootnotemark{id37}{id35}{7} \texttt{cases} environment (not (yet) supported by |
|
|
HTML writers with \texttt{-{}-math-output=MathML}): |
|
|
% |
|
|
\begin{equation*} |
|
|
\mathrm{sgn}(x) = \begin{cases} |
|
|
-1 & x<0\\ |
|
|
1 & x>0 |
|
|
\end{cases} |
|
|
\end{equation*} |
|
|
|
|
|
\section{3 Tests for the LaTeX writer% |
|
|
\label{tests-for-the-latex-writer}% |
|
|
} |
|
|
|
|
|
Test syntax elements which may cause trouble for the LaTeX writer but might |
|
|
not need to be tested with other writers (e.g. the HTML writer). |
|
|
|
|
|
|
|
|
\subsection{3.1 Custom Roles in LaTeX% |
|
|
\label{custom-roles-in-latex}% |
|
|
} |
|
|
|
|
|
\begin{itemize} |
|
|
\item Role names and class arguments are converted to conform to the |
|
|
regular expression \texttt{{[}a-z{]}{[}-a-z0-9{]}*} (letters are downcased, |
|
|
accents and similar decoration is stripped, non-conforming |
|
|
characters are replaced by a hyphen). |
|
|
|
|
|
Class arguments may contain numbers and hyphens, which need special |
|
|
treatment in LaTeX command names. |
|
|
|
|
|
\DUrole{large}{\DUrole{custom4}{\DUrole{small-caps}{\DUrole{custom-role}{\DUrole{custom-role}{Text with role “custom4”}}}}} (but without styling by \texttt{DUrole*} |
|
|
macros). |
|
|
|
|
|
\item With LaTeX, roles can be styled within the document using the \DUroletitlereference{raw} |
|
|
directive. |
|
|
|
|
|
\newcommand{\DUrolelarge}[1]{{\large #1}} |
|
|
\makeatletter |
|
|
\@namedef{DUrolesmall-caps}{\textsc} |
|
|
\@namedef{DUrolecustom4}{\textbf} |
|
|
\makeatother |
|
|
|
|
|
\DUrole{large}{\DUrole{custom4}{\DUrole{small-caps}{\DUrole{custom-role}{\DUrole{custom-role}{inline text}}}}} in large, bold, small-caps. |
|
|
|
|
|
\item Custom roles can be based on standard roles: |
|
|
|
|
|
This is a \emph{\DUrole{custom-emphasis}{customized emphasis text role}} |
|
|
|
|
|
This is a \texttt{\DUrole{custom-literal}{customized literal text role}} |
|
|
|
|
|
This is a \textbf{\DUrole{custom-strong}{customized strong text role}} |
|
|
|
|
|
This is a \textsubscript{\DUrole{custom-subscript}{customized subscript text role}} |
|
|
|
|
|
This is a \textsuperscript{\DUrole{custom-superscript}{customized superscript text role}} |
|
|
|
|
|
This is a \DUroletitlereference{\DUrole{custom-title-reference}{customized title-reference text role}} |
|
|
\end{itemize} |
|
|
|
|
|
|
|
|
\subsection{3.2 class handling% |
|
|
\label{class-handling}% |
|
|
} |
|
|
|
|
|
This section tests class handling for block level elements by the LaTeX |
|
|
writer. See the input file \texttt{classes\_latex.txt} for the raw LaTeX code used |
|
|
to style the examples. |
|
|
|
|
|
An “epigraph” directive is exported as “quote” wrapped in a “DUclass” |
|
|
environment. Here, it is styled by a “DUCLASSepigraph” environment |
|
|
redefining the “quote” environment as “minipage”: |
|
|
|
|
|
\newcommand*{\DUCLASSepigraph}{% |
|
|
\renewenvironment{quote}{\vspace{1em} |
|
|
\footnotesize\hfill{}% |
|
|
\begin{minipage}{0.4\columnwidth}}% |
|
|
{\end{minipage}\vskip\baselineskip}} |
|
|
|
|
|
\begin{DUclass}{epigraph} |
|
|
\begin{quote} |
|
|
Do not play this piece fast. It is never right to play \emph{Ragtime} fast. |
|
|
\nopagebreak |
|
|
|
|
|
\raggedleft —Scott Joplin |
|
|
\end{quote} |
|
|
\end{DUclass} |
|
|
|
|
|
Raw latex is also used to style the following lists: “DUCLASSenumerateitems” |
|
|
redefines “itemize” as “enumerate”, “DUCLASSrules” draws horizontal lines |
|
|
above and below. |
|
|
|
|
|
\newcommand*{\DUCLASSenumerateitems}{% |
|
|
\renewenvironment{itemize}{\begin{enumerate}}% |
|
|
{\end{enumerate}}% |
|
|
} |
|
|
|
|
|
\newenvironment{DUCLASSrules}% |
|
|
{\noindent\rule[0.5ex]{1\columnwidth}{1pt}}% |
|
|
{\noindent\rule[0.5ex]{1\columnwidth}{1pt}} |
|
|
|
|
|
An “enumerated” bullet list: |
|
|
|
|
|
\begin{DUclass}{enumerateitems} |
|
|
\begin{itemize} |
|
|
\item item |
|
|
|
|
|
\item next item |
|
|
|
|
|
\item third item |
|
|
\end{itemize} |
|
|
\end{DUclass} |
|
|
|
|
|
A list with lines above and below: |
|
|
|
|
|
\begin{DUclass}{rules} |
|
|
\begin{itemize} |
|
|
\item item |
|
|
|
|
|
\item next item |
|
|
\end{itemize} |
|
|
\end{DUclass} |
|
|
|
|
|
A normal bullet list is kept unchanged by the above redefinitions: |
|
|
|
|
|
\begin{itemize} |
|
|
\item item |
|
|
|
|
|
\item next item |
|
|
|
|
|
\item third item |
|
|
\end{itemize} |
|
|
|
|
|
A container wraps several elements in a common “class wrapper”. Here, we use |
|
|
it to set 2 paragraphs and a list in small caps: |
|
|
|
|
|
\newcommand*{\DUCLASSscshape}{\scshape} |
|
|
|
|
|
\begin{DUclass}{scshape} |
|
|
|
|
|
paragraph 1 |
|
|
|
|
|
paragraph 2 |
|
|
|
|
|
\begin{itemize} |
|
|
\item bullet list |
|
|
|
|
|
\item still bullet list |
|
|
\end{itemize} |
|
|
\end{DUclass} |
|
|
|
|
|
A right-aligned line-block. Alignment handling is built into the latex |
|
|
writer for image, table, and line block elements. |
|
|
|
|
|
\begin{DUlineblock}{0em} |
|
|
\raggedleft |
|
|
\item[] Max Mustermann |
|
|
\item[] Waldstr. 22 |
|
|
\item[] D 01234 Testdorf |
|
|
\item[] Tel.: 0123/456789 |
|
|
\end{DUlineblock} |
|
|
|
|
|
|
|
|
\subsection{3.3 More Tables% |
|
|
\label{more-tables}% |
|
|
} |
|
|
|
|
|
A table with multi-paragraph multicolumn cells: |
|
|
|
|
|
\setlength{\DUtablewidth}{\linewidth} |
|
|
\begin{longtable*}[c]{|p{0.133\DUtablewidth}|p{0.179\DUtablewidth}|p{0.179\DUtablewidth}|p{0.110\DUtablewidth}|p{0.121\DUtablewidth}|p{0.145\DUtablewidth}|} |
|
|
\hline |
|
|
|
|
|
test |
|
|
& |
|
|
\textbf{bold hd} |
|
|
& \multicolumn{3}{p{0.41\DUtablewidth}|}{% |
|
|
multicolumn 1 |
|
|
|
|
|
With a second paragraph |
|
|
} & |
|
|
\emph{emph hd} |
|
|
\\ |
|
|
\hline |
|
|
\multicolumn{2}{|p{0.31\DUtablewidth}|}{% |
|
|
multicolumn 2 |
|
|
|
|
|
With a second paragraph |
|
|
} & |
|
|
cell |
|
|
& |
|
|
cell |
|
|
& |
|
|
cell |
|
|
& |
|
|
cell |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
cell |
|
|
& \multicolumn{2}{p{0.36\DUtablewidth}|}{% |
|
|
multicolumn 3 (one line, |
|
|
but very very very very |
|
|
very looooong) |
|
|
} & |
|
|
cell |
|
|
& |
|
|
cell |
|
|
& |
|
|
cell |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
cell |
|
|
& |
|
|
cell |
|
|
& |
|
|
cell |
|
|
& \multicolumn{3}{p{0.38\DUtablewidth}|}{% |
|
|
Short multicolumn 4 |
|
|
} \\ |
|
|
\hline |
|
|
\end{longtable*} |
|
|
|
|
|
Tables with multi-paragraph multirow cells currently fail due to a LaTeX |
|
|
limitation (see \url{https://sourceforge.net/p/docutils/bugs/225/}). |
|
|
|
|
|
A table with multirow header and column-widths set by LaTeX: |
|
|
|
|
|
\begin{longtable*}[c]{|l|l|} |
|
|
\hline |
|
|
\multirow{2}{*}{\textbf{XXX}} & \textbf{Variable Summary} \\ |
|
|
\cline{2-2} |
|
|
& \textbf{Description} \\ |
|
|
\hline |
|
|
\endfirsthead |
|
|
\hline |
|
|
\multirow{2}{*}{\textbf{XXX}} & \textbf{Variable Summary} \\ |
|
|
\cline{2-2} |
|
|
& \textbf{Description} \\ |
|
|
\hline |
|
|
\endhead |
|
|
\multicolumn{2}{c}{\hfill ... continued on next page} \\ |
|
|
\endfoot |
|
|
\endlastfoot |
|
|
\multicolumn{2}{|l|}{multicollumn cell} \\ |
|
|
\hline |
|
|
\end{longtable*} |
|
|
|
|
|
In a table with column-widths set by LaTeX, each cell has just one line. |
|
|
Paragraphs are merged (a warning is given). |
|
|
|
|
|
\begin{longtable*}[c]{|l|l|} |
|
|
\hline |
|
|
11 & first paragraph |
|
|
second paragraph |
|
|
third paragraph \\ |
|
|
\hline |
|
|
21 & 22 \\ |
|
|
\hline |
|
|
\end{longtable*} |
|
|
|
|
|
% This file is used by the standalone_rst_latex test. |
|
|
|
|
|
|
|
|
\subsection{3.4 Option lists% |
|
|
\label{id23}% |
|
|
} |
|
|
|
|
|
The LaTeX-2e description environment is used for definition lists. |
|
|
The definition is continued on the same line as the term, this should |
|
|
not happen if a option-list is at the top of the definition. |
|
|
|
|
|
If the option list is not at the first element in the definition, it |
|
|
is contained in a quote |
|
|
|
|
|
\begin{quote} |
|
|
\begin{DUoptionlist} |
|
|
\item[-{}-help] show help |
|
|
|
|
|
\item[-v] verbose |
|
|
\end{DUoptionlist} |
|
|
\end{quote} |
|
|
|
|
|
\begin{description} |
|
|
\item[{In a definition list:}] \leavevmode |
|
|
\begin{DUoptionlist} |
|
|
\item[-{}-help] show help |
|
|
|
|
|
\item[-v] verbose |
|
|
\end{DUoptionlist} |
|
|
|
|
|
\end{description} |
|
|
|
|
|
|
|
|
\subsection{3.5 Monospaced non-alphanumeric characters% |
|
|
\label{monospaced-non-alphanumeric-characters}% |
|
|
} |
|
|
|
|
|
These are all ASCII characters except a-zA-Z0-9 and space: |
|
|
|
|
|
\texttt{!!!\textquotedbl{}\textquotedbl{}\textquotedbl{}\#\#\#\$\$\$\%\%\%\&\&\&'{}'{}'((()))***+++,{},{},-{}-{}-...///:::} |
|
|
|
|
|
\texttt{;;;<{}<{}<===>{}>{}>???@@@{[}{[}{[}\textbackslash{}\textbackslash{}\textbackslash{}{]}{]}{]}\textasciicircum{}\textasciicircum{}\textasciicircum{}\_\_\_`{}`{}`\{\{\{|||\}\}\}\textasciitilde{}\textasciitilde{}\textasciitilde{}} |
|
|
|
|
|
\texttt{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} |
|
|
|
|
|
The two lines of non-alphanumeric characters should both have the same |
|
|
width as the third line. |
|
|
|
|
|
|
|
|
\subsection{3.6 Non-ASCII characters% |
|
|
\label{non-ascii-characters}% |
|
|
} |
|
|
|
|
|
Punctuation and footnote symbols |
|
|
|
|
|
\setlength{\DUtablewidth}{\linewidth} |
|
|
\begin{longtable*}[c]{|p{0.028\DUtablewidth}|p{0.424\DUtablewidth}|} |
|
|
\hline |
|
|
|
|
|
– |
|
|
& |
|
|
en-dash |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
— |
|
|
& |
|
|
em-dash |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
‘ |
|
|
& |
|
|
single turned comma quotation mark |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
’ |
|
|
& |
|
|
single comma quotation mark |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
‚ |
|
|
& |
|
|
low single comma quotation mark |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
“ |
|
|
& |
|
|
double turned comma quotation mark |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
” |
|
|
& |
|
|
double comma quotation mark |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
„ |
|
|
& |
|
|
low double comma quotation mark |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
† |
|
|
& |
|
|
dagger |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
‡ |
|
|
& |
|
|
double dagger |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
\ding{169} |
|
|
& |
|
|
black diamond suit |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
\ding{170} |
|
|
& |
|
|
black heart suit |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
♠ |
|
|
& |
|
|
black spade suit |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
♣ |
|
|
& |
|
|
black club suit |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
… |
|
|
& |
|
|
ellipsis |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
™ |
|
|
& |
|
|
trade mark sign |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
⇔ |
|
|
& |
|
|
left-right double arrow |
|
|
\\ |
|
|
\hline |
|
|
\end{longtable*} |
|
|
|
|
|
The \DUroletitlereference{Latin-1 extended} Unicode block |
|
|
|
|
|
\setlength{\DUtablewidth}{\linewidth} |
|
|
\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}|} |
|
|
\hline |
|
|
|
|
|
% |
|
|
& |
|
|
0 |
|
|
& |
|
|
1 |
|
|
& |
|
|
2 |
|
|
& |
|
|
3 |
|
|
& |
|
|
4 |
|
|
& |
|
|
5 |
|
|
& |
|
|
6 |
|
|
& |
|
|
7 |
|
|
& |
|
|
8 |
|
|
& |
|
|
9 |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
160 |
|
|
& & |
|
|
¡ |
|
|
& |
|
|
¢ |
|
|
& |
|
|
£ |
|
|
& & |
|
|
¥ |
|
|
& |
|
|
¦ |
|
|
& |
|
|
§ |
|
|
& |
|
|
¨ |
|
|
& |
|
|
© |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
170 |
|
|
& |
|
|
ª |
|
|
& |
|
|
« |
|
|
& |
|
|
¬ |
|
|
& |
|
|
\- |
|
|
& |
|
|
® |
|
|
& |
|
|
¯ |
|
|
& |
|
|
° |
|
|
& |
|
|
± |
|
|
& |
|
|
² |
|
|
& |
|
|
³ |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
180 |
|
|
& |
|
|
´ |
|
|
& |
|
|
µ |
|
|
& |
|
|
¶ |
|
|
& |
|
|
· |
|
|
& |
|
|
¸ |
|
|
& |
|
|
¹ |
|
|
& |
|
|
º |
|
|
& |
|
|
» |
|
|
& |
|
|
¼ |
|
|
& |
|
|
½ |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
190 |
|
|
& |
|
|
¾ |
|
|
& |
|
|
¿ |
|
|
& |
|
|
À |
|
|
& |
|
|
Á |
|
|
& |
|
|
 |
|
|
& |
|
|
à |
|
|
& |
|
|
Ä |
|
|
& |
|
|
Å |
|
|
& |
|
|
Æ |
|
|
& |
|
|
Ç |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
200 |
|
|
& |
|
|
È |
|
|
& |
|
|
É |
|
|
& |
|
|
Ê |
|
|
& |
|
|
Ë |
|
|
& |
|
|
Ì |
|
|
& |
|
|
Í |
|
|
& |
|
|
Î |
|
|
& |
|
|
Ï |
|
|
& |
|
|
Ð |
|
|
& |
|
|
Ñ |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
210 |
|
|
& |
|
|
Ò |
|
|
& |
|
|
Ó |
|
|
& |
|
|
Ô |
|
|
& |
|
|
Õ |
|
|
& |
|
|
Ö |
|
|
& |
|
|
× |
|
|
& |
|
|
Ø |
|
|
& |
|
|
Ù |
|
|
& |
|
|
Ú |
|
|
& |
|
|
Û |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
220 |
|
|
& |
|
|
Ü |
|
|
& |
|
|
Ý |
|
|
& |
|
|
Þ |
|
|
& |
|
|
ß |
|
|
& |
|
|
à |
|
|
& |
|
|
á |
|
|
& |
|
|
â |
|
|
& |
|
|
ã |
|
|
& |
|
|
ä |
|
|
& |
|
|
å |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
230 |
|
|
& |
|
|
æ |
|
|
& |
|
|
ç |
|
|
& |
|
|
è |
|
|
& |
|
|
é |
|
|
& |
|
|
ê |
|
|
& |
|
|
ë |
|
|
& |
|
|
ì |
|
|
& |
|
|
í |
|
|
& |
|
|
î |
|
|
& |
|
|
ï |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
240 |
|
|
& |
|
|
ð |
|
|
& |
|
|
ñ |
|
|
& |
|
|
ò |
|
|
& |
|
|
ó |
|
|
& |
|
|
ô |
|
|
& |
|
|
õ |
|
|
& |
|
|
ö |
|
|
& |
|
|
÷ |
|
|
& |
|
|
ø |
|
|
& |
|
|
ù |
|
|
\\ |
|
|
\hline |
|
|
|
|
|
250 |
|
|
& |
|
|
ú |
|
|
& |
|
|
û |
|
|
& |
|
|
ü |
|
|
& |
|
|
ý |
|
|
& |
|
|
þ |
|
|
& |
|
|
ÿ |
|
|
& & & & \\ |
|
|
\hline |
|
|
\end{longtable*} |
|
|
|
|
|
\begin{itemize} |
|
|
\item The following line should not be wrapped, because it uses |
|
|
no-break spaces (\textbackslash{}u00a0): |
|
|
|
|
|
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 |
|
|
|
|
|
\item Line wrapping with/without breakpoints marked by soft hyphens |
|
|
(\textbackslash{}u00ad): |
|
|
|
|
|
pdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-schpdn\-derd\-mdtd\-ri\-sch |
|
|
|
|
|
pdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrischpdnderdmdtdrisch |
|
|
\end{itemize} |
|
|
|
|
|
|
|
|
\subsection{3.7 Encoding special chars% |
|
|
\label{encoding-special-chars}% |
|
|
} |
|
|
|
|
|
The LaTeX Info pages lists under “2.18 Special Characters” |
|
|
|
|
|
\begin{quote} |
|
|
The following characters play a special role in LaTeX and are called |
|
|
“special printing characters”, or simply “special characters”. |
|
|
|
|
|
\begin{quote} |
|
|
\# \$ \% \& \textasciitilde{} \_ \textasciicircum{} \textbackslash{} \{ \} |
|
|
\end{quote} |
|
|
\end{quote} |
|
|
|
|
|
The special chars verbatim: |
|
|
|
|
|
\begin{quote} |
|
|
\begin{alltt} |
|
|
# $ % & ~ _ ^ \textbackslash{} \{ \} |
|
|
\end{alltt} |
|
|
\end{quote} |
|
|
|
|
|
However also \emph{square brackets} {[}{]} need special care. |
|
|
|
|
|
\begin{quote} |
|
|
Commands with optional arguments (e.g. \texttt{\textbackslash{}item}) check |
|
|
if the token right after the macro name is an opening bracket. |
|
|
In that case the contents between that bracket and the following |
|
|
closing bracket on the same grouping level are taken as the |
|
|
optional argument. What makes this unintuitive is the fact that |
|
|
the square brackets aren’t grouping characters themselves, so in |
|
|
your last example item{[}{[}…{]}{]} the optional argument consists of |
|
|
{[}… (without the closing bracket). |
|
|
\end{quote} |
|
|
|
|
|
Compare the items in the following lists: |
|
|
|
|
|
\begin{itemize} |
|
|
\item simple item |
|
|
|
|
|
\item {[}bracketed{]} item |
|
|
\end{itemize} |
|
|
|
|
|
\begin{description} |
|
|
\item[{simple}] \leavevmode |
|
|
description term |
|
|
|
|
|
\item[{{[}bracketed{]}}] \leavevmode |
|
|
description term |
|
|
|
|
|
\end{description} |
|
|
|
|
|
The OT1 font-encoding has different characters for the less-than, |
|
|
greater-than and bar, < | >, except for typewriter font \DUroletitlereference{cmtt}: |
|
|
|
|
|
\begin{quote} |
|
|
\begin{alltt} |
|
|
< | > |
|
|
\end{alltt} |
|
|
\end{quote} |
|
|
|
|
|
|
|
|
\subsection{3.8 Hyperlinks and -targets% |
|
|
\label{hyperlinks-and-targets}% |
|
|
} |
|
|
|
|
|
In LaTeX, we must set an explicit anchor (\texttt{\textbackslash{}phantomsection}) for a |
|
|
% |
|
|
\phantomsection\label{hypertarget-in-plain-text}hypertarget in plain text or in a figure but not in a longtable or |
|
|
caption: |
|
|
|
|
|
\setlength{\DUtablewidth}{\linewidth} |
|
|
\begin{longtable}[c]{|p{0.075\DUtablewidth}|p{0.075\DUtablewidth}|p{0.075\DUtablewidth}|} |
|
|
\caption{Table with % |
|
|
\label{hypertarget-in-table-title}hypertarget in table title.}\\ |
|
|
\hline |
|
|
|
|
|
False |
|
|
& |
|
|
True |
|
|
& |
|
|
None |
|
|
\\ |
|
|
\hline |
|
|
\end{longtable} |
|
|
\label{table-label} |
|
|
|
|
|
\begin{figure} |
|
|
\phantomsection\label{figure-label} |
|
|
\noindent\makebox[\linewidth][c]{\includegraphics{../../../docs/user/rst/images/biohazard.png}} |
|
|
\caption{Figure with % |
|
|
\label{hypertarget-in-figure-caption}hypertarget in figure caption.} |
|
|
\begin{DUlegend} |
|
|
Legend with % |
|
|
\phantomsection\label{hypertarget-in-figure-legend}hypertarget in figure legend. |
|
|
\end{DUlegend} |
|
|
\end{figure} |
|
|
|
|
|
\includegraphics{../../../docs/user/rst/images/biohazard.png} |
|
|
\phantomsection\label{image-label} |
|
|
|
|
|
See \hyperref[hypertarget-in-plain-text]{hypertarget in plain text}, |
|
|
\hyperref[table-label]{table label}, \hyperref[hypertarget-in-table-title]{hypertarget in table title}, |
|
|
\hyperref[figure-label]{figure label}, \hyperref[hypertarget-in-figure-caption]{hypertarget in figure caption}, |
|
|
\hyperref[hypertarget-in-figure-legend]{hypertarget in figure legend}, and |
|
|
\hyperref[image-label]{image label}. |
|
|
|
|
|
|
|
|
\subsection{3.9 External references% |
|
|
\label{external-references}% |
|
|
} |
|
|
|
|
|
Long URLs should be wrapped in the PDF. |
|
|
This can be achieved with the url command which is used by the LaTeX writer |
|
|
whenever the content (name) of a reference node equals the link URL. |
|
|
|
|
|
\begin{description} |
|
|
\item[{Example:}] \leavevmode |
|
|
a long URL that should wrap in the output |
|
|
\url{http://docutils.sourceforge.net/docs/user/latex.html\#id79} |
|
|
|
|
|
\end{description} |
|
|
|
|
|
If the argument contains any “\%”, “\#”, or “\textasciicircum{}\textasciicircum{}”, or ends with \texttt{\textbackslash{}}, it can’t |
|
|
be used in the argument to another command. The argument must not contain |
|
|
unbalanced braces. |
|
|
|
|
|
The characters \textasciicircum{}, \{, \}, and \texttt{\textbackslash{}} are invalid in a “http:” or “ftp:” URL |
|
|
and not recognized as part of it: |
|
|
|
|
|
\begin{DUlineblock}{0em} |
|
|
\item[] \url{http://www.example.org}/strange\textasciicircum{}\textasciicircum{}name |
|
|
\item[] \url{http://www.example.org}\textbackslash{}using\textbackslash{}DOS\textbackslash{}paths\textbackslash{} |
|
|
\item[] \url{http://www.example.org/XML}/strange\{n\}ame |
|
|
\end{DUlineblock} |
|
|
|
|
|
They can, however be used in paths and/or filenames. |
|
|
|
|
|
Handling by the LaTeX writer: |
|
|
|
|
|
\begin{itemize} |
|
|
\item \texttt{\#}, \texttt{\textbackslash{}} and \texttt{\%} are escaped: |
|
|
|
|
|
\begin{DUlineblock}{0em} |
|
|
\item[] \href{http://www.w3.org/XML/Schema\#dev}{URL with \#} |
|
|
\url{http://www.w3.org/XML/Schema\#dev} |
|
|
\item[] \href{http://www.w3.org/XML/Schema\%dev}{URL with \%} |
|
|
\url{http://example.org/Schema\%dev} |
|
|
\item[] \href{A:DOS\\path\\}{file with DOS path}\DUfootnotemark{id42}{id41}{9} \url{A:DOS\\path\\}\DUfootnotemark{id43}{id41}{9} |
|
|
\end{DUlineblock} |
|
|
|
|
|
\DUadmonition[note]{ |
|
|
\DUtitle[note]{Note} |
|
|
|
|
|
These URLs are typeset inside a LaTeX command without error. |
|
|
|
|
|
\begin{DUlineblock}{0em} |
|
|
\item[] \url{http://www.w3.org/XML/Schema\#dev} |
|
|
\item[] \url{http://example.org/Schema\%dev} |
|
|
\item[] \url{A:DOS\\path\\}\DUfootnotemark{id44}{id41}{9} |
|
|
\end{DUlineblock} |
|
|
} |
|
|
\end{itemize} |
|
|
|
|
|
\begin{itemize} |
|
|
\item \textasciicircum{}\textasciicircum{} LaTeX’s special syntax for characters results in “strange” replacements |
|
|
(both with href and url). A warning is given. |
|
|
|
|
|
\href{../strange^^name}{file with \textasciicircum{}\textasciicircum{}}: |
|
|
\url{../strange^^name} |
|
|
|
|
|
\item Unbalanced braces, \{ or \}, will fail (both with href and url): |
|
|
|
|
|
\begin{quote} |
|
|
\begin{alltt} |
|
|
`file with \{ <../strange\{name>`__ |
|
|
`<../strange\{name>`__ |
|
|
\end{alltt} |
|
|
\end{quote} |
|
|
|
|
|
while balanced braces are suported: |
|
|
|
|
|
\begin{DUlineblock}{0em} |
|
|
\item[] \url{../strange{n}ame} |
|
|
\item[] \url{../st{r}ange{n}ame} |
|
|
\item[] \url{../{st{r}ange{n}ame}} |
|
|
\end{DUlineblock} |
|
|
\end{itemize} |
|
|
|
|
|
|
|
|
\subsection{3.10 Section titles with \hyperref[inline-markup]{inline markup}% |
|
|
\label{section-titles-with-inline-markup}% |
|
|
} |
|
|
|
|
|
|
|
|
\subsubsection{3.10.1 \emph{emphasized}, H\textsubscript{2}O and $x^2$% |
|
|
\label{emphasized-h2o-and-x-2}% |
|
|
} |
|
|
|
|
|
|
|
|
\subsubsection{3.10.2 Substitutions work% |
|
|
\label{substitutions-fail}% |
|
|
} |
|
|
|
|
|
|
|
|
\subsection{3.11 Deeply nested sections% |
|
|
\label{deeply-nested-sections}% |
|
|
} |
|
|
|
|
|
In LaTeX and HTML, |
|
|
|
|
|
|
|
|
\subsubsection{3.11.1 Level 3% |
|
|
\label{level-3}% |
|
|
} |
|
|
|
|
|
nested sections |
|
|
|
|
|
|
|
|
\paragraph{3.11.1.1 level 4% |
|
|
\label{level-4}% |
|
|
} |
|
|
|
|
|
reach at some level |
|
|
|
|
|
|
|
|
\subparagraph{3.11.1.1.1 level 5% |
|
|
\label{level-5}% |
|
|
} |
|
|
|
|
|
(depending on the document class) |
|
|
|
|
|
|
|
|
\DUtitle[sectionVI]{3.11.1.1.1.1 level 6% |
|
|
\label{level-6}% |
|
|
} |
|
|
|
|
|
an unsupported level. |
|
|
|
|
|
% unusual combinations (currently separately tested) |
|
|
% .. include:: data/latex_cornercases.txt |
|
|
|
|
|
% Preface for System Messages: |
|
|
|
|
|
|
|
|
\section{4 Error Handling% |
|
|
\label{error-handling}% |
|
|
} |
|
|
|
|
|
Any errors caught during processing will generate system messages. |
|
|
|
|
|
There should be five messages in the following, auto-generated |
|
|
section, “Docutils System Messages”: |
|
|
|
|
|
% section should be added by Docutils automatically |
|
|
|
|
|
|
|
|
\section[Docutils System Messages]{\color{red}Docutils System Messages% |
|
|
} |
|
|
|
|
|
\DUadmonition[system-message]{ |
|
|
\DUtitle[system-message]{system-message} |
|
|
\raisebox{1em}{\hypertarget{id27}{}} |
|
|
|
|
|
{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~104 |
|
|
|
|
|
\hyperlink{id28}{ |
|
|
Undefined substitution referenced: \textquotedbl{}problematic\textquotedbl{}. |
|
|
}} |
|
|
|
|
|
\DUadmonition[system-message]{ |
|
|
\DUtitle[system-message]{system-message} |
|
|
\raisebox{1em}{\hypertarget{id45}{}} |
|
|
|
|
|
{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~391 |
|
|
|
|
|
\hyperlink{id17}{ |
|
|
Unknown target name: \textquotedbl{}5\textquotedbl{}. |
|
|
}} |
|
|
|
|
|
\DUadmonition[system-message]{ |
|
|
\DUtitle[system-message]{system-message} |
|
|
\raisebox{1em}{\hypertarget{id46}{}} |
|
|
|
|
|
{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~400 |
|
|
|
|
|
\hyperlink{id19}{ |
|
|
Unknown target name: \textquotedbl{}nonexistent\textquotedbl{}. |
|
|
}} |
|
|
|
|
|
\DUadmonition[system-message]{ |
|
|
\DUtitle[system-message]{system-message} |
|
|
\raisebox{1em}{\hypertarget{id47}{}} |
|
|
|
|
|
{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~427 |
|
|
|
|
|
\hyperlink{id48}{ |
|
|
Unknown target name: \textquotedbl{}hyperlink reference without a target\textquotedbl{}. |
|
|
}} |
|
|
|
|
|
\DUadmonition[system-message]{ |
|
|
\DUtitle[system-message]{system-message} |
|
|
\raisebox{1em}{\hypertarget{id49}{}} |
|
|
|
|
|
{\color{red}ERROR/3} in \texttt{functional/input/data/standard.txt}, line~440 |
|
|
|
|
|
\hyperlink{id50}{ |
|
|
Duplicate target name, cannot be used as a unique reference: \textquotedbl{}duplicate target names\textquotedbl{}. |
|
|
}} |
|
|
|
|
|
\end{document}
|
|
|
|
