1 ==================================================================
2 Changes to the Docutils latex2e writer since version 0.5
3 ==================================================================
5 A backwards compatibility style sheet
6 *************************************
9 :Contact: docutils-develop@lists.sourceforge.net
12 :Copyright: © 2009 Günter Milde,
13 :License: Released under the terms of the `2-Clause BSD license`_, in short:
15 Copying and distribution of this file, with or without modification,
16 are permitted in any medium without royalty provided the copyright
17 notice and this notice are preserved.
18 This file is offered as-is, without any warranty.
20 :Abstract: This file documents changes and provides a style for best
21 possible compatibility to the behaviour of the `latex2e`
22 writer of Doctutils release 0.5.
24 .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause
28 \NeedsTeXFormat{LaTeX2e}
29 \ProvidesPackage{docutils-05-compat}
30 [2009/03/26 v0.1 compatibility with rst2latex from Docutils 0.5]
38 * To get an (almost) identic look for your old documents,
39 place ``docutils-05-compat.sty`` in the TEXINPUT path (e.g.
40 the current work directory) and pass the
41 ``--stylesheet=docutils-05-compat`` option to ``rst2latex.py``.
43 * To use your custom stylesheets without change, add them to the
44 compatibility style, e.g.
45 ``--stylesheet="docutils-05-compat,mystyle.tex``.
47 .. tip:: As the changes include bug fixes that are partly reverted by this
48 style, it is recommended to adapt the stylesheets to the new version or
49 copy just the relevant parts of this style into them.
57 * Newlines around comments, targets and references prevent run-together
60 + An image directive with hyperlink reference or target did not start a
61 new paragraph (e.g. the first two image examples in
62 standalone_rst_latex.tex).
64 + Paragraphs were not separated if there was a (hyper) target definition
67 + Paragraphs did run together, if separated by a comment-paragraph in the
70 * Fixed missing and spurious internal links/targets.
71 Internal links now take you to the correct place.
73 * Verbose and linked system messages.
75 * `Figure and image alignment`_ now conforms to the rst definition.
77 * Put `header and footer directive`__ content in \DUheader respective
78 \DUfooter macros (ignored by the default style/template).
80 (They were put inside hard-coded markup at the top/bottom of the document
81 without an option to get them on every page.)
83 __ ../ref/rst/directives.html#document-header-footer
85 * Render doctest blocks as literal blocks (fixes bug [1586058] doctest block
86 nested in admonition). I.e.
88 + indent doctest blocks by nesting in a quote environment. This is also
89 the rendering by the HTML writer (html4css2.css).
90 + apply the ``--literal-block-env`` setting also to doctest blocks.
93 (``--literal-block-env=verbatim`` and
94 ``--literal-block-env=lstlistings`` fail with literal or doctest
95 blocks nested in an admonition.
97 * Two-way hyperlinked footnotes and support for symbol footnotes and
98 ``--footnote-references=brackets`` with ``--use-latex-footnotes``.
100 * The packages `fixltx2e` (providing LaTeX patches and the \textsubscript
101 command) and `cmap` (including character maps in the generated PDF for
102 better search and copy-and-paste operations) are now always loaded
103 (configurable with custom templates_).
105 Backwards compatibility:
106 "Bug for bug compatibility" is not provided.
109 New configuration setting defaults
110 ----------------------------------
112 - font-encoding: "T1" (formerly implicitely set by 'ae').
113 - use-latex-toc: true (ToC with page numbers).
114 - use-latex-footnotes: true (no mixup with figures).
116 Backwards compatibility:
117 Reset to the former defaults with:
120 | use-latex-toc: False
121 | use-latex-footnotes: False
123 (in the config file) or the command line options:
125 ``--figure-footnotes --use-docutils-toc --font-encoding=''``
132 * Remove redundant "double protection" from the encoding of the "special
133 printing characters" and square brackets, e.g. ``\%`` instead of
135 * Remove some spurious whitespace, e.g. ``\item [what:] -> \item[what:]``.
136 * Use conventional style for "named" macros, e.g. ``\dots{}`` instead of
139 Backwards compatibility:
140 Changes do not affect the output.
147 LaTeX packages can be used as ``--stylesheet`` argument without
151 Use ``\usepackage`` if style sheet ends with ``.sty`` or has no
152 extension and ``\input`` else.
155 while ``\input`` works with extension as well as without extension,
156 ``\usepackage`` expects the package name without extension. (The latex2e
157 writer will strip a ``.sty`` extension.)
160 Backwards compatibility:
161 Up to Docutils 0.5, if no filename extension is given in the
162 ``stylesheet`` argument, ``.tex`` is assumed (by latex).
164 Since Docutils 0.6, a stylesheet without filename extension is assumed to
165 be a LaTeX package (``*.sty``) and referenced with the ``\usepackage``
169 Always specify the extension if you want the style sheet to be
177 Advanced configuration via custom templates.
180 A ``--template`` option and config setting allows specification of a
183 See the `LaTeX writer documentation`__ for details.
185 __ latex.html#templates
191 New Feature: failsave implementation
192 As with classes to HTML objects, class arguments are silently ignored if
193 there is no styling rule for this class in a custom style sheet.
195 New Feature: custom roles based on standard roles
196 As class support needs to be handled by the LaTeX writer, this feature was
197 not present "automatically" (as in HTML). Modified visit/depart_*()
198 methods for the standard roles now call visit/depart_inline() if there are
199 class arguments to the node.
201 Backwards compatibility:
202 The implementation is fully backwards compatible. (SVN versions 5742 to
203 5861 contained an implementation that did not work with commands expecting
210 1. Add default unit if none given.
211 A poll on docutils-users favoured ``bp`` (Big Point: 1 bp = 1/72 in).
213 2. Do not change ``px`` to ``pt``.
215 3. Lengths specified in the document with unit "pt" will be written with
216 unit "bp" to the LaTeX source.
219 1. prevent LaTeX error "missing unit".
221 2. ``px`` is a valid unit in pdftex since version 1.3.0 released on
224 1px defaults to 1bp (or 72dpi), but can be changed with the
225 ``\pdfpxdimen`` primitive.::
227 \pdfpxdimen=1in % 1 dpi
228 \divide\pdfpxdimen by 96 % 96 dpi
230 -- http://www.tug.org/applications/pdftex/NEWS
232 Modern TeX distributions use pdftex also for dvi generation (i.e.
233 ``latex`` actually calls ``pdftex`` with some options).
235 3. In Docutils (as well as CSS) the unit symbol "pt" denotes the
236 `Postscript point` or `DTP point` while LaTeX uses "pt" for the `LaTeX
237 point`, which is unknown to Docutils and 0.3 % smaller.
239 The `DTP point` is available in LaTeX as "bp" (big point):
241 1 pt = 1/72.25 in < 1 bp = 1/72 in
244 Backwards compatibility:
245 Images with width specification in ``px`` come out slightly (0.3 %) larger:
247 1 px = 1 bp = 1/72 in > 1 pt = 1/72.25 in
249 This can be reset with ::
253 .. caution:: It is impossible to revert the change of lengths specified with
254 "pt" or without unit in a style sheet, however the 0.3 % change will be
255 imperceptible in most cases.
257 .. admonition:: Error ``illegal unit px``
259 The unit ``px`` is not defined in "pure" LaTeX, but introduced by the
260 `pdfTeX` converter on 2005-02-04. `pdfTeX` is used in all modern LaTeX
261 distributions (since ca. 2006) also for conversion into DVI.
263 If you convert the LaTeX source with a legacy program, you might get the
264 error ``illegal unit px``.
266 If updating LaTeX is not an option, just remove the ``px`` from the length
267 specification. HTML/CSS will default to ``px`` while the `latexe2` writer
268 will add the fallback unit ``bp``.
275 Do not mix font-encoding and font settings: do not load the obsolete
276 `ae` and `aeguill` packages unless explicitely required via the
277 ``--stylesheet`` option.
279 :font-encoding = "": do not load `ae` and `aeguill`, i.e.
281 * do not change font settings,
282 * do not use the fontenc package
283 (implicitely loaded via `ae`),
284 * use LaTeX default font encoding (OT1)
286 :font-encoding = "OT1": load `fontenc` with ``\usepackage[OT1]{fontenc}``
289 ``--font-encoding=LGR,T1`` becomes ``\usepackage[LGR,T1]{fontenc}``
290 (Latin, Latin-1 Supplement, and Greek)
293 Backwards compatibility:
294 Load the ae and aeguill packages if fontenc is not used.
296 .. tip:: Using `ae` is not recommended. A similar look (but better
297 implementation) can be achieved with the packages `lmodern`, `cmsuper`,
298 or `cmlgr` all providing Computer Modern look-alikes in vector format and
299 T1 encoding, e.g. ``--font-encoding=T1 --stylesheet=lmodern``.
301 Sub- and superscript as text
302 ----------------------------
305 Set sub- and superscript role argument in text mode not as math.
307 Pass the role content to ``\textsubscript`` or ``\textsuperscript``.
309 Backwards compatibility:
310 The old implementation set the role content in Math mode, where
312 * whitespace is ignored,
313 * a different command set and font setting scheme is active,
314 * Latin letters are typeset italic but numbers upright.
316 Although it is possible to redefine ``\textsubscript`` and
317 ``\textsuperscript`` to typeset the content in math-mode, this can lead to
318 errors with certain input and is therefore not done in this style sheet.
320 .. tip:: To get italic subscripts, define and use in your document
321 `custom roles`_ like ``.. role:: sub(subscript)`` and
322 ``.. role:: super(superscript)`` and define the "role commands"::
324 \newcommand{\DUrolesub}{\itshape}
325 \newcommand{\DUrolesuper}{\itshape}
327 Alternatively, if you want all sub- and superscripts in italic, redefine
330 %% \let\DUsup\textsubscript
331 %% \let\DUsuper\textsuperscript
332 %% \renewcommand*{\textsubscript}{\DUsub\itshape}
333 %% \renewcommand*{\textsuperscript}{\DUsuper\itshape}
335 This is not fully backwards compatible, as it will also set numbers in
336 italic shape and not ignore whitespace.
342 * Margins are configurable via the ``DIV=...`` document option.
344 * The ``\raggedbottom`` setting is no longer inserted into the document. It
345 is the default for article and report classes. If requested in combination
346 with a book class, it can be given in a custom style sheet.
348 Backwards compatibility:
349 Up to version 0.5, use of `typearea` and a DIV setting of 12 were
350 hard-coded into the latex2e writer ::
352 \usepackage{typearea}
355 and the vertical alignment of lower boundary of the text area in book
356 classes disabled via ::
361 ToC and section numbers
362 -----------------------
364 Better conformance to Docutils specifications.
367 * The "depth" argument of the "contents" and "sectnum" directives is
370 * section numbering independent of 'use-latex-toc':
372 + sections are only numbered if there is a "sectnum" directive in the
375 + section numbering by LaTeX if the "sectnum_xforms" config setting is
378 Backwards compatibility:
380 The previous behaviour was to always number sections if 'use-latex-toc' is
381 true, using the document class defaults. It cannot be restored
382 universally, the following code sets the default values of the "article"
385 \setcounter{secnumdepth}{3}
386 \setcounter{tocdepth}{3}
388 .. TODO or not to do? (Back-compatibility problems)
389 * The default "depth" of the LaTeX-created ToC and the LaTeX section
390 numbering is increased to the number of supported section levels.
393 If 'use-latex-toc' is set, local tables of content are typeset using the
394 'minitoc' package (instead of being ignored).
396 Backwards compatibility:
397 Disable the creation of local ToCs (ignoring all special commands) by
398 replacing ``\usepackage{minitoc} with ``\usepackage{mtcoff}``.
401 Default font in admonitions and sidebar
402 ---------------------------------------
405 Use default font in admonitions and sidebar.
407 Backward compatibility:
408 See the fallback definitions for admonitions_, `topic title`_ and
416 Use ``\floatplacement`` from the `float` package instead of
417 "hard-coded" optional argument for the global setting.
419 Default to ``\floatplacement{figure}{H}`` (here definitely). This
420 corresponds most closely to the source and HTML placement (principle of
423 Backwards compatibility:
424 Set the global default back to the previous used value::
427 \floatplacement{figure}{htbp} % here, top, bottom, extra-page
430 Figure and image alignment
431 --------------------------
435 a) Fix behaviour of 'align' argument to a figure (do not align figure
438 As the 'figwidth' argument is still ignored and the "natural width" of a
439 figure in LaTeX is 100% \textwidth, setting the 'align' argument of a
440 figure has currently no effect on the LaTeX output.
442 b) Set default align of image in a figure to 'center'.
444 c) Also center images that are wider than textwidth.
446 d) Align images with class "align-[right|center|left]" (allows setting the
447 alignment of an image in a figure).
449 Backwards compatibility:
450 There is no "automatic" way to reverse these changes via a style sheet.
452 a) The alignment of the image can be set with the "align-left",
453 "align-center" and "align-right" class arguments.
455 As previously, the caption of a figure is aligned according to the
456 document class -- configurable with a style sheet using the "caption"
461 c) Set the alignment of "oversized" images to "left" to get back the
468 The document preamble is pruned to contain only relevant commands and
471 Packages that are no longer required
472 ````````````````````````````````````
474 The following packages where required in pre-0.5 versions and still loaded
477 \usepackage{shortvrb}
481 Packages that are conditionally loaded
482 ``````````````````````````````````````
484 Additional to the `typearea` for `page layout`_, the following packages are
485 only loaded if actually required by doctree elements:
490 Standard package for tables across several pages::
492 \usepackage{longtable}
494 Extra space between text in tables and the line above them
495 ('array' is implicitely loaded by 'tabularx', see below)::
498 \setlength{\extrarowheight}{2pt}
500 Table cells spanning multiple rows::
502 \usepackage{multirow}
507 One-page tables with auto-width columns::
509 \usepackage{tabularx}
513 Include graphic files::
515 \usepackage{graphicx}
519 Set text and/or background colour, coloured boxes with ``\colorbox``::
523 Floats for footnotes settings
524 `````````````````````````````
526 Settings for the use of floats for footnotes are only included if
528 * the option "use-latex-footnotes" is False, and
529 * there is at least one footnote in the document.
533 % begin: floats for footnotes tweaking.
534 \setlength{\floatsep}{0.5em}
535 \setlength{\textfloatsep}{\fill}
536 \addtolength{\textfloatsep}{3em}
537 \renewcommand{\textfraction}{0.5}
538 \renewcommand{\topfraction}{0.5}
539 \renewcommand{\bottomfraction}{0.5}
540 \setcounter{totalnumber}{50}
541 \setcounter{topnumber}{50}
542 \setcounter{bottomnumber}{50}
543 % end floats for footnotes
546 Special lengths, commands, and environments
547 -------------------------------------------
554 The ``admonitionwith`` lenght is replaced by the more powerful
555 ``\DUadmonition`` command (see admonitions_).
557 Backwards compatibility:
558 The default value (90 % of the textwidth) is unchanged.
560 To configure the admonition width, you must redefine the ``DUadmonition``
561 command instead of changing the ``admonitionwith`` length value.
564 Renamed definitions (now conditional)
565 `````````````````````````````````````
567 The names for special doctree elements are now prefixed with ``DU``.
569 Up to version 0.5, all definitions were included in the preamble (before the
570 style sheet) of every document -- even if not used in the body. Since
571 version 0.6, fallback definitions are included after the style sheet and
574 Customization is done by an alternative definition in a style sheet with
575 ``\newcommand`` instead of the former ``\renewcommand``.
577 The following code provides the old definitions and maps them (or their
578 custom variants) to the new interface.
584 \newlength{\docinfowidth}
585 \setlength{\docinfowidth}{0.9\textwidth}
587 \newlength{\DUdocinfowidth}
588 \AtBeginDocument{\setlength{\DUdocinfowidth}{\docinfowidth}}
594 \newlength{\lineblockindentation}
595 \setlength{\lineblockindentation}{2.5em}
596 \newenvironment{lineblock}[1]
598 {\setlength{\partopsep}{\parskip}
599 \addtolength{\partopsep}{\baselineskip}
600 \topsep0pt\itemsep0.15\baselineskip\parsep0pt
605 \newlength{\DUlineblockindent}
606 \AtBeginDocument{\setlength{\DUlineblockindent}{\lineblockindentation}}
607 \newenvironment{DUlineblock}[1]
608 {\begin{lineblock}{#1}}
614 The ``\locallinewidth`` length for internal use in tables is replaced
615 by ``\DUtablewidth``. It was never intended for customization::
617 \newlength{\locallinewidth}
623 \newcommand{\optionlistlabel}[1]{\bf #1 \hfill}
624 \newenvironment{optionlist}[1]
626 {\setlength{\labelwidth}{#1}
627 \setlength{\rightmargin}{1cm}
628 \setlength{\leftmargin}{\rightmargin}
629 \addtolength{\leftmargin}{\labelwidth}
630 \addtolength{\leftmargin}{\labelsep}
631 \renewcommand{\makelabel}{\optionlistlabel}}
634 \newcommand{\DUoptionlistlabel}{\optionlistlabel}
635 \newenvironment{DUoptionlist}
636 {\begin{optionlist}{3cm}}
641 Now less prominent (not bold, normal size) restore with::
643 \newcommand{\rubric}[1]{\subsection*{~\hfill {\it #1} \hfill ~}}
644 \newcommand{\DUrubric}[2][class-arg]{\rubric{#2}}
650 \newcommand{\titlereference}[1]{\textsl{#1}}
651 \newcommand{\DUroletitlereference}[1]{\titlereference{#1}}
658 Enable customization of some more Docutils elements with special commands
660 :admonition: ``DUadmonition`` command (replacing ``\admonitionwidth``),
661 :field list: ``DUfieldlist`` environment,
662 :legend: ``DUlegend`` environment,
663 :sidebar: ``\DUsidebar``, ``\DUtitle``, and
664 ``DUsubtitle`` commands,
665 :topic: ``\DUtopic`` and ``\DUtitle`` commands,
666 :transition: ``\DUtransition`` command.
667 :footnotes: ``\DUfootnotemark`` and ``\DUfootnotetext`` commands with
668 hyperlink support using the Docutils-provided footnote label.
670 Backwards compatibility:
671 In most cases, the default definition corresponds to the previously used
672 construct. The following definitions restore the old behaviour in case of
677 Use sans-serif fonts::
679 \newcommand{\DUadmonition}[2][class-arg]{%
681 \fbox{\parbox{0.9\textwidth}{\sffamily #2}}
689 \newcommand{\DUtopicdedication}[1]{#1}
691 But center the title::
693 \newcommand*{\DUtitlededication}[1]{\centerline{\textbf{#1}}}
697 Use sans-serif fonts, a frame, and a darker shade of grey::
699 \providecommand{\DUsidebar}[2][class-arg]{%
702 \fbox{\colorbox[gray]{0.80}{\parbox{0.9\textwidth}{#2}}}
708 Bold instead of emphasized::
710 \providecommand*{\DUsubtitlesidebar}[1]{\hspace*{\fill}\\
711 \textbf{#1}\smallskip}
715 No quote but normal text::
717 \newcommand{\DUtopic}[2][class-arg]{%
718 \ifcsname DUtopic#1\endcsname%
719 \csname DUtopic#1\endcsname{#2}%
727 Title for "topics" (admonitions, sidebar).
731 \providecommand*{\DUtitletopic}[1]{\textbf{\large #1}\smallskip}
735 Do not add vertical space after the transition. ::
737 \providecommand*{\DUtransition}[1][class-arg]{%
738 \hspace*{\fill}\hrulefill\hspace*{\fill}}