1 ================================
2 Generating LaTeX with Docutils
3 ================================
5 :Author: Engelbert Gruber, Guenter Milde
6 :Contact: docutils-develop@lists.sourceforge.net
9 :Copyright: This document has been placed in the public domain.
17 This document covers topics specific to Docutils' LaTeX__ export. For
18 an introduction to LaTeX see, e.g., `LaTeX2e for authors`_. There exists
19 a wide selecton of `LaTeX Documentation on the net`_ and
20 `books on LaTeX and related topics`_.
23 __ http://www.latex-project.org/
24 .. _LaTeX2e for authors:
25 http://www.latex-project.org/guides/usrguide.pdf
26 .. _LaTeX Documentation on the net:
27 http://www.latex-project.org/guides/
28 .. _books on LaTeX and related topics:
29 http://www.latex-project.org/guides/books.html
32 There are two approaches to typeset documents from reStructuredText
35 1. treat LaTeX as a document format (like HTML):
37 Transform the internal markup into corresponding LaTeX markup.
38 For example, a section title would be written with the LaTeX section
39 command: ``\section{this section title}``.
41 This keeps the document structure and semantic markup produing a readable
42 LaTeX file, but may require hacking around Docutils — LaTeX
45 As with HTML, styling is mostly done via style sheets or
48 If you prefer this approach, try the `latex2e` or the `xetex`
51 2. treat LaTeX as a page description format (like Postscript):
53 Use LaTeX as a typesetting system to produce the desired output
54 without representing document structure in the LaTeX source. This
55 will work around Docutils-incompatible features in LaTeX but
56 produces a hard to read LaTeX file. Styling is done via options to
59 The (orphaned) `newlatex` writer (``rst2newlatex.py``) uses LaTeX as
60 a typesetter without caring about producing readable/stylable LaTeX
63 This documents describes the first approach used by the `latex2e`
70 Unlike HTML/CSS, LaTeX provides one common language for markup and
71 style definitions. Separation of content and style is realized by
72 collecting style definitions in the documentclass_, `LaTeX packages`_,
73 or the document preamble.
78 LaTeX packages (similar to Python modules or C libraries) provide
79 means to extend or modify the LaTeX language by redefining macros or
80 providing new ones. There is a *huge* selection of packages (standard
81 as well as user contributed) coming with your TeX distribution or
82 available at CTAN_ (see the `TeX Catalogue`_).
84 .. _CTAN: http://www.ctan.org
85 .. _TeX Catalogue: http://texcatalogue.sarovar.org/
87 config.html#stylesheet-latex2e-writer
89 http://www.tex.ac.uk/cgi-bin/texfaq2html?label=what-TDS
92 Docutils special LaTeX macros
93 -----------------------------
95 Some Docutils objects have no LaTeX counterpart, they will be typeset
96 using a Docutils specific LaTeX *macro* (command, environment, or
97 length) to allow customization. By convention, special macros use the
100 The generated LaTeX documents should be kept processable by a standard LaTeX
101 installation. Therefore fallback definitions are included after the `custom
102 style sheets`_, if a macro is required in the document.
104 * Custom `style sheets`_ can define alternative implementations with
105 ``\newcommand``, ``\newenvironment``, and ``\newlength`` followed by
108 * Definitions with `raw LaTeX`_ are part of the document body. Use
109 ``\def``, ``\renewcommand`` or ``\renewenvironment``, and ``\setlength``.
111 See the test output standalone_rst_latex.tex_ for an example of the fallback
112 definitions and their use in the document.
114 .. _standalone_rst_latex.tex:
115 ../../test/functional/expected/standalone_rst_latex.tex
117 .. [#] DU for Documentation Utilities = Docutils
123 LaTeX supports all `length units`_ defined for Docutils plus the
124 following less common units:
126 :pt: typewriter's (or LaTeX) point (1 pt = 1/72.27 in)
127 :dd: didôt (1 dd = 1238/1157 pt)
128 :cc: cîcero (1 cc = 12 dd)
129 :sp: scaled point (1sp = 1/65536pt)
131 .. attention:: Different definitions of the unit "pt"!
133 * In Docutils (as well as CSS) the unit symbol "pt" denotes the
134 `Postscript point` or `DTP point`.
136 * LaTeX uses "pt" for the `LaTeX point`, which is unknown to Docutils and
139 * The `DTP point` is available in LaTeX as "bp" (big point):
141 1 pt = 1/72.25 in < 1 bp = 1/72 in
143 Lengths specified in the document with unit "pt" will be given the
144 unit "bp" in the LaTeX source.
146 In `raw LaTeX`_ and `custom style sheets`_, the `DTP point` must be
147 specified as "bp", while "pt" is interpreted as `LaTeX point`.
149 The default length unit (added by Docutils to length specifications
150 without unit) is the "DTP point".
152 For more on lengths in LaTeX, see e.g. `Hypertext Help with LaTeX: Lengths`__
154 .. _length units: ../ref/rst/restructuredtext.html#length-units
155 __ http://www.giss.nasa.gov/tools/latex/ltx-86.html.
161 In most cases, LaTeX code is not the desired end-format of the document.
162 LaTeX offers many ways to generate PDF documents from the LaTeX
166 Generates a PDF document directly from the LaTeX file.
169 Use ``latex`` to generate a DVI file and ``dvipdfmx`` to produce a PDF
170 file. If you take this approach, add ``dvipdfmx`` to the
173 _`latex` + dvips + ps2pdf
174 Produce a DVI file with ``latex``, postscript with ``dvips`` and PDF with
178 The `XeTeX`__ engine works with input files in UTF-8 encoding and system
179 fonts. Export your document with the `xetex` writer (``rst2xetex``),
180 if you want to go this route.
182 You need to call latex (or pdflatex/xelatex) twice (or even three times) to
183 get internal references correct.
185 .. _documentoptions: config.html#documentoptions
186 __ http://tug.org/xetex/
190 The Rubber__ wrapper for LaTeX and friends can be used to automatically
191 run all programs the required number of times and delete "spurious" files.
192 This includes processing bibliographic references or indices, as well as
193 compilation or conversion of figures.
195 __ http://iml.univ-mrs.fr/~beffara/soft/rubber/
201 The LaTeX code generation can be configured via
203 * configuration options_ to the Docutils writer,
205 * custom LaTeX code in
207 + the `LaTeX preamble`_
208 + the document body (`raw LaTeX`_), or
216 Options can be specified as
218 * command-line options (run ``rst2latex.py --help`` to get a list of
219 available options), or
221 * configuration settings (see `Docutils Configuration`_ for details).
223 .. _Docutils Configuration:
228 .. _custom style sheets:
233 A common way of LaTeX customization is the preparation of custom style
234 sheets, either as simple files with LaTeX code snippets or as home-made
235 `LaTeX packages`_ (see the clsguide_ for an introduction on LaTeX
241 It is possible to specify multiple style sheets and mix `LaTeX
242 packages`_ with `custom style sheets`_.
244 You cannot specify package options with the stylesheet_ setting. If
245 you need to pass options to the package, use the ``\usepackage``
246 command in the `LaTeX preamble`_ or a custom style sheet.
249 Select Latin Modern fonts with the `lmodern` package::
254 Use the `preamble.tex` home-made custom style sheet together with
255 the package `kerkis` (Bookman fonts)::
257 --stylesheet=kerkis,preamble.tex
260 Select Palatino fonts with old-style numbers and true small-caps
261 with the LaTeX command ::
263 \usepackage[osf,sc]{mathpazo}
265 in the `LaTeX preamble`_ or `custom style sheets`_.
267 Stylesheet Repository
268 There is a `repository of user-contributed style sheets`_ in the
272 http://mirror.ctan.org/macros/latex/doc/clsguide.pdf
273 .. _embed-stylesheet:
274 config.html#embed-stylesheet-latex2e-writer
275 .. _repository of user-contributed style sheets:
276 ../../../sandbox/stylesheets/
277 .. _sandbox: ../../../sandbox/
283 Configuration by LaTeX code in the document preamble is also possible
284 without a separate stylesheet. This way, packages can be loaded with
285 options or commands re-defined without the need to create a separate
286 file (new in Docutils 0.7).
292 used for `font setup`_
295 To use the better looking ``txtt`` font for monospaced text define the
296 latex-preamble_ setting in a configuration file::
298 latex-preamble: \renewcommand{\ttdefault}{txtt}
299 \usepackage{mathptmx} % Times
300 \usepackage[scaled=.92]{helvet} % Helvetica
303 config.html#latex-preamble
304 .. _PDF standard fonts:
305 http://en.wikipedia.org/wiki/PDF#Standard_Type_1_Fonts
307 http://www.linuxlibertine.org/index.php?id=1&L=1
313 Some customizations require commands at places other than the insertion
314 point of stylesheets or depend on the deletion/replacement of parts of the
315 document. This can be done via a custom template. See the `publisher
316 documentation`_ for a description of the document parts available in a
322 In addition to the 'default.tex' template, the latex writer directory
323 contains the alternative 'titlepage.tex'.
326 Print a title page including docinfo, dedication, and abstract::
328 --template=titlepage.tex
330 .. _publisher documentation: ../api/publisher.html
331 .. _template: config.html#template-latex2e-writer
337 By means of the `raw directive`_ or a derived `custom role`_, one can
338 give commands directly to LaTeX. These can be both, styling as well as
346 \[x^3 + 3x^2a + 3xa^2 + a^3,\]
348 (Drawback: the formula will be invisible in other output formats.)
350 Most LaTeX code examples also work as raw LaTeX inside the document.
351 An exception are commands that need to be given in the document
352 preamble (e.g. package loading with ``\usepackage``, which can be
353 achieved with the ``--style-sheet`` or ``--latex-preamble`` command
354 line options instead). Remember to use *re-defining* commands for
355 customizing `Docutils special LaTeX macros`_ with raw LaTeX.
358 Define the transition command as page break::
362 \renewcommand*{\DUtransition}{\pagebreak[4]}
365 * Defining a macro for a `custom role`_.
366 * Forcing `page breaks`_.
369 ../ref/rst/directives.html#raw
373 How to configure the ...
374 ========================
379 Admonitions__ are specially marked "topics" that can appear anywhere an
380 ordinary body element can.
382 __ ../ref/rst/directives.html#admonitions
388 Typeset in a frame (90 % of text width).
390 The admonition title is typeset with the ``\DUtitle`` command which also
391 takes a class argument. See `topic title`_
394 A lighter layout without the frame::
396 \newcommand{\DUadmonition}[2][class-arg]{%
397 % try \DUadmonition#1{#2}:
398 \ifcsname DUadmonition#1\endcsname%
399 \csname DUadmonition#1\endcsname{#2}%
407 The first part of this definition acts as a "dispatcher". This way it is
408 possible to define a special handling of `specific admonitions`_ based on
409 the "class" argument.
411 .. _specific admonitions:
412 ../ref/rst/directives.html#specific-admonitions
415 Use ``.. note::`` for a margin note::
417 \newcommand{\DUadmonitionnote}[1]{\marginpar{#1}}
419 Make sure there is enough space to fit the note.
420 See also the marginnote_ and pdfcomment_ packages.
423 http://mirror.ctan.org/help/Catalogue/entries/marginnote.html
425 http://mirror.ctan.org/help/Catalogue/entries/pdfcomment.html
430 custom interpreted text roles
431 -----------------------------
433 The rst `role directive`_ allows defining custom `text roles`_
434 that mark parts of inline text (spans) with a class argument.
436 * Role names and class arguments are converted to conform to the regular
437 expression ``[a-z][-a-z0-9]*`` (see `class directive`_).
439 * Class arguments may contain numbers and hyphens, which need special
440 treatment in LaTeX command names. (The special command ``\@namedef`` can
441 help with the definition of corresponding commands.)
443 * Custom roles can have multiple class arguments.
445 In contrast to HTML/CSS, the order of the class arguments might matter.
448 ``\DUrole``: dispatcher command
450 ``\DUroleCLASSARGUMENT``: optional styling command
453 The definition of ``\DUrole{CLASSARGUMENT}{}`` calls the macro named
454 ``\DUroleCLASSARGUMENT{}``\ [#]_ if it is defined (but silently ignores
455 this class argument if a corresponding macro is not defined).
457 .. [#] For backwards compatibility, the prefix ``\docutilsrole...`` in the
458 styling commands also recognized.
461 Typeset text in small caps::
465 :smallcaps:`Fourier` transformation
467 This is transformed to the LaTeX code::
469 \DUrole{smallcaps}{Fourier} transformation
473 \newcommand{\DUrolesmallcaps}{\textsc}
475 as `raw LaTeX`_ or in the custom `style sheet`_ will give the expected
476 result (if the text font_ supports small caps).
479 Subscript text in normal size and *italic* shape::
481 .. role:: sub(subscript)
483 As "sub" inherits from the standard "subscript" role, the LaTeX macro
484 only needs to set the size and shape::
486 \newcommand{\DUrolesub}{\normalsize\itshape}
489 A role with several classes and a converted class name::
492 :class: argI argII arg_3
494 is translated to the nested commands::
496 \DUrole{argi}{\DUrole{argii}{\DUrole{arg-3}{<content>}}}
498 With the definitions::
500 \newcommand{\DUroleargi}[1]{\textsc}
501 \newcommand{\DUroleargii}[1]{{\large #1}}
503 \@namedef{DUrolearg-3}{\textbf}
506 in a `style sheet`_\ [#]_ or as `raw LaTeX`_ in the document source,
507 text styled with ``:custom4:`large bold small-caps``` will be typeset
510 .. [#] Leave out the ``\makeatletter`` - ``\makeatother`` pair if the style
511 sheet is a LaTeX package (``*.sty``).
514 ../ref/rst/directives.html#role
517 ../ref/rst/roles.html
520 ../ref/rst/directives.html#class
525 ReStructuredText `definition lists`__ correspond to HTML ``<dl>`` list
529 ``description``: LaTeX standard environment
532 ``\descriptionlabel``: styling macro for the description term
535 bold label text, hanging indent
538 A non-bold label can be achieved with::
540 \renewcommand\descriptionlabel[1]{\hspace\labelsep \normalfont #1}
542 __ ../ref/rst/restructuredtext.html#definition-lists
548 There are hundreds of LaTeX document classes installed by modern
549 LaTeX distributions, provided by publishers, or available at CTAN_.
550 The `TeX Catalogue`_ lists most of them.
552 Popular document classes:
553 * article, report, book: standard document classes
554 * scrartcl, scrrprt, scrbook: KOMA-script_ classes
555 * memoir_: highly configurable class for larger documents
561 http://mirror.ctan.org/help/Catalogue/entries/koma-script.html
563 http://mirror.ctan.org/help/Catalogue/entries/memoir.html
565 config.html#documentclass
571 Content of the `bibliographic fields`__ at the top of a document.
572 By default, docinfo items are typeset as a table.
575 use-latex-docinfo_, use-latex-abstract_
578 ``\DUdocinfowidth``: the width for the `docinfo` table.
581 90 % of text width: ``0.9\textwidth``
584 set to 70 % of text width::
586 \newlength{\DUdocinfowidth}
587 \setlength{\DUdocinfowidth}{0.7\textwidth}
589 __ ../ref/rst/restructuredtext.html#bibliographic-fields
591 .. _use-latex-docinfo:
592 config.html#use-latex-docinfo
593 .. _use-latex-abstract:
594 config.html#use-latex-abstract
600 A lone top-level section title is (usually) transformed to the document title
601 (see `section structure`_).
603 The format of the document title is defined by the `document class`_. The
604 "article" document class uses an in-page title and the "report" and "book"
605 classes write a separate title page. See the `TeX FAQ`_ on how to customize
606 the `style of document titles`_.
608 The default title page shows only title and subtitle, date and author
609 are shown in the `document info`_ table.
614 ``--template=titlepage.tex`` Put docinfo and abstract into the title page.
615 A separate title page is used also with the "abstract" document class.
617 .. _section structure: rst/quickref.html#section-structure
618 .. _TeX FAQ: http://www.tex.ac.uk/faq
619 .. _style of document titles:
620 http://www.tex.ac.uk/cgi-bin/texfaq2html?label=titlsty
626 `Field lists`__ may be used as generic two-column table constructs in
633 Indented description list.
636 Use a description list customized with enumitem_::
638 \usepackage{enumitem}
639 \newenvironment{DUfieldlist}%
640 {\description[font=,style=sameline,leftmargin=8em]}
644 The `KOMA-script`_ classes provide a similar environment under the name
648 http://mirror.ctan.org/help/Catalogue/entries/enumitem.html
650 __ ../ref/rst/restructuredtext.html#field-lists
653 figure and table captions
654 -------------------------
656 The caption_ package provides many ways to customise the captions in
657 floating environments like figure and table.
659 The chngcntr_ package helps to configure the numbering of figure and table
662 Some document classes (e.g. KOMA-script_) provide additional configuration.
663 Also see the related `LaTeX FAQ entry`__
669 \captionsetup{justification=raggedleft,singlelinecheck=false}
672 http://mirror.ctan.org/help/Catalogue/entries/caption.html
674 http://mirror.ctan.org/help/Catalogue/entries/chngcntr.html
675 __ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=running-nos
681 Figures_ might be typeset at the place of definition (default) or "float"
682 to a suitable place at the top or bottom of a page. This is implemented
683 using the float_ package.
688 The placement setting is valid from the point of definition until the next
689 ``\floatplacement`` command or the end of the document. See float.pdf_ for
693 ``\floatplacement{figure}{H}`` (here definitely). This corresponds most
694 closely to the source and HTML placement (principle of least surprise).
697 In a custom `style sheet`_, set the default to let LaTeX find a suitable
698 place for figure floats::
701 \floatplacement{figure}{htbp} % here, top, bottom, extra-page
704 To move all following figures to the top or bottom of the page write in
705 the document source::
709 \floatplacement{figure}{tb}
711 .. _figures: ../ref/rst/directives.html#figure
713 http://mirror.ctan.org/help/Catalogue/entries/float.html
715 http://mirror.ctan.org/macros/latex/contrib/float/float.pdf
722 The selected text font influences the *look*, the *feel*,
723 and the *readability* of the document (cf.
724 http://www.csarven.ca/web-typography).
725 Selecting a suitable font also solves the problem with `bad looking
728 Font selection is one of the main differences between LaTeX and XeTeX:
731 cannot use the fonts of the operating system directly but needs
732 specially installed fonts with additional supporting files.
735 can use system fonts and provides access to the full feature set of
736 modern OpenType_ fonts.
738 .. _OpenType: http://en.wikipedia.org/wiki/OpenType
740 The default font setup is done in the latex-preamble_:
743 `PDF standard fonts`_ (Times, Helvetica, Courier)
746 `Linux Libertine`_, a free, high quality alternative to Times with a
747 wide coverage of glyphs, styles, and OpenType features.
749 Despite its name, Linux Libertine can be used on any operating
750 system that can handle OpenType fonts.
752 Alternative fonts can be selected by
755 a) specifying the corresponding LaTeX package(s) as argument to the
756 stylesheet_ option_ or with the ``\usepackage`` LaTeX command.
758 * packages can be combined,
759 * passing options to a package is only possible in a `style sheet`_
760 or the `LaTeX preamble`_.
762 b) changing the font-default macros ``\rmdefault``, ``\sfdefault``
763 and/or ``\ttdefault`` in a custom `style sheet`_, the `LaTeX
764 preamble`_ or `raw LaTeX`_.
767 Use `Latin Modern`_. LaTeX code::
771 Command line argument::
776 The _`Times/Helvetica/Courier` `PDF standard fonts`_ are
777 selected by the LaTeX code [#]_::
779 \usepackage{mathptmx} % Times for serif and math
780 \usepackage[scaled=.90]{helvet} % downscaled Helvetica for sans serif
781 \usepackage{courier} % Courier for teletype (mono-space)
783 Since Docutils 0.7, this is the default value of the
784 `latex-preamble`_ option.
786 .. [#] When generating PDF-files from LaTeX, the `PDF standard
787 fonts`_ do not need to be embedded in the document. While this
788 results in smaller files, the actually used fonts on screen and in
789 print might differ! (For details see, e.g., the testflow_ package
794 Use the teletype font from the txfonts_ package. As there is no
795 package for this, we re-define the font macro with the LaTeX code::
797 \renewcommand{\ttdefault}{txtt}
801 using the macros of the fontspec_ package. Use some font-viewer or
802 -manager (e.g. fontmatrix_) to find out the correct names of the
803 fonts on your system.
806 DejaVu_, very wide coverage, screen optimized. As this font
807 runs wide, add ``DIV=10`` to the `documentoptions`_::
809 \setmainfont{DejaVu Serif}
810 \setsansfont{DejaVu Sans}
811 \setmonofont[HyphenChar=None]{DejaVu Sans Mono}
813 .. _fontspec: http://mirror.ctan.org/help/Catalogue/entries/fontspec.html
814 .. _fontmatrix: http://fontmatrix.net/
815 .. _DejaVu: http://dejavu-fonts.org/
816 .. _documentoptions: config.html#documentoptions
818 choice of suitable fonts
819 ````````````````````````
821 High quality free fonts suitable for use with XeTeX are, e.g., listed
822 at `Good Libre Fonts`_, `25 Best Free Quality Fonts`_ and the update
823 `19 More Free Quality Fonts`_.
825 The `LaTeX Font Catalogue`_ provides information and examples for a wide
826 range of fonts available for use with LaTeX. Here is just a selection:
828 a) The `Latin Modern`_ (LM) fonts are extended outline versions of the
829 standard TeX font Computer Modern (CM).
831 +1 simple invocation: ``--stylesheet=lmodern``
833 +1 keeps the traditional TeX "look and feel":
835 +1 generally accepted as high quality CM replacement,
836 +1 comprehensive math support,
837 +1 including optical sizes,
838 +1 compatible with extensions made to match CM,
839 -1 modern types are hard to read at low (screen) resolutions.
841 -2 not part of a minimal standard TeX installation
843 -1 might not work out-of-the-box
844 -1 large additional download (ca. 12 ... 17 MB)
846 b) CM-Super_ is another outline CM replacement.
848 +1 simple invocation: modern LaTeX distributions use CM-Super
849 automatically instead of CM if it is installed.
851 -1 said to be of inferior quality compared to LM.
853 -2 not part of a minimal standard TeX installation,
854 even bigger download size than Latin Modern.
856 c) `Bera`_ (Bitstream Vera)
858 +1 simple invocation: ``--stylesheet=bera``
860 +1 optimized for on-screen viewing with goot hinting
862 -2 not part of a minimal standard TeX installation
864 d) PSNFSS_ Postscript fonts
866 +1 part of every standard TeX installation
868 +1 smaller PDF/Postscript document size if standard fonts are not
871 -1 restricted set of glyphs in the free versions [#]_
873 -1 different fonts for roman, sans-serif and typewriter fonts.
875 -1 invocation somewhat more complex, as several packages are
876 required for a complete font set, sometimes including package
879 Roman (serif) PSNFSS fonts:
882 good legibility but very wide.
885 bread-and-butter type optimized for printing on low-resolution
888 New Century Schoolbook
889 good legibility but very wide.
892 +1 recommended by font experts
893 +1 good LaTeX support including matching math fonts, small caps,
895 -1 bad rendering in xpdf viewer (auto-hinting leads to different
896 x-hight for different characters at some magnifications)
897 (this is fixed in recent versions).
900 +1 the serif `PDF Standard Font`_,
901 -1 overused and quite narrow (devised for multi-column layouts).
904 recommended by font experts
907 .. table:: Font packages for standard Postscript fonts
908 (cf. `Using common Postscript fonts with LaTeX`_)
910 ========= ============ ============= ============= =========
911 Package Roman Sans Serif Typewriter Math
912 ========= ============ ============= ============= =========
913 (none) CM Roman CM Sans Serif CM Typewriter CM Math
915 mathpazo Palatino Palatino
928 bookman Bookman Avant Garde Courier
930 newcent New Century Avant Garde Courier
936 ========= ============ ============= ============= =========
938 .. [#] Extended versions of the standard Postscript fonts including
939 accented chars, Greek and Cyrillic as well as real small-caps
940 and old-style numbers are available with the `TeX Gyre`_ bundle
941 which is part of, e.g., `TeX Live`_.
944 .. _LaTeX Font Catalogue:
945 http://www.tug.dk/FontCatalogue/
947 http://mirror.ctan.org/help/Catalogue/entries/lm.html
949 http://mirror.ctan.org/help/Catalogue/entries/cm-super.html
951 http://mirror.ctan.org/help/Catalogue/entries/bera.html
952 .. _TeX Gyre: http://www.gust.org.pl/projects/e-foundry/tex-gyre
954 http://mirror.ctan.org/help/Catalogue/entries/psnfss.html
955 .. _Using common PostScript fonts with LaTeX:
956 http://mirror.ctan.org/macros/latex/required/psnfss/psnfss2e.pdf
957 .. _TeX Live: http://tug.org/texlive/
959 http://mirror.ctan.org/help/Catalogue/entries/txfonts.html
960 .. _PDF Standard Font:
961 http://en.wikipedia.org/wiki/PDF#Standard_Type_1_Fonts
963 http://www.tex.ac.uk/tex-archive/help/Catalogue/entries/testflow.html
964 .. _Good Libre Fonts:
965 http://typophile.com/node/18207
966 .. _25 Best Free Quality Fonts:
967 http://www.alvit.de/blog/article/20-best-license-free-official-fonts
968 .. _19 More Free Quality Fonts:
969 http://www.smashingmagazine.com/2006/10/11/17-more-free-quality-fonts/
975 LaTeX font encodings are described in detail in the encguide_ which is
976 part of the LaTeX base documentation.
985 Use the (obsolete) LaTeX default encoding "OT1"::
989 or (without loading the fontenc_ package)::
993 This will improve the look on screen with the default Computer Modern
994 fonts at the expense of problems with `search and text extraction`_
995 The recommended way is to select a T1-encoded "Type 1" (vector)
996 font, for example `Latin Modern`_
999 Support for characters in the Unicode blocks Latin, Latin-1 Supplement,
1000 and Greek together with a T1-encoded "Type 1" (vector) font, for example
1003 --font-encoding=LGR,T1 --stylesheet=lmodern
1006 http://mirror.ctan.org/macros/latex/doc/encguide.pdf
1008 config.html#font-encoding
1010 http://mirror.ctan.org/help/Catalogue/entries/fontenc.html
1016 Add font size in points to the document options, e.g.
1017 ``--documentoptions=12``, use e.g. the document classes provided by
1018 extsizes_ for values other than [10,11,12].
1021 http://mirror.ctan.org/help/Catalogue/entries/extsizes.html
1027 By default, footnotes are set with Docutils-specific wrappers around
1028 the standard ``\footnotemark`` and ``\footnotetext`` commands. You
1029 can configure the footnote layout similar to standard LaTeX footnotes
1030 in a custom `style sheet`_.
1032 Further configuration is possible by alternative definitions of
1033 ``\DUfootnotemark`` and ``\DUfootnotetext``
1037 Set footnote text with a hanging indent.
1039 * This is the default with KOMA-script_ classes, e.g::
1041 --documentclass=scrartcl
1043 (for further configuration, see the `KOMA-script Guide`_),
1045 * with package footmisc_::
1047 \usepackage[hang]{footmisc}
1048 \setlength{\footnotemargin}{0em}
1050 (play with the ``\footnotemargin`` setting),
1052 * redefine ``\DUfootnotetext`` inserting `\hangindent`::
1054 \newcommand{\DUfootnotetext}[4]{%
1056 \renewcommand{\thefootnote}{%
1057 \protect\raisebox{1em}{\protect\hypertarget{#1}{}}%
1058 \protect\hyperlink{#2}{#3}}%
1059 \footnotetext{\hangindent=2em #4}%
1063 (adapt the ``\hangindent`` value).
1066 place the footnote text where it appears in the source document (instead
1067 of at the page bottom). This can be used to get the effect of endnotes
1068 (needs the hanging_ package)::
1070 \usepackage{hanging}
1071 \newcommand{\DUfootnotetext}[4]{%
1072 \par\noindent\raisebox{1em}{\hypertarget{#1}{}}%
1074 \hangpara{\parindent}{1}#4%
1078 http://mirror.ctan.org/help/Catalogue/entries/footmisc.html
1080 http://mirror.ctan.org/help/Catalogue/entries/hanging.html
1086 The amount of hyphenation is influenced by ``\hyphenpenalty``, setting it to
1087 10000 almost prevents hyphenation. As this produces lines with more space
1088 between words one should increase Latex's ``\tolerance`` for this.
1101 hyperlink-color_, hyperref-options_
1103 Hyperlinks are realized using the hyperref_ package. As it re-defines many
1104 standard LaTeX macros, this package is loaded last, *after* the style
1107 However, you can load hyperref before a package that requires its
1108 presence in a `style sheet`_ or the `LaTeX preamble`_ (see example
1109 below). This will ignore options set with hyperlink-color_ and
1112 URLs are typeset with the "url" package (loaded implicitely by "hyperref").
1113 The font of URLs can be defined with the ``\urlstyle`` command. Valid
1116 :same: normal text font, Docutils default,
1117 :tt: teletype (monospaced), LaTeX default,
1122 Custom loading of the hyperref package also switches to
1123 the LaTeX default (monospaced fonts for URLs). Reset to use the text
1126 \usepackage[unicode,colorlinks=true,linkcolor=green]{hyperref}
1129 See also `non-breaking hyperlinks`_.
1131 .. _hyperlink-color:
1132 config.html#hyperlink-color
1133 .. _hyperref-options:
1134 config.html#hyperref-options
1140 To suppress the hyper-linking completely (e.g. for printing or to
1141 avoid clashes with other packages), set hyperref-options_ to "draft"
1142 or load the "nohyperref" package that comes with the "hyperref"
1146 ``--hyperref-options=draft``
1150 \usepackage{nohyperref,url}
1154 http://mirror.ctan.org/help/Catalogue/entries/hyperref.html
1159 In `line blocks`__, newlines and leading whitespace are respected.
1162 ``DUlineblock``: special list environment for line blocks
1165 ``\DUlineblockindent``: indentation of indented lineblock parts.
1168 2.5 times the font hight: ``2.5em``
1171 set to the paragraph indentation::
1173 \newlength{\DUlineblockindent}
1174 \setlength{\DUlineblockindent}{\parindent}
1176 __ ../ref/rst/restructuredtext.html#line-blocks
1183 ``\linespread``: for small adjustments
1185 ``\singlespacing``, ``\onehalfspacing``, and ``\doublespacing``: from
1189 Get document wide double spacing::
1191 \usepackage{setspace}
1195 Increase line spacing by five percent for better readability::
1203 No markup processing is done within a `literal block`__. It is left as-is,
1204 and is typically rendered in a monospaced typeface
1211 ``--literal-block-env=lstlisting``
1213 The ``lstlisting`` environment is highly configurable (as documented in
1214 listings.pdf_), for instance ::
1216 \renewcommand{\ttdefault}{txtt}
1217 \lstset{language=Python, morekeywords=[1]{yield}}
1218 \lstloadlanguages{Python}
1220 basicstyle=\ttfamily,
1221 keywordstyle=\bfseries,
1222 commentstyle=\rmfamily\itshape,
1223 stringstyle=\slshape,
1225 \lstset{showstringspaces=false}
1226 \lstset{columns=fullflexible,
1227 basewidth={0.5em,0.4em}}
1230 The indentation of literal blocks can be reset with ::
1232 \lstset{resetmargins=true}
1234 and/or configured with e. g.::
1236 \lstset{xleftmargin=-2em}
1238 __ ../ref/rst/restructuredtext.html#literal-blocks
1239 .. _literal-block-env:
1240 config.html#literal-block-env
1242 http://mirror.ctan.org/macros/latex/contrib/listings/listings.pdf
1245 list of figures/tables
1246 ----------------------
1248 Docutils does not support lists of figures or tables.
1250 However, with LaTeX, they can be generated using `raw LaTeX`_ in the
1254 ``\listoffigures``: a list of figures
1256 ``\listoftables``: a list of tables
1269 `Option lists`__ are two-column lists of command-line options and
1270 descriptions, documenting a program's options.
1273 ``DUoptionlist``: environment for option lists,
1276 ``\DUoptionlistlabel``: set appearance of the options
1279 set command options with a bold monospace font::
1281 \newcommand{\DUoptionlistlabel}{\texttt{\textbf{#1}} \hfill}
1283 __ ../ref/rst/restructuredtext.html#option-lists
1289 * Page breaks before top-level sections are the default with a
1290 documentclass that provides "chapters", e.g. "book", "memoir" or
1293 * Redefining the \section or \section* command in a
1294 style sheet is possible too.
1296 * `Raw LaTeX`_ or a `custom role`_ can be used.
1298 * The transition element can be re-defined to produce a page break,
1301 ``\newpage``: hard pagebreak at exactly this position
1303 ``\pagebreak[2]``: recommended page break after line end (precedence 1...4)
1307 Define the transition command as page break with the LaTeX code::
1309 \newcommand*{\DUtransition}{\pagebreak[4]}
1311 (use ``\renewcommand`` with `raw LaTeX`_).
1316 By default, paper size and margin settings are determined by the document
1319 The following packages help to configure the page layout:
1321 a) The `typearea`_ package (part of the `KOMA-script`_ bundle) calculates a
1322 *good* page layout (based on rules and recommendations of typography
1325 See the `KOMA-Script Guide`_ for details on what is a *good* layout and
1326 how this is achieved.
1328 b) The `geometry`_ package is recommended if you have to follow guidelines
1329 with fixed values for the margins.
1330 For details see the `geometry manual`_.
1333 Let `typearea` determine the type area with ``DIV=calc`` in the
1336 --documentoptions='a4paper,DIV=calc'
1338 The ``DIV`` option can also be specified, like ``DIV=10``. It defines how
1339 "crowded" a page will be: larger values mean larger text area (at the
1340 expense of readability).
1343 LaTeX code to set margins with the geometry_ package::
1345 \usepackage{geometry}
1346 \geometry{hmargin={3cm,0.8in},height=8in}
1347 \geometry{height=10in}.
1350 http://mirror.ctan.org/help/Catalogue/entries/typearea.html
1351 .. _KOMA-Script Guide:
1352 http://mirror.ctan.org/macros/latex/contrib/koma-script/scrguien.pdf
1354 http://mirror.ctan.org/help/Catalogue/entries/geometry.html
1355 .. _geometry manual:
1356 http://mirror.ctan.org/macros/latex/contrib/geometry/geometry.pdf
1359 page headers and footers
1360 ------------------------
1362 With the fancyhdr_ package or the `KOMA-script`_ classes, you can define
1363 custom page head- and foot-lines.
1365 The "header" and "footer" directives save their content in the macros
1366 ``\DUheader`` rsp. ``\DUfooter``. The macros can be used in LaTeX code and
1367 will be replaced by LaTeX with the content of the directives.
1370 Place left-aligned "header" and "footer" on every page with fancyhdr_::
1372 \usepackage{fancyhdr}
1373 \fancyhead[L]{\DUheader}
1374 \fancyfoot{} % reset
1375 \fancyfoot[L]{\DUfooter}
1378 .. _fancyhdr: http://www.ctan.org/pkg/fancyhdr
1385 Number pages by chapter (using the chappg_ package)::
1389 See the `chappg documentation`_ for details.
1392 http://mirror.ctan.org/help/Catalogue/entries/chappg.html
1393 .. _chappg documentation:
1394 http://mirror.ctan.org/macros/latex/contrib/chappg/chappg.pdf
1400 Paper geometry can be changed using ``--documentoptions`` or with the
1401 `geometry`_ package.
1405 \usepackage{geometry}
1406 \geometry{OPTIONLIST}
1413 * a4paper, b3paper, letterpaper, executivepaper, legalpaper
1414 * landscape, portrait, twoside.
1417 Choose A5 pager in landscape orientation with command line argument::
1419 --documentoptions=a5paper,landscape
1421 The same with LaTeX commands in the `style sheet`_::
1423 \usepackage{geometry}
1424 \geometry{a5paper,landscape}
1426 For details see the `geometry manual`_.
1431 Default (in most document classes):
1432 Indent the first line in a paragraph unless it is the first line of a
1433 chapter, section, subsection, or subsubsection.
1436 To set paragraph indentation to zero but add a vertical space between
1437 load the `parskip` package with the command line argument::
1439 --stylesheet=parskip
1441 or in a custom `style sheet`_ with::
1443 \usepackage{parskip}
1449 A rubric__ is like an informal heading that doesn't correspond to the
1450 document's structure.
1456 subsubsection style, italic, centred
1459 set flushleft and red::
1461 \newcommand*{\DUrubric}[2][class-arg]{%
1462 \subsubsection*{{\color{red}#1}\hfill}}
1464 __ ../ref/rst/directives.html#rubric
1470 Sections are numbered if there is a `sectnum directive`_ in the document.
1472 Option: sectnum_xform_
1473 ``--section-numbering``, ``--no-section-numbering``
1475 If sectnum_xform_ is False, section numbers are generated by LaTeX. In this
1476 case the "prefix" and "suffix" arguments of the `sectnum directive`_ are
1477 ignored. The section number style is determined by the `document class`_
1478 and can be configured in a LaTeX `style sheet`_, e.g.::
1480 \setcounter{secnumdepth}{5}
1482 .. note:: The LaTeX name is 'secnumdepth' (whithout 't').
1484 .. _sectnum directive: ../ref/rst/directives.html#sectnum
1485 .. _sectnum_xform: config.html#sectnum-xform
1491 Sidebars__ are like miniature, parallel documents that occur inside other
1492 documents, providing related or reference material. They can be likened to
1493 super-footnotes; their content is outside of the flow of the document's main
1500 Box with grey background.
1503 Less space before the title::
1505 \providecommand{\DUsidebar}[2]{%
1507 \colorbox[gray]{0.90}{\parbox{0.9\textwidth}{%
1508 \smallskip\textbf{#1}\smallskip
1516 \newcommand{\DUsidebar}[2]{\marginpar{\flushleft \textbf{#1} #2}}
1518 * Make sure the margin is wide enough to hold the note.
1519 * This fails with some constructs inside the `side bar` and where
1520 \marginpar cannot be used, e.g., inside floats, footnotes, or in frames
1521 made with the framed package (see marginnote_).
1523 __ http://docutils.sf.net/docutils/docs/ref/rst/directives.html#sidebar
1528 The length unit ``px`` is a "relative length" whose value depends on the
1529 *resolution* of the output device (usually specified in *dots per inch*
1530 (DPI). However, when producing a PDF, the resolution of the output device
1531 (printer, screen (for PDF-viewer)) is generally not known.
1533 With pdftex, the "resolution" is a configuration setting.
1536 72 DPI, i.e. 1 px = 1/72 in.
1539 Set a resolution of 96 DPI with the LaTeX code::
1541 \pdfpxdimen=1in % 1 DPI
1542 \divide\pdfpxdimen by 96 % 96 DPI
1548 A topic_ is like a block quote with a title, or a self-contained section with
1551 Topics and rubrics can be used at places where a `section title`_ is not
1552 allowed (e.g. inside a directive).
1561 If you generally prefer a "normal" section over a block quote, define::
1563 \newcommand{\DUtopic}[2][class-arg]{%
1564 \ifcsname DUtopic#1\endcsname%
1565 \csname DUtopic#1\endcsname{#2}%
1572 If you want a "normal" section for topics with class argument "noquote",
1575 \newcommand{\DUtopicnoquote}[1]{#1}
1577 .. _topic: ../ref/rst/directives.html#topic
1578 .. _section title: ../ref/rst/restructuredtext.html#sections
1584 The titles of admonitions_, sidebar_, and `topic element`_ are defined with
1585 the ``\DUtitle`` command that also takes a "class" argument.
1588 a centered and somewhat larger title for topcis::
1590 \newcommand*{\DUtitletopic}[1]{\subsection*{\centering #1}
1593 a right-pointing hand as title for the "attention" directive::
1596 \newcommand{\DUtitleattention}[1]{\ding{43}}
1598 The title argument is "swallowed" by the command.
1599 To have both, hand and title use::
1602 \newcommand{\DUtitleattention}[1]{\ding{43} #1}
1608 A `contents directive`_ is replaced by a table of contents (ToC).
1610 Option: use-latex-toc_
1611 ``--use-latex-toc``, ``--use-docutils-toc``
1613 With use-latex-toc (default since release 0.6):
1615 * The ToC is generated by LaTeX (via the ``\tableofcontents`` command).
1617 The layout depends on the choosen document class and can be configured in
1618 a custom `style sheet`_ (see e.g. the `KOMA-Script Guide`_ for the
1619 `KOMA-script`_ classes).
1621 * The depth of the ToC and PDF-bookmarks can be configured
1623 + with the "depth" argument of the `contents directive`_, or
1625 + in a style sheet with e.g. ``\setcounter{tocdepth}{5}``.
1627 * Local ToCs are done with the minitoc_ package. See the `minitoc
1628 documentation`_ for the numerous configuration options.
1631 Minitoc supports local ToCs only at "part" and top section level
1632 ("chapter" or "section"). Local `contents` directives at lower levels
1633 are ignored (a warning is issued).
1635 This is an intended feature of the minitoc_ package. If you really
1636 require local ToCs at lower level, turn off the use-latex-toc_ option.
1638 .. _use-latex-toc: config.html#use-latex-toc
1639 .. _contents directive: ../ref/rst/directives.html#contents
1641 http://mirror.ctan.org/help/Catalogue/entries/minitoc.html
1642 .. _minitoc documentation:
1643 http://mirror.ctan.org/macros/latex/contrib/minitoc/minitoc.pdf
1646 title reference role
1647 --------------------
1649 `Title reference`_ is the default `default role`_ for `interpreted text`_.
1652 ``\DUroletitlereference``
1655 use slanted font (``\textsl``)
1658 set title references with a bold monospace font::
1660 \newcommand{\DUroletitlereference}[1]{\texttt{\textbf{#1}}}
1662 .. _title reference:
1663 ../ref/rst/roles.html#title-reference
1665 ../ref/rst/directives.html#setting-the-default-interpreted-text-role
1666 .. _interpreted text:
1667 ../ref/rst/restructuredtext.html#interpreted-text
1673 The encoding of the LaTeX source file is Docutils' *output* encoding
1674 but LaTeX' *input* encoding.
1676 Option: output-encoding_
1677 ``--output-encoding=OUTPUT-ENCODING``
1683 Encode the LaTeX source file with the ISO `latin-1` (west european)
1684 8-bit encoding (the default in Docutils versions up to 0.6.)::
1686 --output-encoding=latin-1
1689 LaTeX comes with two options for UTF-8 support,
1691 :utf8: by the standard `inputenc`_ package with only limited coverage
1692 (mainly accented chars, no Greek).
1694 :utf8x: supported by the `ucs`_ package covers a wider range of Unicode
1695 characters than does "utf8". It is, however, a non-standard
1696 extension and no longer developed.
1698 Currently (in version 0.6), "utf8" is used if the output-encoding is
1699 any of "utf_8", "U8", "UTF", or "utf8".
1702 If LaTeX issues a Warning about unloaded/unknown characters adding ::
1704 \PreloadUnicodePage{n}
1706 (where *n* is the Unicode page-number) to the style sheet might help.
1708 .. _LaTeX Unicode: http://www.unruh.de/DniQ/latex/unicode/
1709 .. _output-encoding: config.html#output-encoding
1711 http://mirror.ctan.org/help/Catalogue/entries/inputenc.html
1713 http://mirror.ctan.org/help/Catalogue/entries/unicode.html
1719 Transitions__ are commonly seen in novels and short fiction, as a gap
1720 spanning one or more lines, marking text divisions or signaling changes in
1721 subject, time, point of view, or emphasis.
1727 A horizontal line, 1/3 of text width
1732 \newcommand*{\DUtransition}[1][class-arg]{\centering{}*\quad*\quad*}
1734 Alternatively use the more elaborated version in `transition-stars.sty`_.
1737 If paragraphs are separated by indentation, you can simply use a vertical
1740 \newcommand*{\DUtransition}[1][class-arg]{\vspace{2ex}}
1742 __ http://docutils.sf.net/docutils/docs/ref/rst/restructuredtext.html#transitions
1744 .. _transition-stars.sty: ../../../sandbox/stylesheets/transition-stars.sty
1750 * The Docutils HISTORY_ lists all changes during the history of docutils.
1752 * Changes since release (0.5) are summarized in the RELEASE-NOTES_
1753 and explained in detail in docutils-05-compat_.
1755 * docutils-05-compat.sty_ is a `style sheet`_ that provides best possible
1756 backwards compatibility.
1758 .. _HISTORY: ../../HISTORY.html
1759 .. _RELEASE-NOTES: ../../RELEASE-NOTES.html
1760 .. _docutils-05-compat: docutils-05-compat.sty.html
1761 .. _docutils-05-compat.sty:
1762 ../../docutils/writers/latex2e/docutils-05-compat.sty
1771 Bad looking PDF output
1772 ``````````````````````
1774 What I am looking for when I try Docutils is if the PDF files I can get
1775 are of high quality. Unfortunaltely that never is the case.
1777 So am I just stupid or is there a way to get really high quality pdf from
1780 Make sure the default font is not a bitmap font.
1782 There is `Latin Modern`_ if you like the look of the standard font on paper,
1783 but want nice pdf. Or select something else like Times, Palatino, ... via
1784 configuration options_ to the Docutils tool. See font_ and font-encoding_.
1787 footnote mark and text at different pages
1788 `````````````````````````````````````````
1790 Docutils stores the footnote text in a separate node, at the position where
1791 it is specified in the input document. With the default settings, the
1792 footnote is put at the bottom of the page where the footnote text is located,
1793 maybe far away from the footnote mark (see e.g. `<rst/demo.txt>`_).
1795 To get footnote mark and text at the same page, keep footnote mark and
1796 footnote text close together!
1799 non-breaking hyperlinks
1800 ```````````````````````
1802 If you convert with ``latex`` (as opposed to ``pdflatex``), hyperlinks will
1803 not wrap and sometimes stick into the margin.
1808 \usepackage[breaklinks=true]{hyperref}
1810 "breaklinks" is an internal option that indicates whether the chosen
1811 driver can handle split links. (It might work to *disable* link breaking.)
1814 Use one of the following:
1816 a) compile with pdflatex_,
1818 b) compile with `latex + dvipdfmx`_,
1820 c) use the package breakurl_,
1822 d) (for printout) `disable hyperlinks`_ using the package "nohyperref".
1824 See also the `Link text doesn’t break at end line`_ FAQ entry.
1827 http://mirror.ctan.org/help/Catalogue/entries/breakurl.html
1829 .. _Link text doesn’t break at end line:
1830 http://www.tex.ac.uk/cgi-bin/texfaq2html?label=breaklinks
1833 Glyph not defined in PD1 encoding
1834 `````````````````````````````````
1836 If a section title or other link contains non-Latin (e.g. Cyrillic)
1837 characters, the LaTeX log contains lots of warnings like::
1839 Package hyperref Warning: Glyph not defined in PD1 encoding,
1840 (hyperref) removing `\CYRZ' on input line 6.
1843 This can be solved with the "unicode" hyperref_option_ setting::
1845 --hyperref-option=unicode
1847 (works also with non-unicode input/output encoding (e.g. "koi8r" or
1848 "latin1"). Newer versions of hyperref default to "unicode=true" if the
1849 document language is "russian".
1851 However, this setting leads to "strange" characters in the bookmarks
1852 if used with xelatex_ in hyperref versions before v6.79g (2009/11/20).
1853 (cf `bugreport 3100778`__).
1855 If updating the hyperref package is not an option, the workaround is
1858 --hyperref-option="unicode=false"
1860 or (in the config file)::
1864 hyperref-option: unicode=false
1866 __ http://sourceforge.net/tracker/?func=detail&aid=3100778&group_id=38414&atid=422030
1867 .. _hyperref_option: config.html#stylesheet-latex2e-writer
1872 Images__ are included in LaTeX with the help of the `graphicx` package. The
1873 supported file formats depend on the used driver:
1875 * Standard latex_ can include **only EPS** graphics, no other format.
1876 * `latex + dvipdfmx`_ works with EPS and JPG (add 'dvipdfmx' to the
1877 documentoptions_ and 'bmpsize' to the stylesheet_ setting).
1878 * pdflatex_ and xelatex_ work with PNG, JPG, or PDF, but **not EPS**.
1880 If PDF-image inclusion in PDF files fails, specifying
1881 ``--graphicx-option=pdftex`` or ``--graphicx-option=auto`` might help.
1883 For details see grfguide.pdf_.
1885 The Rubber_ wrapper can be used for automatic image conversion.
1887 Docutils expects an URI as pointer to the image file. The latex writer
1888 transforms this URI to a local path. By default, LaTeX does not accept
1889 spaces and more than one dot in the filename. If using "traditional"
1890 filenames is not an option, the adding grffile_ to the `style sheets`_
1893 __ ../ref/rst/directives.html#images
1895 http://mirror.ctan.org/macros/latex/required/graphics/grfguide.pdf
1897 http://mirror.ctan.org/help/Catalogue/entries/grffile.html
1901 Why are my images too big?
1902 ``````````````````````````
1904 HTML-browsers use the actual screen resolution (usually around
1907 The CSS specification suggests:
1909 It is recommended that the reference pixel be the visual angle of one
1910 pixel on a device with a pixel density of 96 DPI and a distance from the
1911 reader of an arm's length.
1913 -- http://www.w3.org/TR/CSS2/syndata.html#length-units
1915 This is why pixmap images without size specification or objects with a size
1916 specified in ``px`` tend to come too large in the PDF.
1919 Specify the image size in fixed units (``pt``, ``cm``, ``in``) or
1920 configure the `size of a pixel`_ (length unit px).
1922 Error ``illegal unit px``
1923 `````````````````````````
1925 If you convert the LaTeX source with a legacy program, you might get this
1928 The unit "px" was introduced by the `pdfTeX` converter on 2005-02-04.
1929 `pdfTeX` is used also for conversion into DVI format in all modern LaTeX
1930 distributions (since ca. 2006).
1932 If updating LaTeX is not an option, just remove the "px" from the length
1933 specification. HTML/CSS will default to "px" while the `latexe2` writer
1934 will add the fallback unit "bp".
1936 Error ``Symbol \textcurrency not provided`` ...
1937 ```````````````````````````````````````````````
1939 The currency sign (\\u00a4) is not supported by all fonts (some have
1940 an Euro sign at its place). You might see an error like::
1942 ! Package textcomp Error: Symbol \textcurrency not provided by
1943 (textcomp) font family ptm in TS1 encoding.
1944 (textcomp) Default family used instead.
1946 (which in case of font family "ptm" is a false positive). Add either
1948 :warn: turn the error in a warning, use the default symbol (bitmap), or
1949 :force,almostfull: use the symbol provided by the font at the users
1952 to the document options or use a different font package.
1954 Search and text extraction
1955 ``````````````````````````
1957 Search for text that contains characters outside the ASCII range (e.g.
1958 umlauts) might fail. See font_ and `font encoding`_ (as well as
1959 `Searching PDF files`_ for background information).
1961 .. _Searching PDF files:
1962 http://www.tex.ac.uk/cgi-bin/texfaq2html?label=srchpdf
1964 Unicode box drawing and block characters
1965 ````````````````````````````````````````
1967 The easiest solution is to use xelatex_ for `PDF generation`_.
1969 With "traditional" TeX engines (e.g. pdflatex_):
1971 - Generate LaTeX code with `output-encoding`_ "utf-8".
1973 - Add the pmboxdraw_ package to the `style sheets`_.
1974 (For shaded boxes also add the `color` package.)
1976 Unfortunately, this defines only a subset of the characters
1977 (see pmboxdraw.pdf_ for a list).
1980 http://mirror.ctan.org/help/Catalogue/entries/pmboxdraw.html
1983 http://mirror.ctan.org/macros/latex/contrib/oberdiek/pmboxdraw.pdf
1985 Bugs and open issues
1986 --------------------
1988 Open to be fixed or open to discussion.
1990 See also the entries in the `Docutils TODO list`_,
1991 the BUGS_ documentation and the `SourceForge Bug Tracker`_.
1993 .. _Docutils TODO list: ../dev/todo.html#latex-writer
1994 .. _bugs: ../../BUGS.html
1995 .. _SourceForge Bug Tracker:
1996 http://sourceforge.net/tracker/?group_id=38414&atid=422030
1999 Footnotes and citations
2000 ```````````````````````
2002 Initially both were implemented using figure floats, because hyperlinking
2003 back and forth seemed to be impossible. Later the `figure` directive was
2004 added that puts images into figure floats.
2006 This results in footnotes, citations, and figures possibly being mixed at
2010 Select footnote and citation handling with the docutils-footnotes_ and
2011 use-latex-citations_ options.
2013 If ``use-latex-citations`` is used, a bibliography is inserted right at
2014 the end of the document. *This should be customizable*.
2016 If ``use-latex-citations`` is used adjacent citation references (separated
2017 only by a single space or a newline) are combined to a single citation
2018 group, i.e. ``[cite1]_ [cite2]_`` results in ``\cite{cite1,cite2}``.
2019 The appearance in the output can be configured in a `style sheet`_.
2021 .. _docutils-footnotes: config.html#docutils-footnotes
2022 .. _use-latex-citations: config.html#use-latex-citations
2028 :Tablewidth: reST-documents line length is assumed to be 80 characters. The
2029 tablewidth is set relative to this value. If someone produces
2030 documents with line length of 132 this will fail.
2032 Table width is tried to fit in page even if it is wider than
2033 the assumed linewidth, still assumed linewidth is a hook.
2035 * Table: multicol cells are always left aligned.
2037 * The contents of a rowspan cell do not influence table height.
2038 (multirow "feature", use a phantom or strut?)
2040 * Multirow cells might mix up the following table rows.
2042 * Table cells with both multirow and multicolumn are currently not possible.
2044 * literal-blocks in table cells:
2046 - If verbatim or flushleft is used one gets vertical space above and below.
2047 - This is bad for the topmost paragraph in a cell, therefore the writer
2049 - Ragged right fails on followup paragraphs as the vertical space would be
2052 * ``--table-style=booktabs``, ``..class:: booktab``: `booktabs` version
2053 1.00 does not work with `longtable`. This is solved in newer versions
2054 (current is 2005/04/14 v1.61803).
2060 * Figures are always as wide as the containing text. The "figwidth" argument
2061 is currently not supported. As a consequence, the "align" argument has no
2064 * Wrapping text around figures is currently not supported. (Requires the
2065 `wrapfig`_ package.)
2068 http://mirror.ctan.org/help/Catalogue/entries/wrapfig.html
2074 * Pdfbookmark level 4 (and greater) does not work (might be settable but
2077 * Hyperlinks are not hyphenated; this leads to bad spacing. See
2078 docs/user/rst/demo.txt 2.14 directives.
2080 * Pagestyle headings does not work, when sections are starred. Use LaTeX for
2081 the section numbering with the options_ ``--no-section-numbers``
2082 (command line) or ``sectnum_xform: False`` (config file).