# Changes to the Docutils latex2e writer since version 0.5

## A backwards compatibility style sheet

Author: | Guenter Milde
Contact: | docutils-develop@lists.sourceforge.net
Revision: | 7302
Date: | 2012-01-03
Copyright: | © 2009 Günter Milde,
License: | Released under the terms of the 2-Clause BSD license, in short: Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

Abstract

This file documents changes and provides a style for best possible compatibility to the behaviour of the latex2e writer of Doctutils release 0.5.

    \NeedsTeXFormat{LaTeX2e}
    \ProvidesPackage{docutils-05-compat}
    [2009/03/26 v0.1 compatibility with rst2latex from Docutils 0.5]

Contents

- Usage
- Changes since 0.5
  - Bugfixes
  - New configuration setting defaults
  - Cleaner LaTeX source
  - LaTeX style sheets
  - Templates
  - Custom roles
  - Length units
  - Font encoding
  - Sub- and superscript as text
  - Page layout
  - ToC and section numbers
  - Default font in admonitions and sidebar
  - Figure placement
  - Figure and image alignment
  - Shorter preamble
    - Packages that are no longer required
    - Packages that are conditionally loaded
    - Floats for footnotes settings
  - Special lengths, commands, and environments
    - Removed definitions
    - Renamed definitions (now conditional)
    - New definitions

# Usage

- To get an (almost) identic look for your old documents, place `docutils-05-compat.sty` in the TEXINPUT path (e.g. the current work directory) and pass the `--stylesheet=docutils-05-compat` option to `rst2latex.py`.
- To use your custom stylesheets without change, add them to the compatibility style, e.g. `--stylesheet="docutils-05-compat,mystyle.tex`.

Tip

As the changes include bug fixes that are partly reverted by this style, it is recommended to adapt the stylesheets to the new version or copy just the relevant parts of this style into them.

# Changes since 0.5

## Bugfixes

- Newlines around comments, targets and references prevent run-together paragraphs.

  - An image directive with hyperlink reference or target did not start a new paragraph (e.g. the first two image examples in standalone_rst_latex.tex).
  - Paragraphs were not separated if there was a (hyper) target definition inbetween.
  - Paragraphs did run together, if separated by a comment-paragraph in the rst source.

- Fixed missing and spurious internal links/targets. Internal links now take you to the correct place.

- Verbose and linked system messages.

- Figure and image alignment now conforms to the rst definition.

- Put header and footer directive content in DUheader respective DUfooter macros (ignored by the default style/template).

  (They were put inside hard-coded markup at the top/bottom of the document without an option to get them on every page.)

- Render doctest blocks as literal blocks (fixes bug [1586058] doctest block nested in admonition). I.e.

  - indent doctest blocks by nesting in a quote environment. This is also the rendering by the HTML writer (html4css2.css).
  - apply the `--literal-block-env` setting also to doctest blocks.

  Warning

  (`--literal-block-env=verbatim` and `--literal-block-env=lstlistings` fail with literal or doctest blocks nested in an admonition.

- Two-way hyperlinked footnotes and support for symbol footnotes and `--footnote-references=brackets` with `--use-latex-footnotes`.

- The packages fixltx2e (providing LaTeX patches and the textsubscript command) and cmap (including character maps in the generated PDF for better search and copy-and-paste operations) are now always loaded (configurable with custom templates).

Backwards compatibility:
  "Bug for bug compatibility" is not provided.

## New configuration setting defaults

- font-encoding: "T1" (formerly implicitely set by 'ae').
- use-latex-toc: true (ToC with page numbers).
- use-latex-footnotes: true (no mixup with figures).

Backwards compatibility:

  Reset to the former defaults with:

  font-encoding: ''
  use-latex-toc: False
  use-latex-footnotes: False

  (in the config file) or the command line options:

  > `--figure-footnotes --use-docutils-toc --font-encoding=''`

## Cleaner LaTeX source

New features:
  - Remove redundant "double protection" from the encoding of the "special printing characters" and square brackets, e.g. `\%` instead of `{\%}`.
  - Remove some spurious whitespace, e.g. `\item [what:] -> \item[what:]`.
  - Use conventional style for "named" macros, e.g. `\dots{}` instead of `{\dots}`
Backwards compatibility:
  Changes do not affect the output.

## LaTeX style sheets

New Feature:
  LaTeX packages can be used as `--stylesheet` argument without restriction.
Implementation:
  Use `\usepackage` if style sheet ends with `.sty` or has no extension and `\input` else.
Rationale:
  while `\input` works with extension as well as without extension, `\usepackage` expects the package name without extension. (The latex2e writer will strip a `.sty` extension.)
Backwards compatibility:

  Up to Docutils 0.5, if no filename extension is given in the `stylesheet` argument, `.tex` is assumed (by latex).

  Since Docutils 0.6, a stylesheet without filename extension is assumed to be a LaTeX package (`*.sty`) and referenced with the `\usepackage` command.

Important

Always specify the extension if you want the style sheet to be `\input` by LaTeX.

## Templates

New Feature:
  Advanced configuration via custom templates.
Implementation:
  A `--template` option and config setting allows specification of a template file.

See the LaTeX writer documentation for details.

## Custom roles

New Feature: failsave implementation
  As with classes to HTML objects, class arguments are silently ignored if there is no styling rule for this class in a custom style sheet.
New Feature: custom roles based on standard roles
  As class support needs to be handled by the LaTeX writer, this feature was not present "automatically" (as in HTML). Modified visit/depart_*() methods for the standard roles now call visit/depart_inline() if there are class arguments to the node.
Backwards compatibility:
  The implementation is fully backwards compatible. (SVN versions 5742 to 5861 contained an implementation that did not work with commands expecting an argument.)

## Length units

New Features:
  1. Add default unit if none given. A poll on docutils-users favoured `bp` (Big Point: 1 bp = 1/72 in).
  2. Do not change `px` to `pt`.
  3. Lengths specified in the document with unit "pt" will be written with unit "bp" to the LaTeX source.
Rationale:

  1. prevent LaTeX error "missing unit".

  2. `px` is a valid unit in pdftex since version 1.3.0 released on 2005-02-04:

     > 1px defaults to 1bp (or 72dpi), but can be changed with the `\pdfpxdimen` primitive.:

     >     \pdfpxdimen=1in % 1 dpi
     >     \divide\pdfpxdimen by 96 % 96 dpi

     > —http://www.tug.org/applications/pdftex/NEWS

     Modern TeX distributions use pdftex also for dvi generation (i.e. `latex` actually calls `pdftex` with some options).

  3. In Docutils (as well as CSS) the unit symbol "pt" denotes the Postscript point or DTP point while LaTeX uses "pt" for the LaTeX point, which is unknown to Docutils and 0.3 % smaller.

     The DTP point is available in LaTeX as "bp" (big point):

     > 1 pt = 1/72.25 in < 1 bp = 1/72 in

Backwards compatibility:

  Images with width specification in `px` come out slightly (0.3 %) larger:

  > 1 px = 1 bp = 1/72 in > 1 pt = 1/72.25 in

  This can be reset with

      \pdfpxdimen=1pt

Caution!

It is impossible to revert the change of lengths specified with "pt" or without unit in a style sheet, however the 0.3 % change will be imperceptible in most cases.

Error `illegal unit px`

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

If you convert the LaTeX source with a legacy program, you might get the error `illegal unit px`.

If updating LaTeX is not an option, just remove the `px` from the length specification. HTML/CSS will default to `px` while the latexe2 writer will add the fallback unit `bp`.

## Font encoding

New feature:

  Do not mix font-encoding and font settings: do not load the obsolete ae and aeguill packages unless explicitely required via the `--stylesheet` option.

  font-encoding = "":

  do not load ae and aeguill, i.e.
  - do not change font settings,
  - do not use the fontenc package (implicitely loaded via ae),
  - use LaTeX default font encoding (OT1)

  font-encoding = "OT1":
  | load fontenc with `\usepackage[OT1]{fontenc}`

Example:
  `--font-encoding=LGR,T1` becomes `\usepackage[LGR,T1]{fontenc}` (Latin, Latin-1 Supplement, and Greek)
Backwards compatibility:
  Load the ae and aeguill packages if fontenc is not used.

Tip

Using ae is not recommended. A similar look (but better implementation) can be achieved with the packages lmodern, cmsuper, or cmlgr all providing Computer Modern look-alikes in vector format and T1 encoding, e.g. `--font-encoding=T1 --stylesheet=lmodern`.

## Sub- and superscript as text

New feature:

  Set sub- and superscript role argument in text mode not as math.

  Pass the role content to `\textsubscript` or `\textsuperscript`.

Backwards compatibility:

  The old implementation set the role content in Math mode, where

  - whitespace is ignored,
  - a different command set and font setting scheme is active,
  - Latin letters are typeset italic but numbers upright.

  Although it is possible to redefine `\textsubscript` and `\textsuperscript` to typeset the content in math-mode, this can lead to errors with certain input and is therefore not done in this style sheet.

Tip

To get italic subscripts, define and use in your document custom roles like `.. role:: sub(subscript)` and `.. role:: super(superscript)` and define the "role commands":

    \newcommand{\DUrolesub}{\itshape}
    \newcommand{\DUrolesuper}{\itshape}

Alternatively, if you want all sub- and superscripts in italic, redefine the macros:

    %% \let\DUsup\textsubscript
    %% \let\DUsuper\textsuperscript
    %% \renewcommand*{\textsubscript}{\DUsub\itshape}
    %% \renewcommand*{\textsuperscript}{\DUsuper\itshape}

This is not fully backwards compatible, as it will also set numbers in italic shape and not ignore whitespace.

## Page layout

New features:
  - Margins are configurable via the `DIV=...` document option.
  - The `\raggedbottom` setting is no longer inserted into the document. It is the default for article and report classes. If requested in combination with a book class, it can be given in a custom style sheet.
Backwards compatibility:

  Up to version 0.5, use of typearea and a DIV setting of 12 were hard-coded into the latex2e writer

      \usepackage{typearea}
      \typearea{12}

  and the vertical alignment of lower boundary of the text area in book classes disabled via

      \raggedbottom

## ToC and section numbers

Better conformance to Docutils specifications.

New feature:
  - The "depth" argument of the "contents" and "sectnum" directives is respected.
  - section numbering independent of 'use-latex-toc':
    - sections are only numbered if there is a "sectnum" directive in the document
    - section numbering by LaTeX if the "sectnum_xforms" config setting is False.

Backwards compatibility:

> The previous behaviour was to always number sections if 'use-latex-toc' is true, using the document class defaults. It cannot be restored universally, the following code sets the default values of the "article" document class:

>     \setcounter{secnumdepth}{3}
>     \setcounter{tocdepth}{3}

New feature:
  If 'use-latex-toc' is set, local tables of content are typeset using the 'minitoc' package (instead of being ignored).
Backwards compatibility:
  Disable the creation of local ToCs (ignoring all special commands) by replacing `\usepackage{minitoc} with ``\usepackage{mtcoff}`.

## Default font in admonitions and sidebar

New feature:
  Use default font in admonitions and sidebar.
Backward compatibility:
  See the fallback definitions for admonitions, topic title and sidebar.

## Figure placement

New feature:

  Use `\floatplacement` from the float package instead of "hard-coded" optional argument for the global setting.

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

Backwards compatibility:

  Set the global default back to the previous used value:

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

## Figure and image alignment

New features:

1. Fix behaviour of 'align' argument to a figure (do not align figure contents).

   As the 'figwidth' argument is still ignored and the "natural width" of a figure in LaTeX is 100% textwidth, setting the 'align' argument of a figure has currently no effect on the LaTeX output.

2. Set default align of image in a figure to 'center'.

3. Also center images that are wider than textwidth.

4. Align images with class "align-[right|center|left]" (allows setting the alignment of an image in a figure).

Backwards compatibility:
  There is no "automatic" way to reverse these changes via a style sheet.

1. The alignment of the image can be set with the "align-left", "align-center" and "align-right" class arguments.

   As previously, the caption of a figure is aligned according to the document class -- configurable with a style sheet using the "caption" package.

2. See a)

3. Set the alignment of "oversized" images to "left" to get back the old placement.

## Shorter preamble

New feature:
  The document preamble is pruned to contain only relevant commands and settings.

### Packages that are no longer required

The following packages where required in pre-0.5 versions and still loaded with version 0.5:

    \usepackage{shortvrb}
    \usepackage{amsmath}

### Packages that are conditionally loaded

Additional to the typearea for page layout, the following packages are only loaded if actually required by doctree elements:

#### Tables

Standard package for tables across several pages:

    \usepackage{longtable}

Extra space between text in tables and the line above them ('array' is implicitely loaded by 'tabularx', see below):

    \usepackage{array}
    \setlength{\extrarowheight}{2pt}

Table cells spanning multiple rows:

    \usepackage{multirow}

#### Docinfo

One-page tables with auto-width columns:

    \usepackage{tabularx}

#### Images

Include graphic files:

    \usepackage{graphicx}

#### Problematic, Sidebar

Set text and/or background colour, coloured boxes with `\colorbox`:

    \usepackage{color}

### Floats for footnotes settings

Settings for the use of floats for footnotes are only included if

- the option "use-latex-footnotes" is False, and
- there is at least one footnote in the document.

    % begin: floats for footnotes tweaking.
    \setlength{\floatsep}{0.5em}
    \setlength{\textfloatsep}{\fill}
    \addtolength{\textfloatsep}{3em}
    \renewcommand{\textfraction}{0.5}
    \renewcommand{\topfraction}{0.5}
    \renewcommand{\bottomfraction}{0.5}
    \setcounter{totalnumber}{50}
    \setcounter{topnumber}{50}
    \setcounter{bottomnumber}{50}
    % end floats for footnotes

## Special lengths, commands, and environments

### Removed definitions

#### admonition width

The `admonitionwith` lenght is replaced by the more powerful `\DUadmonition` command (see admonitions).

Backwards compatibility:

  The default value (90 % of the textwidth) is unchanged.

  To configure the admonition width, you must redefine the `DUadmonition` command instead of changing the `admonitionwith` length value.

### Renamed definitions (now conditional)

The names for special doctree elements are now prefixed with `DU`.

Up to version 0.5, all definitions were included in the preamble (before the style sheet) of every document -- even if not used in the body. Since version 0.6, fallback definitions are included after the style sheet and only if required.

Customization is done by an alternative definition in a style sheet with `\newcommand` instead of the former `\renewcommand`.

The following code provides the old definitions and maps them (or their custom variants) to the new interface.

#### docinfo width

    \newlength{\docinfowidth}
    \setlength{\docinfowidth}{0.9\textwidth}

    \newlength{\DUdocinfowidth}
    \AtBeginDocument{\setlength{\DUdocinfowidth}{\docinfowidth}}

#### line block

    \newlength{\lineblockindentation}
    \setlength{\lineblockindentation}{2.5em}
    \newenvironment{lineblock}[1]
    {\begin{list}{}
      {\setlength{\partopsep}{\parskip}
       \addtolength{\partopsep}{\baselineskip}
       \topsep0pt\itemsep0.15\baselineskip\parsep0pt
       \leftmargin#1}
     \raggedright}
    {\end{list}}

    \newlength{\DUlineblockindent}
    \AtBeginDocument{\setlength{\DUlineblockindent}{\lineblockindentation}}
    \newenvironment{DUlineblock}[1]
      {\begin{lineblock}{#1}}
      {\end{lineblock}}

#### local line width

The `\locallinewidth` length for internal use in tables is replaced by `\DUtablewidth`. It was never intended for customization:

    \newlength{\locallinewidth}

#### option lists

    \newcommand{\optionlistlabel}[1]{\bf #1 \hfill}
    \newenvironment{optionlist}[1]
    {\begin{list}{}
      {\setlength{\labelwidth}{#1}
       \setlength{\rightmargin}{1cm}
       \setlength{\leftmargin}{\rightmargin}
       \addtolength{\leftmargin}{\labelwidth}
       \addtolength{\leftmargin}{\labelsep}
       \renewcommand{\makelabel}{\optionlistlabel}}
    }{\end{list}}

    \newcommand{\DUoptionlistlabel}{\optionlistlabel}
    \newenvironment{DUoptionlist}
      {\begin{optionlist}{3cm}}
      {\end{optionlist}}

#### rubric

Now less prominent (not bold, normal size) restore with:

    \newcommand{\rubric}[1]{\subsection*{~\hfill {\it #1} \hfill ~}}
    \newcommand{\DUrubric}[2][class-arg]{\rubric{#2}}

#### title reference role

    \newcommand{\titlereference}[1]{\textsl{#1}}
    \newcommand{\DUroletitlereference}[1]{\titlereference{#1}}

### New definitions

New Feature:

  Enable customization of some more Docutils elements with special commands

  admonition: | `DUadmonition` command (replacing `\admonitionwidth`),
  field list: | `DUfieldlist` environment,
  legend: | `DUlegend` environment,
  sidebar: | `\DUsidebar`, `\DUtitle`, and `DUsubtitle` commands,
  topic: | `\DUtopic` and `\DUtitle` commands,
  transition: | `\DUtransition` command.
  footnotes: | `\DUfootnotemark` and `\DUfootnotetext` commands with hyperlink support using the Docutils-provided footnote label.

Backwards compatibility:
  In most cases, the default definition corresponds to the previously used construct. The following definitions restore the old behaviour in case of changes.

#### admonitions

Use sans-serif fonts:

    \newcommand{\DUadmonition}[2][class-arg]{%
      \begin{center}
        \fbox{\parbox{0.9\textwidth}{\sffamily #2}}
      \end{center}
    }

#### dedication

Do not center:

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

But center the title:

    \newcommand*{\DUtitlededication}[1]{\centerline{\textbf{#1}}}

#### sidebar

Use sans-serif fonts, a frame, and a darker shade of grey:

    \providecommand{\DUsidebar}[2][class-arg]{%
      \begin{center}
        \sffamily
        \fbox{\colorbox[gray]{0.80}{\parbox{0.9\textwidth}{#2}}}
      \end{center}
    }

#### sidebar sub-title

Bold instead of emphasized:

    \providecommand*{\DUsubtitlesidebar}[1]{\hspace*{\fill}\\
      \textbf{#1}\smallskip}

#### topic

No quote but normal text:

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

#### topic title

Title for "topics" (admonitions, sidebar).

Larger font size:

    \providecommand*{\DUtitletopic}[1]{\textbf{\large #1}\smallskip}

#### transition

Do not add vertical space after the transition.

    \providecommand*{\DUtransition}[1][class-arg]{%
      \hspace*{\fill}\hrulefill\hspace*{\fill}}