2.1   LaTeX packages

LaTeX packages (similar to Python modules or C libraries) provide means to extend or modify the LaTeX language by redefining macros or providing new ones. There is a huge selection of packages (standard as well as user contributed) coming with your TeX distribution or available at CTAN (see the TeX Catalogue).

2.2   Docutils special LaTeX macros

Some Docutils objects have no LaTeX counterpart, they will be typeset using a Docutils specific LaTeX macro (command, environment, or length) to allow customization. By convention, special macros use the prefix \DU[1].

The generated LaTeX documents should be kept processable by a standard LaTeX installation. Therefore fallback definitions are included after the custom style sheets, if a macro is required in the document.

• Custom style sheets can define alternative implementations with \newcommand, \newenvironment, and \newlength followed by \setlength.
• Definitions with raw LaTeX are part of the document body. Use \def, \renewcommand or \renewenvironment, and \setlength.

See the test output standalone_rst_latex.tex for an example of the fallback definitions and their use in the document.

2.3   Length units

LaTeX supports all length units defined for Docutils plus the following less common units:

The default length unit (added by Docutils to length specifications without unit) is the "DTP point".

For more on lengths in LaTeX, see e.g. Hypertext Help with LaTeX: Lengths

4.1   Options

Options can be specified as

• command-line options (run rst2latex.py --help to get a list of available options), or
• configuration settings (see Docutils Configuration for details).

4.2   LaTeX code

Custom LaTeX code can be placed in style sheets, the `LaTeX

System Message: WARNING/2 (docs/user/latex.txt, line 230); backlink

Inline interpreted text or phrase reference start-string without end-string.

preamble`_, the document body (raw LaTeX), or custom templates.

5.1   admonitions

Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can.

Command:

\DUadmonition

Default:

Typeset in a frame (90 % of text width).

The admonition title is typeset with the \DUtitle command which also takes a class argument. See topic title

Example 1:

A lighter layout without the frame:

\newcommand{\DUadmonition}[2][class-arg]{%
  % try \DUadmonition#1{#2}:
  \ifcsname DUadmonition#1\endcsname%
    \csname DUadmonition#1\endcsname{#2}%
  \else
    \begin{quote}
      #2
    \end{quote}
  \fi
}

The first part of this definition acts as a "dispatcher". This way it is possible to define a special handling of specific admonitions based on the "class" argument.

Example 2:

Use .. note:: for a margin note:

\newcommand{\DUadmonitionnote}[1]{\marginpar{#1}}

Make sure there is enough space to fit the note. See also the marginnote and pdfcomment packages.

5.2   custom interpreted text roles

The rst role directive allows defining custom text roles that mark parts of inline text (spans) with a class argument.

• Role names and class arguments are converted to conform to the regular expression [a-z][-a-z0-9]* (see class directive).

• Class arguments may contain numbers and hyphens, which need special treatment in LaTeX command names. (The special command \@namedef can help with the definition of corresponding commands.)

• Custom roles can have multiple class arguments.

  In contrast to HTML/CSS, the order of the class arguments might matter.

Commands:

\DUrole: dispatcher command

\DUroleCLASSARGUMENT: optional styling command

Default:

The definition of \DUrole{CLASSARGUMENT}{} calls the macro named \DUroleCLASSARGUMENT{}[2] if it is defined (but silently ignores this class argument if a corresponding macro is not defined).

Example 1:

Typeset text in small caps:

.. role:: smallcaps

:smallcaps:`Fourier` transformation

This is transformed to the LaTeX code:

\DUrole{smallcaps}{Fourier} transformation

The definition

\newcommand{\DUrolesmallcaps}{\textsc}

as raw LaTeX or in the custom style sheet will give the expected result (if the text font supports small caps).

Example 2:

Subscript text in normal size and italic shape:

.. role:: sub(subscript)

As "sub" inherits from the standard "subscript" role, the LaTeX macro only needs to set the size and shape:

\newcommand{\DUrolesub}{\normalsize\itshape}

Example 3:

A role with several classes and a converted class name:

.. role:: custom4
   :class: argI argII arg_3

is translated to the nested commands:

\DUrole{argi}{\DUrole{argii}{\DUrole{arg-3}{<content>}}}

With the definitions:

\newcommand{\DUroleargi}[1]{\textsc}
\newcommand{\DUroleargii}[1]{{\large #1}}
\makeatletter
\@namedef{DUrolearg-3}{\textbf}
\makeatother

in a style sheet[3] or as raw LaTeX in the document source, text styled with :custom4:`large bold small-caps` will be typeset accordingly.

5.3   definition lists

ReStructuredText definition lists correspond to HTML <dl> list objects.

Environment:

description: LaTeX standard environment

Command:

\descriptionlabel: styling macro for the description term

Default:

bold label text, hanging indent

Example:

A non-bold label can be achieved with:

\renewcommand\descriptionlabel[1]{\hspace\labelsep \normalfont #1}

5.4   document class

There are hundreds of LaTeX document classes installed by modern LaTeX distributions, provided by publishers, or available at CTAN. The TeX Catalogue lists most of them.

Popular document classes:

• article, report, book: standard document classes
• scrartcl, scrrprt, scrbook: KOMA-script classes
• memoir: highly configurable class for larger documents

Option:

documentclass

5.5   document info

Content of the bibliographic fields at the top of a document. By default, docinfo items are typeset as a table.

Options:

use-latex-docinfo, use-latex-abstract

Length:

\DUdocinfowidth: the width for the docinfo table.

Default:

90 % of text width: 0.9\textwidth

Example:

set to 70 % of text width:

\newlength{\DUdocinfowidth}
\setlength{\DUdocinfowidth}{0.7\textwidth}

5.6   document title

A lone top-level section title is (usually) transformed to the document title (see section structure).

The format of the document title is defined by the document class. The "article" document class uses an in-page title and the "report" and "book" classes write a separate title page. See the TeX FAQ on how to customize the style of document titles.

The default title page shows only title and subtitle, date and author are shown in the document info table.

Options:

use-latex-docinfo

--template=titlepage.tex Put docinfo and abstract into the title page. A separate title page is used also with the "abstract" document class.

5.7   field lists

Field lists may be used as generic two-column table constructs in documents.

Environment:

DUfieldlist

Default:

Indented description list.

Example:

Use a description list customized with enumitem:

\usepackage{enumitem}
\newenvironment{DUfieldlist}%
  {\description[font=,style=sameline,leftmargin=8em]}
  {\enddescription}
}

The KOMA-script classes provide a similar environment under the name labeling.

5.8   figure and table captions

The caption package provides many ways to customise the captions in floating environments like figure and table.

The chngcntr package helps to configure the numbering of figure and table caption numberings.

Some document classes (e.g. KOMA-script) provide additional configuration. Also see the related LaTeX FAQ entry

Example

\usepackage{caption}
\captionsetup{justification=raggedleft,singlelinecheck=false}

5.9   figure placement

Figures might be typeset at the place of definition (default) or "float" to a suitable place at the top or bottom of a page. This is implemented using the float package.

Command:

\floatplacement

The placement setting is valid from the point of definition until the next \floatplacement command or the end of the document. See float.pdf for details.

Default:

\floatplacement{figure}{H} (here definitely). This corresponds most closely to the source and HTML placement (principle of least surprise).

Example 1:

In a custom style sheet, set the default to let LaTeX find a suitable place for figure floats:

\usepackage{float}
\floatplacement{figure}{htbp} % here, top, bottom, extra-page

Example 2:

To move all following figures to the top or bottom of the page write in the document source:

.. raw:: latex

    \floatplacement{figure}{tb}

5.10   font

The selected text font influences the look, the feel, and the readability of the document (cf. http://www.csarven.ca/web-typography). Selecting a suitable font also solves the problem with bad looking PDF output.

Font selection is one of the main differences between LaTeX and XeTeX:

LaTeX

cannot use the fonts of the operating system directly but needs specially installed fonts with additional supporting files.

XeTeX

can use system fonts and provides access to the full feature set of modern OpenType fonts.

The default font setup is done in the latex-preamble:

LaTeX

PDF standard fonts (Times, Helvetica, Courier)

XeTeX

Linux Libertine, a free, high quality alternative to Times with a wide coverage of glyphs, styles, and OpenType features.

Despite its name, Linux Libertine can be used on any operating system that can handle OpenType fonts.

Alternative fonts can be selected by

LaTeX

1. specifying the corresponding LaTeX package(s) as argument to the stylesheet option or with the \usepackage LaTeX command.
   • packages can be combined,
   • passing options to a package is only possible in a style sheet or the LaTeX preamble.
2. changing the font-default macros \rmdefault, \sfdefault and/or \ttdefault in a custom style sheet, the LaTeX preamble or raw LaTeX.

Example 1:

Use Latin Modern. LaTeX code:

\usepackage{lmodern}

Command line argument:

--stylesheet=lmodern

Example 2:

The Times/Helvetica/Courier PDF standard fonts are selected by the LaTeX code [4]:

\usepackage{mathptmx}            % Times for serif and math
\usepackage[scaled=.90]{helvet}  % downscaled Helvetica for sans serif
\usepackage{courier}             % Courier for teletype (mono-space)

Since Docutils 0.7, this is the default value of the latex-preamble option.

[4]	When generating PDF-files from LaTeX, the PDF standard fonts do not need to be embedded in the document. While this results in smaller files, the actually used fonts on screen and in print might differ! (For details see, e.g., the testflow package documentation.)

Example 3:

Use the teletype font from the txfonts package. As there is no package for this, we re-define the font macro with the LaTeX code:

\renewcommand{\ttdefault}{txtt}

XeTeX

using the macros of the fontspec package. Use some font-viewer or -manager (e.g. fontmatrix) to find out the correct names of the fonts on your system.

Example:

DejaVu, very wide coverage, screen optimized. As this font runs wide, add DIV=10 to the documentoptions:

\setmainfont{DejaVu Serif}
\setsansfont{DejaVu Sans}
\setmonofont[HyphenChar=None]{DejaVu Sans Mono}

5.11   font encoding

LaTeX font encodings are described in detail in the encguide which is part of the LaTeX base documentation.

Option:

font-encoding

Default:

"T1"

Example 1:

Use the (obsolete) LaTeX default encoding "OT1":

--font-encoding=OT1

or (without loading the fontenc package):

--font-encoding=""

This will improve the look on screen with the default Computer Modern fonts at the expense of problems with search and text extraction The recommended way is to select a T1-encoded "Type 1" (vector) font, for example Latin Modern

Example 2:

Support for characters in the Unicode blocks Latin, Latin-1 Supplement, and Greek together with a T1-encoded "Type 1" (vector) font, for example Latin Modern:

--font-encoding=LGR,T1 --stylesheet=lmodern

5.12   font size

Add font size in points to the document options, e.g. --documentoptions=12, use e.g. the document classes provided by extsizes for values other than [10,11,12].

5.13   footnotes

By default, footnotes are set with Docutils-specific wrappers around the standard \footnotemark and \footnotetext commands. You can configure the footnote layout similar to standard LaTeX footnotes in a custom style sheet.

Further configuration is possible by alternative definitions of \DUfootnotemark and \DUfootnotetext

Example 1:

Set footnote text with a hanging indent.

• This is the default with KOMA-script classes, e.g:

  --documentclass=scrartcl
  

  (for further configuration, see the KOMA-script Guide),

• with package footmisc:

  \usepackage[hang]{footmisc}
  \setlength{\footnotemargin}{0em}
  

  (play with the \footnotemargin setting),

• redefine \DUfootnotetext inserting hangindent:

  \newcommand{\DUfootnotetext}[4]{%
    \begingroup%
    \renewcommand{\thefootnote}{%
      \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
      \protect\hyperlink{#2}{#3}}%
      \footnotetext{\hangindent=2em #4}%
    \endgroup%
  }
  

  (adapt the \hangindent value).

Example 2:

place the footnote text where it appears in the source document (instead of at the page bottom). This can be used to get the effect of endnotes (needs the hanging package):

\usepackage{hanging}
\newcommand{\DUfootnotetext}[4]{%
  \par\noindent\raisebox{1em}{\hypertarget{#1}{}}%
  \hyperlink{#2}{#3}%
  \hangpara{\parindent}{1}#4%
}

5.14   hyphenation

The amount of hyphenation is influenced by \hyphenpenalty, setting it to 10000 almost prevents hyphenation. As this produces lines with more space between words one should increase Latex's \tolerance for this.

Example:

\hyphenpenalty=5000
\tolerance=1000

5.15   hyperlinks

Options:

hyperlink-color, hyperref-options

Hyperlinks are realized using the hyperref package. As it re-defines many standard LaTeX macros, this package is loaded last, after the style sheets.

However, you can load hyperref before a package that requires its presence in a style sheet or the LaTeX preamble (see example below). This will ignore options set with hyperlink-color and hyperref-options.

URLs are typeset with the "url" package (loaded implicitely by "hyperref"). The font of URLs can be defined with the \urlstyle command. Valid arguments are

Example:

Custom loading of the hyperref package also switches to the LaTeX default (monospaced fonts for URLs). Reset to use the text font:

\usepackage[unicode,colorlinks=true,linkcolor=green]{hyperref}
\urlstyle{same}

See also non-breaking hyperlinks.

\usepackage{nohyperref,url}
\urlstyle{same}

5.16   line blocks

In line blocks, newlines and leading whitespace are respected.

Environment:

DUlineblock: special list environment for line blocks

Length:

\DUlineblockindent: indentation of indented lineblock parts.

Default:

2.5 times the font hight: 2.5em

Example:

set to the paragraph indentation:

\newlength{\DUlineblockindent}
\setlength{\DUlineblockindent}{\parindent}

5.17   line spacing

Commands:

\linespread: for small adjustments

\singlespacing, \onehalfspacing, and \doublespacing: from package setspace

Example 1:

Get document wide double spacing:

\usepackage{setspace}
\doublespacing

Example 2:

Increase line spacing by five percent for better readability:

\linespread{1.05}

5.18   literal blocks

No markup processing is done within a literal block. It is left as-is, and is typically rendered in a monospaced typeface

Option:

literal-block-env

Example:

--literal-block-env=lstlisting

The lstlisting environment is highly configurable (as documented in listings.pdf), for instance

\renewcommand{\ttdefault}{txtt}
\lstset{language=Python, morekeywords=[1]{yield}}
\lstloadlanguages{Python}
\lstset{
  basicstyle=\ttfamily,
  keywordstyle=\bfseries,
  commentstyle=\rmfamily\itshape,
  stringstyle=\slshape,
}
\lstset{showstringspaces=false}
\lstset{columns=fullflexible,
     basewidth={0.5em,0.4em}}

The indentation of literal blocks can be reset with

\lstset{resetmargins=true}

and/or configured with e. g.:

\lstset{xleftmargin=-2em}

5.19   list of figures/tables

Docutils does not support lists of figures or tables.

However, with LaTeX, they can be generated using raw LaTeX in the document source.

Commands:

\listoffigures: a list of figures

\listoftables: a list of tables

Example:

.. raw:: latex

   \listoffigures

5.20   option list

Option lists are two-column lists of command-line options and descriptions, documenting a program's options.

Environment:

DUoptionlist: environment for option lists,

Command:

\DUoptionlistlabel: set appearance of the options

Example:

set command options with a bold monospace font:

\newcommand{\DUoptionlistlabel}{\texttt{\textbf{#1}} \hfill}

5.21   page breaks

• Page breaks before top-level sections are the default with a documentclass that provides "chapters", e.g. "book", "memoir" or "scrbook".
• Redefining the section or section* command in a style sheet is possible too.
• Raw LaTeX or a custom role can be used.
• The transition element can be re-defined to produce a page break,

Commands

\newpage: hard pagebreak at exactly this position

\pagebreak[2]: recommended page break after line end (precedence 1...4)

Example:

Define the transition command as page break with the LaTeX code:

\newcommand*{\DUtransition}{\pagebreak[4]}

(use \renewcommand with raw LaTeX).

5.22   page layout

By default, paper size and margin settings are determined by the document class.

The following packages help to configure the page layout:

1. The typearea package (part of the KOMA-script bundle) calculates a good page layout (based on rules and recommendations of typography experts).

   See the KOMA-Script Guide for details on what is a good layout and how this is achieved.

2. The geometry package is recommended if you have to follow guidelines with fixed values for the margins. For details see the geometry manual.

Example 1:

Let typearea determine the type area with DIV=calc in the documentoptions:

--documentoptions='a4paper,DIV=calc'

The DIV option can also be specified, like DIV=10. It defines how "crowded" a page will be: larger values mean larger text area (at the expense of readability).

Example 2:

LaTeX code to set margins with the geometry package:

\usepackage{geometry}
\geometry{hmargin={3cm,0.8in},height=8in}
\geometry{height=10in}.

5.23   page headers and footers

With the fancyhdr package or the KOMA-script classes, you can define custom page head- and foot-lines.

The "header" and "footer" directives save their content in the macros \DUheader rsp. \DUfooter. The macros can be used in LaTeX code and will be replaced by LaTeX with the content of the directives.

Example:

LaTeX code to place left-aligned "header" and "footer" on every page with fancyhdr:

\usepackage{fancyhdr}
\fancyhead[L]{\DUheader}
\fancyfoot{} % reset
\fancyfoot[L]{\DUfooter}
\pagestyle{fancy}

5.24   page numbering

Example:

Number pages by chapter (using the chappg package):

\usepackage{chappg}

See the chappg documentation for details.

5.25   paper size

Paper geometry can be changed using --documentoptions or with the geometry package.

LaTeX code:

\usepackage{geometry}
\geometry{OPTIONLIST}

Default:

a4paper

Some possibilities:

• a4paper, b3paper, letterpaper, executivepaper, legalpaper
• landscape, portrait, twoside.

Example:

Choose A5 pager in landscape orientation with command line argument:

--documentoptions=a5paper,landscape

The same with LaTeX commands in the style sheet:

\usepackage{geometry}
\geometry{a5paper,landscape}

For details see the geometry manual.

5.26   paragraph indent

Default (in most document classes):

Indent the first line in a paragraph unless it is the first line of a chapter, section, subsection, or subsubsection.

Example:

To set paragraph indentation to zero but add a vertical space between load the parskip package with the command line argument:

--stylesheet=parskip

or in a custom style sheet with:

\usepackage{parskip}

5.27   rubric

A rubric is like an informal heading that doesn't correspond to the document's structure.

Command:

\DUrubric

Default:

subsubsection style, italic, centred

Example:

set flushleft and red:

\newcommand*{\DUrubric}[2][class-arg]{%
   \subsubsection*{{\color{red}#1}\hfill}}

5.28   section numbering

Sections are numbered if there is a sectnum directive in the document.

Option: sectnum_xform

--section-numbering, --no-section-numbering

If sectnum_xform is False, section numbers are generated by LaTeX. In this case the "prefix" and "suffix" arguments of the sectnum directive are ignored. The section number style is determined by the document class and can be configured in a LaTeX style sheet, e.g.:

\setcounter{secnumdepth}{5}

5.29   sidebar

Sidebars are like miniature, parallel documents that occur inside other documents, providing related or reference material. They can be likened to super-footnotes; their content is outside of the flow of the document's main text.

Command:

DUsidebar

Default:

Box with grey background.

Example 1:

Less space before the title:

\providecommand{\DUsidebar}[2]{%
    \begin{center}
      \colorbox[gray]{0.90}{\parbox{0.9\textwidth}{%
        \smallskip\textbf{#1}\smallskip
        #2}}
    \end{center}
}

Example 2:

Use margin notes:

\newcommand{\DUsidebar}[2]{\marginpar{\flushleft \textbf{#1} #2}}

• Make sure the margin is wide enough to hold the note.
• This fails with some constructs inside the side bar and where marginpar cannot be used, e.g., inside floats, footnotes, or in frames made with the framed package (see marginnote).

5.30   size of a pixel

The length unit px is a "relative length" whose value depends on the resolution of the output device (usually specified in dots per inch (DPI). However, when producing a PDF, the resolution of the output device (printer, screen (for PDF-viewer)) is generally not known.

With pdftex, the "resolution" is a configuration setting.

Default:

72 DPI, i.e. 1 px = 1/72 in.

Example:

Set a resolution of 96 DPI with the LaTeX code:

\pdfpxdimen=1in % 1 DPI
\divide\pdfpxdimen by 96 % 96 DPI

5.31   topic element

A topic is like a block quote with a title, or a self-contained section with no subsections.

Topics and rubrics can be used at places where a section title is not allowed (e.g. inside a directive).

Command:

DUtopic

Default:

"quote" environment

Example 1:

If you generally prefer a "normal" section over a block quote, define:

\newcommand{\DUtopic}[2][class-arg]{%
  \ifcsname DUtopic#1\endcsname%
    \csname DUtopic#1\endcsname{#2}%
  \else
    #2
  \fi
}

Example 2:

If you want a "normal" section for topics with class argument "noquote", define:

\newcommand{\DUtopicnoquote}[1]{#1}

5.32   topic title

The titles of admonitions, sidebar, and topic element are defined with the \DUtitle command that also takes a "class" argument.

Example 1:

a centered and somewhat larger title for topcis:

\newcommand*{\DUtitletopic}[1]{\subsection*{\centering #1}

Example 2:

a right-pointing hand as title for the "attention" directive:

\usepackage{pifont}
\newcommand{\DUtitleattention}[1]{\ding{43}}

The title argument is "swallowed" by the command. To have both, hand and title use:

\usepackage{pifont}
\newcommand{\DUtitleattention}[1]{\ding{43} #1}

5.33   table of contents

A contents directive is replaced by a table of contents (ToC).

Option: use-latex-toc

--use-latex-toc, --use-docutils-toc

With use-latex-toc (default since release 0.6):

• The ToC is generated by LaTeX (via the \tableofcontents command).

  The layout depends on the choosen document class and can be configured in a custom style sheet (see e.g. the KOMA-Script Guide for the KOMA-script classes).

• The depth of the ToC and PDF-bookmarks can be configured

  • with the "depth" argument of the contents directive, or
  • in a style sheet with e.g. \setcounter{tocdepth}{5}.

• Local ToCs are done with the minitoc package. See the minitoc documentation for the numerous configuration options.

5.34   title reference role

Title reference is the default default role for interpreted text.

Command:

\DUroletitlereference

Default:

use slanted font (\textsl)

Example:

set title references with a bold monospace font:

\newcommand{\DUroletitlereference}[1]{\texttt{\textbf{#1}}}

5.35   text encoding

The encoding of the LaTeX source file is Docutils' output encoding but LaTeX' input encoding.

Option: output-encoding

--output-encoding=OUTPUT-ENCODING

Default:

"utf8"

Example:

Encode the LaTeX source file with the ISO latin-1 (west european) 8-bit encoding (the default in Docutils versions up to 0.6.):

--output-encoding=latin-1

Note:

LaTeX comes with two options for UTF-8 support,

utf8:	by the standard inputenc package with only limited coverage (mainly accented characters).
utf8x:	supported by the ucs package covers a wider range of Unicode characters than does "utf8". It is, however, a non-standard extension and no longer developed.

Currently (in version 0.6), "utf8" is used if the output-encoding is any of "utf_8", "U8", "UTF", or "utf8".

5.36   transition element

Transitions are commonly seen in novels and short fiction, as a gap spanning one or more lines, marking text divisions or signaling changes in subject, time, point of view, or emphasis.

Command:

\DUtransition

Default:

A horizontal line, 1/3 of text width

Example 1:

Use three stars:

\newcommand*{\DUtransition}[1][class-arg]{\centering{}*\quad*\quad*}

Alternatively use the more elaborated version in transition-stars.sty.

Example 2:

If paragraphs are separated by indentation, you can simply use a vertical space:

\newcommand*{\DUtransition}[1][class-arg]{\vspace{2ex}}

7.1   Troubleshooting

Package hyperref Warning: Glyph not defined in PD1 encoding,
(hyperref)                removing `\CYRZ' on input line 6.
...

--hyperref-option=unicode

--hyperref-option="unicode=false"

[xetex writer]

hyperref-option: unicode=false

! Package textcomp Error: Symbol \textcurrency not provided by
(textcomp)                font family ptm in TS1 encoding.
(textcomp)                Default family used instead.

7.2   Bugs and open issues

Open to be fixed or open to discussion.

See also the entries in the Docutils TODO list, the BUGS documentation and the SourceForge Bug Tracker.