Better conformance to Docutils specifications with "use_latex_toc".

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

9 files changed, 263 insertions, 180 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index f1f6a3d03..d2b4c19b0 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -98,7 +98,7 @@ Changes Since 0.5
   - Use the name prefix ``DU`` for all Docutils specific LaTeX objects.
   - New custom macros and environments.
   - Simpler LaTeX encoding, e.g. "\%" instead of "{\%}".
-  - Local tocs with `minitoc` (if 'use-latex-toc' is True).
+  - Better conformance to Docutils specifications with "use_latex_toc".
   - Use default font in admonitions and sidebar.
   - Align of image in a figure defaults to 'center'.
   - Bugfix: Newlines around targets and references prevent run-together
diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt
index b56b14978..c815edade 100644
--- a/docutils/RELEASE-NOTES.txt
+++ b/docutils/RELEASE-NOTES.txt
@@ -50,7 +50,7 @@ Changes Since 0.5
   - 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``.
-  - Local tocs with `minitoc` (if 'use-latex-toc' is True).
+  - Better conformance to Docutils specifications with "use_latex_toc".
   - 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').
diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index 2ea4c7321..1706fdff5 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -1788,9 +1788,6 @@ HTML Writer
   omitting ``<p>`` tags.  List compacting would need to be done by
   adjusting CSS margins instead.
 
-* Add support for _`multiple stylesheets`.  See
-  <http://thread.gmane.org/gmane.text.docutils.cvs/4336>.
-
 * Idea for field-list rendering: hanging indent::
 
       Field name (bold): First paragraph of field body begins
@@ -1824,7 +1821,8 @@ PEP/HTML Writer
 * Remove the generic style information (duplicated from html4css1.css)
   from pep.css to avoid redundancy.
 
-  We need support for `multiple stylesheets`_ first, though.
+  Needs support for multiple stylesheets in the PEP writer
+  (is this inherited from HTML?).
 
 
 S5/HTML Writer
@@ -2045,16 +2043,11 @@ Which packages do we want to use?
    ? (My preference is to default to use-latex-* whenever possible [GM])
 
 
-table of contents
-^^^^^^^^^^^^^^^^^
-
-* support non-numbered sections with use-latex-toc
-  (now easy because of the \addtocontents lines)
-* use-latex-doc by default?
-
 Default layout
 --------------
 
+* use-latex-doc by default?
+
 * Which `default font`__ should we use for the output?
 
   Proposal: Use one of the Postscript default fonts supported by standard
@@ -2183,11 +2176,17 @@ Image and figure directives
 Missing features
 ----------------
 
+* test and document selection of LaTeX fontsize. 
+  
+  Add font size in points to the document options, e.g.
+  ``--documentoptions=12``, use extsize or some other
+  package for values other than [10,11,12].
+
 * support "figwidth" argument for figures.
 
   As the 'figwidth' argument is still ignored and the "natural width" of
-  a figure in LaTeX is 100% \textwidth, setting the 'align' argument has
-  currently no effect on the LaTeX output.
+  a figure in LaTeX is 100 % of the text width, setting the 'align'
+  argument has currently no effect on the LaTeX output.
 
 * better citation support
 
diff --git a/docutils/docs/user/docutils-05-compat.sty.txt b/docutils/docs/user/docutils-05-compat.sty.txt
index eccd6af69..e23f1f487 100644
--- a/docutils/docs/user/docutils-05-compat.sty.txt
+++ b/docutils/docs/user/docutils-05-compat.sty.txt
@@ -299,8 +299,31 @@ Backwards compatibility:
 
     \raggedbottom
 
-Local tocs with `minitoc`
--------------------------
+Better conformance to Docutils specifications with "use_latex_toc"
+--------------------------------------------------------------------
+
+New feature:
+  Section numbering is done according to the Docutils specifications also
+  if 'use-latex-toc' is True:
+
+  * sections are only numbered if there is a "sectnum" directive in the
+    document and the "sectnum_xforms" config setting is True,
+
+  * The "depth" argument is respected and the default is set to to the
+    number of supported section levels.
+
+New features:
+  * The default "depth" of the LaTeX-created ToC is increased to the number
+    of supported section levels.
+  * The "depth" argument of the "contents" directive is respected.
+
+Backwards compatibility:
+  The previous behaviour was to use the document class default and cannot be
+  restored universally. The following resets it to the default values of the
+  default document class ("article")::
+
+    \setcounter{secnumdepth}{3}
+    \setcounter{tocdepth}{3}
 
 New feature:
   If 'use-latex-toc' is set, local tables of content are typeset using the
diff --git a/docutils/docs/user/latex.txt b/docutils/docs/user/latex.txt
index 10df3ebf3..c7055a8d8 100644
--- a/docutils/docs/user/latex.txt
+++ b/docutils/docs/user/latex.txt
@@ -345,31 +345,6 @@ Example:
 __ ../ref/rst/directives.html#admonitions
 
 
-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 `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
-
-__ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=running-nos
-
 custom interpreted text roles
 `````````````````````````````
 
@@ -574,12 +549,37 @@ Example:
 __ ../ref/rst/restructuredtext.html#field-lists
 
 
+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 `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
+__ http://www.tex.ac.uk/cgi-bin/texfaq2html?label=running-nos
+
+
 figure placement
 ````````````````
 
-Figure placement can be customized globally with the ``\floatplacement``
-command from the `float`_ package. See the `float package documentation`_
-for details.
+Figure placement can be customized with the ``\floatplacement`` command from
+the `float`_ package. The placement setting is valid from the point of
+definition until the next ``\floatplacement`` command or the end of the
+document. See the `float package documentation`_ for details.
 
 Default:
   ``\floatplacement{figure}{H}`` (here definitely). This corresponds most
@@ -592,8 +592,8 @@ Examples:
     \usepackage{float}
     \floatplacement{figure}{htbp} % here, top, bottom, extra-page
 
-* Place the following figures at top or bottom with `raw LaTeX`_
-  in the document source::
+* To move all following figures to the top or bottom of the page write in
+  the document source::
 
     .. raw:: latex
 
@@ -1016,32 +1016,86 @@ Example:
 __ ../ref/rst/directives.html#rubric
 
 
+section numbering
+`````````````````
+
+Sections are numbered if there is a `sectnum directive`_ in the document and
+the sectnum_xform_ option is True (default).
+
+* If use_latex_toc_ is True, (the `table of contents`_ and) section numbers
+  are generated by LaTeX.
+
+  The number style is determined by the `document class`_ and can be
+  configured in a LaTeX `style sheet`_.
+
+  .. note::
+
+    In this case the "prefix" and "suffix" arguments of the
+    `sectnum directive`_ are ignored.
+
+.. _sectnum directive: ../ref/rst/directives.html#sectnum
+.. _sectnum_xform: ../user/config.html#sectnum-xform
+
+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.
+
+Example:
+  Use margin notes ::
+
+    \newcommand{\DUsidebar}{\marginpar}
+
+  * Make sure the margin is wide enough to hold the note.
+  * This might fail 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
+
+
 table of contents
 `````````````````
 
-If you want page numbers in the table of contents, specify
-``--use-latex-toc``:
+A `contents directive`_ is replaced by a table of contents (ToC).
 
-* LaTeX is used to generate the table of contents (ToC) with the
-  ``\tableofcontents`` macro at the given location.
+If you want page numbers in the ToC, specify ``--use-latex-toc`` or set the
+use_latex_toc_ configuration option to True:
 
-  Styling options depend on the choosen document class
-  (see e.g. the `KOMA-Script Guide`_ for the `KOMA-script`_ classes).
+* The ToC is generated by LaTeX (via the ``\tableofcontents`` command).
+
+  The layout depends on the choosen document class and can be configured in
+  a custom `style sheet`_ (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
+   Minitoc supports local ToCs only at "part" 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.
 
+.. _use_latex_toc: ../user/config.html#use-latex-toc
+.. _contents directive: ../ref/rst/directives.html#contents
 .. _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
 ````````````````````
 
@@ -1160,63 +1214,6 @@ __ http://docutils.sf.net/docutils/docs/ref/rst/restructuredtext.html#transition
 
 .. _transition-stars.sty: ../../../sandbox/stylesheets/transition-stars.sty
 
-section numbering
-`````````````````
-
-The options ``--section-numbering`` and ``--use-latex-toc``, both
-influence section numbering.
-
-* If ``--use-latex-toc`` is specified the latex-writer generates
-  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`` 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
-  used LaTeX document class, usually to four levels.
-
-* If section numbering and LaTeX table of contents is used LaTeX and
-  Docutils will number sections. To switch off displaying of Latex's
-  numbers one has to add following lines to the `style sheet`_ ::
-
-    % no section number display
-    \makeatletter
-    \def\@seccntformat#1{}
-    \makeatother
-    % no numbers in toc
-    \renewcommand{\numberline}[1]{}
-
-  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.
-
-Example:
-  Use margin notes ::
-
-    \newcommand{\DUsidebar}{\marginpar}
-
-  * Make sure the margin is wide enough to hold the note.
-  * This might fail 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
 
 Changes
 =======
@@ -1245,16 +1242,16 @@ Troubleshooting
 Error ``illegal unit px``
 `````````````````````````
 
-The unit ``px`` is not defined in "pure" LaTeX, but introduced by the
-`pdfTeX` converter on 2005-02-04. `pdfTeX` is used in all modern LaTeX
-distributions (since ca. 2006) also for conversion into DVI format.
+If you convert the LaTeX source with a legacy program, you might get this
+error.
 
-If you convert the LaTeX source with a legacy program, you might get the
-error ``illegal unit px``.
+The unit "px" was introduced by the `pdfTeX` converter on 2005-02-04.
+`pdfTeX` is used also for conversion into DVI format in all modern LaTeX
+distributions (since ca. 2006).
 
-If updating LaTeX is not an option, just remove the ``px`` from the length
-specification. HTML/CSS will default to ``px`` while the `latexe2` writer
-will add the fallback unit ``bp``.
+If updating LaTeX is not an option, just remove the "px" from the length
+specification. HTML/CSS will default to "px" while the `latexe2` writer
+will add the fallback unit "bp".
 
 image inclusion
 ```````````````
@@ -1267,13 +1264,13 @@ Bugs and open issues
 
 Open to be fixed or open to discussion.
 
-See also the entries in the `Docutils TODO list`_ and the discussion and
-proposals in the `latex-variants`_ sandbox project.
+See also the entries in the `Docutils TODO list`_.
 
-.. _Docutils TODO list:
-   ../dev/todo.html#latex-writer
-.. _latex-variants:
-   ../../../sandbox/latex-variants/README.html
+.. and the discussion and proposals in the `latex-variants`_ sandbox
+   project.
+
+.. _Docutils TODO list: ../dev/todo.html#latex-writer
+.. _latex-variants: ../../../sandbox/latex-variants/README.html
 
 Footnotes and citations
 ```````````````````````
@@ -1299,6 +1296,8 @@ the end of the document. *This should be customizable*.
 If ``use-latex-citations`` is used adjacent citation references (separated
 only by a single space or a newline) are combined to a single citation
 group, i.e. ``[cite1]_ [cite2]_`` results in ``\cite{cite1,cite2}``.
+The appearance in the output can be configured in a `style sheet`_.
+
 
 Tables
 ``````
@@ -1335,8 +1334,9 @@ Tables
 Figures
 ```````
 
-* Figure (and table) caption alignment of the documentclass overrides the
-  setting by the ``:align:`` argument.
+* Figures are always as wide as the containing text. The "figwidth" argument
+  is currently not supported. As a consequence, the "align" argument has no
+  effect.
 
 * Wrapping text around figures is currently not supported. (Requires the
   `wrapfig`_ package.)
@@ -1346,12 +1346,6 @@ Figures
 Miscellaneous
 `````````````
 
-.. * Selection of LaTeX fontsize configurable (needs an option).
-   What is wrong with ``--documentoptions=12`` or so,
-   maybe combined with extsize or some other package? [GM]
-
-   TODO: test and document
-
 * Pdfbookmark level 4 (and greater) does not work (might be settable but
   complicated).
 
diff --git a/docutils/docutils/transforms/parts.py b/docutils/docutils/transforms/parts.py
index 64de5b5da..64dc721f6 100644
--- a/docutils/docutils/transforms/parts.py
+++ b/docutils/docutils/transforms/parts.py
@@ -30,12 +30,25 @@ class SectNum(Transform):
     """Should be applied before `Contents`."""
 
     def apply(self):
+        try: # leave section numbering to the writer?
+            numbering_by_writer = self.document.settings.use_latex_toc
+        except AttributeError:
+            numbering_by_writer = False
+        #
         self.maxdepth = self.startnode.details.get('depth', sys.maxint)
         self.startvalue = self.startnode.details.get('start', 1)
         self.prefix = self.startnode.details.get('prefix', '')
         self.suffix = self.startnode.details.get('suffix', '')
         self.startnode.parent.remove(self.startnode)
-        if self.document.settings.sectnum_xform:
+        if numbering_by_writer:
+            if self.document.settings.sectnum_xform:
+                self.document.settings.sectnum_depth = self.maxdepth
+            else:
+                self.document.settings.sectnum_depth = 0
+            self.document.settings.sectnum_start = self.startvalue
+            self.document.settings.sectnum_prefix = self.prefix
+            self.document.settings.sectnum_suffix = self.suffix
+        elif self.document.settings.sectnum_xform:
             self.update_section_numbers(self.document)
 
     def update_section_numbers(self, node, prefix=(), depth=0):
@@ -79,14 +92,10 @@ class Contents(Transform):
     default_priority = 720
 
     def apply(self):
-        # build a contents list from the section headings?
-        # if False, the writer (or output software) builds the contents list
-        # Example: the LaTeX writer with option "use-latex-toc".
-        try:
-            build = not(self.document.settings.use_latex_toc)
+        try: # let the writer (or output software) build the contents list?
+            toc_by_writer = self.document.settings.use_latex_toc
         except AttributeError:
-            build = True
-
+            toc_by_writer = False
         details = self.startnode.details
         if 'local' in details:
             startnode = self.startnode.parent.parent
@@ -101,16 +110,16 @@ class Contents(Transform):
             self.backlinks = details['backlinks']
         else:
             self.backlinks = self.document.settings.toc_backlinks
-        if build:
+        if toc_by_writer:
+            # move customization settings to the parent node
+            self.startnode.parent.attributes.update(details)
+            self.startnode.parent.remove(self.startnode)
+        else:
             contents = self.build_contents(startnode)
             if len(contents):
                 self.startnode.replace_self(contents)
             else:
                 self.startnode.parent.parent.remove(self.startnode.parent)
-        else:
-            # pass customization settings to the parent node
-            self.startnode.parent.attributes.update(details)
-            self.startnode.parent.remove(self.startnode)
 
     def build_contents(self, node, level=0):
         level += 1
diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py
index 538314e3d..4b92a2b1c 100644
--- a/docutils/docutils/writers/latex2e/__init__.py
+++ b/docutils/docutils/writers/latex2e/__init__.py
@@ -16,11 +16,9 @@ import os
 import time
 import re
 import string
-from docutils import frontend, nodes, languages, writers, utils
+from docutils import frontend, nodes, languages, writers, utils, transforms
 from docutils.writers.newlatex2e import unicode_map
 
-from docutils.transforms.references import DanglingReferencesVisitor
-
 class Writer(writers.Writer):
 
     supported = ('latex','latex2e')
@@ -78,10 +76,9 @@ class Writer(writers.Writer):
           ' This is the default (if not changed in a config file).',
           ['--link-stylesheet'],
           {'dest': 'embed_stylesheet', 'action': 'store_false'}),
-         ('Table of contents by docutils (default) or LaTeX. LaTeX (writer) '
-          'supports only one ToC per document, but docutils does not know of '
-          'pagenumbers. LaTeX table of contents also means LaTeX generates '
-          'sectionnumbers.',
+         ('Table of contents by Docutils (default) or LaTeX. '
+          '(Docutils does not know of pagenumbers.) '
+	  'With use_latex_toc, LaTeX also generates the section numbers.',
           ['--use-latex-toc'],
           {'default': 0, 'action': 'store_true',
            'validator': frontend.validate_boolean}),
@@ -169,7 +166,9 @@ class Writer(writers.Writer):
           {'default': None, }),
           ),)
 
-    settings_defaults = {'output_encoding': 'latin-1'}
+    settings_defaults = {'output_encoding': 'latin-1',
+                         'sectnum_depth': 0 # updated by SectNum transform
+                        }
 
     relative_path_settings = ('stylesheet_path',)
 
@@ -186,13 +185,15 @@ class Writer(writers.Writer):
         writers.Writer.__init__(self)
         self.translator_class = LaTeXTranslator
 
-    # TODO: footnote collection transform
     # Override parent method to add latex-specific transforms
     ## def get_transforms(self):
     ##    # call the parent class' method
-    ##    # return writers.Writer.get_transforms(self) + [footnotes.collect]
-    ##    return writers.Writer.get_transforms(self)
-     
+    ##    transforms = writers.Writer.get_transforms(self)
+    ##    # print transforms
+    ##    # TODO: footnote collection transform
+    ##    # transforms.append(footnotes.collect)
+    ##    return transforms
+
     def translate(self):
         visitor = self.translator_class(self.document)
         self.document.walkabout(visitor)
@@ -494,6 +495,7 @@ class DocumentClass(object):
         else:
             return self.sections[-1]
 
+
 class Table(object):
     """Manage a table while traversing.
 
@@ -716,7 +718,6 @@ class LaTeXTranslator(nodes.NodeVisitor):
     # Config setting defaults
     # -----------------------
 
-
     # use latex tableofcontents or let docutils do it.
     use_latex_toc = False
     has_latex_toc = False # is there a toc in the doc (needed by minitoc)
@@ -807,6 +808,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
             fontenc_header = '%\\usepackage[OT1]{fontenc}'
         else:
             fontenc_header = '\\usepackage[%s]{fontenc}' % self.font_encoding
+
         if self.settings.graphicx_option == '':
             self.graphicx_package = '\\usepackage{graphicx}'
         elif self.settings.graphicx_option.lower() == 'auto':
@@ -821,6 +823,26 @@ class LaTeXTranslator(nodes.NodeVisitor):
             self.graphicx_package = (
                  r'\usepackage[%s]{graphicx}' % self.settings.graphicx_option)
 
+        if self.use_latex_toc:
+            # include all supported sections (also in PDF bookmarks)
+            self.requirements['tocdepth'] = (r'\setcounter{tocdepth}{%d}' %
+                                             len(self.d_class.sections))
+
+            # section numbering: TODO de-couple latex-toc and latex-sectnum?
+            # limit depth to supported section levels
+            sectnum_depth = min(self.settings.sectnum_depth,
+                                len(self.d_class.sections))
+            sectnum_setup = [r'\setcounter{secnumdepth}{%d}' % sectnum_depth]
+            if settings.sectnum_start != 1:
+                sectnum_setup.append(r'\setcounter{%s}{%d}' %
+                                     (self.d_class.sections[0],
+                                      settings.sectnum_start-1))
+            # currently ignored (use a stylesheet instead):
+            # settings.sectnum_prefix
+            # settings.sectnum_suffix
+            self.requirements['sectnum'] = '\n'.join(sectnum_setup)
+
+
         # packages and/or stylesheets
         # ---------------------------
         self.stylesheet = ['\n%%% User specified packages and stylesheets']
@@ -1836,7 +1858,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
             if isinstance(node.parent, nodes.figure):
                 attrs['align'] = 'center'
             # query 'align-*' class argument
-            for cls in node.get('classes', ''):
+            for cls in node['classes']:
                 if cls.startswith('align-'):
                     attrs['align'] = cls.split('-')[1]
         # pre- and postfix (prefix inserted in reverse order)
@@ -2003,13 +2025,21 @@ class LaTeXTranslator(nodes.NodeVisitor):
             self.literal_block = 0
         self.body.append(self.context.pop())
 
-    def visit_meta(self, node):
-        self.body.append('[visit_meta]\n')
-        # BUG maybe set keywords for pdf
-        ##self.head.append(self.starttag(node, 'meta', **node.attributes))
-
-    def depart_meta(self, node):
-        self.body.append('[depart_meta]\n')
+    ## def visit_meta(self, node):
+    ##     self.body.append('[visit_meta]\n')
+        # TODO: set keywords for pdf?
+        # But:
+        #  The reStructuredText "meta" directive creates a "pending" node,
+        #  which contains knowledge that the embedded "meta" node can only
+        #  be handled by HTML-compatible writers. The "pending" node is
+        #  resolved by the docutils.transforms.components.Filter transform,
+        #  which checks that the calling writer supports HTML; if it doesn't,
+        #  the "pending" node (and enclosed "meta" node) is removed from the
+        #  document.
+        #  --- docutils/docs/peps/pep-0258.html#transformer
+
+    ## def depart_meta(self, node):
+    ##     self.body.append('[depart_meta]\n')
 
     def visit_note(self, node):
         self.visit_admonition(node, 'note')
@@ -2365,7 +2395,13 @@ class LaTeXTranslator(nodes.NodeVisitor):
                 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}{')
+                    # TODO: why a bigskip? (leave this to the style sheet)
                     self.context.append('}\n\\tableofcontents\n\n\\bigskip\n')
                     self.has_latex_toc = True
                 else:
@@ -2406,14 +2442,14 @@ class LaTeXTranslator(nodes.NodeVisitor):
             self.body.append('%' + '_' * 75)
             self.body.append('\n\n')
 
+            section_name = self.d_class.section(self.section_level)
             # (latex)numbered or unnumbered sections:
-            if self.use_latex_toc:
+            if (self.use_latex_toc and
+                (self.section_level <= len(self.d_class.sections))):
                 section_star = ''
             else:
                 section_star = '*'
-
-            section_name = self.d_class.section(self.section_level)
-            self.body.append('\\%s%s{' % (section_name, section_star))
+            self.body.append(r'\%s%s{' % (section_name, section_star))
 
             # System messages heading in red:
             if ('system-messages' in node.parent['classes']):
@@ -2455,9 +2491,9 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.requirements['minitoc-%s' %
                           minitoc_name] = r'\do%stoc' % minitoc_name
         # depth: (Docutils defaults to unlimited depth)
-        max_depth = len(self.d_class.sections)
+        maxdepth = len(self.d_class.sections)
         self.requirements['minitoc-%s-depth' % minitoc_name] = (
-            r'\mtcsetdepth{%stoc}{%d}' % (minitoc_name, max_depth))
+            r'\mtcsetdepth{%stoc}{%d}' % (minitoc_name, maxdepth))
         # TODO: set the depth according to the :depth: argument
         # Attention: Docutils stores a relative depth while minitoc
         # expects an absolute depth!
@@ -2466,7 +2502,6 @@ class LaTeXTranslator(nodes.NodeVisitor):
             offset['part'] = -1
         depth = node.get('depth', 0)
         if depth:
-            # depth += self.section_level
             self.body.append('\\setcounter{%stocdepth}{%d}' %
                              (minitoc_name, depth + offset[minitoc_name]))
         # title:
@@ -2497,9 +2532,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
     def visit_inline(self, node): # <span>, i.e. custom roles
         # insert fallback definition
         self.fallbacks['inline'] = PreambleCmds.inline
-        classes = node.get('classes', [])
-        self.body += [r'\DUrole{%s}{' % cls for cls in classes]
-        self.context.append('}' * (len(classes)))
+        self.body += [r'\DUrole{%s}{' % cls for cls in node['classes']]
+        self.context.append('}' * (len(node['classes'])))
 
     def depart_inline(self, node):
         self.body.append(self.context.pop())
diff --git a/docutils/docutils/writers/latex2e/docutils-05-compat.sty b/docutils/docutils/writers/latex2e/docutils-05-compat.sty
index ff2aa5c79..74989c20f 100644
--- a/docutils/docutils/writers/latex2e/docutils-05-compat.sty
+++ b/docutils/docutils/writers/latex2e/docutils-05-compat.sty
@@ -7,7 +7,7 @@
 % 
 % :Author:    Guenter Milde
 % :Contact:   milde@users.berlios.de
-% :Revision:  $Revision: 5984 $
+% :Revision:  $Revision: 5988 $
 % :Date:      $Date: 2009-02-24$
 % :Copyright: © 2009 G. Milde,
 %             Released  without warranties or conditions of any kind
@@ -299,10 +299,33 @@
 
   \raggedbottom
 
-% Local tocs with `minitoc`
-% -------------------------
+% Better conformance to Docutils specifications with "use_latex_toc"
+% --------------------------------------------------------------------
 % 
 % New feature:
+%   Section numbering is done according to the Docutils specifications also
+%   if 'use-latex-toc' is True:
+% 
+%   * sections are only numbered if there is a "sectnum" directive in the
+%     document and the "sectnum_xforms" config setting is True,
+% 
+%   * The "depth" argument is respected and the default is set to to the
+%     number of supported section levels.
+% 
+% New features:
+%   * The default "depth" of the LaTeX-created ToC is increased to the number
+%     of supported section levels.
+%   * The "depth" argument of the "contents" directive is respected.
+% 
+% Backwards compatibility:
+%   The previous behaviour was to use the document class default and cannot be
+%   restored universally. The following resets it to the default values of the
+%   default document class ("article")::
+
+  \setcounter{secnumdepth}{3}
+  \setcounter{tocdepth}{3}
+
+% New feature:
 %   If 'use-latex-toc' is set, local tables of content are typeset using the
 %   'minitoc' package (instead of being ignored).
 % 
diff --git a/docutils/test/test_writers/test_latex2e.py b/docutils/test/test_writers/test_latex2e.py
index 8a159dbbd..1f0a1c177 100755
--- a/docutils/test/test_writers/test_latex2e.py
+++ b/docutils/test/test_writers/test_latex2e.py
@@ -18,6 +18,7 @@ def suite():
     s.generateTests(totest)
     settings['use_latex_toc'] = 1
     s.generateTests(totest_latex_toc)
+    settings['use_latex_toc'] = 0
     settings['use_latex_citations'] = 1
     s.generateTests(totest_latex_citations)
     return s