| Server IP : 127.0.0.2 / Your IP : 13.59.113.183 Web Server : Apache/2.4.18 (Ubuntu) System : User : www-data ( ) PHP Version : 7.0.33-0ubuntu0.16.04.16 Disable Function : disk_free_space,disk_total_space,diskfreespace,dl,exec,fpaththru,getmyuid,getmypid,highlight_file,ignore_user_abord,leak,listen,link,opcache_get_configuration,opcache_get_status,passthru,pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,php_uname,phpinfo,posix_ctermid,posix_getcwd,posix_getegid,posix_geteuid,posix_getgid,posix_getgrgid,posix_getgrnam,posix_getgroups,posix_getlogin,posix_getpgid,posix_getpgrp,posix_getpid,posix,_getppid,posix_getpwnam,posix_getpwuid,posix_getrlimit,posix_getsid,posix_getuid,posix_isatty,posix_kill,posix_mkfifo,posix_setegid,posix_seteuid,posix_setgid,posix_setpgid,posix_setsid,posix_setuid,posix_times,posix_ttyname,posix_uname,pclose,popen,proc_open,proc_close,proc_get_status,proc_nice,proc_terminate,shell_exec,source,show_source,system,virtual MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /usr/share/doc/docutils-doc/docs/user/ |
Upload File : |
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
<title>Changes to the Docutils latex2e writer since version 0.5</title>
<meta name="author" content="Guenter Milde" />
<meta name="date" content="2012-01-03" />
<meta name="copyright" content="© 2009 Günter Milde," />
<link rel="stylesheet" href="../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="document" id="changes-to-the-docutils-latex2e-writer-since-version-0-5">
<h1 class="title">Changes to the Docutils latex2e writer since version 0.5</h1>
<h2 class="subtitle" id="a-backwards-compatibility-style-sheet">A backwards compatibility style sheet</h2>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Guenter Milde</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>7302</td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2012-01-03</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>© 2009 Günter Milde,</td></tr>
<tr class="field"><th class="docinfo-name">License:</th><td class="field-body"><p class="first">Released under the terms of the <a class="reference external" href="http://www.spdx.org/licenses/BSD-2-Clause">2-Clause BSD license</a>, in short:</p>
<p class="last">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.</p>
</td>
</tr>
</tbody>
</table>
<div class="abstract topic">
<p class="topic-title first">Abstract</p>
<p>This file documents changes and provides a style for best
possible compatibility to the behaviour of the <span class="incremental">latex2e</span>
writer of Doctutils release 0.5.</p>
</div>
<pre class="literal-block">
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{docutils-05-compat}
[2009/03/26 v0.1 compatibility with rst2latex from Docutils 0.5]
</pre>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#usage" id="id3">Usage</a></li>
<li><a class="reference internal" href="#changes-since-0-5" id="id4">Changes since 0.5</a><ul>
<li><a class="reference internal" href="#bugfixes" id="id5">Bugfixes</a></li>
<li><a class="reference internal" href="#new-configuration-setting-defaults" id="id6">New configuration setting defaults</a></li>
<li><a class="reference internal" href="#cleaner-latex-source" id="id7">Cleaner LaTeX source</a></li>
<li><a class="reference internal" href="#latex-style-sheets" id="id8">LaTeX style sheets</a></li>
<li><a class="reference internal" href="#templates" id="id9">Templates</a></li>
<li><a class="reference internal" href="#custom-roles" id="id10">Custom roles</a></li>
<li><a class="reference internal" href="#length-units" id="id11">Length units</a></li>
<li><a class="reference internal" href="#font-encoding" id="id12">Font encoding</a></li>
<li><a class="reference internal" href="#sub-and-superscript-as-text" id="id13">Sub- and superscript as text</a></li>
<li><a class="reference internal" href="#page-layout" id="id14">Page layout</a></li>
<li><a class="reference internal" href="#toc-and-section-numbers" id="id15">ToC and section numbers</a></li>
<li><a class="reference internal" href="#default-font-in-admonitions-and-sidebar" id="id16">Default font in admonitions and sidebar</a></li>
<li><a class="reference internal" href="#figure-placement" id="id17">Figure placement</a></li>
<li><a class="reference internal" href="#figure-and-image-alignment" id="id18">Figure and image alignment</a></li>
<li><a class="reference internal" href="#shorter-preamble" id="id19">Shorter preamble</a><ul>
<li><a class="reference internal" href="#packages-that-are-no-longer-required" id="id20">Packages that are no longer required</a></li>
<li><a class="reference internal" href="#packages-that-are-conditionally-loaded" id="id21">Packages that are conditionally loaded</a></li>
<li><a class="reference internal" href="#floats-for-footnotes-settings" id="id22">Floats for footnotes settings</a></li>
</ul>
</li>
<li><a class="reference internal" href="#special-lengths-commands-and-environments" id="id23">Special lengths, commands, and environments</a><ul>
<li><a class="reference internal" href="#removed-definitions" id="id24">Removed definitions</a></li>
<li><a class="reference internal" href="#renamed-definitions-now-conditional" id="id25">Renamed definitions (now conditional)</a></li>
<li><a class="reference internal" href="#new-definitions" id="id26">New definitions</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="usage">
<h1><a class="toc-backref" href="#id3">Usage</a></h1>
<ul class="simple">
<li>To get an (almost) identic look for your old documents,
place <tt class="docutils literal"><span class="pre">docutils-05-compat.sty</span></tt> in the TEXINPUT path (e.g.
the current work directory) and pass the
<tt class="docutils literal"><span class="pre">--stylesheet=docutils-05-compat</span></tt> option to <tt class="docutils literal">rst2latex.py</tt>.</li>
<li>To use your custom stylesheets without change, add them to the
compatibility style, e.g.
<tt class="docutils literal"><span class="pre">--stylesheet="docutils-05-compat,mystyle.tex</span></tt>.</li>
</ul>
<div class="tip">
<p class="first admonition-title">Tip</p>
<p class="last">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.</p>
</div>
</div>
<div class="section" id="changes-since-0-5">
<h1><a class="toc-backref" href="#id4">Changes since 0.5</a></h1>
<div class="section" id="bugfixes">
<h2><a class="toc-backref" href="#id5">Bugfixes</a></h2>
<ul>
<li><p class="first">Newlines around comments, targets and references prevent run-together
paragraphs.</p>
<ul class="simple">
<li>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).</li>
<li>Paragraphs were not separated if there was a (hyper) target definition
inbetween.</li>
<li>Paragraphs did run together, if separated by a comment-paragraph in the
rst source.</li>
</ul>
</li>
<li><p class="first">Fixed missing and spurious internal links/targets.
Internal links now take you to the correct place.</p>
</li>
<li><p class="first">Verbose and linked system messages.</p>
</li>
<li><p class="first"><a class="reference internal" href="#figure-and-image-alignment">Figure and image alignment</a> now conforms to the rst definition.</p>
</li>
<li><p class="first">Put <a class="reference external" href="../ref/rst/directives.html#document-header-footer">header and footer directive</a> content in DUheader respective
DUfooter macros (ignored by the default style/template).</p>
<p>(They were put inside hard-coded markup at the top/bottom of the document
without an option to get them on every page.)</p>
</li>
</ul>
<ul>
<li><p class="first">Render doctest blocks as literal blocks (fixes bug [1586058] doctest block
nested in admonition). I.e.</p>
<ul class="simple">
<li>indent doctest blocks by nesting in a quote environment. This is also
the rendering by the HTML writer (html4css2.css).</li>
<li>apply the <tt class="docutils literal"><span class="pre">--literal-block-env</span></tt> setting also to doctest blocks.</li>
</ul>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">(<tt class="docutils literal"><span class="pre">--literal-block-env=verbatim</span></tt> and
<tt class="docutils literal"><span class="pre">--literal-block-env=lstlistings</span></tt> fail with literal or doctest
blocks nested in an admonition.</p>
</div>
</li>
<li><p class="first">Two-way hyperlinked footnotes and support for symbol footnotes and
<tt class="docutils literal"><span class="pre">--footnote-references=brackets</span></tt> with <tt class="docutils literal"><span class="pre">--use-latex-footnotes</span></tt>.</p>
</li>
<li><p class="first">The packages <span class="incremental">fixltx2e</span> (providing LaTeX patches and the textsubscript
command) and <span class="incremental">cmap</span> (including character maps in the generated PDF for
better search and copy-and-paste operations) are now always loaded
(configurable with custom <a class="reference internal" href="#templates">templates</a>).</p>
</li>
</ul>
<dl class="docutils">
<dt>Backwards compatibility:</dt>
<dd>"Bug for bug compatibility" is not provided.</dd>
</dl>
</div>
<div class="section" id="new-configuration-setting-defaults">
<h2><a class="toc-backref" href="#id6">New configuration setting defaults</a></h2>
<ul class="simple">
<li>font-encoding: "T1" (formerly implicitely set by 'ae').</li>
<li>use-latex-toc: true (ToC with page numbers).</li>
<li>use-latex-footnotes: true (no mixup with figures).</li>
</ul>
<dl class="docutils">
<dt>Backwards compatibility:</dt>
<dd><p class="first">Reset to the former defaults with:</p>
<div class="line-block">
<div class="line">font-encoding: ''</div>
<div class="line">use-latex-toc: False</div>
<div class="line">use-latex-footnotes: False</div>
</div>
<p>(in the config file) or the command line options:</p>
<blockquote class="last">
<tt class="docutils literal"><span class="pre">--figure-footnotes</span> <span class="pre">--use-docutils-toc</span> <span class="pre">--font-encoding=''</span></tt></blockquote>
</dd>
</dl>
</div>
<div class="section" id="cleaner-latex-source">
<h2><a class="toc-backref" href="#id7">Cleaner LaTeX source</a></h2>
<dl class="docutils">
<dt>New features:</dt>
<dd><ul class="first last simple">
<li>Remove redundant "double protection" from the encoding of the "special
printing characters" and square brackets, e.g. <tt class="docutils literal">\%</tt> instead of
<tt class="docutils literal"><span class="pre">{\%}</span></tt>.</li>
<li>Remove some spurious whitespace, e.g. <tt class="docutils literal">\item [what:] <span class="pre">-></span> \item[what:]</tt>.</li>
<li>Use conventional style for "named" macros, e.g. <tt class="docutils literal">\dots{}</tt> instead of
<tt class="docutils literal">{\dots}</tt></li>
</ul>
</dd>
<dt>Backwards compatibility:</dt>
<dd>Changes do not affect the output.</dd>
</dl>
</div>
<div class="section" id="latex-style-sheets">
<h2><a class="toc-backref" href="#id8">LaTeX style sheets</a></h2>
<dl class="docutils">
<dt>New Feature:</dt>
<dd>LaTeX packages can be used as <tt class="docutils literal"><span class="pre">--stylesheet</span></tt> argument without
restriction.</dd>
<dt>Implementation:</dt>
<dd>Use <tt class="docutils literal">\usepackage</tt> if style sheet ends with <tt class="docutils literal">.sty</tt> or has no
extension and <tt class="docutils literal">\input</tt> else.</dd>
<dt>Rationale:</dt>
<dd>while <tt class="docutils literal">\input</tt> works with extension as well as without extension,
<tt class="docutils literal">\usepackage</tt> expects the package name without extension. (The latex2e
writer will strip a <tt class="docutils literal">.sty</tt> extension.)</dd>
<dt>Backwards compatibility:</dt>
<dd><p class="first">Up to Docutils 0.5, if no filename extension is given in the
<tt class="docutils literal">stylesheet</tt> argument, <tt class="docutils literal">.tex</tt> is assumed (by latex).</p>
<p class="last">Since Docutils 0.6, a stylesheet without filename extension is assumed to
be a LaTeX package (<tt class="docutils literal">*.sty</tt>) and referenced with the <tt class="docutils literal">\usepackage</tt>
command.</p>
</dd>
</dl>
<div class="important">
<p class="first admonition-title">Important</p>
<p class="last">Always specify the extension if you want the style sheet to be
<tt class="docutils literal">\input</tt> by LaTeX.</p>
</div>
</div>
<div class="section" id="templates">
<h2><a class="toc-backref" href="#id9">Templates</a></h2>
<dl class="docutils">
<dt>New Feature:</dt>
<dd>Advanced configuration via custom templates.</dd>
<dt>Implementation:</dt>
<dd>A <tt class="docutils literal"><span class="pre">--template</span></tt> option and config setting allows specification of a
template file.</dd>
</dl>
<p>See the <a class="reference external" href="latex.html#templates">LaTeX writer documentation</a> for details.</p>
</div>
<div class="section" id="custom-roles">
<h2><a class="toc-backref" href="#id10">Custom roles</a></h2>
<dl class="docutils">
<dt>New Feature: failsave implementation</dt>
<dd>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.</dd>
<dt>New Feature: custom roles based on standard roles</dt>
<dd>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.</dd>
<dt>Backwards compatibility:</dt>
<dd>The implementation is fully backwards compatible. (SVN versions 5742 to
5861 contained an implementation that did not work with commands expecting
an argument.)</dd>
</dl>
</div>
<div class="section" id="length-units">
<h2><a class="toc-backref" href="#id11">Length units</a></h2>
<dl class="docutils">
<dt>New Features:</dt>
<dd><ol class="first last arabic simple">
<li>Add default unit if none given.
A poll on docutils-users favoured <tt class="docutils literal">bp</tt> (Big Point: 1 bp = 1/72 in).</li>
<li>Do not change <tt class="docutils literal">px</tt> to <tt class="docutils literal">pt</tt>.</li>
<li>Lengths specified in the document with unit "pt" will be written with
unit "bp" to the LaTeX source.</li>
</ol>
</dd>
<dt>Rationale:</dt>
<dd><ol class="first last arabic">
<li><p class="first">prevent LaTeX error "missing unit".</p>
</li>
<li><p class="first"><tt class="docutils literal">px</tt> is a valid unit in pdftex since version 1.3.0 released on
2005-02-04:</p>
<blockquote>
<p>1px defaults to 1bp (or 72dpi), but can be changed with the
<tt class="docutils literal">\pdfpxdimen</tt> primitive.:</p>
<pre class="literal-block">
\pdfpxdimen=1in % 1 dpi
\divide\pdfpxdimen by 96 % 96 dpi
</pre>
<p class="attribution">—<a class="reference external" href="http://www.tug.org/applications/pdftex/NEWS">http://www.tug.org/applications/pdftex/NEWS</a></p>
</blockquote>
<p>Modern TeX distributions use pdftex also for dvi generation (i.e.
<tt class="docutils literal">latex</tt> actually calls <tt class="docutils literal">pdftex</tt> with some options).</p>
</li>
<li><p class="first">In Docutils (as well as CSS) the unit symbol "pt" denotes the
<span class="incremental">Postscript point</span> or <span class="incremental">DTP point</span> while LaTeX uses "pt" for the <span class="incremental">LaTeX
point</span>, which is unknown to Docutils and 0.3 % smaller.</p>
<p>The <span class="incremental">DTP point</span> is available in LaTeX as "bp" (big point):</p>
<blockquote>
<p>1 pt = 1/72.25 in < 1 bp = 1/72 in</p>
</blockquote>
</li>
</ol>
</dd>
<dt>Backwards compatibility:</dt>
<dd><p class="first">Images with width specification in <tt class="docutils literal">px</tt> come out slightly (0.3 %) larger:</p>
<blockquote>
1 px = 1 bp = 1/72 in > 1 pt = 1/72.25 in</blockquote>
<p>This can be reset with</p>
<pre class="last literal-block">
\pdfpxdimen=1pt
</pre>
</dd>
</dl>
<div class="caution">
<p class="first admonition-title">Caution!</p>
<p class="last">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.</p>
</div>
<div class="admonition-error-illegal-unit-px admonition">
<p class="first admonition-title">Error <tt class="docutils literal">illegal unit px</tt></p>
<p>The unit <tt class="docutils literal">px</tt> is not defined in "pure" LaTeX, but introduced by the
<span class="incremental">pdfTeX</span> converter on 2005-02-04. <span class="incremental">pdfTeX</span> is used in all modern LaTeX
distributions (since ca. 2006) also for conversion into DVI.</p>
<p>If you convert the LaTeX source with a legacy program, you might get the
error <tt class="docutils literal">illegal unit px</tt>.</p>
<p class="last">If updating LaTeX is not an option, just remove the <tt class="docutils literal">px</tt> from the length
specification. HTML/CSS will default to <tt class="docutils literal">px</tt> while the <span class="incremental">latexe2</span> writer
will add the fallback unit <tt class="docutils literal">bp</tt>.</p>
</div>
</div>
<div class="section" id="font-encoding">
<h2><a class="toc-backref" href="#id12">Font encoding</a></h2>
<dl class="docutils">
<dt>New feature:</dt>
<dd><p class="first">Do not mix font-encoding and font settings: do not load the obsolete
<span class="incremental">ae</span> and <span class="incremental">aeguill</span> packages unless explicitely required via the
<tt class="docutils literal"><span class="pre">--stylesheet</span></tt> option.</p>
<table class="last docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name" colspan="2">font-encoding = "":</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first">do not load <span class="incremental">ae</span> and <span class="incremental">aeguill</span>, i.e.</p>
<ul class="simple">
<li>do not change font settings,</li>
<li>do not use the fontenc package
(implicitely loaded via <span class="incremental">ae</span>),</li>
<li>use LaTeX default font encoding (OT1)</li>
</ul>
</td>
</tr>
<tr class="field"><th class="field-name" colspan="2">font-encoding = "OT1":</th></tr>
<tr class="field"><td> </td><td class="field-body"><p class="first last">load <span class="incremental">fontenc</span> with <tt class="docutils literal"><span class="pre">\usepackage[OT1]{fontenc}</span></tt></p>
</td>
</tr>
</tbody>
</table>
</dd>
<dt>Example:</dt>
<dd><tt class="docutils literal"><span class="pre">--font-encoding=LGR,T1</span></tt> becomes <tt class="docutils literal"><span class="pre">\usepackage[LGR,T1]{fontenc}</span></tt>
(Latin, Latin-1 Supplement, and Greek)</dd>
<dt>Backwards compatibility:</dt>
<dd>Load the ae and aeguill packages if fontenc is not used.</dd>
</dl>
<div class="tip">
<p class="first admonition-title">Tip</p>
<p class="last">Using <span class="incremental">ae</span> is not recommended. A similar look (but better
implementation) can be achieved with the packages <span class="incremental">lmodern</span>, <span class="incremental">cmsuper</span>,
or <span class="incremental">cmlgr</span> all providing Computer Modern look-alikes in vector format and
T1 encoding, e.g. <tt class="docutils literal"><span class="pre">--font-encoding=T1</span> <span class="pre">--stylesheet=lmodern</span></tt>.</p>
</div>
</div>
<div class="section" id="sub-and-superscript-as-text">
<h2><a class="toc-backref" href="#id13">Sub- and superscript as text</a></h2>
<dl class="docutils">
<dt>New feature:</dt>
<dd><p class="first">Set sub- and superscript role argument in text mode not as math.</p>
<p class="last">Pass the role content to <tt class="docutils literal">\textsubscript</tt> or <tt class="docutils literal">\textsuperscript</tt>.</p>
</dd>
<dt>Backwards compatibility:</dt>
<dd><p class="first">The old implementation set the role content in Math mode, where</p>
<ul class="simple">
<li>whitespace is ignored,</li>
<li>a different command set and font setting scheme is active,</li>
<li>Latin letters are typeset italic but numbers upright.</li>
</ul>
<p class="last">Although it is possible to redefine <tt class="docutils literal">\textsubscript</tt> and
<tt class="docutils literal">\textsuperscript</tt> to typeset the content in math-mode, this can lead to
errors with certain input and is therefore not done in this style sheet.</p>
</dd>
</dl>
<div class="tip">
<p class="first admonition-title">Tip</p>
<p>To get italic subscripts, define and use in your document
<a class="reference internal" href="#custom-roles">custom roles</a> like <tt class="docutils literal">.. role:: sub(subscript)</tt> and
<tt class="docutils literal">.. role:: super(superscript)</tt> and define the "role commands":</p>
<pre class="literal-block">
\newcommand{\DUrolesub}{\itshape}
\newcommand{\DUrolesuper}{\itshape}
</pre>
<p>Alternatively, if you want all sub- and superscripts in italic, redefine
the macros:</p>
<pre class="literal-block">
%% \let\DUsup\textsubscript
%% \let\DUsuper\textsuperscript
%% \renewcommand*{\textsubscript}{\DUsub\itshape}
%% \renewcommand*{\textsuperscript}{\DUsuper\itshape}
</pre>
<p class="last">This is not fully backwards compatible, as it will also set numbers in
italic shape and not ignore whitespace.</p>
</div>
</div>
<div class="section" id="page-layout">
<h2><a class="toc-backref" href="#id14">Page layout</a></h2>
<dl class="docutils">
<dt>New features:</dt>
<dd><ul class="first last simple">
<li>Margins are configurable via the <tt class="docutils literal"><span class="pre">DIV=...</span></tt> document option.</li>
<li>The <tt class="docutils literal">\raggedbottom</tt> 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.</li>
</ul>
</dd>
<dt>Backwards compatibility:</dt>
<dd><p class="first">Up to version 0.5, use of <span class="incremental">typearea</span> and a DIV setting of 12 were
hard-coded into the latex2e writer</p>
<pre class="literal-block">
\usepackage{typearea}
\typearea{12}
</pre>
<p>and the vertical alignment of lower boundary of the text area in book
classes disabled via</p>
<pre class="last literal-block">
\raggedbottom
</pre>
</dd>
</dl>
</div>
<div class="section" id="toc-and-section-numbers">
<h2><a class="toc-backref" href="#id15">ToC and section numbers</a></h2>
<p>Better conformance to Docutils specifications.</p>
<dl class="docutils">
<dt>New feature:</dt>
<dd><ul class="first last simple">
<li>The "depth" argument of the "contents" and "sectnum" directives is
respected.</li>
<li>section numbering independent of 'use-latex-toc':<ul>
<li>sections are only numbered if there is a "sectnum" directive in the
document</li>
<li>section numbering by LaTeX if the "sectnum_xforms" config setting is
False.</li>
</ul>
</li>
</ul>
</dd>
</dl>
<p>Backwards compatibility:</p>
<blockquote>
<p>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:</p>
<pre class="literal-block">
\setcounter{secnumdepth}{3}
\setcounter{tocdepth}{3}
</pre>
</blockquote>
<!-- 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. -->
<dl class="docutils">
<dt>New feature:</dt>
<dd>If 'use-latex-toc' is set, local tables of content are typeset using the
'minitoc' package (instead of being ignored).</dd>
<dt>Backwards compatibility:</dt>
<dd>Disable the creation of local ToCs (ignoring all special commands) by
replacing <tt class="docutils literal">\usepackage{minitoc} with <span class="pre">``\usepackage{mtcoff}</span></tt>.</dd>
</dl>
</div>
<div class="section" id="default-font-in-admonitions-and-sidebar">
<h2><a class="toc-backref" href="#id16">Default font in admonitions and sidebar</a></h2>
<dl class="docutils">
<dt>New feature:</dt>
<dd>Use default font in admonitions and sidebar.</dd>
<dt>Backward compatibility:</dt>
<dd>See the fallback definitions for <a class="reference internal" href="#admonitions">admonitions</a>, <a class="reference internal" href="#topic-title">topic title</a> and
<a class="reference internal" href="#sidebar">sidebar</a>.</dd>
</dl>
</div>
<div class="section" id="figure-placement">
<h2><a class="toc-backref" href="#id17">Figure placement</a></h2>
<dl class="docutils">
<dt>New feature:</dt>
<dd><p class="first">Use <tt class="docutils literal">\floatplacement</tt> from the <span class="incremental">float</span> package instead of
"hard-coded" optional argument for the global setting.</p>
<p class="last">Default to <tt class="docutils literal"><span class="pre">\floatplacement{figure}{H}</span></tt> (here definitely). This
corresponds most closely to the source and HTML placement (principle of
least surprise).</p>
</dd>
<dt>Backwards compatibility:</dt>
<dd><p class="first">Set the global default back to the previous used value:</p>
<pre class="last literal-block">
\usepackage{float}
\floatplacement{figure}{htbp} % here, top, bottom, extra-page
</pre>
</dd>
</dl>
</div>
<div class="section" id="figure-and-image-alignment">
<h2><a class="toc-backref" href="#id18">Figure and image alignment</a></h2>
<p>New features:</p>
<ol class="loweralpha">
<li><p class="first">Fix behaviour of 'align' argument to a figure (do not align figure
contents).</p>
<p>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.</p>
</li>
<li><p class="first">Set default align of image in a figure to 'center'.</p>
</li>
<li><p class="first">Also center images that are wider than textwidth.</p>
</li>
<li><p class="first">Align images with class "align-[right|center|left]" (allows setting the
alignment of an image in a figure).</p>
</li>
</ol>
<dl class="docutils">
<dt>Backwards compatibility:</dt>
<dd>There is no "automatic" way to reverse these changes via a style sheet.</dd>
</dl>
<ol class="loweralpha">
<li><p class="first">The alignment of the image can be set with the "align-left",
"align-center" and "align-right" class arguments.</p>
<p>As previously, the caption of a figure is aligned according to the
document class -- configurable with a style sheet using the "caption"
package.</p>
</li>
<li><p class="first">See a)</p>
</li>
<li><p class="first">Set the alignment of "oversized" images to "left" to get back the
old placement.</p>
</li>
</ol>
</div>
<div class="section" id="shorter-preamble">
<h2><a class="toc-backref" href="#id19">Shorter preamble</a></h2>
<dl class="docutils">
<dt>New feature:</dt>
<dd>The document preamble is pruned to contain only relevant commands and
settings.</dd>
</dl>
<div class="section" id="packages-that-are-no-longer-required">
<h3><a class="toc-backref" href="#id20">Packages that are no longer required</a></h3>
<p>The following packages where required in pre-0.5 versions and still loaded
with version 0.5:</p>
<pre class="literal-block">
\usepackage{shortvrb}
\usepackage{amsmath}
</pre>
</div>
<div class="section" id="packages-that-are-conditionally-loaded">
<h3><a class="toc-backref" href="#id21">Packages that are conditionally loaded</a></h3>
<p>Additional to the <span class="incremental">typearea</span> for <a class="reference internal" href="#page-layout">page layout</a>, the following packages are
only loaded if actually required by doctree elements:</p>
<div class="section" id="tables">
<h4>Tables</h4>
<p>Standard package for tables across several pages:</p>
<pre class="literal-block">
\usepackage{longtable}
</pre>
<p>Extra space between text in tables and the line above them
('array' is implicitely loaded by 'tabularx', see below):</p>
<pre class="literal-block">
\usepackage{array}
\setlength{\extrarowheight}{2pt}
</pre>
<p>Table cells spanning multiple rows:</p>
<pre class="literal-block">
\usepackage{multirow}
</pre>
</div>
<div class="section" id="docinfo">
<h4>Docinfo</h4>
<p>One-page tables with auto-width columns:</p>
<pre class="literal-block">
\usepackage{tabularx}
</pre>
</div>
<div class="section" id="images">
<h4>Images</h4>
<p>Include graphic files:</p>
<pre class="literal-block">
\usepackage{graphicx}
</pre>
</div>
<div class="section" id="problematic-sidebar">
<h4>Problematic, Sidebar</h4>
<p>Set text and/or background colour, coloured boxes with <tt class="docutils literal">\colorbox</tt>:</p>
<pre class="literal-block">
\usepackage{color}
</pre>
</div>
</div>
<div class="section" id="floats-for-footnotes-settings">
<h3><a class="toc-backref" href="#id22">Floats for footnotes settings</a></h3>
<p>Settings for the use of floats for footnotes are only included if</p>
<ul class="simple">
<li>the option "use-latex-footnotes" is False, and</li>
<li>there is at least one footnote in the document.</li>
</ul>
<pre class="literal-block">
% 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
</pre>
</div>
</div>
<div class="section" id="special-lengths-commands-and-environments">
<h2><a class="toc-backref" href="#id23">Special lengths, commands, and environments</a></h2>
<div class="section" id="removed-definitions">
<h3><a class="toc-backref" href="#id24">Removed definitions</a></h3>
<div class="section" id="admonition-width">
<h4>admonition width</h4>
<p>The <tt class="docutils literal">admonitionwith</tt> lenght is replaced by the more powerful
<tt class="docutils literal">\DUadmonition</tt> command (see <a class="reference internal" href="#admonitions">admonitions</a>).</p>
<dl class="docutils">
<dt>Backwards compatibility:</dt>
<dd><p class="first">The default value (90 % of the textwidth) is unchanged.</p>
<p class="last">To configure the admonition width, you must redefine the <tt class="docutils literal">DUadmonition</tt>
command instead of changing the <tt class="docutils literal">admonitionwith</tt> length value.</p>
</dd>
</dl>
</div>
</div>
<div class="section" id="renamed-definitions-now-conditional">
<h3><a class="toc-backref" href="#id25">Renamed definitions (now conditional)</a></h3>
<p>The names for special doctree elements are now prefixed with <tt class="docutils literal">DU</tt>.</p>
<p>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.</p>
<p>Customization is done by an alternative definition in a style sheet with
<tt class="docutils literal">\newcommand</tt> instead of the former <tt class="docutils literal">\renewcommand</tt>.</p>
<p>The following code provides the old definitions and maps them (or their
custom variants) to the new interface.</p>
<div class="section" id="docinfo-width">
<h4>docinfo width</h4>
<pre class="literal-block">
\newlength{\docinfowidth}
\setlength{\docinfowidth}{0.9\textwidth}
\newlength{\DUdocinfowidth}
\AtBeginDocument{\setlength{\DUdocinfowidth}{\docinfowidth}}
</pre>
</div>
<div class="section" id="line-block">
<h4>line block</h4>
<pre class="literal-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}}
</pre>
</div>
<div class="section" id="local-line-width">
<h4>local line width</h4>
<p>The <tt class="docutils literal">\locallinewidth</tt> length for internal use in tables is replaced
by <tt class="docutils literal">\DUtablewidth</tt>. It was never intended for customization:</p>
<pre class="literal-block">
\newlength{\locallinewidth}
</pre>
</div>
<div class="section" id="option-lists">
<h4>option lists</h4>
<pre class="literal-block">
\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}}
</pre>
</div>
<div class="section" id="rubric">
<h4>rubric</h4>
<p>Now less prominent (not bold, normal size) restore with:</p>
<pre class="literal-block">
\newcommand{\rubric}[1]{\subsection*{~\hfill {\it #1} \hfill ~}}
\newcommand{\DUrubric}[2][class-arg]{\rubric{#2}}
</pre>
</div>
<div class="section" id="title-reference-role">
<h4>title reference role</h4>
<pre class="literal-block">
\newcommand{\titlereference}[1]{\textsl{#1}}
\newcommand{\DUroletitlereference}[1]{\titlereference{#1}}
</pre>
</div>
</div>
<div class="section" id="new-definitions">
<h3><a class="toc-backref" href="#id26">New definitions</a></h3>
<dl class="docutils">
<dt>New Feature:</dt>
<dd><p class="first">Enable customization of some more Docutils elements with special commands</p>
<table class="last docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">admonition:</th><td class="field-body"><tt class="docutils literal">DUadmonition</tt> command (replacing <tt class="docutils literal">\admonitionwidth</tt>),</td>
</tr>
<tr class="field"><th class="field-name">field list:</th><td class="field-body"><tt class="docutils literal">DUfieldlist</tt> environment,</td>
</tr>
<tr class="field"><th class="field-name">legend:</th><td class="field-body"><tt class="docutils literal">DUlegend</tt> environment,</td>
</tr>
<tr class="field"><th class="field-name">sidebar:</th><td class="field-body"><tt class="docutils literal">\DUsidebar</tt>, <tt class="docutils literal">\DUtitle</tt>, and
<tt class="docutils literal">DUsubtitle</tt> commands,</td>
</tr>
<tr class="field"><th class="field-name">topic:</th><td class="field-body"><tt class="docutils literal">\DUtopic</tt> and <tt class="docutils literal">\DUtitle</tt> commands,</td>
</tr>
<tr class="field"><th class="field-name">transition:</th><td class="field-body"><tt class="docutils literal">\DUtransition</tt> command.</td>
</tr>
<tr class="field"><th class="field-name">footnotes:</th><td class="field-body"><tt class="docutils literal">\DUfootnotemark</tt> and <tt class="docutils literal">\DUfootnotetext</tt> commands with
hyperlink support using the Docutils-provided footnote label.</td>
</tr>
</tbody>
</table>
</dd>
<dt>Backwards compatibility:</dt>
<dd>In most cases, the default definition corresponds to the previously used
construct. The following definitions restore the old behaviour in case of
changes.</dd>
</dl>
<div class="section" id="admonitions">
<h4>admonitions</h4>
<p>Use sans-serif fonts:</p>
<pre class="literal-block">
\newcommand{\DUadmonition}[2][class-arg]{%
\begin{center}
\fbox{\parbox{0.9\textwidth}{\sffamily #2}}
\end{center}
}
</pre>
</div>
<div class="section" id="dedication">
<h4>dedication</h4>
<p>Do not center:</p>
<pre class="literal-block">
\newcommand{\DUtopicdedication}[1]{#1}
</pre>
<p>But center the title:</p>
<pre class="literal-block">
\newcommand*{\DUtitlededication}[1]{\centerline{\textbf{#1}}}
</pre>
</div>
<div class="section" id="sidebar">
<h4>sidebar</h4>
<p>Use sans-serif fonts, a frame, and a darker shade of grey:</p>
<pre class="literal-block">
\providecommand{\DUsidebar}[2][class-arg]{%
\begin{center}
\sffamily
\fbox{\colorbox[gray]{0.80}{\parbox{0.9\textwidth}{#2}}}
\end{center}
}
</pre>
</div>
<div class="section" id="sidebar-sub-title">
<h4>sidebar sub-title</h4>
<p>Bold instead of emphasized:</p>
<pre class="literal-block">
\providecommand*{\DUsubtitlesidebar}[1]{\hspace*{\fill}\\
\textbf{#1}\smallskip}
</pre>
</div>
<div class="section" id="topic">
<h4>topic</h4>
<p>No quote but normal text:</p>
<pre class="literal-block">
\newcommand{\DUtopic}[2][class-arg]{%
\ifcsname DUtopic#1\endcsname%
\csname DUtopic#1\endcsname{#2}%
\else
#2
\fi
}
</pre>
</div>
<div class="section" id="topic-title">
<h4>topic title</h4>
<p>Title for "topics" (admonitions, sidebar).</p>
<p>Larger font size:</p>
<pre class="literal-block">
\providecommand*{\DUtitletopic}[1]{\textbf{\large #1}\smallskip}
</pre>
</div>
<div class="section" id="transition">
<h4>transition</h4>
<p>Do not add vertical space after the transition.</p>
<pre class="literal-block">
\providecommand*{\DUtransition}[1][class-arg]{%
\hspace*{\fill}\hrulefill\hspace*{\fill}}
</pre>
</div>
</div>
</div>
</div>
</div>
</body>
</html>