================================
Generating LaTeX with Docutils
================================
:Author: Engelbert Gruber, Guenter Milde
:Contact: docutils-develop@lists.sourceforge.net
:Revision: $Revision: 7667 $
:Date: $Date: 2013-06-03 12:11:36 +0200 (Mon, 03 Jun 2013) $
:Copyright: This document has been placed in the public domain.
.. contents::
.. sectnum::
Introduction
============
This document covers topics specific to Docutils' LaTeX__ export. For
an introduction to LaTeX see, e.g., `LaTeX2e for authors`_. There exists
a wide selecton of `LaTeX Documentation on the net`_ and
`books on LaTeX and related topics`_.
__ http://www.latex-project.org/
.. _LaTeX2e for authors:
http://www.latex-project.org/guides/usrguide.pdf
.. _LaTeX Documentation on the net:
http://www.latex-project.org/guides/
.. _books on LaTeX and related topics:
http://www.latex-project.org/guides/books.html
There are two approaches to typeset documents from reStructuredText
sources via LaTeX:
1. treat LaTeX as a document format (like HTML):
Transform the internal markup into corresponding LaTeX markup.
For example, a section title would be written with the LaTeX section
command: ``\section{this section title}``.
This keeps the document structure and semantic markup produing a readable
LaTeX file, but may require hacking around Docutils â LaTeX
incompatibilities.
As with HTML, styling is mostly done via style sheets or
`LaTeX packages`_.
If you prefer this approach, try the `latex2e` or the `xetex`
writer.
2. treat LaTeX as a page description format (like Postscript):
Use LaTeX as a typesetting system to produce the desired output
without representing document structure in the LaTeX source. This
will work around Docutils-incompatible features in LaTeX but
produces a hard to read LaTeX file. Styling is done via options to
the latex writer.
The (orphaned) `newlatex` writer (``rst2newlatex.py``) uses LaTeX as
a typesetter without caring about producing readable/stylable LaTeX
files.
This documents describes the first approach used by the `latex2e`
and `xetex` writers.
LaTeX
=====
Unlike HTML/CSS, LaTeX provides one common language for markup and
style definitions. Separation of content and style is realized by
collecting style definitions in the documentclass_, `LaTeX packages`_,
or the document preamble.
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`_).
.. _CTAN: http://www.ctan.org
.. _TeX Catalogue: http://texcatalogue.sarovar.org/
.. _stylesheet:
config.html#stylesheet-latex2e-writer
.. _TeX input path:
http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
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``\ [#]_.
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.
.. _standalone_rst_latex.tex:
../../test/functional/expected/standalone_rst_latex.tex
.. [#] DU for Documentation Utilities = Docutils
Length units
------------
LaTeX supports all `length units`_ defined for Docutils plus the
following less common units:
:pt: typewriter's (or LaTeX) point (1 pt = 1/72.27 in)
:dd: didôt (1 dd = 1238/1157 pt)
:cc: cîcero (1 cc = 12 dd)
:sp: scaled point (1sp = 1/65536pt)
.. attention:: Different definitions of the unit "pt"!
* In Docutils (as well as CSS) the unit symbol "pt" denotes the
`Postscript point` or `DTP point`.
* 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
Lengths specified in the document with unit "pt" will be given the
unit "bp" in the LaTeX source.
In `raw LaTeX`_ and `custom style sheets`_, the `DTP point` must be
specified as "bp", while "pt" is interpreted as `LaTeX point`.
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`__
.. _length units: ../ref/rst/restructuredtext.html#length-units
__ http://www.giss.nasa.gov/tools/latex/ltx-86.html.
PDF generation
==============
In most cases, LaTeX code is not the desired end-format of the document.
LaTeX offers many ways to generate PDF documents from the LaTeX
source, including:
_`pdflatex`
Generates a PDF document directly from the LaTeX file.
_`latex + dvipdfmx`
Use ``latex`` to generate a DVI file and ``dvipdfmx`` to produce a PDF
file. If you take this approach, add ``dvipdfmx`` to the
_documentoptions.
_`latex` + dvips + ps2pdf
Produce a DVI file with ``latex``, postscript with ``dvips`` and PDF with
``ps2pdf``.
_`xelatex`
The `XeTeX`__ engine works with input files in UTF-8 encoding and system
fonts. Export your document with the `xetex` writer (``rst2xetex``),
if you want to go this route.
You need to call latex (or pdflatex/xelatex) twice (or even three times) to
get internal references correct.
.. _documentoptions: config.html#documentoptions
__ http://tug.org/xetex/
_`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.
__ http://iml.univ-mrs.fr/~beffara/soft/rubber/
Configuration
=============
The LaTeX code generation can be configured via
* configuration options_ to the Docutils writer,
* `LaTeX packages`_,
* custom `LaTeX code`_ in
+ `style sheets`_,
+ the `LaTeX preamble`_,
+ the document body (`raw LaTeX`_), or
+ custom templates_.
.. _option:
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).
.. _Docutils Configuration:
config.html
LaTeX code
----------
Custom LaTeX code can be placed in `style sheets`_, the `LaTeX
preamble`_, the document body (`raw LaTeX`_), or custom templates_.
.. _style sheet:
.. _custom style sheets:
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 the clsguide_ for an introduction on LaTeX
package writing).
Options:
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_.
.. _clsguide:
http://mirror.ctan.org/macros/latex/doc/clsguide.pdf
.. _embed-stylesheet:
config.html#embed-stylesheet-latex2e-writer
.. _repository of user-contributed style sheets:
../../../sandbox/stylesheets/
.. _sandbox: ../../../sandbox/
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).
Option:
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
.. _latex-preamble:
config.html#latex-preamble
.. _PDF standard fonts:
http://en.wikipedia.org/wiki/PDF#Standard_Type_1_Fonts
.. _Linux Libertine:
http://www.linuxlibertine.org/index.php?id=1&L=1
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.
Option:
template_
In addition to the 'default.tex' template, the latex writer directory
contains the alternative 'titlepage.tex'.
Example:
Print a title page including docinfo, dedication, and abstract::
--template=titlepage.tex
.. _publisher documentation: ../api/publisher.html
.. _template: config.html#template-latex2e-writer
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.)
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 special 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`_.
.. _raw directive:
../ref/rst/directives.html#raw
How to configure the ...
========================
admonitions
-----------
Admonitions__ are specially marked "topics" that can appear anywhere an
ordinary body element can.
__ ../ref/rst/directives.html#admonitions
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.
.. _specific admonitions:
../ref/rst/directives.html#specific-admonitions
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.
.. _marginnote:
http://mirror.ctan.org/help/Catalogue/entries/marginnote.html
.. _pdfcomment:
http://mirror.ctan.org/help/Catalogue/entries/pdfcomment.html
.. _custom role:
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{}``\ [#]_ if it is defined (but silently ignores
this class argument if a corresponding macro is not defined).
.. [#] For backwards compatibility, the prefix ``\docutilsrole...`` in the
styling commands also recognized.
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`_\ [#]_ or as `raw LaTeX`_ in the document source,
text styled with ``:custom4:`large bold small-caps``` will be typeset
accordingly.
.. [#] Leave out the ``\makeatletter`` - ``\makeatother`` pair if the style
sheet is a LaTeX package (``*.sty``).
.. _role directive:
../ref/rst/directives.html#role
.. _text roles:
../ref/rst/roles.html
.. _class directive:
../ref/rst/directives.html#class
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}
__ ../ref/rst/restructuredtext.html#definition-lists
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_
.. _KOMA-script:
http://mirror.ctan.org/help/Catalogue/entries/koma-script.html
.. _memoir:
http://mirror.ctan.org/help/Catalogue/entries/memoir.html
.. _documentclass:
config.html#documentclass
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}
__ ../ref/rst/restructuredtext.html#bibliographic-fields
.. _use-latex-docinfo:
config.html#use-latex-docinfo
.. _use-latex-abstract:
config.html#use-latex-abstract
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.
.. _section structure: rst/quickref.html#section-structure
.. _TeX FAQ: http://www.tex.ac.uk/faq
.. _style of document titles:
http://www.tex.ac.uk/cgi-bin/texfaq2html?label=titlsty
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`.
.. _enumitem:
http://mirror.ctan.org/help/Catalogue/entries/enumitem.html
__ ../ref/rst/restructuredtext.html#field-lists
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}
.. _caption:
http://mirror.ctan.org/help/Catalogue/entries/caption.html
.. _chngcntr:
http://mirror.ctan.org/help/Catalogue/entries/chngcntr.html
__ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=running-nos
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}
.. _figures: ../ref/rst/directives.html#figure
.. _float:
http://mirror.ctan.org/help/Catalogue/entries/float.html
.. _float.pdf:
http://mirror.ctan.org/macros/latex/contrib/float/float.pdf
.. _font setup:
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.
.. _OpenType: http://en.wikipedia.org/wiki/OpenType
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
a) 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`_.
b) 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 [#]_::
\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.
.. [#] 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}
.. _fontspec: http://mirror.ctan.org/help/Catalogue/entries/fontspec.html
.. _fontmatrix: http://fontmatrix.net/
.. _DejaVu: http://dejavu-fonts.org/
.. _documentoptions: config.html#documentoptions
choice of suitable fonts
````````````````````````
High quality free fonts suitable for use with XeTeX are, e.g., listed
at `Good Libre Fonts`_, `25 Best Free Quality Fonts`_ and the update
`19 More Free Quality Fonts`_.
The `LaTeX Font Catalogue`_ provides information and examples for a wide
range of fonts available for use with LaTeX. Here is just a selection:
a) 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.
-2 not part of a minimal standard TeX installation
-1 might not work out-of-the-box
-1 large additional download (ca. 12 ... 17 MB)
b) 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.
-2 not part of a minimal standard TeX installation,
even bigger download size than Latin Modern.
c) `Bera`_ (Bitstream Vera)
+1 simple invocation: ``--stylesheet=bera``
+1 optimized for on-screen viewing with goot hinting
-2 not part of a minimal standard TeX installation
d) 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 [#]_
-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
.. table:: 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 Avant Garde Courier
Schoolbook
charter Charter
utopia Utopia
========= ============ ============= ============= =========
.. [#] Extended versions of the standard Postscript fonts including
accented chars, Greek and Cyrillic 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`_.
.. _LaTeX Font Catalogue:
http://www.tug.dk/FontCatalogue/
.. _Latin Modern:
http://mirror.ctan.org/help/Catalogue/entries/lm.html
.. _CM-Super:
http://mirror.ctan.org/help/Catalogue/entries/cm-super.html
.. _bera:
http://mirror.ctan.org/help/Catalogue/entries/bera.html
.. _TeX Gyre: http://www.gust.org.pl/projects/e-foundry/tex-gyre
.. _PSNFSS:
http://mirror.ctan.org/help/Catalogue/entries/psnfss.html
.. _Using common PostScript fonts with LaTeX:
http://mirror.ctan.org/macros/latex/required/psnfss/psnfss2e.pdf
.. _TeX Live: http://tug.org/texlive/
.. _txfonts:
http://mirror.ctan.org/help/Catalogue/entries/txfonts.html
.. _PDF Standard Font:
http://en.wikipedia.org/wiki/PDF#Standard_Type_1_Fonts
.. _testflow:
http://www.tex.ac.uk/tex-archive/help/Catalogue/entries/testflow.html
.. _Good Libre Fonts:
http://typophile.com/node/18207
.. _25 Best Free Quality Fonts:
http://www.alvit.de/blog/article/20-best-license-free-official-fonts
.. _19 More Free Quality Fonts:
http://www.smashingmagazine.com/2006/10/11/17-more-free-quality-fonts/
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
.. _encguide:
http://mirror.ctan.org/macros/latex/doc/encguide.pdf
.. _font-encoding:
config.html#font-encoding
.. _fontenc:
http://mirror.ctan.org/help/Catalogue/entries/fontenc.html
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].
.. _extsizes:
http://mirror.ctan.org/help/Catalogue/entries/extsizes.html
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%
}
.. _footmisc:
http://mirror.ctan.org/help/Catalogue/entries/footmisc.html
.. _hanging:
http://mirror.ctan.org/help/Catalogue/entries/hanging.html
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
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
: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`_.
.. _hyperlink-color:
config.html#hyperlink-color
.. _hyperref-options:
config.html#hyperref-options
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.
Option:
``--hyperref-options=draft``
`LaTeX code`_::
\usepackage{nohyperref,url}
\urlstyle{same}
.. _hyperref:
http://mirror.ctan.org/help/Catalogue/entries/hyperref.html
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}
__ ../ref/rst/restructuredtext.html#line-blocks
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}
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}
__ ../ref/rst/restructuredtext.html#literal-blocks
.. _literal-block-env:
config.html#literal-block-env
.. _listings.pdf:
http://mirror.ctan.org/macros/latex/contrib/listings/listings.pdf
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
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}
__ ../ref/rst/restructuredtext.html#option-lists
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`_).
page layout
-----------
By default, paper size and margin settings are determined by the document
class.
The following packages help to configure the page layout:
a) 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.
b) 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}.
.. _typearea:
http://mirror.ctan.org/help/Catalogue/entries/typearea.html
.. _KOMA-Script Guide:
http://mirror.ctan.org/macros/latex/contrib/koma-script/scrguien.pdf
.. _geometry:
http://mirror.ctan.org/help/Catalogue/entries/geometry.html
.. _geometry manual:
http://mirror.ctan.org/macros/latex/contrib/geometry/geometry.pdf
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}
.. _fancyhdr: http://www.ctan.org/pkg/fancyhdr
.. _"header" and "footer" directives: ../ref/rst/directives.html#header
page numbering
--------------
Example:
Number pages by chapter (using the chappg_ package)::
\usepackage{chappg}
See the `chappg documentation`_ for details.
.. _chappg:
http://mirror.ctan.org/help/Catalogue/entries/chappg.html
.. _chappg documentation:
http://mirror.ctan.org/macros/latex/contrib/chappg/chappg.pdf
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`_.
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}
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}}
__ ../ref/rst/directives.html#rubric
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}
.. note:: The LaTeX name is 'secnumdepth' (whithout 't').
.. _sectnum directive: ../ref/rst/directives.html#sectnum
.. _sectnum_xform: config.html#sectnum-xform
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_).
__ http://docutils.sf.net/docutils/docs/ref/rst/directives.html#sidebar
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
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}
.. _topic: ../ref/rst/directives.html#topic
.. _section title: ../ref/rst/restructuredtext.html#sections
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}
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.
.. 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.
.. _use-latex-toc: config.html#use-latex-toc
.. _contents directive: ../ref/rst/directives.html#contents
.. _minitoc:
http://mirror.ctan.org/help/Catalogue/entries/minitoc.html
.. _minitoc documentation:
http://mirror.ctan.org/macros/latex/contrib/minitoc/minitoc.pdf
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}}}
.. _title reference:
../ref/rst/roles.html#title-reference
.. _default role:
../ref/rst/directives.html#setting-the-default-interpreted-text-role
.. _interpreted text:
../ref/rst/restructuredtext.html#interpreted-text
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".
.. with utf8x:
If LaTeX issues a Warning about unloaded/unknown characters adding ::
\PreloadUnicodePage{n}
(where *n* is the Unicode page-number) to the style sheet might help.
.. _LaTeX Unicode: http://www.unruh.de/DniQ/latex/unicode/
.. _output-encoding: config.html#output-encoding
.. _inputenc:
http://mirror.ctan.org/help/Catalogue/entries/inputenc.html
.. _ucs:
http://mirror.ctan.org/help/Catalogue/entries/unicode.html
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}}
__ http://docutils.sf.net/docutils/docs/ref/rst/restructuredtext.html#transitions
.. _transition-stars.sty: ../../../sandbox/stylesheets/transition-stars.sty
Changes
=======
* The Docutils HISTORY_ lists all changes during the history of docutils.
* Changes since release (0.5) are summarized in the RELEASE-NOTES_
and explained in detail in docutils-05-compat_.
* docutils-05-compat.sty_ is a `style sheet`_ that provides best possible
backwards compatibility.
.. _HISTORY: ../../HISTORY.html
.. _RELEASE-NOTES: ../../RELEASE-NOTES.html
.. _docutils-05-compat: docutils-05-compat.sty.html
.. _docutils-05-compat.sty:
../../docutils/writers/latex2e/docutils-05-compat.sty
Problems
========
Troubleshooting
---------------
Bad looking PDF output
``````````````````````
What I am looking for when I try Docutils is if the PDF files I can get
are of high quality. Unfortunaltely 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 options_ to the Docutils tool. See font_ and font-encoding_.
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.txt>`_).
To get footnote mark and text at the same page, keep footnote mark and
footnote text close together!
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:
a) compile with pdflatex_,
b) compile with `latex + dvipdfmx`_,
c) use the package breakurl_,
d) (for printout) `disable hyperlinks`_ using the package "nohyperref".
See also the `Link text doesnât break at end line`_ FAQ entry.
.. _breakurl:
http://mirror.ctan.org/help/Catalogue/entries/breakurl.html
.. _Link text doesnât break at end line:
http://www.tex.ac.uk/cgi-bin/texfaq2html?label=breaklinks
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" if the
document language is "russian".
However, this setting leads to "strange" characters in the bookmarks
if used with xelatex_ in hyperref versions before v6.79g (2009/11/20).
(cf `bugreport 3100778`__).
If updating the hyperref package is not an option, the workaround is
to set ::
--hyperref-option="unicode=false"
or (in the config file)::
[xetex writer]
hyperref-option: unicode=false
__ http://sourceforge.net/tracker/?func=detail&aid=3100778&group_id=38414&atid=422030
.. _hyperref_option: config.html#stylesheet-latex2e-writer
image inclusion
```````````````
Images__ are included in LaTeX with the help of the `graphicx` package. The
supported file formats depend on the used driver:
* Standard latex_ can include **only EPS** graphics, no other format.
* `latex + dvipdfmx`_ works with EPS and JPG (add 'dvipdfmx' to the
documentoptions_ and 'bmpsize' to the stylesheet_ setting).
* pdflatex_ and xelatex_ work with PNG, JPG, or PDF, but **not EPS**.
If PDF-image inclusion in PDF files fails, specifying
``--graphicx-option=pdftex`` or ``--graphicx-option=auto`` might help.
For details see grfguide.pdf_.
The Rubber_ wrapper can be used for automatic image conversion.
Docutils expects an URI as pointer to the image file. The latex writer
transforms this URI to a local path. By default, LaTeX does not accept
spaces and more than one dot in the filename. If using "traditional"
filenames is not an option, the adding grffile_ to the `style sheets`_
can help.
__ ../ref/rst/directives.html#images
.. _grfguide.pdf:
http://mirror.ctan.org/macros/latex/required/graphics/grfguide.pdf
.. _grffile:
http://mirror.ctan.org/help/Catalogue/entries/grffile.html
Why are my images too big?
``````````````````````````
HTML-browsers use the actual screen resolution (usually around
100Â DPI).
The CSS specification suggests:
It is recommended that the reference pixel be the visual angle of one
pixel on a device with a pixel density of 96Â DPI and a distance from the
reader of an arm's length.
-- http://www.w3.org/TR/CSS2/syndata.html#length-units
This is why pixmap images without size specification or objects with a size
specified in ``px`` tend to come too large in the PDF.
Solution:
Specify the image size in fixed units (``pt``, ``cm``, ``in``) or
configure the `size of a pixel`_ (length unit px).
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).
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".
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 symbol (bitmap), or
:force,almostfull: use the symbol provided by the font at the users
risk,
to the document options or use a different font package.
Search and text extraction
``````````````````````````
Search for text that contains characters outside the ASCII range (e.g.
umlauts) might fail. See font_ and `font encoding`_ (as well as
`Searching PDF files`_ for background information).
.. _Searching PDF files:
http://www.tex.ac.uk/cgi-bin/texfaq2html?label=srchpdf
Unicode box drawing and block characters
````````````````````````````````````````
The easiest solution is to use xelatex_ for `PDF generation`_.
With "traditional" TeX engines (e.g. pdflatex_):
- Generate LaTeX code with `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).
.. _pmboxdraw:
http://mirror.ctan.org/help/Catalogue/entries/pmboxdraw.html
.. _pmboxdraw.pdf:
http://mirror.ctan.org/macros/latex/contrib/oberdiek/pmboxdraw.pdf
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`_.
.. _Docutils TODO list: ../dev/todo.html#latex-writer
.. _bugs: ../../BUGS.html
.. _SourceForge Bug Tracker:
http://sourceforge.net/tracker/?group_id=38414&atid=422030
Footnotes and citations
```````````````````````
Initially both 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 footnotes, citations, and figures possibly being mixed at
page foot.
Workaround:
Select footnote and citation handling with the docutils-footnotes_ and
use-latex-citations_ options.
If ``use-latex-citations`` is used, a bibliography is inserted right at
the end of the document. *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`_.
.. _docutils-footnotes: config.html#docutils-footnotes
.. _use-latex-citations: config.html#use-latex-citations
Tables
``````
:Tablewidth: reST-documents line length is assumed to be 80 characters. The
tablewidth is set relative to this value. If someone produces
documents with line length of 132 this will fail.
Table width is tried to fit in page even if it is wider than
the assumed linewidth, still assumed linewidth is a hook.
* Table: multicol cells are always left aligned.
* The contents of a rowspan cell do not influence table height.
(multirow "feature", use a phantom or strut?)
* Multirow cells might mix up the following table rows.
* Table cells with both multirow and multicolumn are currently not possible.
* literal-blocks in table cells:
- If verbatim or flushleft is used one gets vertical space above and below.
- This is bad for the topmost paragraph in a cell, therefore the writer
uses raggedright.
- Ragged right fails on followup paragraphs as the vertical space would be
missing.
* ``--table-style=booktabs``, ``..class:: booktab``: `booktabs` version
1.00 does not work with `longtable`. This is solved in newer versions
(current is 2005/04/14 v1.61803).
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.)
.. _wrapfig:
http://mirror.ctan.org/help/Catalogue/entries/wrapfig.html
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.txt 2.14 directives.
* Pagestyle headings does not work, when sections are starred. Use LaTeX for
the section numbering with the options_ ``--no-section-numbers``
(command line) or ``sectnum_xform: False`` (config file).
