From d8c9e6faf4638a0ee3a8193f2d94521147e74847 Mon Sep 17 00:00:00 2001 From: Toshio Kuratomi Date: Wed, 20 Jul 2011 16:30:28 -0700 Subject: [PATCH] Replace the Apache licensed files with BSD licensed versions from upstream --- docutils-05-compat.sty | 738 +++++++++++++++++++++++++++++++++++++ docutils-05-compat.sty.txt | 738 +++++++++++++++++++++++++++++++++++++ python-docutils.spec | 15 +- 3 files changed, 1487 insertions(+), 4 deletions(-) create mode 100644 docutils-05-compat.sty create mode 100644 docutils-05-compat.sty.txt diff --git a/docutils-05-compat.sty b/docutils-05-compat.sty new file mode 100644 index 0000000..b80a3ae --- /dev/null +++ b/docutils-05-compat.sty @@ -0,0 +1,738 @@ +% ================================================================== +% 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: 6156 $ +% :Date: $Date: 2009-02-24 $ +% :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}} diff --git a/docutils-05-compat.sty.txt b/docutils-05-compat.sty.txt new file mode 100644 index 0000000..ddcbb93 --- /dev/null +++ b/docutils-05-compat.sty.txt @@ -0,0 +1,738 @@ +================================================================== + 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: 7096 $ +:Date: $Date: 2011-07-20 13:39:57 -0700 (Wed, 20 Jul 2011) $ +: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}} diff --git a/python-docutils.spec b/python-docutils.spec index c50a73f..6ac5433 100644 --- a/python-docutils.spec +++ b/python-docutils.spec @@ -11,7 +11,7 @@ Name: python-%{srcname} Version: 0.8 -Release: 1%{?dist} +Release: 2%{?dist} Summary: System for processing plaintext documentation Group: Development/Languages @@ -19,6 +19,9 @@ Group: Development/Languages License: Public Domain and BSD and Python and GPLv3+ URL: http://docutils.sourceforge.net Source0: http://downloads.sourceforge.net/docutils/%{srcname}-%{version}.tar.gz +# These have been relicensed to BSD in upstream svn so use those copies +Source1: docutils-05-compat.sty +Source2: docutils-05-compat.sty.txt # Sometimes we need snapshots. Instructions below: # svn co -r $REV svn://svn.berlios.de/docutils/trunk/docutils # cd docutils @@ -80,9 +83,10 @@ This package contains the module, ported to run under python3. %patch0 -p1 -b .testexc %patch1 -p1 -b .testencoding -# Remove Apache licensed files for now. Can stop doing this when this bug is resolved -# https://sourceforge.net/tracker/?func=detail&aid=3364658&group_id=38414&atid=422030 -rm -f docs/user/docutils-05-compat.sty.txt docutils/writers/latex2e/docutils-05-compat.sty +# Replace Apache licensed files with copies from upstream. Next upstream +# release should have the files licensed BSD +cp %{SOURCE1} docutils/writers/latex2e/docutils-05-compat.sty +cp cp %{SOURCE2} docs/user/docutils-05-compat.sty.txt # Remove shebang from library files for file in docutils/_string_template_compat.py docutils/math/{__init__.py,latex2mathml.py}; do @@ -184,6 +188,9 @@ rm -rf %{buildroot} %{python3_sitelib}/* %changelog +* Wed Jul 20 2011 Toshio Kuratomi - 0.8-2 +- Replace the Apache licensed files with BSD licensed versions from upstream + * Tue Jul 12 2011 Toshio Kuratomi - 0.8-1 - Upgrade to 0.8 final. - Remove the two remaining Apache licensed files until their license is fixed.