Spelling fixes
[docutils.git] / docs / user / docutils-05-compat.sty.txt
blob70078521e0632815847a8393a2dd627d411e3843
1 ==================================================================
2     Changes to the Docutils latex2e writer since version 0.5
3 ==================================================================
5 A backwards compatibility style sheet
6 *************************************
8 :Author:    Guenter Milde
9 :Contact:   docutils-develop@lists.sourceforge.net
10 :Revision:  $Revision$
11 :Date:      $Date$
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]
32 .. contents::
33    :depth: 3
35 Usage
36 =====
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.
51 Changes since 0.5
52 =================
54 Bugfixes
55 --------
57 * Newlines around comments, targets and references prevent run-together
58   paragraphs.
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
65     inbetween.
67   + Paragraphs did run together, if separated by a comment-paragraph in the
68     rst source.
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.
92   .. warning::
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 implicitly 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:
119   | font-encoding: ''
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=''``
128 Cleaner LaTeX source
129 --------------------
131 New features:
132   * Remove redundant "double protection" from the encoding of the "special
133     printing characters" and square brackets, e.g. ``\%`` instead of
134     ``{\%}``.
135   * Remove some spurious whitespace, e.g. ``\item [what:] -> \item[what:]``.
136   * Use conventional style for "named" macros, e.g. ``\dots{}`` instead of
137     ``{\dots}``
139 Backwards compatibility:
140   Changes do not affect the output.
143 LaTeX style sheets
144 ------------------
146 New Feature:
147   LaTeX packages can be used as ``--stylesheet`` argument without
148   restriction.
150 Implementation:
151   Use ``\usepackage`` if style sheet ends with ``.sty`` or has no
152   extension and ``\input`` else.
154 Rationale:
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``
166   command.
168 .. important::
169   Always specify the extension if you want the style sheet to be
170   ``\input`` by LaTeX.
173 Templates
174 ---------
176 New Feature:
177   Advanced configuration via custom templates.
179 Implementation:
180   A ``--template`` option and config setting allows specification of a
181   template file.
183 See the `LaTeX writer documentation`__ for details.
185 __ latex.html#templates
188 Custom roles
189 ------------
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
204   an argument.)
206 Length units
207 ------------
209 New Features:
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.
218 Rationale:
219   1. prevent LaTeX error "missing unit".
221   2. ``px`` is a valid unit in pdftex since version 1.3.0 released on
222      2005-02-04:
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 ::
251     \pdfpxdimen=1pt
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``.
271 Font encoding
272 -------------
274 New feature:
275   Do not mix font-encoding and font settings: do not load the obsolete
276   `ae` and `aeguill` packages unless explicitly 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                           (implicitly loaded via `ae`),
284                         * use LaTeX default font encoding (OT1)
286   :font-encoding = "OT1": load `fontenc` with ``\usepackage[OT1]{fontenc}``
288 Example:
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 ----------------------------
304 New feature:
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
328    the macros::
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.
338 Page layout
339 -----------
341 New features:
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}
353     \typearea{12}
355   and the vertical alignment of lower boundary of the text area in book
356   classes disabled via ::
358     \raggedbottom
361 ToC and section numbers
362 -----------------------
364 Better conformance to Docutils specifications.
366 New feature:
367   * The "depth" argument of the "contents" and "sectnum" directives is
368     respected.
370   * section numbering independent of 'use-latex-toc':
372     + sections are only numbered if there is a "sectnum" directive in the
373       document
375     + section numbering by LaTeX if the "sectnum_xforms" config setting is
376       False.
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"
383   document class::
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.
392 New feature:
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 ---------------------------------------
404 New feature:
405   Use default font in admonitions and sidebar.
407 Backward compatibility:
408   See the fallback definitions for admonitions_, `topic title`_ and
409   `sidebar`_.
412 Figure placement
413 ----------------
415 New feature:
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
421   least surprise).
423 Backwards compatibility:
424   Set the global default back to the previous used value::
426     \usepackage{float}
427     \floatplacement{figure}{htbp} % here, top, bottom, extra-page
430 Figure and image alignment
431 --------------------------
433 New features:
435 a) Fix behaviour of 'align' argument to a figure (do not align figure
436    contents).
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"
457    package.
459 b) See a)
461 c) Set the alignment of "oversized" images to "left" to get back the
462    old placement.
464 Shorter preamble
465 ----------------
467 New feature:
468   The document preamble is pruned to contain only relevant commands and
469   settings.
471 Packages that are no longer required
472 ````````````````````````````````````
474 The following packages where required in pre-0.5 versions and still loaded
475 with version 0.5::
477   \usepackage{shortvrb}
478   \usepackage{amsmath}
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:
487 Tables
488 ^^^^^^
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 implicitly loaded by 'tabularx', see below)::
497   \usepackage{array}
498   \setlength{\extrarowheight}{2pt}
500 Table cells spanning multiple rows::
502   \usepackage{multirow}
504 Docinfo
505 ^^^^^^^
507 One-page tables with auto-width columns::
509   \usepackage{tabularx}
511 Images
512 ^^^^^^
513 Include graphic files::
515   \usepackage{graphicx}
517 Problematic, Sidebar
518 ^^^^^^^^^^^^^^^^^^^^
519 Set text and/or background colour, coloured boxes with ``\colorbox``::
521   \usepackage{color}
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 -------------------------------------------
549 Removed definitions
550 ```````````````````
552 admonition width
553 ^^^^^^^^^^^^^^^^
554 The ``admonitionwith`` length 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
572 only if required.
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.
580 docinfo width
581 ^^^^^^^^^^^^^
584   \newlength{\docinfowidth}
585   \setlength{\docinfowidth}{0.9\textwidth}
587   \newlength{\DUdocinfowidth}
588   \AtBeginDocument{\setlength{\DUdocinfowidth}{\docinfowidth}}
590 line block
591 ^^^^^^^^^^
594   \newlength{\lineblockindentation}
595   \setlength{\lineblockindentation}{2.5em}
596   \newenvironment{lineblock}[1]
597   {\begin{list}{}
598     {\setlength{\partopsep}{\parskip}
599      \addtolength{\partopsep}{\baselineskip}
600      \topsep0pt\itemsep0.15\baselineskip\parsep0pt
601      \leftmargin#1}
602    \raggedright}
603   {\end{list}}
605   \newlength{\DUlineblockindent}
606   \AtBeginDocument{\setlength{\DUlineblockindent}{\lineblockindentation}}
607   \newenvironment{DUlineblock}[1]
608     {\begin{lineblock}{#1}}
609     {\end{lineblock}}
611 local line width
612 ^^^^^^^^^^^^^^^^
614 The ``\locallinewidth`` length for internal use in tables is replaced
615 by ``\DUtablewidth``. It was never intended for customization::
617   \newlength{\locallinewidth}
619 option lists
620 ^^^^^^^^^^^^
623   \newcommand{\optionlistlabel}[1]{\bf #1 \hfill}
624   \newenvironment{optionlist}[1]
625   {\begin{list}{}
626     {\setlength{\labelwidth}{#1}
627      \setlength{\rightmargin}{1cm}
628      \setlength{\leftmargin}{\rightmargin}
629      \addtolength{\leftmargin}{\labelwidth}
630      \addtolength{\leftmargin}{\labelsep}
631      \renewcommand{\makelabel}{\optionlistlabel}}
632   }{\end{list}}
634   \newcommand{\DUoptionlistlabel}{\optionlistlabel}
635   \newenvironment{DUoptionlist}
636     {\begin{optionlist}{3cm}}
637     {\end{optionlist}}
639 rubric
640 ^^^^^^
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}}
646 title reference role
647 ^^^^^^^^^^^^^^^^^^^^
650   \newcommand{\titlereference}[1]{\textsl{#1}}
651   \newcommand{\DUroletitlereference}[1]{\titlereference{#1}}
654 New definitions
655 ```````````````
657 New Feature:
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
673   changes.
675 admonitions
676 ^^^^^^^^^^^
677 Use sans-serif fonts::
679   \newcommand{\DUadmonition}[2][class-arg]{%
680     \begin{center}
681       \fbox{\parbox{0.9\textwidth}{\sffamily #2}}
682     \end{center}
683   }
685 dedication
686 ^^^^^^^^^^
687 Do not center::
689   \newcommand{\DUtopicdedication}[1]{#1}
691 But center the title::
693   \newcommand*{\DUtitlededication}[1]{\centerline{\textbf{#1}}}
695 sidebar
696 ^^^^^^^
697 Use sans-serif fonts, a frame, and a darker shade of grey::
699   \providecommand{\DUsidebar}[2][class-arg]{%
700     \begin{center}
701       \sffamily
702       \fbox{\colorbox[gray]{0.80}{\parbox{0.9\textwidth}{#2}}}
703     \end{center}
704   }
706 sidebar sub-title
707 ^^^^^^^^^^^^^^^^^
708 Bold instead of emphasized::
710   \providecommand*{\DUsubtitlesidebar}[1]{\hspace*{\fill}\\
711     \textbf{#1}\smallskip}
713 topic
714 ^^^^^
715 No quote but normal text::
717   \newcommand{\DUtopic}[2][class-arg]{%
718     \ifcsname DUtopic#1\endcsname%
719       \csname DUtopic#1\endcsname{#2}%
720     \else
721       #2
722     \fi
723   }
725 topic title
726 ^^^^^^^^^^^
727 Title for "topics" (admonitions, sidebar).
729 Larger font size::
731   \providecommand*{\DUtitletopic}[1]{\textbf{\large #1}\smallskip}
733 transition
734 ^^^^^^^^^^
735 Do not add vertical space after the transition. ::
737   \providecommand*{\DUtransition}[1][class-arg]{%
738     \hspace*{\fill}\hrulefill\hspace*{\fill}}