Menu
▾
▴
[Docutils-checkins] r5931 - in trunk/docutils: HISTORY.txt RELEASE-NOTES.txt docs/dev/todo.txt docs/user/docutils-05-compat.sty.txt docs/user/latex.txt docutils/writers/latex2e/__init__.py docutils/writers/latex2e/docutils-05-compat.sty test/functional/expected/latex_docinfo.tex test/functional/expected/multistyle_path_embed_rst_latex2e.tex test/functional/expected/multistyle_path_rst_latex2e.tex test/functional/expected/standalone_rst_latex.tex test/test_writers/test_latex2e.py
Author: milde
Date: 2009-04-29 21:28:06 +0200 (Wed, 29 Apr 2009)
New Revision: 5931
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: new custom macros
update relevant documentation (including spelling and whitespace fixes)
update tests
Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt 2009-04-29 13:13:07 UTC (rev 5930)
+++ trunk/docutils/HISTORY.txt 2009-04-29 19:28:06 UTC (rev 5931)
@@ -21,7 +21,7 @@
- Docutils is now compatible with Python versions from 2.3 up to 3.0 (or
even 3.1?)
-
+
+ Node.__nonzero__ returns True instead of 1.
+ use os.walk instead os.path.walk.
+ minimize "types" module where possible.
@@ -29,10 +29,10 @@
+ Text nodes now subclass unicode rather than UserString
(which is gone in python 3.0)
+ 3.0 compatibility module docutils._compat
-
+
+ drop 2.2 compatibility workarounds
-
- - Apply [ 1719345 ] Galician translation
+
+ - Apply [ 1719345 ] Galician translation
- Apply [ 1905741 ] polish-translation
- Apply [ 1878977 ] make_id(): deaccent characters.
@@ -47,7 +47,7 @@
" " (non-breaking space), and "¡ ¿" openers.
* docutils/utils.py:
-
+
- Added ``get_stylesheet_list`` function.
* docutils/writers/html4css1/__init__.py:
@@ -72,8 +72,6 @@
- Failsave implementation of custom roles. LaTeX compilation now ignores
unknown classes instead of aborting with an error.
- Support custom roles based on standard roles.
- - Smaller document preamble: use fallback definitions, include only if
- needed in the document.
- LaTeX packages can be used as ``--stylesheet`` arguments without
restriction. (A style sheet is now referenced with the ``\usepackage``
command, if it ends with ``.sty`` or has no extension.)
@@ -86,6 +84,8 @@
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.
* docs/ref/rst/restructuredtext.txt:
@@ -99,7 +99,7 @@
* docutils/languages/he.py: Added to project: Hebrew mappings by
Meir Kriheli.
-* docutils/parsers/rst/languages/he.py: Added to project: Hebrew
+* docutils/parsers/rst/languages/he.py: Added to project: Hebrew
mappings by Meir Kriheli.
* docutils/frontend.py:
@@ -218,7 +218,7 @@
- Put ensuremath around some latin1 chars.
- Set ``usepackage[utf8x]{inputenc}`` for utf-8.
- New option ``--use-bibtex=style,db1,db2``.
- - New option ``--reference-label`` to allow usage of LaTeX ref for
+ - New option ``--reference-label`` to allow usage of LaTeX ref for
labels in section references.
- Add a label after every section to support sectionnumbers as reference
labels.
@@ -226,7 +226,7 @@
- Remove inactive code for use_optionlist_for_option_list.
- Remove latex comments from option_list output.
- Fix: bug# 1612270 double qoutes in italian literal.
- - Fix: output ``hypertarget{ node.get(refid) }{}`` from visit_target.
+ - Fix: output ``hypertarget{ node.get(refid) }{}`` from visit_target.
- Add option --use-latex-abstract.
- Image width unit ``px`` is translated to ``pt``.
- Add image height support.
@@ -383,7 +383,7 @@
* docutils/parsers/rst/languages/ja.py: Added to project: Japanese
mappings by David Goodger.
-
+
* docutils/parsers/rst/languages/zh_cn.py: Added to project:
Simplified Chinese mappings by Panjunyong.
@@ -455,7 +455,7 @@
- Made ``xmlcharrefreplace`` the default output encoding error
handler.
-* docutils/writers/html4css1/:
+* docutils/writers/html4css1/:
- Added support for image width and height units.
- Made ``xmlcharrefreplace`` the default output encoding error
Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt 2009-04-29 13:13:07 UTC (rev 5930)
+++ trunk/docutils/RELEASE-NOTES.txt 2009-04-29 19:28:06 UTC (rev 5931)
@@ -39,6 +39,7 @@
- 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``
Release 0.5 (2008-06-25)
Modified: trunk/docutils/docs/dev/todo.txt
===================================================================
--- trunk/docutils/docs/dev/todo.txt 2009-04-29 13:13:07 UTC (rev 5930)
+++ trunk/docutils/docs/dev/todo.txt 2009-04-29 19:28:06 UTC (rev 5931)
@@ -1895,53 +1895,94 @@
.. _latex-variants:
http://docutils.sourceforge.net/sandbox/latex-variants/README.html
+Bug fixes
+---------
+
+* A multirow cell in a table expects empty cells in the spanned rows while
+ the doctree contains only the remaining cells ("Exchange Table Model", see
+ docs/ref/soextblx.dtd).
+
+ Needs bookkeeping of "open" multirow cells (how many how long) and
+ insertion of additional '&'s.
+
+ See `<../../test/functional/input/data/latex.txt>`__
+
+* Aligning a figure also aligns the legend *but not the caption* nor a table
+ in the legend.
+
+
Generate clean and configurable LaTeX source
----------------------------------------------
+* Check the generated source with package `nag`.
+
+* LaTeX code style (?)::
+
+ \item {} -> \item % as '[' is already escaped
+ \item[{Term}] -> \item[Term]
+ \item [what:] -> \item[what:]
+ {\macro} -> \macro{}
+ {\$} -> \$
+ {\&} -> \&
+ {\%} -> \%
+ {\#} -> \#
+
+
LaTeX macros for Docutils-specific objects
``````````````````````````````````````````
-:sidebar: ``DUsidebar`` environment
-:transition: ``\DUtransition`` command
-:admonition: ``DUadmonition`` environment
-:field list: ``DUfieldlist`` environment
-:legend: needed?
-:subtitle: is there a native construct?
+:legend: Conflict with flushright/flushleft for image alignment
+ ``! LaTeX Error: There's no line here to end.``
+ --> Re-try after fixing the alignment bug.
+:subtitle: Is there a native construct?
+
+:admonitions: Provide separate commands for specific admonitions (error,
+ note, ...)?
+
LaTeX constructs and packages in stead of re-implementations
````````````````````````````````````````````````````````````
-* ``alltt`` environment for literal block
+Which packages do we want to use?
-* find out and use the correct width parameter
- instead of the ``\locallinewidth`` workaround.
+a) only base packages:
+ * conservative, always present, few dependencies
+ * needs workarounds/hacks (reinventing the wheel) for advanced features
- * linewidth - width of a line in the local environment
- * textwidth - the width of text on the page
+b) base and "recommended" packages
- Maybe always use linewidth ?
+ (packages that should be in a "reasonably sized and reasonably modern
+ LaTeX installation like the `texlive-latex-recommended` Debian package,
+ say):
- *Bug* inside a minipage a (e.g. Sidebar) the linewidth is
- not changed, needs fix in docutils so that tables
- are not too wide.
+ * no "fancy" or "exotic" dependencies
+ * some workarounds still required for newer packages
- So we add ``\locallinewidth`` set it initially and
- on entering sidebar and reset on exit.
+c) state-of-the-art packages (recommendations from comp.text.tex)
+ * high dependencies, some packages might not be available in older
+ distributions
+ * cleanest possible LaTeX code, stable solution, no re-inventing of wheels.
+
+* ``alltt`` environment for literal block
+
+* Sub- and superscript with ``\textsubscript`` (needs
+ ``\usepackage{fixltx2e}``) and ``\textsuperscript``.
+
* footnotes
+ enable symbolic footnotes (parallel to numeric)
- + document customization (links to howto and packages)
+ + document customization (links to how-to and packages)
- + find out how to link and backlink to footnotes with hyperref
+ + find out how to link and back-link to footnotes with `hyperref`
- The hyperref manual says:
+ The `hyperref` manual says:
- :hyperfootnotes: Makes the footnote marks into hyperlinks to the
- footnote text. Easily broken ...
+ hyperfootnotes: Makes the footnote marks into hyperlinks to the
+ footnote text. Easily broken ...
- the hyperref README says:
+ the `hyperref` README says:
The footnote support is rather limited. It is beyond the scope to use
\footnotemark and \footnotetext out of order or reusing \footnotemark.
@@ -1959,9 +2000,10 @@
* enumeration environment, field list
- use mdwlist.sty from texlive-latex-recommended?
+ use `mdwlist` from texlive-latex-recommended?
-* ``--use-latex`` »super option« that would set the following::
+* ``--use-latex-when-possible`` »super option« that would set the
+ following::
--use-latex-toc
--use-latex-docinfo
@@ -1969,44 +2011,98 @@
--use-latex-footnotes
--use-latex-citations
- .. proposed by Alan G Isaac as ``--use-latex-when-possible``
+ ?
-* center subsection{Abstract} gives a LaTeX error here.
- ``! LaTeX Error: Something's wrong--perhaps a missing \item.``
- Committed a HACK: centering by hfill.
+.. center subsection{Abstract} gives a LaTeX error here.
+ ``! LaTeX Error: Something's wrong--perhaps a missing \item.``
+ Committed a HACK: centring by ``\hfill``.
Default layout
--------------
-* Use italic instead of slanted for titlereference?
+* Always include `fixltx2e`_ ("visible" LaTeX bugfixes, ``\textsubscript``)
-* Let meta insert comment into header instead of document?
+* Which `default font`__ should we use for the output?
-* Insert system messages? Where? As comment or visible?
+ Proposal: Use one of the Postscript default fonts supported by standard
+ LaTeX (pages 10 and 11 of the `PSNFSS documentation`_), e.g. Times or
+ Palatino.
+* 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)?
+ (Maybe continue if the `compound paragraph`_ directive is used?)
+
+* Indent/handle doctest blocks similar to literal blocks?
+
* Definitions in definition lists start on the same line as the term.
Putting ``\leavevmode`` after the term results in a new newline if the
definition starts with a bullet list or similar.
-* Sidebar handling?
+* Sidebar handling (environment with `framed`, `marginnote`, `wrapfig`,
+ ...)?
-* Use optionlist for docinfo, the table does only work for single page.
+* Use optionlist for docinfo? The table does only work for single page.
+* Recognize LaTeX and replace by ``\LaTeX`` (or not?).
+
+* Keep literal-blocks together on a page, avoid pagebreaks.
+
+ Failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before
+ the block.
+
+ Should be possible with ``--literal-block-env==lstlistings`` and some
+ configuration...
+
+
+__ ../../../sandbox/latex-variants/README.html#default-font
+
+.. _PSNFSS documentation:
+ http://dante.ctan.org/CTAN/macros/latex/required/psnfss/psnfss2e.pdf
+.. _compound paragraph:
+ ../ref/rst/directives.html#compound-paragraph
+.. _fixltx2e:
+ http://dante.ctan.org/CTAN/help/Catalogue/entries/fixltx2e.html
+
Tables
``````
* Improve/simplify logic to set the column width in the output.
-* Assumed reST linelength for table width setting configurable.
+ + Assumed reST line length for table width setting configurable.
+ + Maybe use `ltxtable` (a combination of `tabularx` (auto-width) and
+ `longtable` (page breaks))?
+ Use tabularx column type ``X`` and let LaTeX decide width?
+
+* csv-tables do not have a colwidth.
+
* Add more classes or options, e.g. for
+ column width set by latex,
- + horizontal aligment and rules.
+ + horizontal alignment and rules.
* Table heads and footer for longtable (firstpage lastpage ..)?
+* In tools.txt the option tables right column, there should be some more
+ spacing between the description and the next paragraph "Default:".
+* Paragraph separation in tables is hairy.
+ see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab
+
+ - The strut solution did not work.
+ - setting extrarowheight added ad top of row not between paragraphs in
+ a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
+ - baselineskip/stretch does not help.
+
+* Should there be two hlines after table head and on table end ?
+
+
Image and figure directives
```````````````````````````
@@ -2018,19 +2114,14 @@
+ `<../../test/functional/expected/standalone_rst_html4css1.html>`__
+ `<../../test/functional/expected/standalone_rst_latex.tex>`__
-* Should image start a new paragraph?
+* Should image start a new paragraph? (Keep support for inlined images with
+ substitutions!)
-* Centered and aligned images with ``\centerline``, ``\flushleft``,
+* Centred and aligned images with ``\centerline``, ``\flushleft``,
``\flushright`` instead of environments (avoids spurious whitespace).
-* Aligning a figure also aligns the legend *but not the caption*
-
- What should be aligned?
-
- Should the surrounding text wrap around the figure?
-
* Wrap text around figures with class "wrap".
- Use the "wrapfig" (or other recommended) package.
+ Use `wrapfig` (or other recommended) package.
Missing features
@@ -2042,23 +2133,44 @@
is inserted right at the end of the document. *This should be
customizable*.
-* Document errors are also too silent.
+* Document errors are also too silent. (Use admonition/error?)
No link to system errors.
- The intentional problematic error in docs/user/rst/demo.txt is not
- referring anywhere. (still true?)
-
* Meta keywords into PDF ?
+* Multiple author entries in docinfo (same thing as in html).
+ (already solved?)
+* LaTeX does not support multiple tocs in one document
+ (might be no limitation except for docutils documentation).
+
+ The "minitoc" latex package can produce per-chapter tocs in
+ book and report document classes.
+
+* Hyperlinks are not hyphenated; this leads to bad spacing. See
+ docs/user/rst/demo.txt 2.14 directives.
+
+ --> Pass the right option to ``\hypersetup``
+
template file
`````````````
+* Consider peter funk's hooks for TeXpert (or use a template file)?
+
+ * Define his own document preamble (including the choice to
+ choose his own documentclass. That would make the ``--documentclass``
+ option superfluous). I suggest to call this option ``--preamble``
+ * Use two additional hooks to put additional stuff just behind the
+ ``\begin{document}`` and just before the ``\end{document}`` macros.
+ Typical uses would be ``\tableofcontents``, ``\listoffigures`` and
+ ``\appendix``, ``\makeindex``, ``\makeglossary`` and some such
+ for larger documents.
+
Using a template file instead of hard-coded string literals for the
-sceleton of the exported LaTeX file would provide improved configurability.
+skeleton of the exported LaTeX file would provide improved configurability.
A power user could replace the template with a custom version,
-e.g. to overcome issues with order of package loading or supressing some
+e.g. to overcome issues with order of package loading or suppressing some
parts.
* Template Strings, ``from string import Template``, provide a suitable
@@ -2067,7 +2179,7 @@
For 2.3 compatibility, %-substitution is needed, which is less readable
(and LaTeX' comment sign '%' must be escaped).
- -> provide a 2.3 compatibility implememtation?
+ -> provide a 2.3 compatibility implementation?
Unicode to LaTeX with ``unicodesymbols`` file from LyX
``````````````````````````````````````````````````````
@@ -2077,8 +2189,24 @@
that lists LaTeX counterparts for a wide range of Unicode characters.
Use this in the LaTeXTranslator.unicode_to_latex() method.
+Think of copyright issues!
+Allow choice between utf8 (standard) and utf8x (extended) encodings
+```````````````````````````````````````````````````````````````````
+* Allow the user to select *utf8* or *utf8x* LaTeX encoding. (Docutil's
+ output encoding becomes LaTeX's input encoding.)
+
+The `ucs` package provides extended support for UTF-8 encoding in LaTeX
+via the `inputenc`-option ``utf8x``. It is, however, a non-standard
+extension and no longer developed.
+
+Ideas:
+ * Python has 4 names for the UTF-8 encoding (``utf_8, U8, UTF, utf8``)
+ give a special meaning to one of the aliases,
+
+ * scan "stylesheets" option and use ``utf8x`` if it contains ``ucs``
+
Front-End Tools
===============
Modified: trunk/docutils/docs/user/docutils-05-compat.sty.txt
===================================================================
--- trunk/docutils/docs/user/docutils-05-compat.sty.txt 2009-04-29 13:13:07 UTC (rev 5930)
+++ trunk/docutils/docs/user/docutils-05-compat.sty.txt 2009-04-29 19:28:06 UTC (rev 5931)
@@ -151,12 +151,12 @@
unless explicitely required via the ``--stylesheet`` option.
: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}``
Example:
@@ -290,10 +290,35 @@
\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
-```````````````````````````````````````````
+-------------------------------------------
+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
@@ -309,14 +334,12 @@
admonition width
^^^^^^^^^^^^^^^^
-::
+The ``admonitionwith`` lenght is replaced by the more powerful
+``\DUadmonition`` (see `New Definitions`_)::
\newlength{\admonitionwidth}
\setlength{\admonitionwidth}{0.9\textwidth}
- \newlength{\DUadmonitionwidth}
- \AtBeginDocument{\setlength{\DUadmonitionwidth}{\admonitionwidth}}
-
docinfo width
^^^^^^^^^^^^^
::
@@ -348,6 +371,14 @@
{\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
^^^^^^^^^^^^
::
@@ -384,24 +415,26 @@
\newcommand{\DUroletitlereference}[1]{\titlereference{#1}}
-Floats for footnotes settings
-`````````````````````````````
-Settings for the use of floats for footnotes are only included if
+New definitions
+```````````````
-* the option "use-latex-footnotes" is False, and
-* there is at least one footnote in the document.
+New Feature:
+ Enable customization of some more Docutils elements with special commands
-::
+ :sidebar: ``DUsidebar`` command (better environment?)
+ :transition: ``\DUtransition`` command
+ :admonition: ``DUadmonition`` environment (replacing ``\admonitionwidth``
+ :field list: ``DUfieldlist`` environment
- % 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
+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 the ``\admonitionwidth`` variable)::
+
+ \newcommand{\DUadmonition}[1]{%
+ \begin{center}
+ \fbox{\parbox{\admonitionwidth}{\sffamily #1}}
+ \end{center}
Modified: trunk/docutils/docs/user/latex.txt
===================================================================
--- trunk/docutils/docs/user/latex.txt 2009-04-29 13:13:07 UTC (rev 5930)
+++ trunk/docutils/docs/user/latex.txt 2009-04-29 19:28:06 UTC (rev 5931)
@@ -89,7 +89,7 @@
in a configuration file (see `Docutils Configuration`_ for details).
.. _Docutils Configuration:
- http://docutils.sourceforge.net/docs/user/config.html
+ ../user/config.html
Custom style sheets
@@ -196,7 +196,7 @@
\\end{center}
.. _raw directive:
- http://docutils.sourceforge.net/docs/ref/rst/directives.html#raw
+ ../ref/rst/directives.html#raw
Docutils special LaTeX macros
@@ -230,22 +230,22 @@
Admonitions__ are specially marked "topics" that can appear anywhere an
ordinary body element can.
-Default:
- typeset in a frame using a sans-serif font.
+Command:
+ ``\DUadmonition``
-Length:
- ``\DUadmonitionwidth``: the width of admonitions.
-
Default:
- 90 % of text width: ``0.9\textwidth``
+ Typeset in a frame (90 % of text width) using a sans-serif font.
Example:
- set to 70% of text width::
+ use standard document font and 95 % of text widht::
- \newlength{\DUadmonitionwidth}
- \setlength{\DUadmonitionwidth}{0.7\textwidth}
+ \newcommand{\DUadmonition}[1]{%
+ \begin{center}
+ \fbox{\parbox{0.95\textwidth}{#1}}
+ \end{center}
+ }
-__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions
+__ ../ref/rst/directives.html#admonitions
custom interpreted text roles
`````````````````````````````
@@ -280,49 +280,49 @@
Examples:
* Typeset text in small caps::
-
+
.. role:: smallcaps
-
+
:smallcaps:`Fourier` transformation
-
+
This is transformed to the LaTeX code::
-
+
\DUrole{smallcaps}{Fourier} transformation
-
+
The default definition of ``\DUrole`` will look for a macro named
``\docutilsrolesmallcaps``. The definition ::
-
+
\newcommand{\docutilsrolesmallcaps}{\textsc}
-
+
as `raw LaTeX`_ or in the custom style sheet will give the expected result
(if the chosen font supports small caps).
-
+
* Subscript text in normal size and *italic* shape::
-
+
.. role:: sub(subscript)
-
+
As "sub" inherits from the standard "subscript" role, the LaTeX macro
only needs to set the size and shape::
-
+
\newcommand{\docutilsrolesub}{\normalsize\itshape}
-
+
* A role with several classes and a converted class name::
-
+
.. role:: custom4
:class: argI argII arg_3
-
+
is translated to the nested commands::
-
+
\DUrole{argi}{\DUrole{argii}{\DUrole{arg-3}{<content>}}}
-
+
With the definitions::
-
+
\newcommand{\docutilsroleargi}[1]{\textsc}
\newcommand{\docutilsroleargii}[1]{{\large #1}}
\makeatletter
\@namedef{docutilsrolearg-3}{\textbf}
\makeatother
-
+
in a style sheet\ [#]_ or as `raw LaTeX`_ in the document source,
text styled with ``:custom4:`large bold small-caps``` will be typeset
accordingly.
@@ -331,13 +331,13 @@
sheet is a LaTeX package (``*.sty``).
.. _role directive:
- http://docutils.sourceforge.net/docs/ref/rst/directives.html#role
+ ../ref/rst/directives.html#role
.. _text roles:
- http://docutils.sourceforge.net/docs/ref/rst/roles.html
+ ../ref/rst/roles.html
.. _class directive:
- http://docutils.sourceforge.net/docs/ref/rst/directives.html#class
+ ../ref/rst/directives.html#class
definition lists
`````````````````
@@ -359,7 +359,7 @@
\renewcommand\descriptionlabel[1]{\hspace\labelsep \normalfont #1}
-__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists
+__ ../ref/rst/restructuredtext.html#definition-lists
document class
@@ -374,10 +374,10 @@
Standard document classes:
article, report, book
-
+
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
* memoir_
@@ -386,7 +386,7 @@
.. _CTAN: http://www.dante.de/ctan
.. _KOMA-script:
http://dante.ctan.org/CTAN/help/Catalogue/entries/koma-script.html
-.. _memoir:
+.. _memoir:
http://dante.ctan.org/CTAN/help/Catalogue/entries/memoir.html
.. _TeX Catalogue:
http://dante.ctan.org/CTAN/help/Catalogue/
@@ -418,9 +418,39 @@
\newlength{\DUdocinfowidth}
\setlength{\DUdocinfowidth}{0.7\textwidth}
-__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bibliographic-fields
+__ ../ref/rst/restructuredtext.html#bibliographic-fields
+field lists
+```````````
+
+`Field lists`__ may be used as generic two-column table constructs in
+documents.
+
+Environment:
+ ``DUfieldlist``
+
+Default:
+ Indented description list.
+
+Example:
+ Use a description list customized with enumitem_::
+
+ \usepackage{enumitem}
+ \newenvironment{DUfieldlist}%
+ {\description[font=,style=sameline,leftmargin=8em]}
+ {\enddescription}
+ }
+
+ The `KOMA-script`_ classes provide a similar environment under the name
+ `labeling`.
+
+.. _enumitem:
+ http://dante.ctan.org/CTAN/macros/latex/contrib/enumitem/enumitem.pdf
+
+__ ../ref/rst/restructuredtext.html#field-lists
+
+
font encoding
`````````````
@@ -429,19 +459,21 @@
--font-encoding=FONT_ENCODING
LaTeX font encoding. Possible values are "", "T1",
"OT1", "LGR,T1" or any other combination of options to
- the `fontenc`_ package. Default is "" which does not
- load `fontenc`.
+ the `fontenc`_ package.
+Default
+ 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`_::
--font-encoding=T1 --stylesheet=lmodern
-
+
* Support for characters in the Unicode blocks Latin, Latin-1 Supplement,
and Greek::
-
+
--font-encoding=LGR,T1
.. _fontenc:
@@ -474,7 +506,7 @@
If PDF-image inclusion in PDF files fails, specifying
``--graphicx-option=pdftex`` or ``--graphicx-option=auto`` might help.
-__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#images
+__ ../ref/rst/directives.html#images
line blocks
@@ -496,7 +528,7 @@
\newlength{\DUlineblockindent}
\setlength{\DUlineblockindent}{\parindent}
-__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#line-blocks
+__ ../ref/rst/restructuredtext.html#line-blocks
line spacing
````````````
@@ -563,7 +595,7 @@
basewidth={0.5em,0.4em}}
-__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-blocks
+__ ../ref/rst/restructuredtext.html#literal-blocks
.. _listings.pdf:
http://dante.ctan.org/CTAN/macros/latex/contrib/listings/listings.pdf
@@ -605,7 +637,7 @@
\newcommand{\DUoptionlistlabel}{\texttt{\textbf{#1}} \hfill}
-__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists
+__ ../ref/rst/restructuredtext.html#option-lists
page layout
```````````
@@ -616,20 +648,20 @@
document options_.
The ``DIV`` document option defines how "crowded" a page will be: larger
-values mean larger text area.
+values mean larger text area.
The typearea package even with option ``DIV=calc`` calculates a very
generous text area. Many conservative typographers will state that the
resulting line length is still excessive. The calculated DIV value may
be found in the log file for the respective document. Thus one can
select a smaller value easily after the first LaTeX run.
-
+
-- `KOMA-Script Guide`_
-Default:
+Default:
``DIV=12`` (resulting in good paper use at the expense of unreadable long
- lines).
-
+ lines).
+
The `typearea` default for A4 paper and 10 pt fonts is ``DIV=8``.
Examples:
@@ -740,7 +772,7 @@
\newcommand{\DUrubric}[1]{\subsection*{{\color{red}#1}\hfill~}}
-__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#rubric
+__ ../ref/rst/directives.html#rubric
title reference role
````````````````````
@@ -759,11 +791,11 @@
\newcommand{\DUroletitlereference}[1]{\texttt{\textbf{#1}}}
.. _title reference:
- http://docutils.sourceforge.net/docs/ref/rst/roles.html#title-reference
+ ../ref/rst/roles.html#title-reference
.. _default role:
- http://docutils.sourceforge.net/docs/ref/rst/directives.html#setting-the-default-interpreted-text-role
+ ../ref/rst/directives.html#setting-the-default-interpreted-text-role
.. _interpreted text:
- http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#interpreted-text
+ ../ref/rst/restructuredtext.html#interpreted-text
text font
@@ -783,10 +815,10 @@
a) specifying the corresponding LaTeX package as arguments to the
``--stylesheet`` option or in a custom style sheet.
-
+
* Packages can be combined.
* Passing options to a package is only possible in the style sheet.
-
+
b) changing the font-default macros.
@@ -927,7 +959,32 @@
The macro ``\@title`` contains the title.
+transition element
+``````````````````
+Transitions__ are commonly seen in novels and short fiction, as a gap
+spanning one or more lines, marking text divisions or signaling changes in
+subject, time, point of view, or emphasis.
+
+
+Command:
+ ``\DUtransition``
+
+Default:
+ A horizontal line, 1/3 of text width
+
+Examples:
+ Use three stars::
+
+ \newcommand*{\DUtransition}{\centering{}*\ \ \ *\ \ \ *}
+
+ If paragraphs are separated by indentation, you can simply use a vertical
+ space::
+
+ \newcommand*{\DUtransition}{\vspace{2ex}}
+
+__ http://docutils.sf.net/docutils/docs/ref/rst/restructuredtext.html#transitions
+
section numbering
`````````````````
@@ -958,6 +1015,42 @@
This enables to have the same section numbers as in other Docutils
writers and page numbers in the table of contents.
+sidebar element
+```````````````
+
+Sidebars__ are like miniature, parallel documents that occur inside other
+documents, providing related or reference material. They can be likened to
+super-footnotes; their content is outside of the flow of the document's main
+text.
+
+Command:
+ ``DUsidebar``
+
+Default:
+ Box (similar to admonition) with grey background.
+ Sans-serif fonts.
+
+Examples:
+ Use a lighter background and standard document fonts::
+
+ \newcommand{\DUsidebar}[1]{%
+ \begin{center}
+ \fbox{\colorbox[gray]{0.95}{\parbox{0.9\textwidth}{#1}}}
+ \end{center}
+ }
+
+ Use margin notes with package marginnote_::
+
+ \usepackage{marginnote}
+ \newcommand{\DUsidebar}{\marginnote}
+
+ * Make sure the margin is wide enought to hold the note.
+ * This might fail with some constructs inside the `side bar`.
+
+__ http://docutils.sf.net/docutils/docs/ref/rst/directives.html#sidebar
+.. _marginnote:
+ http://dante.ctan.org/CTAN/macros/latex/contrib/marginnote/marginnote.pdf
+
size of a pixel (length unit ``px``)
````````````````````````````````````
@@ -1016,32 +1109,29 @@
proposals in the `latex-variants`_ sandbox project.
.. _Docutils TODO list:
- http://docutils.sourceforge.net/docs/dev/todo.html#latex-writer
+ ../dev/todo.html#latex-writer
.. _latex-variants:
../../../sandbox/latex-variants/README.html
-
-Lists
------
-
-Definitions in definition lists start on the same line as the term. Putting
-``\leavevmode`` after the term results in a new newline if the definition
-starts with a bullet list or similar.
-
Footnotes and citations
-----------------------
-Initially both were implemented using figures, because hyperlinking back
-and forth seemed to be impossible. Later images were put into figures.
+Initially both were implemented using figure floats, because hyperlinking
+back and forth seemed to be impossible. Later the `figure` directive was
+added that puts images into figure floats.
-This results in footnotes images and figures possibly being mixed at page
-foot.
+This results in footnotes, citations, and figures possibly being mixed at
+page foot.
-* Use LaTeX footnotes and citations for printing or more complex layout.
-* Footnotes and citations done with figures might excell in hyperlink
- support.
+Workaround:
+ Select footnote and citation handling with the ``use-latex-footnotes`` and
+ ``use-latex-citations`` options.
-If ``use-latex-citations`` is used a bibliography is inserted right at
+ * Use LaTeX footnotes and citations for printing or more complex layout.
+ * Footnotes and citations done with figures might excell in hyperlink
+ support.
+
+If ``use-latex-citations`` is used, a bibliography is inserted right at
the end of the document. *This should be customizable*.
If ``use-latex-citations`` is used adjacent citation references (separated
@@ -1058,28 +1148,12 @@
Table width is tried to fit in page even if it is wider than
the assumed linewidth, still assumed linewidth is a hook.
-* In tools.txt the option tables right column, there should be some more
- spacing between the description and the next paragraph "Default:".
+* Table: multicol cells are always left aligned.
-* Paragraph separation in tables is hairy.
- see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=struttab
-
- - The strut solution did not work.
- - setting extrarowheight added ad top of row not between paragraphs in
- a cell. ALTHOUGH i set it to 2pt because, text is too close to the topline.
- - baselineskip/stretch does not help.
-
-* Should there be two hlines after table head and on table end ?
-
-* Table: multicol cells are always {l}.
-
* The contents of a rowspan cell do not influence table height.
(multirow "feature", use a phantom or strut?)
-* The frame around a multirow cell in the last column is incomplete
- (see functional test output standalone_rst_latex.tex).
- Actually, the writer inserts too many && in lines following the rowspan
- (see `<../../../sandbox/latex-variants/tests/table-with-spans.txt>`__).
+* Multirow cells might mix up the following table rows (BUG__).
* Table cells with both multirow and multicolumn are currently not possible.
@@ -1091,14 +1165,13 @@
- Ragged right fails on followup paragraphs as the vertical space would be
missing.
-* Use tabularx column type ``X`` and let LaTeX decide width.
-
-* csv-tables do not have a colwidth.
-
* ``--table-style=booktabs``, ``..class:: booktab``: `booktabs` version
1.00 does not work with `longtable`. This is solved in newer versions
(current is 2005/04/14 v1.61803).
+__ ../dev/todo.html#bug-fixes
+
+
Figures
-------
Wrapping text around figures is currently not supported.
@@ -1114,50 +1187,24 @@
What is wrong with ``--documentoptions=12`` or so,
maybe combined with extsize or some other package? [GM]
-* recognize LaTeX and replace by ``\LaTeX`` (or not?).
+ TODO: test and document
* Pdfbookmark level 4 (and greater) does not work (might be settable but
complicated).
-* Consider peter funk's hooks for TeXpert (or use a `template file`__)?
-
- * Define his own document preamble (including the choice to
- choose his own documentclass. That would make the ``--documentclass``
- option superfluous). I suggest to call this option ``--preamble``
- * Use two additional hooks to put additional stuff just behind the
- ``\begin{document}`` and just before the ``\end{document}`` macros.
- Typical uses would be ``\tableofcontents``, ``\listoffigures`` and
- ``\appendix``, ``\makeindex``, ``\makeglossary`` and some such
- for larger documents.
-
* Footnotes are not all on the same page (as in
docs/user/rst/demo.txt) and do not link back and forth.
* 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.
* For additional docinfo items: the field_body is inserted as text, i.e. no
markup is done.
-* Multiple author entries in docinfo (same thing as in html).
- (already solved?)
+* LaTeX does not support multiple tocs in one document
+ (might be no limitation except for docutils documentation).
-* Keep literal-blocks together on a page, avoid pagebreaks.
-
- Failed experiments up to now: samepage, minipage, pagebreak 1 to 4 before
- the block.
-
- Should be possible with ``--literal-block-env==lstlistings``.
-
-* Enable the choice between ``utf8`` (standard `fontenc`) and ``utf8x``
- (`ucs`) text encoding.
-
-* LaTeX does not support multiple tocs in one document.
- (might be no limitation except for docutils documentation)
-
- However, the "minitoc" latex package can produce per-chapter tocs in
+ The "minitoc" latex package can produce per-chapter tocs in
book and report document classes.
-
-__ http://docutils.sourceforge.net/docs/dev/todo.html#template-file
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2009-04-29 13:13:07 UTC (rev 5930)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2009-04-29 19:28:06 UTC (rev 5931)
@@ -1,4 +1,4 @@
-i# $Id$
+# $Id$
# Author: Engelbert Gruber <gr...@us...>
# Copyright: This module has been placed in the public domain.
@@ -324,23 +324,28 @@
class PreambleCmds(object):
"""Building blocks for the latex preamble."""
-PreambleCmds.admonition = r"""% width of admonitions:
-\ifthenelse{\isundefined{\DUadmonitionwidth}}{
- \newlength{\DUadmonitionwidth}
- \setlength{\DUadmonitionwidth}{0.9\textwidth}
-}{}"""
+PreambleCmds.admonition = r"""% admonitions (specially marked "topics")
+\providecommand{\DUadmonition}[1]{%
+ \begin{center}
+ \fbox{\parbox{0.9\textwidth}{\sffamily #1}}
+ \end{center}
+}"""
PreambleCmds.docinfo = r"""% width of docinfo table:
-\ifthenelse{\isundefined{\DUdocinfowidth}}{
- \newlength{\DUdocinfowidth}
- \setlength{\DUdocinfowidth}{0.9\textwidth}
-}{}"""
+\DUprovidelength{\DUdocinfowidth}{0.9\textwidth}"""
PreambleCmds.embedded_package_wrapper = r"""\makeatletter
%% embedded stylesheet: %s
%s
\makeatother"""
+PreambleCmds.fieldlist = r"""% field list environment:
+\ifthenelse{\isundefined{\DUfieldlist}}{
+ \newenvironment{DUfieldlist}%
+ {\quote\description}
+ {\enddescription\endquote}
+}{}"""
+
PreambleCmds.footnote_floats = r"""% settings for footnotes as floats:
\setlength{\floatsep}{0.5em}
\setlength{\textfloatsep}{\fill}
@@ -353,8 +358,8 @@
\setcounter{bottomnumber}{50}"""
PreambleCmds.inline = r"""% custom roles:
-% \DUrole{NAME}{content} calls \docutilsroleNAME if it exists
-\providecommand{\DUrole}[2]{%
+% \DUrole{NAME} calls \docutilsroleNAME if it exists
+\providecommand*{\DUrole}[2]{%
\ifcsname docutilsrole#1\endcsname%
\csname docutilsrole#1\endcsname{#2}%
\else%
@@ -362,20 +367,22 @@
\fi%
}"""
-PreambleCmds.lineblock = r"""% lineblock environment:
-\ifthenelse{\isundefined{\DUlineblockindent}}{
- \newlength{\DUlineblockindent}
- \setlength{\DUlineblockindent}{2.5em}
-}{}
+PreambleCmds.legend = r"""% legend (extending a caption):
+\providecommand{\DUlegend}[1]{{\\small #1}}"""
+
+PreambleCmds.lineblock = r"""% line block environment:
+\DUprovidelength{\DUlineblockindent}{2.5em}
\ifthenelse{\isundefined{\DUlineblock}}{
- \newenvironment{DUlineblock}[1]
- {\begin{list}{}
- {\setlength{\partopsep}{\parskip}
- \addtolength{\partopsep}{\baselineskip}
- \topsep0pt\itemsep0.15\baselineskip\parsep0pt
- \leftmargin#1}
- \raggedright}
- {\end{list}}
+ \newenvironment{DUlineblock}[1]{%
+ \list{}{\setlength{\partopsep}{\parskip}
+ \addtolength{\partopsep}{\baselineskip}
+ \setlength{\topsep}{0pt}
+ \setlength{\itemsep}{0.15\baselineskip}
+ \setlength{\parsep}{0pt}
+ \setlength{\leftmargin}{#1}}
+ \raggedright
+ }
+ {\endlist}
}{}"""
PreambleCmds.linking = r"""%% hyperref (PDF hyperlinks):
@@ -384,36 +391,40 @@
}{}"""
PreambleCmds.optionlist = r"""% option list:
-\providecommand{\DUoptionlistlabel}[1]{\bf #1 \hfill}
-\ifthenelse{\isundefined{\DUoptionlistindent}}{
- \newlength{\DUoptionlistindent}
- \setlength{\DUoptionlistindent}{3cm}
-}{}
+\providecommand*{\DUoptionlistlabel}[1]{\bf #1 \hfill}
+\DUprovidelength{\DUoptionlistindent}{3cm}
\ifthenelse{\isundefined{\DUoptionlist}}{
- \newenvironment{DUoptionlist}
- {\begin{list}{}
- {\setlength{\labelwidth}{\DUoptionlistindent}
- \setlength{\rightmargin}{1cm}
- \setlength{\leftmargin}{\rightmargin}
- \addtolength{\leftmargin}{\labelwidth}
- \addtolength{\leftmargin}{\labelsep}
- \renewcommand{\makelabel}{\DUoptionlistlabel}}
+ \newenvironment{DUoptionlist}{%
+ \list{}{\setlength{\labelwidth}{\DUoptionlistindent}
+ \setlength{\rightmargin}{1cm}
+ \setlength{\leftmargin}{\rightmargin}
+ \addtolength{\leftmargin}{\labelwidth}
+ \addtolength{\leftmargin}{\labelsep}
+ \renewcommand{\makelabel}{\DUoptionlistlabel}}
}
- {\end{list}}
+ {\endlist}
}{}"""
+PreambleCmds.providelenght = r"""% provide a length variable and set it
+\newcommand*{\DUprovidelength}[2]{
+ \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{}
+}"""
+
PreambleCmds.rubric = r"""% rubric (an informal heading):
-\newcommand{\DUrubric}[1]{\subsection*{~\hfill {\it #1} \hfill ~}}"""
+\providecommand*{\DUrubric}[1]{\subsection*{~\hfill {\it #1} \hfill ~}}"""
-PreambleCmds.sidebar = r"""
-\setlength{\locallinewidth}{0.9\DUadmonitionwidth}
-\begin{center}\begin{sffamily}
-\fbox{\colorbox[gray]{0.80}{\parbox{\DUadmonitionwidth}{
-"""
+PreambleCmds.sidebar = r"""% sidebar (text outside the main text flow)
+\providecommand{\DUsidebar}[1]{%
+ \begin{center}
+ \sffamily
+ \fbox{\colorbox[gray]{0.80}{\parbox{0.9\textwidth}{#1}}}
+ \end{center}
+}"""
PreambleCmds.table = r"""\usepackage{longtable}
\usepackage{array}
-\setlength{\extrarowheight}{2pt}"""
+\setlength{\extrarowheight}{2pt}
+\newlength{\DUtablewidth} % internal use in tables"""
PreambleCmds.title = r"""
%%%%%% Title metadata
@@ -422,9 +433,15 @@
\date{%s}"""
PreambleCmds.titlereference = r"""% title reference role:
-\newcommand{\DUroletitlereference}[1]{\textsl{#1}}"""
+\providecommand*{\DUroletitlereference}[1]{\textsl{#1}}"""
+PreambleCmds.topictitle = r"""% title for "topics" (admonitions, sidebar)
+\providecommand*{\DUtopictitle}[1]{\textbf{\large #1}\smallskip}"""
+PreambleCmds.transition = r"""% transition ([fancy]break, anonymous section)
+\providecommand*{\DUtransition}{\hspace*{\fill}\hrulefill\hspace*{\fill}}"""
+
+
class DocumentClass(object):
"""Details of a LaTeX document class."""
@@ -503,18 +520,22 @@
if attr in self._attrs:
return self._attrs[attr]
return None
+
def get_vertical_bar(self):
if self._table_style == 'standard':
return '|'
return ''
- # horizontal lines are drawn below a row, because we.
+
+ # horizontal lines are drawn below a row,
def get_opening(self):
if self._latex_type == 'longtable':
# otherwise longtable might move before paragraph and subparagraph
prefix = '\\leavevmode\n'
else:
prefix = ''
- return '%s\\begin{%s}[c]' % (prefix, self._latex_type)
+ prefix += '\setlength{\DUtablewidth}{\linewidth}'
+ return '%s\n\\begin{%s}[c]' % (prefix, self._latex_type)
+
def get_closing(self):
line = ''
if self._table_style == 'booktabs':
@@ -559,13 +580,12 @@
colwidth = factor * float(node['colwidth']+1) / width
self._col_width.append(colwidth+0.005)
self._rowspan.append(0)
- latex_table_spec += '%sp{%.3f\\locallinewidth}' % (bar,
- colwidth+0.005)
+ latex_table_spec += '%sp{%.3f\\DUtablewidth}' % (bar, colwidth+0.005)
return latex_table_spec+bar
def get_column_width(self):
"""Return columnwidth for current cell (not multicell)."""
- return '%.2f\\locallinewidth' % self._col_width[self._cell_in_row-1]
+ return '%.2f\\DUtablewidth' % self._col_width[self._cell_in_row-1]
def get_caption(self):
if not self.caption:
@@ -814,17 +834,8 @@
fontenc_header,
r'\usepackage[%s]{inputenc}' % self.latex_encoding,
r'\usepackage{ifthen}',
- # possible other packages.
- # * fancyhdr
- # * ltxtable is a combination of tabularx and longtable
- # (pagebreaks). but ??
- #
- # linewidth of current environment, so tables are not wider than
- # the sidebar: using locallinewidth seems to defer evaluation of
- # linewidth, this is fixing it.
- r'\newlength{\locallinewidth}',
- # will be set later.
- ]
+ ## r'\usepackage{fixltx2e} % "visible" LaTeX bugfixes',
+ ] # custom requirements will be added later
# Part of LaTeX preamble following the stylesheet
self.head = []
@@ -938,10 +949,10 @@
u'\u2013' : '{--}',
u'\u2014' : '{---}',
u'\u2018' : '`',
- u'\u2019' : '\'',
+ u'\u2019' : "'",
u'\u201A' : ',',
u'\u201C' : '``',
- u'\u201D' : '\'\'',
+ u'\u201D' : "''",
u'\u201E' : ',,',
u'\u2020' : '{\\dag}',
u'\u2021' : '{\\ddag}',
@@ -973,42 +984,36 @@
def encode(self, text):
"""Return text with special characters (``#$%&~_^\{}``) escaped."""
- # Escaping with a backslash does not help with backslashes, ~ and ^.
-
- # < > are only available in math-mode or tt font. (really ?)
- # $ starts math- mode.
- # AND quotes
+ # \ ~ ^ Escaping with a backslash does not help.
+ # < > are only available in math-mode or tt font. (really ?)
+ # $ starts math- mode.
+ # " active in some languages (e.g. German) TODO!
if self.verbatim:
return text
# compile the regexps once. do it here so one can see them.
#
# first the braces.
- if not 'encode_re_braces' in self.__dict__:
+ if not hasattr(self, 'encode_re_braces'):
self.encode_re_braces = re.compile(r'([{}])')
text = self.encode_re_braces.sub(r'{\\\1}',text)
- if not 'encode_re_bslash' in self.__dict__:
+ if not hasattr(self, 'encode_re_bslash'):
# find backslash: except in the form '{\{}' or '{\}}'.
self.encode_re_bslash = re.compile(r'(?<!{)(\\)(?![{}]})')
# then the backslash: except in the form from line above:
# either '{\{}' or '{\}}'.
text = self.encode_re_bslash.sub(r'{\\textbackslash}', text)
-
- # then dollar
+ # then dollar ...
text = text.replace('$', '{\\$}')
+ text = text.replace('&', '{\\&}')
+ text = text.replace('%', '{\\%}')
+ text = text.replace('#', '{\\#}')
+ text = text.replace('^', '{\\textasciicircum}')
+ text = text.replace('~', '{\\textasciitilde}')
+ #
if not ( self.literal_block or self.literal ):
text = text.replace('|', '{\\textbar}')
text = text.replace('<', '{\\textless}')
text = text.replace('>', '{\\textgreater}')
- # then
- text = text.replace('&', '{\\&}')
- # the ^:
- # * verb|^| does not work in mbox.
- # * mathmode has wedge. hat{~} would also work.
- # text = text.replace('^', '{\\ensuremath{^\\wedge}}')
- text = text.replace('^', '{\\textasciicircum}')
- text = text.replace('%', '{\\%}')
- text = text.replace('#', '{\\#}')
- text = text.replace('~', '{\\textasciitilde}')
# Separate compound characters, e.g. '--' to '-{}-'. (The
# actual separation is done later; see below.)
separate_chars = '-'
@@ -1019,7 +1024,7 @@
separate_chars += ',`\'"<>'
# pdflatex does not produce doublequotes for ngerman.
text = self.babel.double_quotes_in_tt(text)
- if self.font_encoding == 'OT1':
+ if self.font_encoding in ['OT1', '']:
# We're using OT1 font-encoding and have to replace
# underscore by underlined blank, because this has
# correct width.
@@ -1074,16 +1079,15 @@
def visit_admonition(self, node, name=''):
self.fallbacks['admonition'] = PreambleCmds.admonition
- self.body.append('\\begin{center}\\begin{sffamily}\n')
- self.body.append('\\fbox{\\parbox{\\DUadmonitionwidth}{\n')
+ self.fallbacks['topictitle'] = PreambleCmds.topictitle
+ self.body.append('\\DUadmonition{')
if name:
- self.body.append(r'\textbf{\large ' +
- self.language.labels[name] + '}\n');
- self.body.append('\\vspace{2mm}\n')
+ self.body.append('\\DUtopictitle{%s}\n' %
+ self.language.labels[name]);
+ ## self.body.append('\\vspace{2mm}\n')
def depart_admonition(self, node=None):
- self.body.append('}}\n') # end parbox fbox
- self.body.append('\\end{sffamily}\n\\end{center}\n');
+ self.body.append('}\n')
def visit_attention(self, node):
self.visit_admonition(node, 'attention')
@@ -1308,6 +1312,7 @@
def visit_docinfo(self, node):
# tabularx: automatic width of columns, no page breaks allowed.
self.requirements['tabularx'] = r'\usepackage{tabularx}'
+ self.requirements['~providelenght'] = PreambleCmds.providelenght
self.fallbacks['docinfo'] = PreambleCmds.docinfo
self.docinfo = ['%' + '_'*75 + '\n',
'\\begin{center}\n',
@@ -1377,7 +1382,6 @@
if (self.use_latex_docinfo or len(node) and
isinstance(node[0], nodes.title)):
self.body_prefix.append('\\maketitle\n\n')
- self.body.append('\n\\setlength{\\locallinewidth}{\\linewidth}\n')
def depart_document(self, node):
# Complete header with information gained from walkabout
@@ -1444,8 +1448,11 @@
def visit_entry(self, node):
self.active_table.visit_entry()
# cell separation
+ # BUG: the following fails, with more than one multirow
+ # starting in the second column (or later) see
+ # ../../../test/functional/input/data/latex.txt
if self.active_table.get_entry_number() == 1:
- # if the firstrow is a multirow, this actually is the second row.
+ # if the first row is a multirow, this actually is the second row.
# this gets hairy if rowspans follow each other.
if self.active_table.get_rowspan(0):
count = 0
@@ -1455,8 +1462,7 @@
self.active_table.visit_entry() # increment cell count
else:
self.body.append(' & ')
-
- # multi{row,column}
+ # multirow, multicolumn
# IN WORK BUG TODO HACK continues here
# multirow in LaTeX simply will enlarge the cell over several rows
# (the following n if n is positive, the former if negative).
@@ -1468,10 +1474,9 @@
count = node['morerows'] + 1
self.active_table.set_rowspan(
self.active_table.get_entry_number()-1,count)
- self.body.append('\\multirow{%d}{%s}{' %
+ self.body.append('\\multirow{%d}{%s}{%%' %
(count,self.active_table.get_column_width()))
self.context.append('}')
- # BUG following rows must have empty cells.
elif 'morecols' in node:
# the vertical bar before column is missing if it is the first
# column. the one after always.
@@ -1488,7 +1493,7 @@
# header / not header
if isinstance(node.parent.parent, nodes.thead):
- self.body.append('\\textbf{')
+ self.body.append('\\textbf{%')
self.context.append('}')
elif self.active_table.is_stub_column():
self.body.append('\\textbf{')
@@ -1597,14 +1602,13 @@
self.body.append( '\n' )
def visit_field_list(self, node):
+ self.fallbacks['fieldlist'] = PreambleCmds.fieldlist
if not self.docinfo:
- self.body.append('\\begin{quote}\n')
- self.body.append('\\begin{description}\n')
+ self.body.append('\\begin{DUfieldlist}\n')
def depart_field_list(self, node):
if not self.docinfo:
- self.body.append('\\end{description}\n')
- self.body.append('\\end{quote}\n')
+ self.body.append('\\end{DUfieldlist}\n')
def visit_field_name(self, node):
# BUG this duplicates docinfo_item
@@ -1815,6 +1819,10 @@
self.depart_literal(node)
def visit_legend(self, node):
+ # DUlegend command incompatible with flush* aligning:
+ # ! LaTeX Error: There's no line here to end.
+ ## self.fallbacks['legend'] = PreambleCmds.legend
+ ## self.body.append('\DUlegend{')
self.body.append('{\\small ')
def depart_legend(self, node):
@@ -1827,6 +1835,7 @@
self.body.append('\n')
def visit_line_block(self, node):
+ self.requirements['~providelenght'] = PreambleCmds.providelenght
self.fallbacks['lineblock'] = PreambleCmds.lineblock
if isinstance(node.parent, nodes.line_block):
self.body.append('\\item[]\n'
@@ -1840,6 +1849,7 @@
def visit_list_item(self, node):
# Append '{}' in case the next character is '[', which would break
# LaTeX's list environment (no numbering and the '[' is not printed).
+ # TODO: is this still needed? We already protect '['.
self.body.append('\\item {} ')
def depart_list_item(self, node):
@@ -1882,7 +1892,7 @@
packages = {'listing': r'\usepackage{moreverb}',
'lstlisting': r'\usepackage{listings}',
'Verbatim': r'\usepackage{fancyvrb}',
- '#verbatim': '',
+ # 'verbatim': '',
'verbatimtab': r'\usepackage{moreverb}'}
if not self.active_table.is_open():
@@ -1955,6 +1965,7 @@
self.body.append('] ')
def visit_option_list(self, node):
+ self.requirements['~providelenght'] = PreambleCmds.providelenght
self.fallbacks['optionlist'] = PreambleCmds.optionlist
self.body.append('\\begin{DUoptionlist}\n')
@@ -2045,16 +2056,14 @@
self.section_level -= 1
def visit_sidebar(self, node):
- # BUG: this is just a hack to make sidebars render something
+ # TODO: this is just a hack to make sidebars render something
+ # fallback definition requires the color package for background colour
self.requirements['color'] = r'\usepackage{color}'
- # current implementation relies on \DUadmonitionwidth
- self.fallbacks['admonition'] = PreambleCmds.admonition
- self.body.append(PreambleCmds.sidebar)
+ self.fallbacks['sidebar'] = PreambleCmds.sidebar
+ self.body.append('\n\\DUsidebar{\n')
def depart_sidebar(self, node):
- self.body.append('}}}\n') # end parbox colorbox fbox
- self.body.append('\\end{sffamily}\n\\end{center}\n');
- self.body.append('\n\\setlength{\\locallinewidth}{\\linewidth}\n')
+ self.body.append('}\n')
attribution_formats = {'dash': ('---', ''),
'parentheses': ('(', ')'),
@@ -2245,8 +2254,9 @@
# either specify every possible node or ... ?
elif (isinstance(node.parent, nodes.sidebar) or
isinstance(node.parent, nodes.admonition)):
- self.body.append('\\textbf{\\large ')
- self.context.append('}\n\\smallskip\n')
+ self.fallbacks['topictitle'] = PreambleCmds.topictitle
+ self.body.append('\\DUtopictitle{')
+ self.context.append('}\n')
elif isinstance(node.parent, nodes.table):
# caption must be written after column spec
self.active_table.caption = self.encode(node.astext())
@@ -2314,9 +2324,10 @@
self.body.append(self.context.pop())
def visit_transition(self, node):
+ self.fallbacks['transition'] = PreambleCmds.transition
self.body.append('\n\n')
- self.body.append('%' + '_' * 75)
- self.body.append('\n\\hspace*{\\fill}\\hrulefill\\hspace*{\\fill}')
+ self.body.append('%' + '_' * 75 + '\n')
+ self.body.append(r'\DUtransition')
self.body.append('\n\n')
def depart_transition(self, node):
Modified: trunk/docutils/docutils/writers/latex2e/docutils-05-compat.sty
===================================================================
--- trunk/docutils/docutils/writers/latex2e/docutils-05-compat.sty 2009-04-29 13:13:07 UTC (rev 5930)
+++ trunk/docutils/docutils/writers/latex2e/docutils-05-compat.sty 2009-04-29 19:28:06 UTC (rev 5931)
@@ -4,41 +4,41 @@
%
% :Author: Guenter Milde
% :Contact: mi...@us...
-% :Revision: $Revision: 5892 $
+% :Revision: $Revision: 5927 $
% :Date: $Date: 2009-02-24$
-% :Copyright: © 2007, 2009 G. Milde,
+% :Copyright: © 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]
+% This file documents changes and provides a style for best possible
+% compatibility to the behaviour of the `latex2e` writer of Doctutils
+% release 0.5
+%
% .. contents::
-% :depth: 2
+% :depth: 3
%
% Usage
% =====
%
-% To get an (almost) identic look for your old documents without further
-% configuration, place ``docutils-05-compat.sty`` and
-% ``docutils-05-compat2.sty`` in the TEXINPUT path (e.g. the current work
-% directory) and pass the
-% ``--stylesheet=docutils-05-compat,docutils-05-compat2`` option to
-% ``rst2latex.py``.
+% * To get an (almost) identic look for your old documents without further
+% configuration, place ``docutils-05-compat.sty`` in the TEXINPUT path (e.g.
+% the current work directory) and pass the
+% ``--st...
[truncated message content] |