|
|
================================================================== |
|
|
Changes to the Docutils latex2e writer since version 0.5 |
|
|
================================================================== |
|
|
|
|
|
A backwards compatibility style sheet |
|
|
************************************* |
|
|
|
|
|
:Author: Guenter Milde |
|
|
:Contact: docutils-develop@lists.sourceforge.net |
|
|
:Revision: $Revision: 7302 $ |
|
|
:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $ |
|
|
:Copyright: © 2009 Günter Milde, |
|
|
:License: Released under the terms of the `2-Clause BSD license`_, in short: |
|
|
|
|
|
Copying and distribution of this file, with or without modification, |
|
|
are permitted in any medium without royalty provided the copyright |
|
|
notice and this notice are preserved. |
|
|
This file is offered as-is, without any warranty. |
|
|
|
|
|
: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. |
|
|
|
|
|
.. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause |
|
|
|
|
|
:: |
|
|
|
|
|
\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}}
|
|
|
|
