# Generating LaTeX with Docutils

Author:

  Engelbert Gruber, Günter Milde

Contact:
  docutils-develop@lists.sourceforge.net
Revision:
  10331
Date:
  2026-05-08
Copyright:
  This document has been placed in the public domain.

Abstract

This document covers topics specific to Docutils' LaTeX export.

## 1 LaTeX

LaTeX, is a document preparation system for high-quality typesetting. It is most often used for medium-to-large technical or scientific documents but it can be used for almost any form of publishing. There exists a wide selection of LaTeX Documentation on the net and books on LaTeX and related topics. For an introduction to LaTeX see, e.g., LaTeX2e for authors [usrguide].

### 1.1 LaTeX document classes and packages

Unlike HTML with CSS, LaTeX uses one common language for markup and style definitions. Separation of content and style is realized by collecting style definitions in LaTeX classes and packages, or the document preamble.

LaTeX document classes and packages (similar to Python modules or C libraries) provide means to extend or modify the LaTeX language by redefining macros or providing new ones.

Using the document class and style sheet configuration settings, you can select from a huge selection of classes and packages (standard as well as user contributed) coming with your TeX distribution or available at CTAN as well as custom style sheets.

### 1.2 Docutils specific 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, these macros use the prefix \DU[1]. Fallback definitions are included after the custom style sheets, for all macros required in the document. Alternatively, you may list "docutils" in the stylesheet setting to use the "docutils" package instead.

- 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 docutils.sty and the test output standalone_rst_latex.tex for an example of the fallback definitions and their use in the document.

[1]

DU for Documentation Utilities = Docutils

### 1.3 Length units

The LaTeX writer supports all reStructuredText length units with the following peculiarities:

- In LaTeX, the size of the pixel unit defaults to 1 px = 1/72 in while the CSS3 pixel unit is defined as 1 px = 1/96 in. The LaTeX conversion factor can be configured, see below for the size of a "px".

- LaTeX uses "pt" for the American point (TeX point), 1 pt = 1/72.25 in. The DTP point (Postscript point) used in CSS is available in LaTeX as big point, 1 bp = 1/72 in.

  Lengths specified in the source with unit "pt" are written with unit "bp" by the LaTeX writer. In raw LaTeX and custom style sheets, the DTP point must be specified as "bp", while "pt" is interpreted as TeX point.

- The default length unit (added by the latex writer to length values without unit) is the DTP point "bp". It will change to "px" in Docutils 1.0.

The TeX units:

bp | "big" point (DTP point) | 1 bp = 1/72 in
cc | cîcero | 1 cc = 12 dd
dd | didôt | 1 dd = 1238/1157 pt
sp | scaled point | 1sp = 1/65536pt

can be used in raw LaTeX and custom style sheets but not in reStructuredText.

## 2 PDF generation

In most cases, LaTeX code is not the desired end-format of the document. There are several programs to generate PDF documents from the LaTeX source, including:

pdflatex

  Generates a PDF document directly from the LaTeX file. Export your document with the LaTeX2e writer (writer name "latex", frontend tool rst2latex).

xelatex or lualatex

  The XeTeX and LuaTeX engines work with input files in UTF-8 encoding and system fonts. Export your document with the XeLaTeX writer (writer name "xetex", frontend tool rst2xetex).

You may need to call the respective command two or three times to get internal references correct.

rubber

  The Rubber wrapper for LaTeX and friends can be used to automatically run all programs the required number of times and delete "spurious" files. This includes processing bibliographic references or indices, as well as compilation or conversion of figures.

## 3 Configuration

### 3.1 Options/Settings

Docutils configuration settings can be specified as command-line options or configuration settings.

Run rst2latex --help to get a list of available options or see Docutils Configuration for details.

### 3.2 Classes

The "classes" attribute is one of the common attributes, shared by all Docutils elements. In HTML, the common use is to provide selection criteria for style rules in CSS stylesheets. As there is no comparable framework for LaTeX, Docutils emulates some of this behaviour via Docutils specific LaTeX macros. Due to LaTeX limitations, class arguments are ignored for some elements (e.g. a rubric).

Inline elements

  are handled via the \DUrole{} macro that calls the optional styling command \DUrole«classargument» with one argument (the role content). See custom interpreted text roles.

Block level elements

  are wrapped in "class environments": \begin{DUclass} calls the optional styling command \DUCLASS«classargument»{}, \end{DUclass} tries \endDUCLASS«classargument».

Customization is done by defining matching macros or environments.

Example 1:

  Use small caps font inside elements with class value "custom".

  Inline elements

    The LaTeX function \textsc sets the argument in small caps:

        \newcommand{\DUrolecustom}[1]{\textsc{#1}}

  Block-level elements

    The LaTeX directive (macro without argument) \scshape switches to the small caps font. Its effect is confined to the wrapper DUclass environment:

        \newcommand*{\DUCLASScustom}{\scshape}

Example 2:

  It is even possible to locally redefine other LaTeX macros, e.g. to turn bullet lists with class value "enumerateitems" into enumerated lists:

      \newcommand*{\DUCLASSenumerateitems}{%
        \renewenvironment{itemize}{\begin{enumerate}}%
                                  {\end{enumerate}}%
      }

Notes

- Class arguments may contain numbers and hyphens, which need special treatment in LaTeX command names (see class directive). The commands \csname and \endcsname or the special command \@namedef can help with the definition of corresponding macros or environments, e.g.:

      \expandafter\newcommand\csname gg1\endcsname{Definition of gg1.}

  or

      \makeatletter
      \@namedef{DUCLASSadmonition-test}{…}
      \makeatother

- Elements can have multiple class arguments. In contrast to HTML/CSS, the order of the class arguments cannot be ignored in LaTeX

- Class handling differs for some elements and class values:

  - Class argument values starting with align- are transformed to "align" argument values. Class argument values starting with language- set the elements language property.

  - The table element recognizes some special class values. See section table style.

  - If the legacy-class-functions setting is True, the special macros \DUadmonition and \DUtitle are written with a comma separated list of class values as optional argument.

### 3.3 LaTeX code

Custom LaTeX code can be placed in style sheets, the LaTeX preamble, the document body (raw LaTeX), or custom templates.

The functional tests that come with Docutils, can serve as example.

input:

  standalone_rst_latex.rst (includes files from tests/functional/input/data)

expected output:

  standalone_rst_latex.tex

#### 3.3.1 Style sheets

A common way of LaTeX customization is the preparation of custom style sheets, either as simple files with LaTeX code snippets or as home-made LaTeX packages (see [clsguide] for an introduction on LaTeX package writing).

Setting:

  stylesheet

  It is possible to specify multiple style sheets and mix LaTeX packages with custom style sheets.

You cannot specify package options with the stylesheet setting. If you need to pass options to the package, use the \usepackage command in the LaTeX preamble or a custom style sheet.

Example 1:

  Select Latin Modern fonts with the lmodern package:

      --stylesheet=lmodern

Example 2:

  Use the preamble.tex home-made custom style sheet together with the package kerkis (Bookman fonts):

      --stylesheet=kerkis,preamble.tex

Example 3:

  Select Palatino fonts with old-style numbers and true small-caps with the LaTeX command

      \usepackage[osf,sc]{mathpazo}

  in the LaTeX preamble or custom style sheets.

Stylesheet Repository

  There is a repository of user-contributed style sheets in the Docutils Sandbox.

#### 3.3.2 LaTeX preamble

Configuration by LaTeX code in the document preamble is also possible without a separate stylesheet. This way, packages can be loaded with options or commands re-defined without the need to create a separate file (new in Docutils 0.7).

Setting:

  latex-preamble

Default:

  used for font setup

Example:

  To use the better looking txtt font for monospaced text define the latex-preamble setting in a configuration file:

      latex-preamble: \renewcommand{\ttdefault}{txtt}
                      \usepackage{mathptmx}          % Times
                      \usepackage[scaled=.92]{helvet}  % Helvetica

#### 3.3.3 Templates

Some customizations require commands at places other than the insertion point of stylesheets or depend on the deletion/replacement of parts of the document. This can be done via a custom template. See the publisher documentation for a description of the document parts available in a template file.

Setting:

  template

In addition to the 'default.tex' template, the latex writer directory contains the alternatives 'titlepage.tex' (separate title page) and 'titlingpage.tex'" (separate title page with the memoir document class).

Example:

  Print a title page including docinfo, dedication, and abstract:

      --template=titlepage.tex

#### 3.3.4 Raw LaTeX

By means of the raw directive or a derived custom role, one can give commands directly to LaTeX. These can be both, styling as well as printing commands.

Example:

  Math formula:

      .. raw:: latex

         \[x^3 + 3x^2a + 3xa^2 + a^3,\]

  (Drawback: the formula will be invisible in other output formats. Better use the math directive)

Most LaTeX code examples also work as raw LaTeX inside the document. An exception are commands that need to be given in the document preamble (e.g. package loading with \usepackage, which can be achieved with the --style-sheet or --latex-preamble command line options instead). Remember to use re-defining commands for customizing Docutils specific LaTeX macros with raw LaTeX.

Example:

  Define the transition command as page break:

      .. raw:: latex

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

See also:

  - Defining a macro for a custom role.

  - Forcing page breaks.

## 4 How to configure the ...

### 4.1 admonitions

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

Environment:

  DUadmonition

  (Command \DUadmonition with legacy-class-functions.)

Default:

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

The admonition title is typeset with the \DUtitle command (see titles).

Example 1:

  A lighter layout without the frame:

      \newenvironment{DUadmonition}%
        {\begin{quote}}
        {\end{quote}}

Example 2:

  Print all admonitions in the margin:

      \usepackage{environ}
      \NewEnviron{DUadmonition}{\marginpar{\BODY}}

Example 3:

  Use the .. note:: admonition for a margin note:

      \usepackage{environ}
      \newcommand{\DUCLASSnote}{%
        \RenewEnviron{DUadmonition}{\marginpar{\BODY}}%
        \renewcommand{\DUtitle}[1]{}% suppress title ("Note")
      }

Caution!

Make sure there is enough space in the margin. \marginpar fails in some places or with some content. See also the environ and marginnote packages.

### 4.2 custom interpreted text roles

The rst role directive allows defining custom text roles that mark parts of inline text (spans) with class arguments (see section classes).

Commands:

  \DUrole: dispatcher command

  \DUrole«classargument»: optional styling command with 1 argument (the role content).

Default:

  The default definition of \DUrole{«classargument»}{} calls the macro named \DUrole«classargument»{} if it is defined and silently ignores this class argument if not.

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[2] or as raw LaTeX in the document source, text styled with :custom4:`large bold small-caps` will be typeset accordingly.

[2]

Leave out the \makeatletter - \makeatother pair if the style sheet is a LaTeX package (*.sty).

### 4.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}

### 4.4 document class

There are hundreds of LaTeX document classes installed by modern LaTeX distributions, provided by publishers, or available at CTAN.

Setting:

  documentclass

Popular document classes:

  - Standard document classes: article, report, book

  - KOMA-script classes: scrartcl, scrrprt, scrbook

  - memoir: a highly configurable document class for larger documents

### 4.5 document info

The bibliographic fields at the top of a document specify document information like author name(s) and copyright info. By default, they are typeset as a table.

Settings:

  use-latex-docinfo, use-latex-abstract

  If use-latex-docinfo is True, the content of the "Author", "Authors", "Address", "Contact", "Organization", and "Date" fields is attached to the document title (see below).

  If use-latex-abstract is True, the "Abstract" field content is placed in an "abstract" environment. The "abstract" environment can be customized or set up (for the "book" documentclass) with the "abstract" LaTeX package.

Length:
  \DUdocinfowidth (width of the docinfo table).
  Default: 0.9\textwidth (90 % of text width)
Example:

  Change the width of the docinfo table to 70 % of text width:

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

### 4.6 document title

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

Settings:

  doctitle_xform, documentclass, use-latex-docinfo, template

The format of the document title is defined by the document class and can be modified by latex packages. The "article" document class uses an in-page title while the "report" and "book" classes use a separate title page. See section Templates and the TeX FAQ on how to customize the style of document titles.

Example:

  With use-latex-docinfo, author information and date are typeset as part of the document title instead of the document info table.

  Paper by three authors, two of them from the same organisation:

      Shop Sketches
      =============

      :authors: * Mr. Mousebender
                * Mr. Arthur Wensleydale
      :organization: Ye National Cheese Emporium

      :author: Hr. Hallmackenreuther
      :organization: Bettengeschäft

  With --use-latex-docinfo, authors and their affiliations are typeset below the title using the standard LaTeX command \author with a simple hack for the common affiliation. [3]

[3]

Unfortunately, author names don't wrap if there are more authors than fit on one line in one "authors" field.

### 4.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.

### 4.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. See also The style of captions in the LaTeX FAQ.

Example

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

### 4.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}

### 4.10 font

The selected text font influences the look, the feel, and the readability of the document (cf. Typography on the information highway). Selecting a suitable font also solves the problem with bad looking PDF output.

Font selection is one of the main differences between pdflatex and xelatex/lualatex:

pdflatex

  requires specially installed fonts in a set of legacy font encodings.

xelatex and lualatex

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

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

pdflatex

  PDF standard fonts (Times, Helvetica, Courier)

xelatex/lualatex

  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

pdflatex

  1. specifying the corresponding LaTeX package(s) as argument to the stylesheet setting 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 setting.

  [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}

xelatex/lualatex

  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}

#### 4.10.1 choice of suitable fonts

With xelatex/lualatex, you may use any of the system fonts.

The LaTeX Font Catalogue provides information and examples for a wide range of fonts available for use with PdfLaTeX. Here is just a selection:

1. The Latin Modern (LM) fonts are extended outline versions of the standard TeX font Computer Modern (CM).

   `+1`

     simple invocation: --stylesheet=lmodern

   `+1`

     keeps the traditional TeX "look and feel":

     `+1`

       generally accepted as high quality CM replacement,

     `+1`

       comprehensive math support,

     `+1`

       including optical sizes,

     `+1`

       compatible with extensions made to match CM,

     `-1`

       modern types are hard to read at low (screen) resolutions.

   `-1`

     not part of a minimal standard TeX installation

2. CM-Super is another outline CM replacement.

   `+1`

     simple invocation: modern LaTeX distributions use CM-Super automatically instead of CM if it is installed.

   `-1`

     said to be of inferior quality compared to LM.

   `-1`

     not part of a minimal standard TeX installation, bigger download size than Latin Modern (64 MB).

3. Bera (Bitstream Vera)

   `+1`

     simple invocation: --stylesheet=bera

   `+1`

     optimized for on-screen viewing with goot hinting

   `-1`

     not part of a minimal standard TeX installation

4. PSNFSS Postscript fonts

   `+1`

     part of every standard TeX installation

   `+1`

     smaller PDF/Postscript document size if standard fonts are not embedded

   `-1`

     restricted set of glyphs in the free versions [5]

   `-1`

     different fonts for roman, sans-serif and typewriter fonts.

   `-1`

     invocation somewhat more complex, as several packages are required for a complete font set, sometimes including package options.

   Roman (serif) PSNFSS fonts:

   Bookman

     good legibility but very wide.

   Charter

     bread-and-butter type optimized for printing on low-resolution printers

   New Century Schoolbook

     good legibility but very wide.

   Palatino
     `+1`

       recommended by font experts

     `+1`

       good LaTeX support including matching math fonts, small caps, old-style figures

     `-1`

       bad rendering in xpdf viewer (auto-hinting leads to different x-hight for different characters at some magnifications) (this is fixed in recent versions).

   Times
     `+1`

       the serif PDF Standard Font,

     `-1`

       overused and quite narrow (devised for multi-column layouts).

   Utopia

     recommended by font experts

   Font packages for standard Postscript fonts (cf. Using common Postscript fonts with LaTeX)
   Package | Roman | Sans Serif | Typewriter | Math
   --- | --- | --- | --- | ---
   (none) | CM Roman | CM Sans Serif | CM Typewriter | CM Math
   mathpazo | Palatino |  |  | Palatino
   mathptmx | Times |  |  | Times
   helvet |  | Helvetica |  |
   avant |  | Avant Garde |  |
   courier |  |  | Courier |
   chancery | Zapf Chancery |  |  |
   bookman | Bookman | Avant Garde | Courier |
   newcent | New Century Schoolbook | Avant Garde | Courier |
   charter | Charter |  |  |
   utopia | Utopia |  |  |
   fourier | Utopia |  |  | Fourier

[5]

Extended versions of the standard Postscript fonts including accented chars, as well as real small-caps and old-style numbers are available with the TeX Gyre bundle which is part of, e.g., TeX Live.

### 4.11 font encoding

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

Setting:

  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

### 4.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].

### 4.13 footnotes

Setting:

  latex_footnotes

By default, footnote references and footnotes are set with the macros \DUfootnotemark and \DUfootnotetext using the footnote labels from the source or generated by Docutils.

If the setting latex_footnotes is True (or with the command line option --latex-footnotes), numbering and placement of footnotes is handled by LaTeX:

- Footnotes are set with the standard LaTeX \footnote command at the place of the first matching footnote reference.

- LaTeX does its best to place the footnote at the same page as the footnote reference.

- There is no distinction between numbered footnotes and symbol footnotes, by default all footnotes are numbered.

- Footnotes are sorted and numbered in the order of the footnote references.

- There is no backlink from footnote to footnote reference.

- Unreferenced footnotes are silently ignored!

Important

LaTeX footnotes in figures and table captions are dropped.

LaTeX footnotes in a sidebar and corner cases like footnotes referenced from a title and containing a footnote reference lead to compilation errors!

LaTeX offers a wide range of footnote configuration options (cf. the LaTeX WikiBook and the TeX FAQ). Additionally, the \DUfootnotemark and \DUfootnotetext commands can be configured in a custom style sheet or the LaTeX preamble.

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 [scrguide]),

  - LaTeX preamble code for hanging indent with the footmisc package:

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

    (play with the \footnotemargin setting),

Example 2:

  Footnote marks in normal font size, not superscript:

      \usepackage{scrextend} % not required with KOMA-script document classes
      \deffootnote{1em}{1em}{\thefootnotemark\ }

  (See [scrguide] for details and other options.)

Example 3:

  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 (requires the hanging package):

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

### 4.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

### 4.15 hyperlinks

Settings:

  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 implicitly by "hyperref"). The font of URLs can be defined with the \urlstyle command. Valid arguments are

same:

  normal text font, Docutils default,

tt:

  teletype (monospaced), LaTeX default,

rm:

  roman,

sf:

  sans serif

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.

#### 4.15.1 disable hyperlinks

To suppress the hyper-linking completely (e.g. for printing or to avoid clashes with other packages), set hyperref-options to "draft" or load the "nohyperref" package that comes with the "hyperref" bundle.

Setting:

  hyperref-options

LaTeX code:

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

### 4.16 language

The global document language can be set with the language-code configuration setting. The language of text parts can be set adding the language tag prefixed by "language-" to an element's classes attribute, e.g. language-el for a Greek text part.

### 4.17 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 height: 2.5em

Example:

  set to the paragraph indentation:

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

### 4.18 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}

### 4.19 literal blocks

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

Setting:

  literal-block-env

Example:

> --literal-block-env=lstlisting

> The lstlisting environment is highly configurable (as documented in listings.pdf) and provides syntax highlight for many programming languages, 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}}

> and to get LaTeX syntax highlight for a code block with "listings":

>     \lstloadlanguages{[LaTeX]TeX} %  comma separated list of languages
>     \newcommand{\DUCLASSlatex}{\lstset{language=[LaTeX]TeX}}

> The indentation of literal blocks can be reset with

>     \lstset{resetmargins=true}

> and/or configured with e. g.:

>     \lstset{xleftmargin=-2em}

### 4.20 lists

Remove extra vertical whitespace between items of bullet lists and enumerated lists.

Example:

  Pass the class argument "compact" to the list:

      .. class:: compact

      * first item
      * second item

  The following lines for the LaTeX preamble use the enumitem package to remove spacing from all lists with class argument "compact":

      \usepackage{enumitem}
      \newcommand*{\DUCLASScompact}{\setlist{noitemsep}}

### 4.21 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

### 4.22 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}

### 4.23 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).

### 4.24 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 [scrguide] 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}.

### 4.25 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}

### 4.26 page numbering

Example:

  Number pages by chapter (using the chappg package):

      \usepackage{chappg}

  See the chappg documentation for details.

### 4.27 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.

### 4.28 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 1:

  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}

Example 2:

  To suppress the indentation of a specific paragraph, you may give it the class "noindent" with, e.g.

      .. class:: noindent

      This paragraph should not be indented.

  and define the custom role command:

      \newcommand{\DUrolenoindent}[1]{\noindent #1}

### 4.29 rubric

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

Command:

  \DUrubric

Default:

  subsubsection style (unnumbered), italic

Example1:

  Set centred and red:

      \newcommand*{\DUrubric}[1]{%
         \subsubsection*{\centerline{\color{red}#1}}}

Note

Class attribute values are ignored because the "classes wrapper" interferes with LaTeX's formatting (spacing/indentation) of text following a section heading. Consider using a topic element or a container.

### 4.30 section headings

Settings: documentclass, use-part-section

Section headings are converted into LaTeX macros according to their level, the document class and the value of the use-part-section setting:

Level | article | article with part | book [6] | book with part
--- | --- | --- | --- | ---
1 | section | part | chapter | part
2 | subsection | section | section | chapter
3 | subsubsection | subsection | subsection | section
4 | paragraph | subsubsection | subsubsection | subsection
5 | subparagraph | paragraph | paragraph | subsubsection
6 | DUtitle | subparagraph | subparagraph | paragraph
7 | DUtitle | DUtitle | DUtitle | subparagraph

[6]

One of the document classes 'book', 'memoir', 'report 'scrbook', or 'scrreprt'.

### 4.31 section numbering

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

Setting: sectnum_xform

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}

Note

The LaTeX name is 'secnumdepth' (without 't').

### 4.32 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:

  Use margin notes:

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

  - 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).

### 4.33 size of a "px"

The length unit "px" is defined in pdfTeX and LuaTeX, the "XeTeX" writer uses the \pdfpxdimen macro as workaround.

Default:

  1 px = 1/72 in

Example:

  Set the value to match the CSS3 pixel unit 1 px = 1/96 in with the LaTeX code:

      \pdfpxdimen=1in
      \divide\pdfpxdimen by 96

### 4.34 table style

A pre-configured table style can be globally selected via the table_style setting or set for individual tables via a class directive or the class option of the table directives.

Supported values:

standard

  Borders around all cells.

booktabs

  Use the booktabs package for publication quality tables (no vertical rules).

borderless

  No borders around table cells.

colwidths-auto

  Column width determination by LaTeX. Overridden by the table directive option widths.

  Caution!

  Auto-sized columns work only with simple cell content.

### 4.35 table width and column widths

To support automatic line breaks, standard LaTeX tables need to know the column widths. Therefore, the LaTeX writer determines default values for both, relative column widths and the total width of a table from the table's colwidth [7] values. [8] The algorithm works sufficiently well in typical use cases. However, there are cases where the table layout requires manual intervention, for example:

- Tables where the cells contain only numbers or short text look better with auto-sized columns.

- If the input table contains verbose markup syntax, column widths in the source may be bad indicators for output column widths.

- Columns may become too narrow in tables that are nested inside lists, quotes, or similar.

To improve the table layout, you may:

- Use the table directive option width to set the table width to a custom length or percentage of the current line width.

- Adjust the table column widths in the source document or use the table directive option widths to specify column widths.

- Set the table directive option widths to the value "auto" or select the table style "colwidths-auto" to let LaTeX determine table and column widths from the table content.

  Caution!

  Auto-sized columns only work with simple cell content.

  LaTeX sets cell content in auto-sized columns in one line (merging paragraphs) and fails with other block level content.

The legacy_column_widths setting provides backwards compatibility with the (faulty) legacy algorithm.

[7] (1,2)

Docutils stores the column widths in the reStructuredText table markup (in characters) in the colwidth attribute of the table column specifications. (The colwidths of a list table or CSV table with n columns default to w i = 100 ⫽ n .) The widths table directive option can be used to provide custom values.

[8]

The default width w of a table with n columns and colwidth [7] values w i is computed using the equation

w = 100 % 40 ( n + ∑ i = 1 n w i )

with an upper limit of 100%.

### 4.36 table of contents

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

Setting:: use-latex-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 chosen document class and can be configured in a custom style sheet (see, e.g., [scrguide] for the KOMA-script classes).

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

  - with the depth option 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.

Note

Minitoc supports local ToCs only at "part" and top section level ("chapter" or "section"). Local "contents" directives at lower levels are ignored (a warning is issued).

This is an intended feature of the minitoc package. If you really require local ToCs at lower level, turn off the use-latex-toc option.

### 4.37 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}}}

### 4.38 titles

The titles of admonitions, sidebar, and topic element use the \DUtitle command which can be re-defined in the corresponding DUCLASS environment.

- The re-definition is local to the environment, so you don't need to save/restore the original function.

- In the nested function redefinition, the argument placeholder requires two hashes, #1 → ##1!

Example 1:

  a centered and somewhat larger title for topcis:

      \newcommand*{\DUCLASStopic}{
        \renewcommand*{\DUtitle}[1]{\subsection*{\centering ##1}}
      }

Example 2:

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

      \usepackage{pifont}
      \newcommand*{\DUCLASSattention}{
        \renewcommand*{\DUtitle}[1]{\ding{43}}
      }

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

      \usepackage{pifont}
      \newcommand*{\DUCLASSattention}{
        \renewcommand*{\DUtitle}[1]{\ding{43} ##1}
      }

### 4.39 text encoding

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

Setting: output_encoding

Default:

  "utf-8" (LaTeX's default input encoding)

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:

  8-bit LaTeX comes with two packages 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.

### 4.40 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).

Example:

  Use a standard paragraph for a topic:

      \newcommand{\DUCLASStopic}{%
        \renewenvironment{quote}{}{}%
      }

### 4.41 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}{\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}{\vspace{2ex}}

## 5 Changes

- The Docutils HISTORY lists all changes during the history of docutils. Important changes are summarized in the RELEASE-NOTES.

## 6 Problems

### 6.1 Troubleshooting

#### 6.1.1 Bad looking PDF output

> What I am looking for when I try Docutils is PDF files of high quality. Unfortunately that never is the case.

> So am I just stupid or is there a way to get really high quality PDF from Docutils?

Make sure the default font is not a bitmap font.

There is Latin Modern if you like the look of the standard font on paper, but want nice pdf. Or select something else like Times, Palatino, ... via configuration settings. See font and font-encoding.

#### 6.1.2 footnote mark and text at different pages

Docutils stores the footnote text in a separate node, at the position where it is specified in the input document. With the default settings, the footnote is put at the bottom of the page where the footnote text is located, maybe far away from the footnote mark (see e.g. rst/demo.rst).

To get footnote mark and text at the same page, keep footnote mark and footnote text close together or use the latex_footnotes setting.

#### 6.1.3 empty line before footnote content

If footnotes start with any body element other than a paragraph, there is a spurious vertical space after the footnote number/symbol. This is a LaTeX limitation.

#### 6.1.4 non-breaking hyperlinks

If you convert with latex (as opposed to pdflatex), hyperlinks will not wrap and sometimes stick into the margin.

Wrong:

      \usepackage[breaklinks=true]{hyperref}

  "breaklinks" is an internal option that indicates whether the chosen driver can handle split links. (It might work to disable link breaking.)

Right:

  Use one of the following:

  1. compile with pdflatex,

  2. use the package breakurl,

  3. (for printout) disable hyperlinks using the package "nohyperref".

See also the Link text doesn’t break at end line LaTeX FAQ entry.

#### 6.1.5 Glyph not defined in PD1 encoding

If a section title or other link contains non-Latin (e.g. Cyrillic) characters, the LaTeX log contains lots of warnings like:

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

This can be solved with the "unicode" hyperref_option setting:

    --hyperref-option=unicode

(works also with non-unicode input/output encoding (e.g. "koi8r" or "latin1"). Newer versions of hyperref default to "unicode=true".

#### 6.1.6 image inclusion

Images are included in LaTeX with the help of the graphicx package. The supported graphic formats depend on the postprocessor:

- pdflatex, lualatex, and xelatex work with PNG, JPG, and PDF but not EPS.

- When compiling to DVI with the latex command, support depends on the viewer or post-processor:

  - dvips supports EPS but not other format,

  - dvipdfmx works with EPS and JPG (add 'dvipdfmx' to the documentoptions or graphicx-option setting and 'bmpsize' to the stylesheet setting).

- SVG images are supported if the "svg" package is listed in the stylesheet setting. Pass the --shell-escape option to the LaTeX compiler to enable image conversion on the fly by Inkscape. (New in Docutils 0.22.)

- The Rubber wrapper can be used for automatic image conversion.

For details see [grfguide].

Docutils expects a URI-reference as pointer to the image ressource. The LaTeX writer transforms it to a filesystem path. By default, LaTeX does not accept spaces and more than one dot in the filename. If using "traditional" filenames is not an option, loading the grffile package may help.

#### 6.1.7 Why are my images too big?

In LaTeX, the size of the pixel unit defaults to 1 px = 1/72 in while the CSS3 pixel unit is defined as 1 px = 1/96 in.

This is why pixmap images without size specification or objects with a size specified in px tend to come out too large in the PDF.

Solution:

  Specify the image size in fixed length units (pt, cm, in, …) or configure the size of a "px".

#### 6.1.8 Error illegal unit px

If you convert the LaTeX source with a legacy program, you might get this error.

The unit "px" was introduced by the pdfTeX converter on 2005-02-04. pdfTeX is used also for conversion into DVI format in all modern LaTeX distributions (since ca. 2006).

#### 6.1.9 Error Symbol \textcurrency not provided ...

The currency sign (\u00a4) is not supported by all fonts (some have an Euro sign at its place). You might see an error like:

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

(which in case of font family "ptm" is a false positive).

Add either warn (turn the error in a warning, use the default (bitmap) symbol), or force,almostfull (use the symbol provided by the font at the users risk) to the document options or use a different font package.

#### 6.1.10 Warning: language … not supported

The "latex" writer uses the LaTeX package Babel and the "xetex" writer uses Polyglossia for language support (hyphenation rules, auto-text localisations and typographic rules). Polyglossia supports more languages, so switching to the "xetex" writer may help.

For short quotes or if language support is provided by the user via other LaTeX document classes and packages, the warning can be ignored.

#### 6.1.11 Search and text extraction

Search for text that contains characters outside the ASCII range might fail. See font and font encoding (as well as Searching PDF files for background information).

It may help to load the cmap package (via style sheets or the custom LaTeX preamble (see also Proper use of cmap and mmmap).

#### 6.1.12 Unicode box drawing and block characters

The easiest solution is to use xelatex or lualatex which directly support all Unicode characters (if included in the used font).

With "traditional" TeX engines (e.g. pdflatex):

- Generate LaTeX code with the default output_encoding "utf-8".

- Add the pmboxdraw package to the style sheets. (For shaded boxes also add the color package.)

Unfortunately, this defines only a subset of the characters (see pmboxdraw.pdf for a list).

### 6.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.

#### 6.2.1 Citations

Initially citations were implemented using figure floats, because hyperlinking back and forth seemed to be impossible. Later the figure directive was added that puts images into figure floats.

This results in citations and figures possibly being mixed at page foot.

Solution:

  Select citation handling with the use_latex_citations setting.

If use_latex_citations is True, a bibliography is inserted right at the end of the document. TODO: This should be customizable.

If use-latex-citations is used adjacent citation references (separated only by a single space or a newline) are combined to a single citation group, i.e. [cite1]_ [cite2]_ results in \cite{cite1,cite2}. The appearance in the output can be configured in a style sheet.

#### 6.2.2 Tables

- Too wide tables:

  - Turn off the legacy_column_widths setting (cf. bug #422) or manually set the table width.

- Table cells with both multirow and multicolumn are currently not possible.

#### 6.2.3 Figures

- Figures are always as wide as the containing text. The "figwidth" argument is currently not supported. As a consequence, the "align" argument has no effect.

- Wrapping text around figures is currently not supported. (Requires the wrapfig package.)

#### 6.2.4 Miscellaneous

- Pdfbookmark level 4 (and greater) does not work (might be settable but complicated).

- Hyperlinks are not hyphenated; this leads to bad spacing. See docs/user/rst/demo.rst section 2.14 "directives".

## 7 References

[clsguide]

LaTeX for package and class authors, https://mirrors.ctan.org/macros/latex/base/clsguide.pdf

[encguide]

LaTeX font encodings, https://mirrors.ctan.org/macros/latex/base/encguide.pdf

[grfguide]

Packages in the ‘graphics’ bundle https://mirrors.ctan.org/macros/latex/required/graphics/grfguide.pdf

[scrguide] (1,2,3,4)

KOMA - Script a versatile LATEX 2ε bundle, https://mirrors.ctan.org/macros/latex/contrib/koma-script/doc/scrguide-en.pdf

[usrguide]

LaTeX2e for authors, https://www.latex-project.org/guides/usrguide.pdf