Local tocs with `minitoc` if "use-latex-toc" is True.

Plus some more ideas/updates in todo.txt

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@5948 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

6 files changed, 188 insertions, 82 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 518f43137..fe1a313b2 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -87,6 +87,7 @@ Changes Since 0.5
   - Use the name prefix ``DU`` for all Docutils specific LaTeX objects.
   - New custom macros.
   - Simpler LaTeX encoding, e.g. "\%" instead of "{\%}".
+  - Local tocs with `minitoc` (if 'use-latex-toc' is True).
 
 * docs/ref/rst/restructuredtext.txt:
 
diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt
index 053c3c3be..1b9959775 100644
--- a/docutils/RELEASE-NOTES.txt
+++ b/docutils/RELEASE-NOTES.txt
@@ -39,7 +39,8 @@ Changes Since 0.5
   - 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``
+  - Docutils specific LaTeX objects are now all prefixed with ``DU``.
+  - Local tocs with `minitoc` (if 'use-latex-toc' is True).
 
 
 Release 0.5 (2008-06-25)
diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index d61d2c409..6cdae30fc 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -1909,22 +1909,12 @@ Bug fixes
 
   See `<../../test/functional/input/data/latex.txt>`__
 
-* Aligning a figure also aligns the legend *but not the caption* nor a table
-  in the legend.
+* The `align` argument of a figure directive aligns both, figure and legend
+  but *not* the caption nor a table in the legend.
 
-  + Use tabular instead of longtable for tables in legends.
+  + align the *figure* "en-bloc"
 
-  + Use `caption` package for caption alignment
-    (CTAN /macros/latex/contrib/caption,
-    Debian package texlive-latex-recommended).
-    Set alignment with ::
-
-      \captionsetup{justification=raggedleft,singlelinecheck=false}
-
-    For a single caption use this inside the figure environment.
-
-    ``singlelinecheck=false`` in the preamble and justification in the
-    caption would allow configuring "singlelinecheck" in the style file.
+  + Use tabular instead of longtable for tables in legends?
 
 * An image directive with target URI does not start a new paragraph
   (see first two image examples in standalone_rst_latex.tex).
@@ -1941,14 +1931,14 @@ LaTeX macros for Docutils-specific objects
 ``````````````````````````````````````````
 
 :legend:     Conflict with flushright/flushleft for image alignment
-	     ``! LaTeX Error: There's no line here to end.``
-	     --> Re-try after fixing the alignment bug.
-	     Try with raggedleft/raggedright.
+             ``! LaTeX Error: There's no line here to end.``
+             --> Re-try after fixing the alignment bug.
+             Try with raggedleft/raggedright.
 
 :subtitle:   Is there a native construct?
 
 :admonitions: Provide separate commands for specific admonitions (error,
-	      note, ...)?
+              note, ...)?
 
 LaTeX constructs and packages in stead of re-implementations
 ````````````````````````````````````````````````````````````
@@ -2024,11 +2014,29 @@ Which packages do we want to use?
    ``! LaTeX Error: Something's wrong--perhaps a missing \item.``
    Committed a HACK: centring by ``\hfill``.
 
+
+table of contents
+^^^^^^^^^^^^^^^^^
+
+Problem:
+  when I specify a :depth: to a contents directive, this value is used but
+  not preserved in the doctree.
+
+David wrote:
+
+  There is a setting, use_latex_toc. Unfortunately its implementation is
+  suboptimal. When use_latex_toc is True, the Docutils-generated ToC
+  shouldn't be built at all. It's a waste of time.
+
+  Instead, the docutils.transforms.parts.Contents transform should be
+  made aware of use_latex_toc, and do the right thing for LaTeX. Or the
+  LaTeX writer should override that transform and substitute a custom
+  version.
+
+
 Default layout
 --------------
 
-* Always include `fixltx2e`_ ("visible" LaTeX bugfixes, ``\textsubscript``)
-
 * Which `default font`__ should we use for the output?
 
   Proposal: Use one of the Postscript default fonts supported by standard
@@ -2043,7 +2051,11 @@ Default layout
 
 * 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?)
+
+  Overriding:
+
+  * continue if the `compound paragraph`_ directive is used, or
+  * force a new paragraph with an empty comment.
 
 * Indent/handle doctest blocks similar to literal blocks?
 
@@ -2068,9 +2080,6 @@ Default layout
 * Configurable `classifier` in description list?
   \emph instead of bold as default?
 
-* Use teletype (literal) for  references without targets (currently
-   ``\color{red}\bfseries{}``)
-
 __ ../../../sandbox/latex-variants/README.html#default-font
 
 .. _PSNFSS documentation:
@@ -2125,13 +2134,12 @@ Image and figure directives
   + `<../../test/functional/expected/standalone_rst_html4css1.html>`__
   + `<../../test/functional/expected/standalone_rst_latex.tex>`__
 
-* Should image start a new paragraph? (Keep support for inlined images with
-  substitutions!)
-
-* Centred and aligned images with ``\centerline``, ``\flushleft``,
-  ``\flushright`` instead of environments (avoids spurious whitespace).
+* Centred and aligned images in figures with ``\centerline``,
+  ``\flushleft``, ``\flushright`` instead of environments (avoids
+  spurious whitespace) (but see also the discussion about figure
+  alignment).
 
-* Wrap text around figures with class "wrap".
+* Wrap text around figures/images with class "wrap"?
   Use `wrapfig` (or other recommended) package.
 
 
@@ -2153,12 +2161,6 @@ Missing features
 * 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.
 
diff --git a/docutils/docs/user/docutils-05-compat.sty.txt b/docutils/docs/user/docutils-05-compat.sty.txt
index 0fe6c6e58..c3682f214 100644
--- a/docutils/docs/user/docutils-05-compat.sty.txt
+++ b/docutils/docs/user/docutils-05-compat.sty.txt
@@ -11,8 +11,8 @@
             under the terms of the Apache License, Version 2.0
             http://www.apache.org/licenses/LICENSE-2.0
 :Abstract:  This file documents changes and provides a style for best
-	    possible compatibility to the behaviour of the `latex2e` 
-	    writer of Doctutils release 0.5.
+            possible compatibility to the behaviour of the `latex2e`
+            writer of Doctutils release 0.5.
 
 ::
 
@@ -67,7 +67,7 @@ Backwards compatibility:
   be a LaTeX package (``*.sty``) and referenced with the ``\usepackage``
   command.
 
-.. important:: 
+.. important::
   Always specify the extension if you want the style sheet to be
   ``\input`` by LaTeX.
 
@@ -85,7 +85,7 @@ New Feature: custom roles based on standard roles
   methods for the standard roles now call visit/depart_inline() if there are
   class arguments to the node.
 
-Backwards compatibility: 
+Backwards compatibility:
   The implementation is fully backwards compatible. (SVN versions 5742 to
   5861 contained an implementation that did not work with commands expecting
   an argument.)
@@ -256,6 +256,18 @@ Backwards compatibility:
 
     \raggedbottom
 
+Local tocs with `minitoc`
+`````````````````````````
+
+New feature:
+  If 'use-latex-toc' is set, local tables of content are typeset using the
+  'minitoc' package (instead of being ignored).
+
+Backwards compatibility:
+  Disable the creation of local ToCs (ignoring all special commands) by
+  replacing ``\usepackage{minitoc} with ``\usepackage{mtcoff}``.
+
+
 Shorter preamble
 ----------------
 
diff --git a/docutils/docs/user/latex.txt b/docutils/docs/user/latex.txt
index f0b085f77..9f45d0241 100644
--- a/docutils/docs/user/latex.txt
+++ b/docutils/docs/user/latex.txt
@@ -248,12 +248,25 @@ Example:
 __ ../ref/rst/directives.html#admonitions
 
 
-caption numbering
-`````````````````
+figure and table captions
+`````````````````````````
+The caption_ package provides many ways to customise the captions in
+floating environments like figure and table.
 
 The chngcntr_ package helps to configure the numbering of figure and table
-caption numberings. Some document classes (e.g. KOMA-script_) provide
-additional configuration. Also see the related `FAQ entry`__
+caption numberings.
+
+Some document classes (e.g. KOMA-script_) provide additional configuration.
+Also see the related `LaTeX FAQ entry`__
+
+Example
+  ::
+
+    \usepackage{caption}
+    \captionsetup{justification=raggedleft,singlelinecheck=false}
+
+.. _caption:
+   http://dante.ctan.org/CTAN/help/Catalogue/entries/caption.html
 
 .. _chngcntr:
    http://dante.ctan.org/CTAN/help/Catalogue/entries/chngcntr.html
@@ -775,6 +788,33 @@ Example:
 
 __ ../ref/rst/directives.html#rubric
 
+
+table of contents
+`````````````````
+
+If you want page numbers in the table of contents, specify
+``--use-latex-toc``:
+
+* LaTeX is used to generate the table of contents (ToC) with the
+  ``\tableofcontents`` macro at the given location.
+
+  Styling options depend on the choosen document class
+  (see e.g. the `KOMA-Script Guide`_ for the `KOMA-script`_ classes).
+
+* Local ToCs are done with the minitoc_ package. See its documentation__ for
+  the numerous configuration options.
+
+.. note::
+   Minitoc supports local ToCs only at "part" level and top section level
+   ("chapter" or "section"). Local `contents` directives at lower levels
+   are ignored (a warning is issued).
+
+   If you really require "low-level" local ToCs, turn off the
+   `use-latex-toc` option.
+
+.. _minitoc: http://dante.ctan.org/CTAN/help/Catalogue/entries/minitoc.html
+__ http://dante.ctan.org/CTAN/macros/latex/contrib/minitoc/minitoc.pdf
+
 title reference role
 ````````````````````
 
@@ -999,7 +1039,7 @@ influence section numbering.
   LaTeX output, so that LaTeX generates a table of contents and
   generates section numbers. Usually one does not want to have
   section numbers generated by Docutils in this case, therefore
-  ``--no-section-numbering`` should be specified.
+  ``--no-section-numbering`` is the default with this option.
 
   The advantage is that LaTeX does put page numbers into the
   table of contents, but the section depth is limited by the
@@ -1227,9 +1267,3 @@ Miscellaneous
 
 * For additional docinfo items: the field_body is inserted as text, i.e. no
   markup is done.
-
-* 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.
diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py
index 9ef4f6bbb..324c72ff3 100644
--- a/docutils/docutils/writers/latex2e/__init__.py
+++ b/docutils/docutils/writers/latex2e/__init__.py
@@ -327,6 +327,10 @@ PreambleCmds.admonition = r"""% admonitions (specially marked "topics")
   \end{center}
 }"""
 
+## PreambleCmds.caption = r"""% configure caption layout
+## \usepackage{caption}
+## \captionsetup{singlelinecheck=false}% no exceptions for one-lined captions"""
+
 PreambleCmds.docinfo = r"""% width of docinfo table:
 \DUprovidelength{\DUdocinfowidth}{0.9\textwidth}"""
 
@@ -386,6 +390,9 @@ PreambleCmds.linking = r"""%% hyperref (PDF hyperlinks):
   \usepackage[colorlinks=%s,linkcolor=%s,urlcolor=%s]{hyperref}
 }{}"""
 
+PreambleCmds.minitoc = r"""%% local table of contents
+\usepackage{minitoc}"""
+
 PreambleCmds.optionlist = r"""% option list:
 \providecommand*{\DUoptionlistlabel}[1]{\bf #1 \hfill}
 \DUprovidelength{\DUoptionlistindent}{3cm}
@@ -444,6 +451,13 @@ class DocumentClass(object):
     def __init__(self, document_class, with_part=False):
         self.document_class = document_class
         self._with_part = with_part
+        self.sections = ['section', 'subsection', 'subsubsection',
+                         'paragraph', 'subparagraph']
+        if self.document_class in ('book', 'memoir', 'report',
+                                   'scrbook', 'scrreprt'):
+            self.sections.insert(0, 'chapter')
+        if self._with_part:
+            self.sections.insert(0, 'part')
 
     def section(self, level):
         """Return the LaTeX section name for section `level`.
@@ -452,16 +466,10 @@ class DocumentClass(object):
         Level is 1,2,3..., as level 0 is the title.
         """
 
-        sections = [ 'section', 'subsection', 'subsubsection',
-                     'paragraph', 'subparagraph' ]
-        if self.document_class in ('book', 'report', 'scrreprt', 'scrbook'):
-            sections.insert(0, 'chapter')
-        if self._with_part:
-            sections.insert(0, 'part')
-        if level <= len(sections):
-            return sections[level-1]
+        if level <= len(self.sections):
+            return self.sections[level-1]
         else:
-            return sections[-1]
+            return self.sections[-1]
 
 class Table(object):
     """Manage a table while traversing.
@@ -685,8 +693,10 @@ class LaTeXTranslator(nodes.NodeVisitor):
     # Config setting defaults
     # -----------------------
 
+
     # use latex tableofcontents or let docutils do it.
-    use_latex_toc = 0
+    use_latex_toc = False
+    has_latex_toc = False # is there a toc in the doc (needed by minitoc)
 
     # TODO: use mixins for different implementations.
     # list environment for docinfo. else tabularx
@@ -1445,6 +1455,9 @@ class LaTeXTranslator(nodes.NodeVisitor):
                 self.body.append('\n\\bibliographystyle{%s}\n' %
                                  self.bibtex[0])
                 self.body.append('\\bibliography{%s}\n' % self.bibtex[1])
+        # Make sure to generate a toc file if needed for local contents:
+        if 'minitoc' in self.requirements and not self.has_latex_toc:
+            self.body.append('\n\\faketableofcontents % for local ToCs\n')
 
     def visit_emphasis(self, node):
         self.body.append('\\emph{')
@@ -1637,6 +1650,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
             self.body.append(':]')
 
     def visit_figure(self, node):
+        # TODO: use LaTeX default alignment (left) (similar to HTML)
         if ('align' not in node.attributes or
             node.attributes['align'] == 'center'):
             # centering does not add vertical space like center.
@@ -1774,6 +1788,19 @@ class LaTeXTranslator(nodes.NodeVisitor):
         post = []
         include_graphics_options = []
         inline = isinstance(node.parent, nodes.TextElement)
+        align_prepost = {
+            # key == (<inline>, <align>)
+            # By default latex aligns the bottom of an image.
+            (1, 'bottom'): ('', ''),
+            (1, 'middle'): ('\\raisebox{-0.5\\height}{', '}'),
+            (1, 'top'): ('\\raisebox{-\\height}{', '}'),
+            (0, 'center'): ('{\\hfill', '\\hfill}'),
+            # According to the HTML standard
+            # http://www.w3.org/TR/html4/struct/objects.html#adef-align-IMG
+            # the image should be floated alongside the paragraph.
+            # However, this is not even honoured by all HTML browsers.
+            (0, 'left'): ('{', '\\hfill}'),
+            (0, 'right'): ('{\\hfill', '}'),}
         if 'scale' in attrs:
             # Could also be done with ``scale`` option to
             # ``\includegraphics``; doing it this way for consistency.
@@ -1786,17 +1813,6 @@ class LaTeXTranslator(nodes.NodeVisitor):
             include_graphics_options.append('height=%s' % (
                             self.latex_image_length(attrs['height']), ))
         if 'align' in attrs:
-            align_prepost = {
-                # By default latex aligns the bottom of an image.
-                (1, 'bottom'): ('', ''),
-                (1, 'middle'): ('\\raisebox{-0.5\\height}{', '}'),
-                (1, 'top'): ('\\raisebox{-\\height}{', '}'),
-                (0, 'center'): ('{\\hfill', '\\hfill}'),
-                # These 2 don't exactly do the right thing.  The image should
-                # be floated alongside the paragraph.  See
-                # http://www.w3.org/TR/html4/struct/objects.html#adef-align-IMG
-                (0, 'left'): ('{', '\\hfill}'),
-                (0, 'right'): ('{\\hfill', '}'),}
             try:
                 pre.append(align_prepost[inline, attrs['align']][0])
                 post.append(align_prepost[inline, attrs['align']][1])
@@ -2244,8 +2260,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
     def visit_title(self, node):
         """Append section and other titles."""
 
+	# Table of contents:
         if isinstance(node.parent, nodes.topic):
-            # the table of contents.
             if ('contents' in self.topic_classes and
                 self.settings.use_titlepage_env):
                 self.body.append('\\end{titlepage}\n')
@@ -2254,14 +2270,12 @@ class LaTeXTranslator(nodes.NodeVisitor):
                 self.use_latex_toc):
                 self.body.append('\\renewcommand{\\contentsname}{')
                 self.context.append('}\n\\tableofcontents\n\n\\bigskip\n')
-            elif ('abstract' in self.topic_classes and
-                  self.settings.use_latex_abstract):
-                raise nodes.SkipNode
+                self.has_latex_toc = True
             else: # or section titles before the table of contents.
-                # BUG: latex chokes on center environment with
-                # "perhaps a missing item", therefore we use hfill.
+                # In LaTeX, alignment of sections is determined by the
+                # document class. Use \hfill as a workaround.
+                # TODO: keep standard alignment, use `sectsty` or `titlesec`?
                 self.body.append('\\subsubsection*{~\\hfill ')
-                # the closing brace for subsection.
                 self.context.append('\\hfill ~}\n')
         # TODO: for admonition titles before the first section
         # either specify every possible node or ... ?
@@ -2302,11 +2316,53 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.body.append(self.context.pop())
         self.body += ['\\label{%s}\n' % id for id in node.parent['ids']]
 
+    def minitoc(self, node):
+        """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 = ''
+        # name-prefix for current section level
+        section_name = self.d_class.section(self.section_level)
+        if section_name == 'part':
+            level = 'part'
+        elif section_name == 'chapter':
+            level = 'mini'
+        elif (section_name == 'section' and
+              'chapter' not in self.d_class.sections):
+            level = 'sect'
+        else: # minitoc only supports local toc in part- or top-level
+            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' % level] = r'\do%stoc' % level
+        # depth: (Docutils defaults to unlimited depth)
+        depth = len(self.d_class.sections)
+        self.requirements['minitoc-%s-depth' % level] = (
+            r'\mtcsetdepth{%stoc}{%d}' % (level, depth))
+        # TODO: set the depth according to the :depth: argument
+        # Attention: Docutils stores a relative depth while minitoc
+        # expects an absolute depth!
+        ## self.body.append('\\setcounter{%stocdepth}{%d}' % (level, depth))
+        # title:
+        self.body.append('\\mtcsettitle{%stoc}{%s}\n' % (level, toctitle))
+        # the toc-generating command:
+        self.body.append('\\%stoc\n' % level)
+
     def visit_topic(self, node):
         self.topic_classes = node['classes']
-        if ('abstract' in self.topic_classes and
+        if (self.use_latex_toc and
+            'contents' in node['classes'] and 'local' in node['classes']):
+            self.minitoc(node)
+        elif ('abstract' in self.topic_classes and
             self.settings.use_latex_abstract):
-            self.body.append('\\begin{abstract}\n')
+            self.body.append('\\begin{abstract}')
+            if isinstance(node.next_node(), nodes.title):
+                node.pop(0) # dump title
 
     def depart_topic(self, node):
         if ('abstract' in self.topic_classes and