Author: milde Date: 2009-08-22 23:50:35 +0200 (Sat, 22 Aug 2009) New Revision: 6094 Modified: trunk/docutils/HISTORY.txt trunk/docutils/RELEASE-NOTES.txt trunk/docutils/docs/dev/todo.txt trunk/docutils/docs/user/docutils-05-compat.sty.txt trunk/docutils/docs/user/latex.txt trunk/docutils/docutils/writers/latex2e/__init__.py trunk/docutils/docutils/writers/latex2e/docutils-05-compat.sty trunk/docutils/test/functional/expected/latex_docinfo.tex trunk/docutils/test/functional/expected/multistyle_path_embed_rst_latex2e.tex trunk/docutils/test/functional/expected/multistyle_path_rst_latex2e.tex trunk/docutils/test/functional/expected/standalone_rst_latex.tex trunk/docutils/test/test_writers/test_latex2e.py Log: latex2e writer refactoring and cleanup: * new and renamed custom commands with optional "classes" argument * layout generic topic as "quote with title" * refactoring of visitor methods: admonition, subtitle, system_message, title, topic * table-of-contents: handle in visit_topic(), use generic DUtitle (if not use-latex-toc) Modified: trunk/docutils/HISTORY.txt =================================================================== --- trunk/docutils/HISTORY.txt 2009-08-20 09:58:30 UTC (rev 6093) +++ trunk/docutils/HISTORY.txt 2009-08-22 21:50:35 UTC (rev 6094) @@ -33,6 +33,8 @@ + drop 2.2 compatibility workarounds - OpenOffice export: ODT writer moved from sandbox to Doctutils core. + - Unix man page export: manpage writer moved from sandbox to Doctutils + core. - Apply [ 1719345 ] Galician translation - Apply [ 1905741 ] polish-translation @@ -75,8 +77,7 @@ * docutils/writers/latex2e/__init__.py (see also `<docs/user/docutils-05-compat.sty.html>`__) : - - Add option ``--use-titlepage-env``. - - Add option ``--embed-stylesheet``. + - Add options ``--use-titlepage-env`` and ``--embed-stylesheet``. - Apply [ 1474017 ] image vertical alignment is reversed. - Apply [ 2051599 ] multi-page tables in latex writer (from pabigot). - Change: has_key for dictionaries (not Nodes) to in-operator. @@ -97,10 +98,10 @@ Use a custom role based on sub-/superscript if you want italic shape. - Shorter preamble and less dependencies: Load packages and define macros only if required in the document. - - Use the name prefix ``DU`` for all Docutils specific LaTeX objects. - - New custom macros and environments. + - Use the name prefix ``DU`` for all Docutils specific LaTeX macros. + - New custom environments and commands with optional "classes" argument. - Simpler LaTeX encoding, e.g. "\%" instead of "{\%}". - - Better conformance to Docutils specifications with "use_latex_toc". + - Better conformance to Docutils specifications with ``--use-latex-toc``. Support for LaTeX generated ToC also with unnumbered sections. - If 'sectnum_xform' is False, the 'sectnum' directive triggers section numbering by LaTeX. @@ -109,8 +110,9 @@ - Bugfix: Newlines around targets and references prevent run-together paragraphs. - Fix internal hyperlinks. - - Default type area defined in the document class (not by 'typearea'). - - Float placement made configurable and changed to "here definitely". + - Use class defaults for page margins ('typearea' now optional). + - Float placement made configurable, default changed to "here definitely". + - Typeset generic topic as "quote block with title". * docutils/writers/manpage.py Modified: trunk/docutils/RELEASE-NOTES.txt =================================================================== --- trunk/docutils/RELEASE-NOTES.txt 2009-08-20 09:58:30 UTC (rev 6093) +++ trunk/docutils/RELEASE-NOTES.txt 2009-08-22 21:50:35 UTC (rev 6094) @@ -24,7 +24,7 @@ .. Note:: Docutils 0.5 is the last version supporting Python 2.2, - Docutils 0.6 requires Python 2.3 or newer (including Python 3). + Docutils 0.6 requires Python 2.3 or newer. Also works with Python 3. * reStructuredText: @@ -49,19 +49,25 @@ - Set sub- and superscript role argument as text not math. - Support custom roles based on standard roles. - Load packages and define macros only if required in the document. - - Docutils specific LaTeX objects are now all prefixed with ``DU``. + - All Docutils specific LaTeX macros are prefixed with ``DU``. - Better conformance to Docutils specifications with "use_latex_toc". - If 'sectnum_xform' is False, the 'sectnum' directive triggers section numbering by LaTeX. - Use default font in admonitions and sidebar. - Align of image in a figure defaults to 'center'. - - Default type area defined in the document class (not by 'typearea'). - - Float placement made configurable and changed to "here definitely". + - Use class defaults for page margins ('typearea' now optional). + - Float placement made configurable, default changed to "here definitely". + - Typeset generic topic as "quote with title". * ODT writer: - moved from sandbox to Doctutils core. +* manpage writer: + + - moved from sandbox to Doctutils core. + + Release 0.5 (2008-06-25) ======================== Modified: trunk/docutils/docs/dev/todo.txt =================================================================== --- trunk/docutils/docs/dev/todo.txt 2009-08-20 09:58:30 UTC (rev 6093) +++ trunk/docutils/docs/dev/todo.txt 2009-08-22 21:50:35 UTC (rev 6094) @@ -1914,6 +1914,7 @@ * Symbol footnotes fail with "use_latex_footnotes". + Generate clean and configurable LaTeX source ---------------------------------------------- @@ -1924,29 +1925,6 @@ :subtitle: Is there a package or native construct? -:section titles: Custom command or package `hypbmsec`? - -:admonitions: optional "type" argument:: - - \providecommand{\DUadmonition}[2][]{% - \ifcsname DU#1\endcsname% - \csname DU#1\endcsname{#2}% - \else - \begin{center} - \fbox{\parbox{0.9\textwidth}{#2}} - \end{center} - \fi% - } - - Would allow individual restyling of e.g. Notes, - e.g. with pdfcomment.sty__ or todonotes.sty. - - Use a "type" argument also for ``\DUtopictitle``? - (would allow red error etc.) - -__ http://dante.ctan.org/CTAN/help/Catalogue/entries/pdfcomment.html - - Configurable placement of figure and table floats ````````````````````````````````````````````````` @@ -2063,10 +2041,6 @@ * Use italic instead of slanted for titlereference? -* Let `meta` directive insert comment into header instead of document? - -* More prominent system messages (use admonition?, red?) - * Start a new paragraph after lists (as currently) or continue (no blank line in source, no parindent in output)? @@ -2187,7 +2161,7 @@ * better citation support -* Meta keywords into PDF ? +* Let `meta` directive insert PDF-keywords into header? * Multiple author entries in docinfo (same thing as in html). (already solved?) Modified: trunk/docutils/docs/user/docutils-05-compat.sty.txt =================================================================== --- trunk/docutils/docs/user/docutils-05-compat.sty.txt 2009-08-20 09:58:30 UTC (rev 6093) +++ trunk/docutils/docs/user/docutils-05-compat.sty.txt 2009-08-22 21:50:35 UTC (rev 6094) @@ -22,7 +22,7 @@ \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{docutils-05-compat} [2009/03/26 v0.1 compatibility with rst2latex from Docutils 0.5] - + .. contents:: :depth: 3 @@ -159,7 +159,7 @@ \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. @@ -182,7 +182,7 @@ 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. @@ -228,7 +228,7 @@ \@ifundefined{@ifl@ter@@} {\RequirePackage{ae,aeguill}} {} - + .. Why not ``\@ifpackageloaded{fontenc}``? 'fontenc' disables the test to enable loading more than once with @@ -263,9 +263,9 @@ `custom roles`_ like ``.. role:: sub(subscript)`` and ``.. role:: super(superscript)`` and define the "role commands":: - \newcommand{\docutilsrolesub}{\itshape} - \newcommand{\docutilsrolesuper}{\itshape} - + \newcommand{\DUrolesub}{\itshape} + \newcommand{\DUrolesuper}{\itshape} + Alternatively, if you want all sub- and superscripts in italic, redefine the macros:: @@ -273,7 +273,7 @@ %% \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. @@ -293,13 +293,13 @@ \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 ----------------------- @@ -326,7 +326,7 @@ \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. @@ -367,8 +367,8 @@ \usepackage{float} \floatplacement{figure}{htbp} % here, top, bottom, extra-page - - + + Figure and image alignment -------------------------- @@ -418,7 +418,7 @@ \usepackage{shortvrb} \usepackage{amsmath} - + Packages that are conditionally loaded `````````````````````````````````````` @@ -431,36 +431,36 @@ 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 ````````````````````````````` @@ -482,8 +482,8 @@ \setcounter{topnumber}{50} \setcounter{bottomnumber}{50} % end floats for footnotes - - + + Special lengths, commands, and environments ------------------------------------------- @@ -524,10 +524,10 @@ \newlength{\docinfowidth} \setlength{\docinfowidth}{0.9\textwidth} - + \newlength{\DUdocinfowidth} \AtBeginDocument{\setlength{\DUdocinfowidth}{\docinfowidth}} - + line block ^^^^^^^^^^ :: @@ -542,13 +542,13 @@ \leftmargin#1} \raggedright} {\end{list}} - + \newlength{\DUlineblockindent} \AtBeginDocument{\setlength{\DUlineblockindent}{\lineblockindentation}} \newenvironment{DUlineblock}[1] {\begin{lineblock}{#1}} {\end{lineblock}} - + local line width ^^^^^^^^^^^^^^^^ @@ -556,7 +556,7 @@ by ``\DUtablewidth``. It was never intended for customization:: \newlength{\locallinewidth} - + option lists ^^^^^^^^^^^^ :: @@ -571,41 +571,39 @@ \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}[1]{\rubric{#1}} - + \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`` environment (replacing ``\admonitionwidth``), + :admonition: ``DUadmonition`` command (replacing ``\admonitionwidth``), :field list: ``DUfieldlist`` environment, :legend: ``DUlegend`` environment, - :sidebar: ``\DUsidebar``, ``\DUsidebartitle``, and - ``DUsidebarsubtitle`` commands, - :topic: ``\DUtopictitle`` command, + :sidebar: ``\DUsidebar``, ``\DUtitle``, and + ``DUsubtitle`` commands, + :topic: ``\DUtopic`` and ``\DUtitle`` commands, :transition: ``\DUtransition`` command. Backwards compatibility: @@ -617,40 +615,41 @@ ^^^^^^^^^^^ Use sans-serif fonts:: - \newcommand{\DUadmonition}[1]{% + \newcommand{\DUadmonition}[2][class-arg]{% \begin{center} - \fbox{\parbox{0.9\textwidth}{\sffamily #1}} + \fbox{\parbox{0.9\textwidth}{\sffamily #2}} \end{center} } - + topic title ^^^^^^^^^^^ Title for "topics" (admonitions, sidebar). Larger font size:: - \providecommand*{\DUtopictitle}[1]{\textbf{\large #1}\smallskip} - + \providecommand*{\DUtitletopic}[1]{\textbf{\large #1}\smallskip} + sidebar ^^^^^^^ -Use sans-serif fonts and a darker shade of grey:: +Use sans-serif fonts, a frame, and a darker shade of grey:: - \providecommand{\DUsidebar}[1]{% + \providecommand{\DUsidebar}[2][class-arg]{% \begin{center} \sffamily - \fbox{\colorbox[gray]{0.80}{\parbox{0.9\textwidth}{#1}}} + \fbox{\colorbox[gray]{0.80}{\parbox{0.9\textwidth}{#2}}} \end{center} } - + sidebar sub-title ^^^^^^^^^^^^^^^^^ Bold instead of emphasized:: - \providecommand*{\DUsidebarsubtitle}[1]{\hspace*{\fill}\\ + \providecommand*{\DUsubtitlesidebar}[1]{\hspace*{\fill}\\ \textbf{#1}\smallskip} - + transition ^^^^^^^^^^ Do not add vertical space after the transition. :: - \providecommand*{\DUtransition}{\hspace*{\fill}\hrulefill\hspace*{\fill}} + \providecommand*{\DUtransition}[1][class-arg]{% + \hspace*{\fill}\hrulefill\hspace*{\fill}} Modified: trunk/docutils/docs/user/latex.txt =================================================================== --- trunk/docutils/docs/user/latex.txt 2009-08-20 09:58:30 UTC (rev 6093) +++ trunk/docutils/docs/user/latex.txt 2009-08-22 21:50:35 UTC (rev 6094) @@ -9,13 +9,15 @@ :Copyright: This document has been placed in the public domain. .. contents:: +.. sectnum:: Introduction ============ Producing LaTeX code from reST input can be done in at least two ways: -treat LaTeX as a document format (like HTML): +1. treat LaTeX as a document format (like HTML): + Transform the internal markup into corresponding LaTeX markup. For example, a section title would be written with the LaTeX section command: ``\section{this section title}``. @@ -25,7 +27,8 @@ If you prefer this approach, try ``rst2latex.py``. -treat LaTeX as a page description format (like Postscript): +2. treat LaTeX as a page description format (like Postscript): + Use LaTeX as a typesetting system to produce the desired output without bothering with the usual LaTeX idioms for representing document structure information. @@ -42,11 +45,11 @@ ============== In many cases, LaTeX code is not the desired end-format of the document. -LaTeX offers four ways to generate PDF documents from the LaTeX source: +LaTeX offers (at least) four ways to generate PDF documents from the LaTeX +source: pdflatex - Generates a PDF document directly from the LaTeX file. As always one - might need to call it twice (thrice) to get internal references correct. + Generates a PDF document directly from the LaTeX file. latex dvipdfm Use ``latex`` to generate a DVI file and ``dvipdfm`` to produce a PDF @@ -61,13 +64,15 @@ The `XeTeX`_ engine works with input files in UTF-8 encoding and system fonts. It is currently not supported by Docutils. -The Rubber_ wrapper for LaTeX and friends can be used to automatically run -all programs the required number of times and delete "spurious" files. +You might need to call latex (or pdflatex/xelatex) twice (or even thrice) to +get internal references correct. The Rubber_ wrapper for LaTeX and friends +can be used to automatically run all programs the required number of times +and delete "spurious" files. .. _Rubber: http://iml.univ-mrs.fr/~beffara/soft/rubber/ -Specialities of the LaTeX format +Specialities of the LaTeX writer ================================ Length units @@ -101,9 +106,10 @@ .. _length units: ../ref/rst/restructuredtext.html#length-units -For more on lengths in LaTeX, see e.g. -http://www.giss.nasa.gov/tools/latex/ltx-86.html. +For more on lengths in LaTeX, see e.g. `Hypertext Help with LaTeX: Lengths`__ +__ http://www.giss.nasa.gov/tools/latex/ltx-86.html. + default length unit ``````````````````` @@ -141,7 +147,7 @@ specified in ``px`` tend to come too large in the PDF. Solution: - Specify the image size in fixed units (`pt``, ``cm``, ``in``) or + Specify the image size in fixed units (``pt``, ``cm``, ``in``) or configure the "resolution" in a style sheet. Example: @@ -150,7 +156,7 @@ \pdfpxdimen=1in % 1 DPI \divide\pdfpxdimen by 96 % 96 DPI -images +Images ------ Images__ are included in LaTeX with the help of the `graphicx` package. The @@ -167,25 +173,30 @@ ----------------------------- Some Docutils objects have no LaTeX counterpart, they will be typeset using -a Docutils specific LaTeX macro. The specific commands, environments, and -lengths allow layout changes from the `style sheet`_ or with `raw LaTeX`_. -By convention, these special definitions use the prefix ``\DU``\ [#]_. +a Docutils specific LaTeX *macro* (command, environment, or length) to allow +layout changes from the `style sheet`_ or with `raw LaTeX`_. By convention, +special macros use the prefix ``\DU``\ [#]_. The generated LaTeX documents should be kept processable by a standard LaTeX installation. Therefore fallback definitions are included after the custom style sheet, if the macro is needed in the document. -* `Custom style sheets`_ can define alternative implementations with +* Custom `style sheets`_ can define alternative implementations with ``\newcommand``, ``\newenvironment``, and ``\newlength`` plus ``\setlength``. * Definitions with `raw LaTeX`_ are part of the document body. Use ``\def``, ``\renewcommand`` or ``\renewenvironment``, and ``\setlength``. -.. [#] for Documentation Utilities = Docutils +See the test output standalone_rst_latex.tex_ for an example of all fallback +definitions and their use in the document. +.. _standalone_rst_latex.tex: + ../../test/functional/output/standalone_rst_latex.tex +.. [#] DU for Documentation Utilities = Docutils + Configuration ============= @@ -210,6 +221,7 @@ ../user/config.html .. _style sheet: +.. _style sheets: Custom style sheets ------------------- @@ -223,7 +235,7 @@ references STYLESHEET using the command ``\usepackage`` if STYLESHEET has no extension or the extension ``.sty`` (the extension will be dropped). With -any other extension, the command ``\input`` is used. +any other extension, the LaTeX command ``\input`` is used. It is possible to specify multiple style sheets (see examples below). @@ -236,6 +248,7 @@ the given path (i.e. without search in the `TeX input path`_). Examples: + .. * Times Roman fonts with `mathptmx` package:: @@ -275,6 +288,7 @@ uses one common language for content and style. Examples: + .. * Amost all examples for the `style sheet`_ will also work as raw LaTeX inside the document. An exception are commands that need to be given in @@ -295,25 +309,8 @@ (Drawback: the formula will be invisible in other output formats.) -* Making a "colorbox": If someone wants to get a red background for a - text block, she/he can define ``\definecolor{bg}{rgb}{.9,0,0}`` in a custom - `style sheet`_ and in the document do something like this:: +* Defining a macro for a `custom role`_. - |begincolorbox| - Nobody expects the Spanish inquisition. - |endcolorbox| - - .. |begincolorbox| raw:: latex - - \\begin{center} - \\colorbox{bg}{ - \\parbox{0.985\\linewidth}{ - - .. |endcolorbox| raw:: latex - - }} - \\end{center} - .. _raw directive: ../ref/rst/directives.html#raw @@ -327,24 +324,52 @@ Admonitions__ are specially marked "topics" that can appear anywhere an ordinary body element can. +__ ../ref/rst/directives.html#admonitions + Command: ``\DUadmonition`` Default: Typeset in a frame (90 % of text width). -Example: - use sans-serif font and 95 % of text widht:: +Examples: + .. - \newcommand{\DUadmonition}[1]{% - \begin{center} - \fbox{\parbox{0.95\textwidth}{\textsf{#1}}} - \end{center} + +* A lighter layout without the frame:: + + \newcommand{\DUadmonition}[2][class-arg]{% + % try \DUadmonition#1{#2}: + \ifcsname DUadmonition#1\endcsname% + \csname DUadmonition#1\endcsname{#2}% + \else + \begin{quote} + #2 + \end{quote} + \fi } -__ ../ref/rst/directives.html#admonitions +The first part of this definition acts as a "dispatcher". This way it is +possible to define a special handling of `specific admonitions`_ or based on +the optional "class" argument. +.. _specific admonitions: + ../ref/rst/directives.html#specific-admonitions +Example: + layout ``.. note::`` as a margin note:: + + \newcommand{\DUadmonitionnote}[1]{\marginpar{#1}} + + Make sure you have enought space to hold the note. + See also the marginnote_ and pdfcomment_ packages. + +The admonition title is typeset with the ``\DUtitle`` command which also +takes a class argument. See `topic title`_ + + +.. _custom role: + custom interpreted text roles ````````````````````````````` @@ -365,17 +390,18 @@ Commands: ``\DUrole``: dispatcher command - ``\docutilsroleCLASSARGUMENT``\ [#]_: optional styling command + ``\DUroleCLASSARGUMENT``: optional styling command -.. [#] The prefix ``\docutilsrole...`` instead of ``\DUrole...`` in the - styling commands is kept for backwards compatibility. - Default: The definition of ``\DUrole{CLASSARGUMENT}{}`` calls the macro named - ``\docutilsroleCLASSARGUMENT{}`` if it is defined (but silently ignores + ``\DUroleCLASSARGUMENT{}``\ [#]_ if it is defined (but silently ignores this class argument if a corresponding macro is not defined). +.. [#] For backwards compatibility, the prefix ``\docutilsrole...`` in the + styling commands also recognized. + Examples: + .. * Typeset text in small caps:: @@ -387,10 +413,9 @@ \DUrole{smallcaps}{Fourier} transformation - The default definition of ``\DUrole`` will look for a macro named - ``\docutilsrolesmallcaps``. The definition :: + The definition :: - \newcommand{\docutilsrolesmallcaps}{\textsc} + \newcommand{\DUrolesmallcaps}{\textsc} as `raw LaTeX`_ or in the custom `style sheet`_ will give the expected result (if the chosen font supports small caps). @@ -402,7 +427,7 @@ As "sub" inherits from the standard "subscript" role, the LaTeX macro only needs to set the size and shape:: - \newcommand{\docutilsrolesub}{\normalsize\itshape} + \newcommand{\DUrolesub}{\normalsize\itshape} * A role with several classes and a converted class name:: @@ -415,10 +440,10 @@ With the definitions:: - \newcommand{\docutilsroleargi}[1]{\textsc} - \newcommand{\docutilsroleargii}[1]{{\large #1}} + \newcommand{\DUroleargi}[1]{\textsc} + \newcommand{\DUroleargii}[1]{{\large #1}} \makeatletter - \@namedef{docutilsrolearg-3}{\textbf} + \@namedef{DUrolearg-3}{\textbf} \makeatother in a `style sheet`_\ [#]_ or as `raw LaTeX`_ in the document source, @@ -476,20 +501,12 @@ There are hundreds of alternative LaTeX document classes installed by modern LaTeX distributions, provided by publishers or available at CTAN_ e.g. -* scrarticle, scrreport, scrbook: KOMA-script_ classes +* scrartcl, scrrprt, scrbook: KOMA-script_ classes * memoir_ The `TeX Catalogue`_ lists most of them. -.. _CTAN: http://www.dante.de/ctan -.. _KOMA-script: - http://dante.ctan.org/CTAN/help/Catalogue/entries/koma-script.html -.. _memoir: - http://dante.ctan.org/CTAN/help/Catalogue/entries/memoir.html -.. _TeX Catalogue: - http://dante.ctan.org/CTAN/help/Catalogue/ - document info ````````````` @@ -586,7 +603,9 @@ closely to the source and HTML placement (principle of least surprise). Examples: + .. + * Set the default back to the pre-0.6 value in a custom `style sheet`_:: \usepackage{float} @@ -629,11 +648,14 @@ * Packages can be combined. * Passing options to a package is only possible in the style sheet. -b) changing the font-default macros. +b) changing the font-default macros ``\rmdefault``, ``sfdefault`` and/or + ``ttdefault``. Examples: + .. + * Use `LaTeX Modern`, a Type 1 variant of CM. LaTeX code:: @@ -657,15 +679,16 @@ --stylesheet="mathptmx,helvet,courier" -* Changing a font without using a package (the macros are ``\rmdefault``, - ``sfdefault`` and ``ttdefault``):: + .. hint:: + When generating PDF-files from LaTeX, the files can become smaller if + this font combination is used as the fonts do not need to be embedded in + the document. +* Use the teletype font from the txfonts_ package:: + \renewcommand{\ttdefault}{txtt} -When generating PDF-files from LaTeX, the files can become smaller if -standard Postscript fonts are used. - The following table lists the font packages for standard Postscript fonts (see `Using common Postscript fonts with LaTeX`_ for details): @@ -725,7 +748,9 @@ is "" which does not load `fontenc`. Examples: + .. + * The recommended setting for Latin based scripts is "T1" together with a T1-encoded "Type 1" (vector) font, for example `Latin Modern`_:: @@ -788,7 +813,9 @@ package `setspace` Examples: + .. + * Get document wide double spacing:: \usepackage{setspace} @@ -907,7 +934,9 @@ For details see the `geometry manual`_. Examples: + .. + * Let `typearea` determine the type area with ``DIV=calc`` in the document options_:: @@ -966,7 +995,9 @@ * landscape, portrait, twoside. Examples: + .. + * Choose A5 pager in landscape orientation with command line argument:: --documentoptions=a5paper,landscape @@ -1006,12 +1037,13 @@ ``\DUrubric`` Default: - subsection style italic, centred + subsubsection style, italic, centred Example: - set rubric to subsection style, flushleft and red:: + set flushleft and red:: - \newcommand{\DUrubric}[1]{\subsection*{{\color{red}#1}\hfill~}} + \newcommand*{\DUrubric}[2][class-arg]{% + \subsubsection*{{\color{red}#1}\hfill}} __ ../ref/rst/directives.html#rubric @@ -1046,23 +1078,95 @@ ``DUsidebar`` Default: - Box (similar to admonition) with grey background. + Box with grey background. -Example: - Use margin notes :: +Examples: + .. - \newcommand{\DUsidebar}{\marginpar} +* Less space before the title:: + + \providecommand{\DUsidebar}[2]{% + \begin{center} + \colorbox[gray]{0.90}{\parbox{0.9\textwidth}{% + \smallskip\textbf{#1}\smallskip + #2}} + \end{center} + } + +* Use margin notes:: + + \newcommand{\DUsidebar}[2]{\marginpar{\flushleft \textbf{#1} #2}} + * Make sure the margin is wide enough to hold the note. - * This might fail with some constructs inside the `side bar` and where + * This fails with some constructs inside the `side bar` and where \marginpar cannot be used, e.g., inside floats, footnotes, or in frames made with the framed package (see marginnote_). __ http://docutils.sf.net/docutils/docs/ref/rst/directives.html#sidebar -.. _marginnote: - http://dante.ctan.org/CTAN/macros/latex/contrib/marginnote/marginnote.pdf +topic element +````````````` + +A topic_ is like a block quote with a title, or a self-contained section with +no subsections. + +Topics and rubrics can be used at places where a `section title`_ is not +allowed (e.g. inside a directive). + +Command: + ``DUtopic`` + +Default: + "quote" environment + +Examples: + .. + +* If you generally prefer a "normal" section over a block quote, define:: + + \newcommand{\DUtopic}[2][class-arg]{% + \ifcsname DUtopic#1\endcsname% + \csname DUtopic#1\endcsname{#2}% + \else + #2 + \fi + } + +* If you want a "normal" section for topics with class argument "noquote", + define:: + + \newcommand{\DUtopicnoquote}[1]{#1} + +.. _topic: ../ref/rst/directives.html#topic +.. _section title: ../ref/rst/restructuredtext.html#sections + +topic title +``````````` + +The title of admonition, sidebar, and topic elements is defined in the +``\DUtitle`` command, that also takes a "class" argument. + +Examples: + .. + +* You can get a centered and somewhat larger title for topcis with :: + + \newcommand*{\DUtitletopic}[1]{\subsection*{\centering #1} + +* Use a right-pointing hand as title for the "attention" directive:: + + \usepackage{pifont} + \newcommand{\DUtitleattention}[1]{\ding{43}} + + The title argument is "swallowed" by the command. + To have both, hand and title use:: + + \usepackage{pifont} + \newcommand{\DUtitleattention}[1]{\ding{43} #1} + + table of contents ````````````````` @@ -1203,16 +1307,18 @@ A horizontal line, 1/3 of text width Examples: - Use three stars:: + .. - \newcommand*{\DUtransition}{\centering{}*\quad*\quad*} +* Use three stars:: + \newcommand*{\DUtransition}[1][class-arg]{\centering{}*\quad*\quad*} + Alternatively use the more elaborated version in `transition-stars.sty`_. - If paragraphs are separated by indentation, you can simply use a vertical +* If paragraphs are separated by indentation, you can simply use a vertical space:: - \newcommand*{\DUtransition}{\vspace{2ex}} + \newcommand*{\DUtransition}[1][class-arg]{\vspace{2ex}} __ http://docutils.sf.net/docutils/docs/ref/rst/restructuredtext.html#transitions @@ -1345,7 +1451,6 @@ * Wrapping text around figures is currently not supported. (Requires the `wrapfig`_ package.) -.. _wrapfig: http://dante.ctan.org/CTAN/help/Catalogue/entries/wrapfig.html Miscellaneous ````````````` @@ -1356,10 +1461,31 @@ * Footnotes are not all on the same page (as in docs/user/rst/demo.txt) and do not link back and forth. + Until this is fixed, keep footnote mark and footnote text close together! + * Hyperlinks are not hyphenated; this leads to bad spacing. See docs/user/rst/demo.txt 2.14 directives. -* Pagestyle headings does not work, when sections are starred. +* Pagestyle headings does not work, when sections are starred. Use LaTeX for + the section numbering with the options_ ``--no-section-numbers`` + (command line) ``sectnum_xform: False`` (config file). * For additional docinfo items: the field_body is inserted as text, i.e. no markup is done. + +.. _CTAN: http://www.dante.de/ctan +.. _TeX Catalogue: + http://www.ctan.org/tex-archive/help/Catalogue/ + +.. _KOMA-script: + http://www.ctan.org/tex-archive/help/Catalogue/entries/koma-script.html +.. _memoir: + http://www.ctan.org/tex-archive/help/Catalogue/entries/memoir.html +.. _marginnote: + http://www.ctan.org/tex-archive/help/Catalogue/entries/marginnote.html +.. _pdfcomment: + http://www.ctan.org/tex-archive/help/Catalogue/entries/pdfcomment.html +.. _txfonts: + http://www.ctan.org/tex-archive/help/Catalogue/entries/txfonts.html +.. _wrapfig: + http://www.ctan.org/tex-archive/help/Catalogue/entries/wrapfig.html Modified: trunk/docutils/docutils/writers/latex2e/__init__.py =================================================================== --- trunk/docutils/docutils/writers/latex2e/__init__.py 2009-08-20 09:58:30 UTC (rev 6093) +++ trunk/docutils/docutils/writers/latex2e/__init__.py 2009-08-22 21:50:35 UTC (rev 6094) @@ -322,26 +322,50 @@ class PreambleCmds(object): """Building blocks for the latex preamble.""" -PreambleCmds.admonition = r"""% admonitions (specially marked "topics") -\providecommand{\DUadmonition}[1]{% - \begin{center} - \fbox{\parbox{0.9\textwidth}{#1}} - \end{center} +PreambleCmds.abstract = r""" +% abstract title +\providecommand*{\DUtitleabstract}[1]{\centerline{\textbf{#1}}}""" + +PreambleCmds.admonition = r""" +% admonition (specially marked topic) +\providecommand{\DUadmonition}[2][class-arg]{% + % try \DUadmonition#1{#2}: + \ifcsname DUadmonition#1\endcsname% + \csname DUadmonition#1\endcsname{#2}% + \else + \begin{center} + \fbox{\parbox{0.9\textwidth}{#2}} + \end{center} + \fi }""" ## PreambleCmds.caption = r"""% configure caption layout ## \usepackage{caption} -## \captionsetup{singlelinecheck=false}% no exceptions for one-lined captions""" +## \captionsetup{singlelinecheck=false}% no exceptions for one-liners""" -PreambleCmds.docinfo = r"""% width of docinfo table: +PreambleCmds.color = r"""\usepackage{color}""" + +PreambleCmds.docinfo = r""" +% docinfo (width of docinfo table) \DUprovidelength{\DUdocinfowidth}{0.9\textwidth}""" +# PreambleCmds.docinfo._requirements = 'providelength' PreambleCmds.embedded_package_wrapper = r"""\makeatletter %% embedded stylesheet: %s %s \makeatother""" -PreambleCmds.fieldlist = r"""% field list environment: +PreambleCmds.dedication = r""" +% dedication topic +\providecommand{\DUtopicdedication}[1]{\begin{center}#1\end{center}}""" + +PreambleCmds.error = r""" +% error admonition title +\providecommand*{\DUtitleerror}[1]{\DUtitle{\color{red}#1}}""" +# PreambleCmds.errortitle._requirements = 'color' + +PreambleCmds.fieldlist = r""" +% fieldlist environment \ifthenelse{\isundefined{\DUfieldlist}}{ \newenvironment{DUfieldlist}% {\quote\description} @@ -370,24 +394,29 @@ \fi'))""" -PreambleCmds.inline = r"""% custom roles: -% \DUrole{NAME} calls \docutilsroleNAME if it exists +PreambleCmds.inline = r""" +% inline markup (custom roles) +% \DUrole{#1}{#2} tries \DUrole#1{#2} \providecommand*{\DUrole}[2]{% - \ifcsname docutilsrole#1\endcsname% - \csname docutilsrole#1\endcsname{#2}% - \else% - #2% + \ifcsname DUrole#1\endcsname% + \csname DUrole#1\endcsname{#2}% + \else% backwards compatibility: try \docutilsrole#1{#2} + \ifcsname docutilsrole#1\endcsname% + \csname docutilsrole#1\endcsname{#2}% + \else% + #2% + \fi% \fi% }""" -PreambleCmds.legend = r"""% legend environment: +PreambleCmds.legend = r""" +% legend environment \ifthenelse{\isundefined{\DUlegend}}{ - \newenvironment{DUlegend}% - {\small} - {} + \newenvironment{DUlegend}{\small}{} }{}""" -PreambleCmds.lineblock = r"""% line block environment: +PreambleCmds.lineblock = r""" +% lineblock environment \DUprovidelength{\DUlineblockindent}{2.5em} \ifthenelse{\isundefined{\DUlineblock}}{ \newenvironment{DUlineblock}[1]{% @@ -401,8 +430,10 @@ } {\endlist} }{}""" +# PreambleCmds.lineblock._requirements = 'providelength' -PreambleCmds.linking = r"""%% hyperref (PDF hyperlinks): +PreambleCmds.linking = r""" +%% hyperref package (PDF hyperlinks): \ifthenelse{\isundefined{\hypersetup}}{ \usepackage[colorlinks=%s,linkcolor=%s,urlcolor=%s]{hyperref} }{}""" @@ -410,7 +441,8 @@ PreambleCmds.minitoc = r"""%% local table of contents \usepackage{minitoc}""" -PreambleCmds.optionlist = r"""% option list: +PreambleCmds.optionlist = r""" +% optionlist environment \providecommand*{\DUoptionlistlabel}[1]{\bf #1 \hfill} \DUprovidelength{\DUoptionlistindent}{3cm} \ifthenelse{\isundefined{\DUoptionlist}}{ @@ -424,53 +456,75 @@ } {\endlist} }{}""" +# PreambleCmds.optionlist._requirements = 'providelength' -PreambleCmds.providelength = r"""% provide a length variable and set it -\newcommand*{\DUprovidelength}[2]{ +PreambleCmds.providelength = r""" +% providelength (provide a length variable and set default, if it is new) +\providecommand*{\DUprovidelength}[2]{ \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{} }""" -PreambleCmds.rubric = r"""% rubric (an informal heading): -\providecommand*{\DUrubric}[1]{% - \subsection*{\centering\textit{\textmd{#1}}}% -}""" +PreambleCmds.rubric = r""" +% rubric (informal heading) +\providecommand*{\DUrubric}[2][class-arg]{% + \subsubsection*{\centering\textit{\textmd{#2}}}}""" -PreambleCmds.sidebar = r"""% sidebar (text outside the main text flow) -\providecommand{\DUsidebar}[1]{% +PreambleCmds.sidebar = r""" +% sidebar (text outside the main text flow) +\providecommand{\DUsidebar}[2][class-arg]{% \begin{center} - \fbox{\colorbox[gray]{0.80}{\parbox{0.9\textwidth}{#1}}} + \colorbox[gray]{0.80}{\parbox{0.9\textwidth}{#2}} \end{center} }""" -PreambleCmds.sidebartitle = r"""% sidebar title -\providecommand*{\DUsidebartitle}{\DUtopictitle}""" +PreambleCmds.subtitle = r""" +% subtitle (for topic/sidebar) +\providecommand*{\DUsubtitle}[2][class-arg]{\par\emph{#2}\smallskip}""" -PreambleCmds.sidebarsubtitle = r"""% sidebar sub-title -\providecommand*{\DUsidebarsubtitle}[1]{\hspace*{\fill}\\\emph{#1}\smallskip}""" - PreambleCmds.table = r"""\usepackage{longtable} \usepackage{array} \setlength{\extrarowheight}{2pt} \newlength{\DUtablewidth} % internal use in tables""" -PreambleCmds.title = r""" +PreambleCmds.documenttitle = r""" %%%%%% Title metadata \title{%s} \author{%s} \date{%s}""" -PreambleCmds.titlereference = r"""% title reference role: +PreambleCmds.titlereference = r""" +% titlereference role \providecommand*{\DUroletitlereference}[1]{\textsl{#1}}""" -PreambleCmds.topictitle = r"""% title for "topics" (admonitions, sidebar) -\providecommand*{\DUtopictitle}[1]{\textbf{#1}\smallskip}""" +PreambleCmds.title = r""" +% title for topics, admonitions and sidebar +\providecommand*{\DUtitle}[2][class-arg]{% + % call \DUtitle#1{#2} if it exists: + \ifcsname DUtitle#1\endcsname% + \csname DUtitle#1\endcsname{#2}% + \else + \smallskip\noindent\textbf{#2}\smallskip% + \fi +}""" -PreambleCmds.transition = r"""% transition ([fancy]break, anonymous section) -\providecommand*{\DUtransition}{% +PreambleCmds.topic = r""" +% topic (quote with heading) +\providecommand{\DUtopic}[2][class-arg]{% + \ifcsname DUtopic#1\endcsname% + \csname DUtopic#1\endcsname{#2}% + \else + \begin{quote}#2\end{quote} + \fi +}""" + +PreambleCmds.transition = r""" +% transition (break, fancybreak, anonymous section) +\providecommand*{\DUtransition}[1][class-arg]{% \hspace*{\fill}\hrulefill\hspace*{\fill} \vskip 0.5\baselineskip }""" + class DocumentClass(object): """Details of a LaTeX document class.""" @@ -1166,20 +1220,23 @@ def depart_address(self, node): self.depart_docinfo_item(node) - def visit_admonition(self, node, name=''): + def visit_admonition(self, node): self.fallbacks['admonition'] = PreambleCmds.admonition - self.fallbacks['topictitle'] = PreambleCmds.topictitle - self.body.append('\n\\DUadmonition{') - if name: - self.body.append('\\DUtopictitle{%s}\n' % - self.language.labels.get(name, name)); - ## self.body.append('\\vspace{2mm}\n') + if node.tagname is 'admonition': + classes = ','.join(node['classes']) + title = '' + else: # specific admonitions + self.fallbacks['title'] = PreambleCmds.title + classes = node.tagname.replace('_', '-') + title = '\\DUtitle[%s]{%s}\n' % ( + classes, self.language.labels.get(classes, classes)) + self.body.append('\n\\DUadmonition[%s]{\n%s' % (classes, title)) def depart_admonition(self, node=None): self.body.append('}\n') def visit_attention(self, node): - self.visit_admonition(node, 'attention') + self.visit_admonition(node) def depart_attention(self, node): self.depart_admonition() @@ -1204,13 +1261,13 @@ self.body.append( '\n\\end{quote}\n') def visit_bullet_list(self, node): - if 'contents' in self.topic_classes: + if self.is_toc_list: self.body.append( '%\n\\begin{list}{}{}\n' ) else: self.body.append( '%\n\\begin{itemize}\n' ) def depart_bullet_list(self, node): - if 'contents' in self.topic_classes: + if self.is_toc_list: self.body.append( '\n\\end{list}\n' ) else: self.body.append( '\n\\end{itemize}\n' ) @@ -1242,7 +1299,7 @@ self.body.append('}\n') def visit_caution(self, node): - self.visit_admonition(node, 'caution') + self.visit_admonition(node) def depart_caution(self, node): self.depart_admonition() @@ -1358,7 +1415,7 @@ self.depart_docinfo_item(node) def visit_danger(self, node): - self.visit_admonition(node, 'danger') + self.visit_admonition(node) def depart_danger(self, node): self.depart_admonition() @@ -1402,7 +1459,7 @@ def visit_docinfo(self, node): # tabularx: automatic width of columns, no page breaks allowed. self.requirements['tabularx'] = r'\usepackage{tabularx}' - self.requirements['~providelength'] = PreambleCmds.providelength + self.fallbacks['_providelength'] = PreambleCmds.providelength self.fallbacks['docinfo'] = PreambleCmds.docinfo self.docinfo = ['%' + '_'*75 + '\n', '\\begin{center}\n', @@ -1498,7 +1555,7 @@ # To deactivate it, self.astext() adds \title{...}, \author{...}, # \date{...}, even if the"..." are empty strings. if '\\maketitle\n\n' in self.body_prefix: - title = [PreambleCmds.title % ( + title = [PreambleCmds.documenttitle % ( '%\n '.join(self.title), ' \\and\n'.join(['\\\\\n'.join(author_lines) for author_lines in self.author_stack]), @@ -1667,7 +1724,8 @@ self._enumeration_counters.pop() def visit_error(self, node): - self.visit_admonition(node, 'error') + self.fallbacks['error'] = PreambleCmds.error + self.visit_admonition(node) def depart_error(self, node): self.depart_admonition() @@ -1836,7 +1894,7 @@ del self.body[start:] def visit_hint(self, node): - self.visit_admonition(node, 'hint') + self.visit_admonition(node) def depart_hint(self, node): self.depart_admonition() @@ -1920,7 +1978,7 @@ pass def visit_important(self, node): - self.visit_admonition(node, 'important') + self.visit_admonition(node) def depart_important(self, node): self.depart_admonition() @@ -1947,7 +2005,7 @@ self.body.append('\n') def visit_line_block(self, node): - self.requirements['~providelength'] = PreambleCmds.providelength + self.fallbacks['_providelength'] = PreambleCmds.providelength self.fallbacks['lineblock'] = PreambleCmds.lineblock if isinstance(node.parent, nodes.line_block): self.body.append('\\item[]\n' @@ -2051,7 +2109,7 @@ ## self.body.append('[depart_meta]\n') def visit_note(self, node): - self.visit_admonition(node, 'note') + self.visit_admonition(node) def depart_note(self, node): self.depart_admonition() @@ -2082,7 +2140,7 @@ self.body.append('] ') def visit_option_list(self, node): - self.requirements['~providelength'] = PreambleCmds.providelength + self.fallbacks['_providelength'] = PreambleCmds.providelength self.fallbacks['optionlist'] = PreambleCmds.optionlist self.body.append('%\n\\begin{DUoptionlist}\n') @@ -2189,8 +2247,7 @@ self.section_level -= 1 def visit_sidebar(self, node): - # fallback definition requires the color package for background colour - self.requirements['color'] = r'\usepackage{color}' + self.requirements['color'] = PreambleCmds.color self.fallbacks['sidebar'] = PreambleCmds.sidebar self.body.append('\n\\DUsidebar{\n') @@ -2237,47 +2294,44 @@ self.unimplemented_visit(node) def visit_subtitle(self, node): - if isinstance(node.parent, nodes.sidebar): - self.fallbacks['sidebarsubtitle'] = PreambleCmds.sidebarsubtitle - self.body.append('\\DUsidebarsubtitle{') - self.context.append('}\n') - elif isinstance(node.parent, nodes.document): + if isinstance(node.parent, nodes.document): self.title.append(r'\\ % subtitle') self.title.append(r'\large{%s}' % self.encode(node.astext())) self.title += self.labels(node, set_anchor=False) raise nodes.SkipNode + # Section subtitle -> always "starred": no number, not in ToC elif isinstance(node.parent, nodes.section): - # Section subtitle: - self.body.append('\\textbf{') - self.context.append('}\\vspace{0.2cm}\n\n\\noindent ') + self.body.append(r'\%s*{' % + self.d_class.section(self.section_level + 1)) + else: + self.fallbacks['subtitle'] = PreambleCmds.subtitle + self.body.append('\n\\DUsubtitle[%s]{' % node.parent.tagname) def depart_subtitle(self, node): - self.body.append(self.context.pop()) + self.body.append('}\n') def visit_system_message(self, node): - self.requirements['color'] = r'\usepackage{color}' - self.visit_admonition(node) - self.body.append('\\DUtopictitle{System Message:}\n') + self.requirements['color'] = PreambleCmds.color + self.fallbacks['error'] = PreambleCmds.error + self.visit_admonition(node) # error or warning self.append_hypertargets(node) try: line = ', line~%s' % node['line'] except KeyError: line = '' - self.body.append('\n%s/%s in %s%s\n' % (node['type'], - node['level'], - self.encode(node['source']), - line)) - ## self.body.append(r'\color{red}\\') + self.body.append('\n\n{\color{red}%s/%s} in \\texttt{%s}%s\n' % + (node['type'], node['level'], + self.encode(node['source']), line)) if len(node['backrefs']) == 1: self.body.append('\n\\hyperlink{%s}{' % node['backrefs'][0]) + self.context.append('}') + else: + backrefs = ['\\hyperlink{%s}{%d}' % (href, i+1) + for (i, href) in enumerate(node['backrefs'])] + self.context.append('backrefs: ' + ' '.join(backrefs)) def depart_system_message(self, node): - if len(node['backrefs']) == 1: - self.body.append('}') - else: - self.body.append('backrefs: ') - self.body += ['\\hyperlink{%s}{%d}' % (href, i+1) - for (i,href) in enumerate(node['backrefs'])] + self.body.append(self.context.pop()) self.depart_admonition() def visit_table(self, node): @@ -2380,7 +2434,7 @@ self._thead_depth -= 1 def visit_tip(self, node): - self.visit_admonition(node, 'tip') + self.visit_admonition(node) def depart_tip(self, node): self.depart_admonition() @@ -2400,107 +2454,72 @@ def visit_title(self, node): """Append section and other titles.""" - # Topic titles - if isinstance(node.parent, nodes.topic): - # Table of contents - if 'contents' in self.topic_classes: - if self.settings.use_titlepage_env: - self.body.append('\\end{titlepage}\n') - if self.use_latex_toc: - tocdepth = node.parent.get('depth', 0) - if tocdepth: - self.body.append('\n\\setcounter{tocdepth}{%d}' % - tocdepth) - # use the Docutils-provided title for the ToC - self.body.append('\n\\renewcommand{\\contentsname}{') - self.context.append('}\n\\tableofcontents\n\n') - self.has_latex_toc = True - else: - # In LaTeX, alignment of sections is determined by the - # document class. Use \hfill as a workaround. - self.body.append('\\subsubsection*{~\\hfill ') - self.context.append('\\hfill ~%s}\n' % self.bookmark(node)) - else: # other topic titles - # TODO: use DUtopictitle: - # self.body.append('\n\\DUtopictitle{') - # self.context.append('}\n') - self.body.append('\n\\subsubsection*{~\\hfill ') - self.context.append('\\hfill ~}\n') - # Admonition titles (render as topic title) - elif isinstance(node.parent, nodes.admonition): - self.fallbacks['topictitle'] = PreambleCmds.topictitle - self.body.append('\\DUtopictitle{') - self.context.append('}\n') - elif isinstance(node.parent, nodes.sidebar): - self.fallbacks['sidebartitle'] = PreambleCmds.sidebartitle - self.body.append('\\DUsidebartitle{') - self.context.append('}\n') - # Table - elif isinstance(node.parent, nodes.table): - # caption must be written after column spec - self.active_table.caption = self.encode(node.astext()) - raise nodes.SkipNode # Document title - elif self.section_level == 0: + if node.parent.tagname == 'document': self.title.insert(0, self.encode(node.astext())) if not self.pdfinfo == None: self.pdfinfo.append(' pdftitle={%s},' % self.encode(node.astext()) ) raise nodes.SkipNode + # Topic titles (topic, admonition, sidebar) + elif (isinstance(node.parent, nodes.topic) or + isinstance(node.parent, nodes.admonition) or + isinstance(node.parent, nodes.sidebar)): + self.fallbacks['title'] = PreambleCmds.title + classes = ','.join(node.parent['classes']) + if not classes: + classes = node.tagname + self.body.append('\\DUtitle[%s]{' % classes) + self.context.append('}\n') + # Table caption + elif isinstance(node.parent, nodes.table): + # caption must be written after column spec + self.active_table.caption = self.encode(node.astext()) + raise nodes.SkipNode # Section title else: self.body.append('\n\n') self.body.append('%' + '_' * 75) self.body.append('\n\n') - + # section_name = self.d_class.section(self.section_level) # number sections? - section_star = '' # LaTeX numbered sections - if (# numbering by Docutils or unsupported level: - self.settings.sectnum_xform or - (self.section_level > len(self.d_class.sections))): + if (self.settings.sectnum_xform # numbering by Docutils + or (self.section_level > len(self.d_class.sections))): section_star = '*' + else: # LaTeX numbered sections + section_star = '' self.body.append(r'\%s%s{' % (section_name, section_star)) - # System messages heading in red: if ('system-messages' in node.parent['classes']): - self.requirements['color'] = r'\usepackage{color}' + self.requirements['color'] = PreambleCmds.color self.body.append('\color{red}') - + # label and ToC entry: self.context.append(self.bookmark(node) + '}\n') # MAYBE postfix paragraph and subparagraph with \leavemode to # ensure floats stay in the section and text starts on a new line. def depart_title(self, node): self.body.append(self.context.pop()) - # too many newlines before paragraphs: - ## self.body.append('\n') - def minitoc(self, node): + def minitoc(self, title, depth): """Generate a local table of contents with LaTeX package minitoc""" - # title - if isinstance(node.next_node(), nodes.title): - toctitle = self.encode(node.pop(0).astext()) - else: # no title - toctitle = '' + section_name = self.d_class.section(self.section_level) # name-prefix for current section level - section_name = self.d_class.section(self.section_level) - if section_name == 'part': - minitoc_name = 'part' - elif section_name == 'chapter': - minitoc_name = 'mini' - elif (section_name == 'section' and - 'chapter' not in self.d_class.sections): - minitoc_name = 'sect' - else: # minitoc only supports local toc in part- or top-level + minitoc_names = {'part': 'part', 'chapter': 'mini'} + if 'chapter' not in self.d_class.sections: + minitoc_names['section'] = 'sect' + try: + minitoc_name = minitoc_names[section_name] + except KeyError: # minitoc only supports part- and toplevel warn = self.document.reporter.warning warn('Skipping local ToC at %s level.\n' % section_name + ' Feature not supported with option "use-latex-toc"') return # Requirements/Setup self.requirements['minitoc'] = PreambleCmds.minitoc - self.requirements['minitoc-%s' % - minitoc_name] = r'\do%stoc' % minitoc_name + self.requirements['minitoc-'+minitoc_name] = (r'\do%stoc' % + minitoc_name) # depth: (Docutils defaults to unlimited depth) maxdepth = len(self.d_class.sections) self.requirements['minitoc-%s-depth' % minitoc_name] = ( @@ -2510,34 +2529,68 @@ offset = {'sect': 1, 'mini': 0, 'part': 0} if 'chapter' in self.d_class.sections: offset['part'] = -1 - depth = node.get('depth', 0) if depth: self.body.append('\\setcounter{%stocdepth}{%d}' % (minitoc_name, depth + offset[minitoc_name])) # title: - self.body.append('\\mtcsettitle{%stoc}{%s}\n' % - (minitoc_name, toctitle)) + self.body.append('\\mtcsettitle{%stoc}{%s}\n' % (minitoc_name, title)) # the toc-generating command: self.body.append('\\%stoc\n' % minitoc_name) def visit_topic(self, node): - self.topic_classes = node['classes'] - if ('contents' in node['classes'] and 'local' in node['classes']): + # Topic nodes can be generic topic, abstract, dedication, or ToC + # table of contents: + if 'contents' in node['classes']: + self.body.append('\n') + self.body += self.labels(node) + if self.settings.use_titlepage_env: + # TODO: move this to a save place + # (what if the contents are at the end of the document?) + self.body.append('\\end{titlepage}\n') + # add contents to PDF bookmarks sidebar + if isinstance(node.next_node(), nodes.title): + self.body.append('\n\\pdfbookmark[%d]{%s}{%s}\n' % + (self.section_level+1, + node.next_node().astext(), + node.get('ids', ['contents'])[0] + )) if self.use_latex_toc: - self.minitoc(node) - elif not isinstance(node.next_node(), nodes.title): - self.body += self.labels(node) - elif ('abstract' in self.topic_classes and - self.settings.use_latex_abstract): + title = '' + if isinstance(node.next_node(), nodes.title): + title = self.encode(node.pop(0).astext()) + depth = node.get('depth', 0) + if 'local' in node['classes']: + self.minitoc(title, depth) + self.context.append('') + return + if depth: + self.body.append('\\setcounter{tocdepth}{%d}\n' % depth) + if title != 'Contents': + self.body.append('\\renewcommand{\\contentsname}{%s}\n' + % title) + self.body.append('\\tableofcontents\n\n') + self.has_latex_toc = True + else: # Docutils generated contents list + # set flag for visit_bullet_list() and visit_title() + self.is_toc_list = True + self.context.append('') + elif ('abstract' in node['classes'] and + self.settings.use_latex_abstract): self.body.append('\\begin{abstract}') - if isinstance(node.next_node(), nodes.title): - node.pop(0) # dump title + self.context.append('\\end{abstract}\n') + else: + self.fallbacks['topic'] = PreambleCmds.topic + # special topics: + if 'abstract' in node['classes']: + self.fallbacks['abstract'] = PreambleCmds.abstract + if 'dedication' in node['classes']: + self.fallbacks['dedication'] = PreambleCmds.dedication + self.body.append('\n\\DUtopic[%s]{\n' % ','.join(node['classes'])) + self.context.append('}\n') def depart_topic(self, node): - if ('abstract' in self.topic_classes and - self.settings.use_latex_abstract): - self.body.append('\\end{abstract}\n') - self.topic_classes = [] + self.body.append(self.context.pop()) + self.is_toc_list = False def visit_inline(self, node): # <span>, i.e. custom roles # insert fallback definition @@ -2573,7 +2626,7 @@ self.depart_docinfo_item(node) def visit_warning(self, node): - self.visit_admonition(node, 'warning') + self.visit_admonition(node) def depart_warning(self, node): self.depart_admonition() Modified: trunk/docutils/docutils/writers/latex2e/docutils-05-compat.sty =================================================================== --- trunk/docutils/docutils/writers/latex2e/docutils-05-compat.sty 2009-08-20 09:58:30 UTC (rev 6093) +++ trunk/docutils/docutils/writers/latex2e/docutils-05-compat.sty 2009-08-22 21:50:35 UTC (rev 6094) @@ -263,8 +263,8 @@ % `custom roles`_ like ``.. role:: sub(subscript)`` and % ``.. role:: super(superscript)`` and define the "role commands":: - \newcommand{\docutilsrolesub}{\itshape} - \newcommand{\docutilsrolesuper}{\itshape} + \newcommand{\DUrolesub}{\itshape} + \newcommand{\DUrolesuper}{\itshape} % Alternatively, if you want all sub- and superscripts in italic, redefine % the macros:: @@ -579,18 +579,16 @@ % 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}} -\newcommand{\DUrubric}[1]{\rubric{#1}} - % title reference role % ^^^^^^^^^^^^^^^^^^^^ % :: \newcommand{\titlereference}[1]{\textsl{#1}} - \newcommand{\DUroletitlereference}[1]{\titlereference{#1}} @@ -600,12 +598,12 @@ % New Feature: % Enable customization of some more Docutils elements with special commands % -% :admonition: ``DUadmonition`` environment (replacing ``\admonitionwidth``), +% :admonition: ``DUadmonition... [truncated message content] |