python/helpers/docutils/writers/latex2e/docutils-05-compat.sty

% ==================================================================
%     Changes to the Docutils latex2e writer since version 0.5
% ==================================================================
% 
% A backwards compatibility style sheet
% *************************************
% 
% :Author:    Guenter Milde
% :Contact:   milde@users.berlios.de
% :Revision:  $Revision: 6152 $
% :Date:      $Date: 2009-02-24$
% :Copyright: © 2009 G. Milde,
%             Released  without warranties or conditions of any kind
%             under the terms of the Apache License, Version 2.0
%             http://www.apache.org/licenses/LICENSE-2.0
% :Abstract:  This file documents changes and provides a style for best
%             possible compatibility to the behaviour of the `latex2e`
%             writer of Doctutils release 0.5.
% 
% ::

\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{docutils-05-compat}
[2009/03/26 v0.1 compatibility with rst2latex from Docutils 0.5]

% .. contents::
%    :depth: 3
% 
% Usage
% =====
% 
% * To get an (almost) identic look for your old documents,
%   place ``docutils-05-compat.sty`` in the TEXINPUT path (e.g.
%   the current work directory) and pass the
%   ``--stylesheet=docutils-05-compat`` option to ``rst2latex.py``.
% 
% * To use your custom stylesheets without change, add them to the
%   compatibility style, e.g.
%   ``--stylesheet="docutils-05-compat,mystyle.tex``.
% 
% .. tip:: As the changes include bug fixes that are partly reverted by this
%    style, it is recommended to adapt the stylesheets to the new version or
%    copy just the relevant parts of this style into them.
% 
% Changes since 0.5
% =================
% 
% Bugfixes
% --------
% 
% * Newlines around comments, targets and references prevent run-together
%   paragraphs.
% 
%   + An image directive with hyperlink reference or target did not start a
%     new paragraph (e.g. the first two image examples in
%     standalone_rst_latex.tex).
% 
%   + Paragraphs were not separated if there was a (hyper) target definition
%     inbetween.
% 
%   + Paragraphs did run together, if separated by a comment-paragraph in the
%     rst source.
% 
% * Fixed missing and spurious internal links/targets.
%   Internal links now take you to the correct place.
% 
% * Verbose and linked system messages.
% 
% * `Figure and image alignment`_ now conforms to the rst definition.
% 
% * Put `header and footer directive`__ content in \DUheader respective
%   \DUfooter macros (ignored by the default style/template).
% 
%   (They were put inside hard-coded markup at the top/bottom of the document
%   without an option to get them on every page.)
% 
% __ ../ref/rst/directives.html#document-header-footer
% 
% * Render doctest blocks as literal blocks (fixes bug [1586058] doctest block
%   nested in admonition). I.e.
% 
%   + indent doctest blocks by nesting in a quote environment. This is also
%     the rendering by the HTML writer (html4css2.css).
%   + apply the ``--literal-block-env`` setting also to doctest blocks.
% 
%   .. warning::
%       (``--literal-block-env=verbatim`` and
%       ``--literal-block-env=lstlistings`` fail with literal or doctest
%       blocks nested in an admonition.
% 
% * Two-way hyperlinked footnotes and support for symbol footnotes and
%   ``--footnote-references=brackets`` with ``--use-latex-footnotes``.
% 
% * The packages `fixltx2e` (providing LaTeX patches and the \textsubscript
%   command) and `cmap` (including character maps in the generated PDF for
%   better search and copy-and-paste operations) are now always loaded
%   (configurable with custom templates_).
% 
% Backwards compatibility:
%   "Bug for bug compatibility" is not provided.
% 
% 
% New configuration setting defaults
% ----------------------------------
% 
% - font-encoding: "T1" (formerly implicitely set by 'ae').
% - use-latex-toc: true (ToC with page numbers).
% - use-latex-footnotes: true (no mixup with figures).
% 
% Backwards compatibility:
%   Reset to the former defaults with:
% 
%   | font-encoding: ''
%   | use-latex-toc: False
%   | use-latex-footnotes: False
% 
%   (in the config file) or the command line options:
% 
%     ``--figure-footnotes --use-docutils-toc  --font-encoding=''``
% 
% 
% Cleaner LaTeX source
% --------------------
% 
% New features:
%   * Remove redundant "double protection" from the encoding of the "special
%     printing characters" and square brackets, e.g. ``\%`` instead of
%     ``{\%}``.
%   * Remove some spurious whitespace, e.g. ``\item [what:] -> \item[what:]``.
%   * Use conventional style for "named" macros, e.g. ``\dots{}`` instead of
%     ``{\dots}``
% 
% Backwards compatibility:
%   Changes do not affect the output.
% 
% 
% LaTeX style sheets
% ------------------
% 
% New Feature:
%   LaTeX packages can be used as ``--stylesheet`` argument without
%   restriction.
% 
% Implementation:
%   Use ``\usepackage`` if style sheet ends with ``.sty`` or has no
%   extension and ``\input`` else.
% 
% Rationale:
%   while ``\input`` works with extension as well as without extension,
%   ``\usepackage`` expects the package name without extension. (The latex2e
%   writer will strip a ``.sty`` extension.)
% 
% 
% Backwards compatibility:
%   Up to Docutils 0.5, if no filename extension is given in the
%   ``stylesheet`` argument, ``.tex`` is assumed (by latex).
% 
%   Since Docutils 0.6, a stylesheet without filename extension is assumed to
%   be a LaTeX package (``*.sty``) and referenced with the ``\usepackage``
%   command.
% 
% .. important::
%   Always specify the extension if you want the style sheet to be
%   ``\input`` by LaTeX.
% 
% 
% Templates
% ---------
% 
% New Feature:
%   Advanced configuration via custom templates.
% 
% Implementation:
%   A ``--template`` option and config setting allows specification of a
%   template file.
% 
% See the `LaTeX writer documentation`__ for details.
% 
% __ latex.html#templates
% 
% 
% Custom roles
% ------------
% 
% New Feature: failsave implementation
%   As with classes to HTML objects, class arguments are silently ignored if
%   there is no styling rule for this class in a custom style sheet.
% 
% New Feature: custom roles based on standard roles
%   As class support needs to be handled by the LaTeX writer, this feature was
%   not present "automatically" (as in HTML). Modified visit/depart_*()
%   methods for the standard roles now call visit/depart_inline() if there are
%   class arguments to the node.
% 
% Backwards compatibility:
%   The implementation is fully backwards compatible. (SVN versions 5742 to
%   5861 contained an implementation that did not work with commands expecting
%   an argument.)
% 
% Length units
% ------------
% 
% New Features:
%   1. Add default unit if none given.
%      A poll on docutils-users favoured ``bp`` (Big Point: 1 bp  = 1/72 in).
% 
%   2. Do not change ``px`` to ``pt``.
% 
%   3. Lengths specified in the document with unit "pt" will be written with
%      unit "bp" to the LaTeX source.
% 
% Rationale:
%   1. prevent LaTeX error "missing unit".
% 
%   2. ``px`` is a valid unit in pdftex since version 1.3.0 released on
%      2005-02-04:
% 
%        1px defaults to 1bp (or 72dpi), but can be changed with the
%        ``\pdfpxdimen`` primitive.::

        \pdfpxdimen=1in % 1 dpi
        \divide\pdfpxdimen by 96 % 96 dpi

%        --  http://www.tug.org/applications/pdftex/NEWS
% 
%      Modern TeX distributions use pdftex also for dvi generation (i.e.
%      ``latex`` actually calls ``pdftex`` with some options).
% 
%   3. In Docutils (as well as CSS) the unit symbol "pt" denotes the
%      `Postscript point` or `DTP point` while LaTeX uses "pt" for the `LaTeX
%      point`, which is unknown to Docutils and 0.3 % smaller.
% 
%      The `DTP point` is available in LaTeX as "bp" (big point):
% 
%        1 pt = 1/72.25 in < 1 bp  = 1/72 in
% 
% 
% Backwards compatibility:
%   Images with width specification in ``px`` come out slightly (0.3 %) larger:
% 
%     1 px = 1 bp  = 1/72 in > 1 pt = 1/72.25 in
% 
%   This can be reset with ::

  \pdfpxdimen=1pt

% .. caution:: It is impossible to revert the change of lengths specified with
%    "pt" or without unit in a style sheet, however the 0.3 % change will be
%    imperceptible in most cases.
% 
% .. admonition:: Error ``illegal unit px``
% 
%   The unit ``px`` is not defined in "pure" LaTeX, but introduced by the
%   `pdfTeX` converter on 2005-02-04. `pdfTeX` is used in all modern LaTeX
%   distributions (since ca. 2006) also for conversion into DVI.
% 
%   If you convert the LaTeX source with a legacy program, you might get the
%   error ``illegal unit px``.
% 
%   If updating LaTeX is not an option, just remove the ``px`` from the length
%   specification. HTML/CSS will default to ``px`` while the `latexe2` writer
%   will add the fallback unit ``bp``.
% 
% 
% Font encoding
% -------------
% 
% New feature:
%   Do not mix font-encoding and font settings: do not load the obsolete
%   `ae` and `aeguill` packages unless explicitely required via the
%   ``--stylesheet`` option.
% 
%   :font-encoding = "":  do not load `ae` and `aeguill`, i.e.
% 
%                         * do not change font settings,
%                         * do not use the fontenc package
%                           (implicitely loaded via `ae`),
%                         * use LaTeX default font encoding (OT1)
% 
%   :font-encoding = "OT1": load `fontenc` with ``\usepackage[OT1]{fontenc}``
% 
% Example:
%   ``--font-encoding=LGR,T1`` becomes ``\usepackage[LGR,T1]{fontenc}``
%   (Latin, Latin-1 Supplement, and Greek)
% 
% 
% Backwards compatibility:
%   Load the ae and aeguill packages if fontenc is not used.
% 
% .. tip:: Using `ae` is not recommended. A similar look (but better
%    implementation) can be achieved with the packages `lmodern`, `cmsuper`,
%    or `cmlgr` all providing Computer Modern look-alikes in vector format and
%    T1 encoding, e.g. ``--font-encoding=T1 --stylesheet=lmodern``.
% 
% Sub- and superscript as text
% ----------------------------
% 
% New feature:
%   Set sub- and superscript role argument in text mode not as math.
% 
%   Pass the role content to ``\textsubscript`` or ``\textsuperscript``.
% 
% Backwards compatibility:
%   The old implementation set the role content in Math mode, where
% 
%   * whitespace is ignored,
%   * a different command set and font setting scheme is active,
%   * Latin letters are typeset italic but numbers upright.
% 
%   Although it is possible to redefine ``\textsubscript`` and
%   ``\textsuperscript`` to typeset the content in math-mode, this can lead to
%   errors with certain input and is therefore not done in this style sheet.
% 
% .. tip:: To get italic subscripts, define and use in your document
%    `custom roles`_ like ``.. role:: sub(subscript)`` and
%    ``.. role:: super(superscript)`` and define the "role commands"::

   \newcommand{\DUrolesub}{\itshape}
   \newcommand{\DUrolesuper}{\itshape}

%    Alternatively, if you want all sub- and superscripts in italic, redefine
%    the macros::

   %% \let\DUsup\textsubscript
   %% \let\DUsuper\textsuperscript
   %% \renewcommand*{\textsubscript}{\DUsub\itshape}
   %% \renewcommand*{\textsuperscript}{\DUsuper\itshape}

%    This is not fully backwards compatible, as it will also set numbers in
%    italic shape and not ignore whitespace.
% 
% Page layout
% -----------
% 
% New features:
%   * Margins are configurable via the ``DIV=...`` document option.
% 
%   * The ``\raggedbottom`` setting is no longer inserted into the document. It
%     is the default for article and report classes. If requested in combination
%     with a book class, it can be given in a custom style sheet.
% 
% Backwards compatibility:
%   Up to version 0.5, use of `typearea` and a DIV setting of 12 were
%   hard-coded into the latex2e writer ::

  \usepackage{typearea}
  \typearea{12}

%   and the vertical alignment of lower boundary of the text area in book
%   classes disabled via ::

  \raggedbottom


% ToC and section numbers
% -----------------------
% 
% Better conformance to Docutils specifications.
% 
% New feature:
%   * The "depth" argument of the "contents" and "sectnum" directives is
%     respected.
% 
%   * section numbering independent of 'use-latex-toc':
% 
%     + sections are only numbered if there is a "sectnum" directive in the
%       document
% 
%     + section numbering by LaTeX if the "sectnum_xforms" config setting is
%       False.
% 
% Backwards compatibility:
% 
%   The previous behaviour was to always number sections if 'use-latex-toc' is
%   true, using the document class defaults. It cannot be restored
%   universally, the following code sets the default values of the "article"
%   document class::

  \setcounter{secnumdepth}{3}
  \setcounter{tocdepth}{3}

% .. TODO or not to do? (Back-compatibility problems)
%   * The default "depth" of the LaTeX-created ToC and the LaTeX section
%     numbering is increased to the number of supported section levels.
% 
% New feature:
%   If 'use-latex-toc' is set, local tables of content are typeset using the
%   'minitoc' package (instead of being ignored).
% 
% Backwards compatibility:
%   Disable the creation of local ToCs (ignoring all special commands) by
%   replacing ``\usepackage{minitoc} with ``\usepackage{mtcoff}``.
% 
% 
% Default font in admonitions and sidebar
% ---------------------------------------
% 
% New feature:
%   Use default font in admonitions and sidebar.
% 
% Backward compatibility:
%   See the fallback definitions for admonitions_, `topic title`_ and
%   `sidebar`_.
% 
% 
% Figure placement
% ----------------
% 
% New feature:
%   Use ``\floatplacement`` from the `float` package instead of
%   "hard-coded" optional argument for the global setting.
% 
%   Default to ``\floatplacement{figure}{H}`` (here definitely). This
%   corresponds most closely to the source and HTML placement (principle of
%   least surprise).
% 
% Backwards compatibility:
%   Set the global default back to the previous used value::

  \usepackage{float}
  \floatplacement{figure}{htbp} % here, top, bottom, extra-page


% Figure and image alignment
% --------------------------
% 
% New features:
% 
% a) Fix behaviour of 'align' argument to a figure (do not align figure
%    contents).
% 
%    As the 'figwidth' argument is still ignored and the "natural width" of a
%    figure in LaTeX is 100% \textwidth, setting the 'align' argument of a
%    figure has currently no effect on the LaTeX output.
% 
% b) Set default align of image in a figure to 'center'.
% 
% c) Also center images that are wider than textwidth.
% 
% d) Align images with class "align-[right|center|left]" (allows setting the
%    alignment of an image in a figure).
% 
% Backwards compatibility:
%    There is no "automatic" way to reverse these changes via a style sheet.
% 
% a) The alignment of the image can be set with the "align-left",
%    "align-center" and "align-right" class arguments.
% 
%    As previously, the caption of a figure is aligned according to the
%    document class -- configurable with a style sheet using the "caption"
%    package.
% 
% b) See a)
% 
% c) Set the alignment of "oversized" images to "left" to get back the
%    old placement.
% 
% Shorter preamble
% ----------------
% 
% New feature:
%   The document preamble is pruned to contain only relevant commands and
%   settings.
% 
% Packages that are no longer required
% ````````````````````````````````````
% 
% The following packages where required in pre-0.5 versions and still loaded
% with version 0.5::

\usepackage{shortvrb}
\usepackage{amsmath}


% Packages that are conditionally loaded
% ``````````````````````````````````````
% 
% Additional to the `typearea` for `page layout`_, the following packages are
% only loaded if actually required by doctree elements:
% 
% Tables
% ^^^^^^
% 
% Standard package for tables across several pages::

\usepackage{longtable}

% Extra space between text in tables and the line above them
% ('array' is implicitely loaded by 'tabularx', see below)::

\usepackage{array}
\setlength{\extrarowheight}{2pt}

% Table cells spanning multiple rows::

\usepackage{multirow}

% Docinfo
% ^^^^^^^
% 
% One-page tables with auto-width columns::

\usepackage{tabularx}

% Images
% ^^^^^^
% Include graphic files::

\usepackage{graphicx}

% Problematic, Sidebar
% ^^^^^^^^^^^^^^^^^^^^
% Set text and/or background colour, coloured boxes with ``\colorbox``::

\usepackage{color}

% Floats for footnotes settings
% `````````````````````````````
% 
% Settings for the use of floats for footnotes are only included if
% 
% * the option "use-latex-footnotes" is False, and
% * there is at least one footnote in the document.
% 
% ::

% begin: floats for footnotes tweaking.
\setlength{\floatsep}{0.5em}
\setlength{\textfloatsep}{\fill}
\addtolength{\textfloatsep}{3em}
\renewcommand{\textfraction}{0.5}
\renewcommand{\topfraction}{0.5}
\renewcommand{\bottomfraction}{0.5}
\setcounter{totalnumber}{50}
\setcounter{topnumber}{50}
\setcounter{bottomnumber}{50}
% end floats for footnotes


% Special lengths, commands, and environments
% -------------------------------------------
% 
% Removed definitions
% ```````````````````
% 
% admonition width
% ^^^^^^^^^^^^^^^^
% The ``admonitionwith`` lenght is replaced by the more powerful
% ``\DUadmonition`` command (see admonitions_).
% 
% Backwards compatibility:
%   The default value (90 % of the textwidth) is unchanged.
% 
%   To configure the admonition width, you must redefine the ``DUadmonition``
%   command instead of changing the ``admonitionwith`` length value.
% 
% 
% Renamed definitions (now conditional)
% `````````````````````````````````````
% 
% The names for special doctree elements are now prefixed with ``DU``.
% 
% Up to version 0.5, all definitions were included in the preamble (before the
% style sheet) of every document -- even if not used in the body. Since
% version 0.6, fallback definitions are included after the style sheet and
% only if required.
% 
% Customization is done by an alternative definition in a style sheet with
% ``\newcommand`` instead of the former ``\renewcommand``.
% 
% The following code provides the old definitions and maps them (or their
% custom variants) to the new interface.
% 
% docinfo width
% ^^^^^^^^^^^^^
% ::

\newlength{\docinfowidth}
\setlength{\docinfowidth}{0.9\textwidth}

\newlength{\DUdocinfowidth}
\AtBeginDocument{\setlength{\DUdocinfowidth}{\docinfowidth}}

% line block
% ^^^^^^^^^^
% ::

\newlength{\lineblockindentation}
\setlength{\lineblockindentation}{2.5em}
\newenvironment{lineblock}[1]
{\begin{list}{}
  {\setlength{\partopsep}{\parskip}
   \addtolength{\partopsep}{\baselineskip}
   \topsep0pt\itemsep0.15\baselineskip\parsep0pt
   \leftmargin#1}
 \raggedright}
{\end{list}}

\newlength{\DUlineblockindent}
\AtBeginDocument{\setlength{\DUlineblockindent}{\lineblockindentation}}
\newenvironment{DUlineblock}[1]
  {\begin{lineblock}{#1}}
  {\end{lineblock}}

% local line width
% ^^^^^^^^^^^^^^^^
% 
% The ``\locallinewidth`` length for internal use in tables is replaced
% by ``\DUtablewidth``. It was never intended for customization::

\newlength{\locallinewidth}

% option lists
% ^^^^^^^^^^^^
% ::

\newcommand{\optionlistlabel}[1]{\bf #1 \hfill}
\newenvironment{optionlist}[1]
{\begin{list}{}
  {\setlength{\labelwidth}{#1}
   \setlength{\rightmargin}{1cm}
   \setlength{\leftmargin}{\rightmargin}
   \addtolength{\leftmargin}{\labelwidth}
   \addtolength{\leftmargin}{\labelsep}
   \renewcommand{\makelabel}{\optionlistlabel}}
}{\end{list}}

\newcommand{\DUoptionlistlabel}{\optionlistlabel}
\newenvironment{DUoptionlist}
  {\begin{optionlist}{3cm}}
  {\end{optionlist}}

% rubric
% ^^^^^^
% Now less prominent (not bold, normal size) restore with::

\newcommand{\rubric}[1]{\subsection*{~\hfill {\it #1} \hfill ~}}
\newcommand{\DUrubric}[2][class-arg]{\rubric{#2}}

% title reference role
% ^^^^^^^^^^^^^^^^^^^^
% ::

\newcommand{\titlereference}[1]{\textsl{#1}}
\newcommand{\DUroletitlereference}[1]{\titlereference{#1}}


% New definitions
% ```````````````
% 
% New Feature:
%   Enable customization of some more Docutils elements with special commands
% 
%   :admonition: ``DUadmonition`` command (replacing ``\admonitionwidth``),
%   :field list: ``DUfieldlist``  environment,
%   :legend:     ``DUlegend``     environment,
%   :sidebar:    ``\DUsidebar``, ``\DUtitle``, and
%                ``DUsubtitle`` commands,
%   :topic:      ``\DUtopic`` and ``\DUtitle`` commands,
%   :transition: ``\DUtransition`` command.
%   :footnotes:  ``\DUfootnotemark`` and ``\DUfootnotetext`` commands with
%                hyperlink support using the Docutils-provided footnote label.
% 
% Backwards compatibility:
%   In most cases, the default definition corresponds to the previously used
%   construct. The following definitions restore the old behaviour in case of
%   changes.
% 
% admonitions
% ^^^^^^^^^^^
% Use sans-serif fonts::

\newcommand{\DUadmonition}[2][class-arg]{%
  \begin{center}
    \fbox{\parbox{0.9\textwidth}{\sffamily #2}}
  \end{center}
}

% dedication
% ^^^^^^^^^^
% Do not center::

\newcommand{\DUtopicdedication}[1]{#1}

% But center the title::

\newcommand*{\DUtitlededication}[1]{\centerline{\textbf{#1}}}

% sidebar
% ^^^^^^^
% Use sans-serif fonts, a frame, and a darker shade of grey::

\providecommand{\DUsidebar}[2][class-arg]{%
  \begin{center}
    \sffamily
    \fbox{\colorbox[gray]{0.80}{\parbox{0.9\textwidth}{#2}}}
  \end{center}
}

% sidebar sub-title
% ^^^^^^^^^^^^^^^^^
% Bold instead of emphasized::

\providecommand*{\DUsubtitlesidebar}[1]{\hspace*{\fill}\\
  \textbf{#1}\smallskip}

% topic
% ^^^^^
% No quote but normal text::

\newcommand{\DUtopic}[2][class-arg]{%
  \ifcsname DUtopic#1\endcsname%
    \csname DUtopic#1\endcsname{#2}%
  \else
    #2
  \fi
}

% topic title
% ^^^^^^^^^^^
% Title for "topics" (admonitions, sidebar).
% 
% Larger font size::

\providecommand*{\DUtitletopic}[1]{\textbf{\large #1}\smallskip}

% transition
% ^^^^^^^^^^
% Do not add vertical space after the transition. ::

\providecommand*{\DUtransition}[1][class-arg]{%
  \hspace*{\fill}\hrulefill\hspace*{\fill}}