Menu
▾
▴
[Docutils-checkins] r5891 - in trunk/docutils: docs/user/docutils-05-compat.sty.txt docs/user/docutils-05-compat.sty.txt docs/user/latex.txt docutils/writers/latex2e/docutils-05-compat.sty
Author: milde Date: 2009-04-02 10:53:39 +0200 (Thu, 02 Apr 2009) New Revision: 5891 Added: trunk/docutils/docs/user/docutils-05-compat.sty.txt Removed: trunk/docutils/docs/user/docutils-05-compat.sty.txt Modified: trunk/docutils/docs/user/latex.txt trunk/docutils/docutils/writers/latex2e/docutils-05-compat.sty Log: docutils-05-compat: add real file instead of link, add toc Deleted: trunk/docutils/docs/user/docutils-05-compat.sty.txt Added: trunk/docutils/docs/user/docutils-05-compat.sty.txt =================================================================== --- trunk/docutils/docs/user/docutils-05-compat.sty.txt 2009-04-01 20:09:08 UTC (rev 5890) +++ trunk/docutils/docs/user/docutils-05-compat.sty.txt 2009-04-02 08:53:39 UTC (rev 5891) @@ -0,0 +1,196 @@ +Backwards compatibility settings for the Docutils latex2e writer +================================================================ + +:Author: Günter Milde +:Contact: mi...@us... +:Revision: $Revision$ +:Date: $Date: 2009-02-24$ +:Copyright: © 2007, 2009 G. Milde, + Released without warranties or conditions of any kind + under the terms of the Apache License, Version 2.0 + http://www.apache.org/licenses/LICENSE-2.0 + +This file documents changes and provides a style for best possible +compatibility to the behaviour of the `latex2e` writer of Doctutils +release 0.5 :: + + \NeedsTeXFormat{LaTeX2e} + \ProvidesPackage{docutils-05-compat} + [2009/03/26 v0.1 compatibility with rst2latex from Docutils 0.5] + +.. contents:: + :depth: 2 + +Usage +----- + +To get an (almost) identic look for your old documents without further +configuration, place this file in the TEXINPUT path (e.g. the current work +directory) and pass the +``--stylesheet=latex2e-compat`` option to ``rst2latex.py``. + + +Changes since 0.5 +----------------- + +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. + +Needed Action: + Always specify the extension if you want the style sheet to be + ``\input`` by LaTeX. + + +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 +""""""""""""""""""""""" +SVN versions 5742 to 5861 contained an implementation that +did not work with commands expecting an argument. +The implementation from version 5862 is fully backwards compatible. + + +Length units +~~~~~~~~~~~~ + +#. add default unit if none given (to prevent LaTeX error) + a poll on docutils-users favoured ``bp`` (Big Point: 1 bp = 1/72 in) + +#. Do not change ``px`` to ``pt``. + + * ``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). + +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 + +It is impossible to revert the change of lengths specified without unit in a +style sheet, however the 0.3 % change will be imperceptible in most cases. + +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 +~~~~~~~~~~~~~ + +* Do not mix font-encoding and font settings: do not load `ae` and `aeguill` + unless explicitely required via the ``--stylesheet`` option. + + +Example: + ``--font-encoding=LGR,T1`` becomes ``\usepackage[LGR,T1]{fontenc}`` + (Latin, Latin-1 Supplement, and Greek) + + +Backwards compatibility +""""""""""""""""""""""" + +The following behaviour is new: + +:font-encoding = '': do not load `ae` and `aeguill` packages, 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}`` + +Load the ae and aeguill packages if fontenc is not used:: + + \@ifpackageloaded{fontenc} + {} + {\RequirePackage{ae,aeguill}} + +However, 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Set sub- and superscript role argument in text mode not as math. + + Wraps the role argument in ``$_{\mbox{\scriptsize <subscript text>}}$`` + or ``$^{\mbox{\scriptsize <superscript text>}}$``. + + +Backwards compatibility +""""""""""""""""""""""" + +In math mode, Latin letters are typeset italic and whitespace is ignored. + +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{\docutilsrolesub}{\itshape} + \newcommand{\docutilsrolesuper}{\itshape} + +This is not fully backwards compatible, as it will also set numbers in +italic shape and not ignore whitespace. However, switching to math-mode is +insecure with some characters like '$'. + Property changes on: trunk/docutils/docs/user/docutils-05-compat.sty.txt ___________________________________________________________________ Name: svn:keywords + Author Date Id Revision Name: svn:eol-style + native Modified: trunk/docutils/docs/user/latex.txt =================================================================== --- trunk/docutils/docs/user/latex.txt 2009-04-01 20:09:08 UTC (rev 5890) +++ trunk/docutils/docs/user/latex.txt 2009-04-02 08:53:39 UTC (rev 5891) @@ -812,19 +812,19 @@ The Docutils HISTORY_ lists all changes during the history of docutils. Changes since the last release (0.5) are summarized in the RELEASE-NOTES_ -and explained in detail in docutils-05-compat.sty.txt_ +and explained in detail in docutils-05-compat_ Compatibility Style Sheet ------------------------- docutils-05-compat.sty_ is a style sheet that provides some backwards -compatibility (it is the LaTeX source version of docutils-05-compat.sty.txt_). +compatibility (it is the LaTeX source version of docutils-05-compat_). .. _HISTORY: ../../HISTORY.html .. _RELEASE-NOTES: ../../RELEASE-NOTES.html -.. _docutils-05-compat.sty.txt: docutils-05-compat.sty.txt +.. _docutils-05-compat: docutils-05-compat.sty.html .. _docutils-05-compat.sty: ../../docutils/writers/latex2e/docutils-05-compat.sty Modified: trunk/docutils/docutils/writers/latex2e/docutils-05-compat.sty =================================================================== --- trunk/docutils/docutils/writers/latex2e/docutils-05-compat.sty 2009-04-01 20:09:08 UTC (rev 5890) +++ trunk/docutils/docutils/writers/latex2e/docutils-05-compat.sty 2009-04-02 08:53:39 UTC (rev 5891) @@ -10,20 +10,23 @@ % under the terms of the Apache License, Version 2.0 % http://www.apache.org/licenses/LICENSE-2.0 % -% :: +% This file documents changes and provides a style for best possible +% compatibility to the behaviour of the `latex2e` writer of Doctutils +% release 0.5 :: \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{latex2e-compat} +\ProvidesPackage{docutils-05-compat} [2009/03/26 v0.1 compatibility with rst2latex from Docutils 0.5] -% Documents changes and provides a compatibility to the behaviour of the -% `latex2e` writer of Doctutils release 0.5 +% .. contents:: +% :depth: 2 % % Usage % ----- % % To get an (almost) identic look for your old documents without further -% configuration, pass the +% configuration, place this file in the TEXINPUT path (e.g. the current work +% directory) and pass the % ``--stylesheet=latex2e-compat`` option to ``rst2latex.py``. % % @@ -105,27 +108,30 @@ % Backwards compatibility % """"""""""""""""""""""" % -% Images with width specification in ``px`` or ``bp`` come out slightly -% (0.3 %) larger: +% Images with width specification in ``px`` come out slightly (0.3 %) larger: % -% 1 bp = 1/72 in > 1 pt = 1/72.25 in +% 1 px = 1 bp = 1/72 in > 1 pt = 1/72.25 in % -% :: +% This can be reset with :: \pdfpxdimen=1pt -% This does not revert the change of lengths specified without unit, however -% the 0.3 % change might be imperceptible in most cases. +% It is impossible to revert the change of lengths specified without unit in a +% style sheet, however the 0.3 % change will be imperceptible in most cases. % -% 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. +% 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 updating LaTeX is not an option, just remove the ``px`` from the lengh -% specification. HTML/CSS will default to ``px`` while the `latexe2` writer -% will add the fallback unit ``bp``. -% +% 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 % ~~~~~~~~~~~~~ % @@ -156,8 +162,7 @@ \@ifpackageloaded{fontenc} {} - {\RequirePackage{ae%,aeguill - }} + {\RequirePackage{ae,aeguill}} % However, using `ae` is not recommended. A similar look (but better % implementation) can be achieved with the packages `lmodern`, `cmsuper`, or |