Spelling fixes
[docutils.git] / docutils / writers / latex2e / docutils-05-compat.sty
blob31f7b4e1ba491f1571b49b1de16266be2967ea3b
1 % ==================================================================
2 % Changes to the Docutils latex2e writer since version 0.5
3 % ==================================================================
4 %
5 % A backwards compatibility style sheet
6 % *************************************
7 %
8 % :Author: Guenter Milde
9 % :Contact: milde@users.sourceforge.net
10 % :Revision: $Revision: 6156 $
11 % :Date: $Date: 2009-02-24 $
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
26 % ::
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.
531 % ::
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 % ^^^^^^^^^^^^^
582 % ::
584 \newlength{\docinfowidth}
585 \setlength{\docinfowidth}{0.9\textwidth}
587 \newlength{\DUdocinfowidth}
588 \AtBeginDocument{\setlength{\DUdocinfowidth}{\docinfowidth}}
590 % line block
591 % ^^^^^^^^^^
592 % ::
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 % ^^^^^^^^^^^^
621 % ::
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 % ^^^^^^^^^^^^^^^^^^^^
648 % ::
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}
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}
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
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}}