New class-argument handling in LaTeX writer.

If the new "legacy_class_functions" setting is False,
class values are handled with wrappers
and admonitions use the ``DUadmonition`` environment.
This will become the new default in 0.18.

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

3 files changed, 127 insertions, 45 deletions

diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index a4ea84290..16a81d2e5 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -1415,13 +1415,6 @@ instead of the `bibliographic fields`_.
 
 Default: off.  Options: ``--use-latex-docinfo, --use-docutils-docinfo``.
 
-docutils_footnotes
-~~~~~~~~~~~~~~~~~~
-Use the Docutils-specific macros ``\DUfootnote`` and
-``\DUfootnotetext`` for footnotes_.
-
-Default: on.  Option: ``--docutils-footnotes``.
-
 use_latex_citations
 ~~~~~~~~~~~~~~~~~~~
 
@@ -1622,7 +1615,6 @@ Option: ``--literal-block-env``.
    A LaTeX verbatim environment is only usable if there is no other
    markup contained in the literal-block.
 
-
 section_prefix_for_enumerators
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1744,6 +1736,30 @@ Default: "T1".  Option: ``--font-encoding``.
 .. _LaTeX font encodings:
    http://mirror.ctan.org/macros/latex/doc/encguide.pdf
 
+legacy_class_functions
+~~~~~~~~~~~~~~~~~~~~~~
+
+Use legacy functions ``\DUtitle`` and ``\DUadmonition`` with a
+comma-separated list of class values as optional argument. If `False`, class
+values are handled with wrappers and admonitions use the ``DUadmonition``
+environment. See `Generating LaTeX with Docutils`__ for details.
+
+Default: True (this will change to False in version 0.18).
+Options: ``--legacy-class-functions``, ``--new-class-functions``.
+
+New in Docutils 0.17.
+
+__ latex.html#classes
+
+docutils_footnotes
+~~~~~~~~~~~~~~~~~~
+Use the Docutils-specific macros ``\DUfootnote`` and
+``\DUfootnotetext`` for footnotes_.
+
+TODO: The alternative, "use_latex_footnotes" is not implemented yet.
+
+Default: on.  Option: ``--docutils-footnotes``.
+
 
 [xetex writer]
 ~~~~~~~~~~~~~~
diff --git a/docutils/docs/user/latex.txt b/docutils/docs/user/latex.txt
index 9c09d9a0a..3c8dd1821 100644
--- a/docutils/docs/user/latex.txt
+++ b/docutils/docs/user/latex.txt
@@ -238,17 +238,8 @@ Example 2:
 * Elements can have multiple class arguments. In contrast to HTML/CSS, the
   order of the class arguments cannot be ignored in LaTeX
 
-* For "historical reasons", class handling differs for some elements and
-  class values:
-
-  * The special macros ``\DUadmonition``, ``\DUtitle``, and ``\DUtopic`` are
-    written with a comma separated list of class values as optional
-    argument.  See http://www.ctan.org/topic/keyval for LaTeX packages that
-    help parsing value lists.
-
-    See the sections on admonitions_, titles_, and the `topic element`_ for
-    customization examples.
-
+* Class handling differs for some elements and class values:
+  
   * Class argument values starting with ``align-`` are transformed to
     "align" argument values. Class argument values starting with
     ``language-`` set the elements language property.
@@ -256,8 +247,14 @@ Example 2:
   * The table element recognizes some special class values. See section
     table_.
 
-.. _"classes" attribute: ../ref/doctree.html#classes
+  * For "historical reasons", the special macros ``\DUadmonition`` and
+    ``\DUtitle`` are written with a comma separated list of class values as
+    optional argument if the legacy-class-functions_ setting is True.
+
+    See the sections on admonitions_ and titles_ for customization examples.
 
+.. _"classes" attribute: ../ref/doctree.html#classes
+.. _legacy-class-functions: config.html#legacy-class-functions
 
 LaTeX code
 ----------
@@ -443,13 +440,17 @@ ordinary body element can.
 __ ../ref/rst/directives.html#admonitions
 
 Command:
-  ``\DUadmonition``
+  ``\DUadmonition`` (with legacy-class-functions_)
+  
+Environment:
+  ``DUadmonition`` (with new-class-functions_)
+ 
+  .. _new-class-functions: legacy-class-functions_
 
 Default:
   Typeset in a frame (90 % of text width).
 
-The admonition title is typeset with the ``\DUtitle`` command which also
-takes a class argument. See `titles`_
+The admonition title is typeset with the ``\DUtitle`` command (see `titles`_).
 
 Example 1:
   A lighter layout without the frame::
@@ -464,13 +465,13 @@ Example 1:
         \end{quote}
       \fi
     }
+    
+  rsp with new-class-functions_::
+  
+    \newenvironment{DUadmonition}%
+      {\begin{quote}}
+      {\end{quote}}
 
-  The first part of this definition acts as a "dispatcher". This way it is
-  possible to define a special handling of `specific admonitions`_ based on
-  the "class" argument.
-
-.. _specific admonitions:
-   ../ref/rst/directives.html#specific-admonitions
 
 Example 2:
   Print admonitions in the margin::
@@ -485,8 +486,15 @@ Example 3:
 
     \newcommand{\DUadmonitionnote}[1]{\marginpar{#1}}
 
+  rsp with new-class-functions_ we re-define the environment in the
+  class-wrapper::
+
+    \newcommand{\DUCLASSnote}{%
+      \renewcommand{\DUadmonition}{\marginpar}
+
   Make sure there is enough space to fit the note.
 
+
 .. _marginnote:
    http://mirror.ctan.org/help/Catalogue/entries/marginnote.html
 
diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py
index 7c50f0ddc..97895a15c 100644
--- a/docutils/docutils/writers/latex2e/__init__.py
+++ b/docutils/docutils/writers/latex2e/__init__.py
@@ -211,6 +211,18 @@ class Writer(writers.Writer):
           '"--use-bibtex=mystyle,mydb1,mydb2".',
           ['--use-bibtex'],
           {'default': ''}),
+         ('Use legacy functions with class value list for '
+          '\\DUtitle and \\DUadmonition (current default). ',
+          ['--legacy-class-functions'],
+          {'default': True,
+           'action': 'store_true',
+           'validator': frontend.validate_boolean}),
+         ('Use \\DUrole and "DUclass" wrappers for class values. '
+          'Place admonition content in an environment (future default).',
+          ['--new-class-functions'],
+          {'dest': 'legacy_class_functions',
+           'action': 'store_false',
+           'validator': frontend.validate_boolean}),
          # TODO: implement "latex footnotes" alternative
          ('Footnotes with numbers/symbols by Docutils. (default) '
           '(The alternative, --latex-footnotes, is not implemented yet.)',
@@ -482,11 +494,17 @@ class SortableDict(dict):
 class PreambleCmds(object):
     """Building blocks for the latex preamble."""
 
-PreambleCmds.abstract = r"""
+PreambleCmds.abstract_legacy = r"""
 % abstract title
 \providecommand*{\DUtitleabstract}[1]{\centerline{\textbf{#1}}}"""
 
-PreambleCmds.admonition = r"""
+PreambleCmds.abstract = r"""
+\providecommand*{\DUCLASSabstract}{
+  \renewcommand{\DUtitle}[1]{\centerline{\textbf{##1}}}
+}"""
+
+# deprecated, see https://sourceforge.net/p/docutils/bugs/339/
+PreambleCmds.admonition_legacy = r"""
 % admonition (specially marked topic)
 \providecommand{\DUadmonition}[2][class-arg]{%
   % try \DUadmonition#1{#2}:
@@ -499,6 +517,22 @@ PreambleCmds.admonition = r"""
   \fi
 }"""
 
+PreambleCmds.admonition = r"""
+% admonition (specially marked topic)
+\ifx\DUadmonition\undefined % poor man's "provideenvironment"
+ \newbox{\DUadmonitionbox}
+ \newenvironment{DUadmonition}%
+  {\begin{center}
+     \begin{lrbox}{\DUadmonitionbox}
+       \begin{minipage}{0.9\linewidth}
+  }%
+  {    \end{minipage}
+     \end{lrbox}
+     \fbox{\usebox{\DUadmonitionbox}}
+   \end{center}
+  }
+\fi"""
+
 ## PreambleCmds.caption = r"""% configure caption layout
 ## \usepackage{caption}
 ## \captionsetup{singlelinecheck=false}% no exceptions for one-liners"""
@@ -515,6 +549,7 @@ PreambleCmds.dedication = r"""
 \providecommand*{\DUCLASSdedication}{%
   \renewenvironment{quote}{\begin{center}}{\end{center}}%
 }"""
+# TODO: add \em to set dedication text in italics.
 
 PreambleCmds.duclass = r"""
 % class handling for environments (block-level elements)
@@ -527,10 +562,13 @@ PreambleCmds.duclass = r"""
   {\csname end\DocutilsClassFunctionName \endcsname}%
 \fi"""
 
-PreambleCmds.error = r"""
+PreambleCmds.error_legacy = r"""
 % error admonition title
 \providecommand*{\DUtitleerror}[1]{\DUtitle{\color{red}#1}}"""
 
+PreambleCmds.error = r"""
+\providecommand*{\DUCLASSerror}{\color{red}}"""
+
 PreambleCmds.fieldlist = r"""
 % fieldlist environment
 \ifthenelse{\isundefined{\DUfieldlist}}{
@@ -682,7 +720,7 @@ PreambleCmds.titlereference = r"""
 % titlereference role
 \providecommand*{\DUroletitlereference}[1]{\textsl{#1}}"""
 
-PreambleCmds.title = r"""
+PreambleCmds.title_legacy = r"""
 % title for topics, admonitions, unsupported section levels, and sidebar
 \providecommand*{\DUtitle}[2][class-arg]{%
   % call \DUtitle#1{#2} if it exists:
@@ -693,6 +731,10 @@ PreambleCmds.title = r"""
   \fi
 }"""
 
+PreambleCmds.title = r"""
+% title for topics, admonitions, unsupported section levels, and sidebar
+\providecommand*{\DUtitle}[1]{\subsubsection*{#1}}"""
+
 PreambleCmds.transition = r"""
 % transition (break, fancybreak, anonymous section)
 \providecommand*{\DUtransition}{%
@@ -1648,7 +1690,6 @@ class LaTeXTranslator(nodes.NodeVisitor):
             if cls.startswith('language-'):
                 language = self.babel.language_name(cls[9:])
                 if language:
-                    self.babel.otherlanguages[language] = True
                     self.out.append('\\end{selectlanguage}\n')
             else:
                 self.fallbacks['DUclass'] = PreambleCmds.duclass
@@ -1691,16 +1732,27 @@ class LaTeXTranslator(nodes.NodeVisitor):
         self.depart_docinfo_item(node)
 
     def visit_admonition(self, node):
-        self.fallbacks['admonition'] = PreambleCmds.admonition
-        if 'error' in node['classes']:
-            self.fallbacks['error'] = PreambleCmds.error
         # strip the generic 'admonition' from the list of classes
         node['classes'] = [cls for cls in node['classes']
                            if cls != 'admonition']
-        self.out.append('\n\\DUadmonition[%s]{' % ','.join(node['classes']))
+        if self.settings.legacy_class_functions:
+            self.fallbacks['admonition'] = PreambleCmds.admonition_legacy
+            if 'error' in node['classes']:
+                self.fallbacks['error'] = PreambleCmds.error_legacy
+            self.out.append('\n\\DUadmonition[%s]{' % ','.join(node['classes']))
+            return
+        self.fallbacks['admonition'] = PreambleCmds.admonition
+        if 'error' in node['classes']:
+            self.fallbacks['error'] = PreambleCmds.error
+        self.duclass_open(node)
+        self.out.append('\\begin{DUadmonition}')
 
     def depart_admonition(self, node):
-        self.out.append('}\n')
+        if self.settings.legacy_class_functions:
+            self.out.append('}\n')
+            return
+        self.out.append('\\end{DUadmonition}\n')
+        self.duclass_close(node)
 
     def visit_author(self, node):
         self.pdfauthor.append(self.attval(node.astext()))
@@ -1780,7 +1832,6 @@ class LaTeXTranslator(nodes.NodeVisitor):
         if self._use_latex_citations:
             self.push_output_collector([])
         else:
-            # TODO: do we need these?
             ## self.requirements['~fnt_floats'] = PreambleCmds.footnote_floats
             self.out.append(r'\begin{figure}[b]')
             self.append_hypertargets(node)
@@ -1813,6 +1864,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
             self.out.append('\\hyperlink{%s}{[' % href)
 
     def depart_citation_reference(self, node):
+        # TODO: normalize labels
         if self._use_latex_citations:
             followup_citation = False
             # check for a following citation separated by a space or newline
@@ -2910,6 +2962,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
     def visit_system_message(self, node):
         self.requirements['color'] = PreambleCmds.color
         self.fallbacks['title'] = PreambleCmds.title
+        if self.settings.legacy_class_functions:
+            self.fallbacks['title'] = PreambleCmds.title_legacy
         node['classes'] = ['system-message']
         self.visit_admonition(node)
         self.out.append('\n\\DUtitle[system-message]{system-message}\n')
@@ -3050,11 +3104,13 @@ class LaTeXTranslator(nodes.NodeVisitor):
         elif (isinstance(node.parent, nodes.topic) or
               isinstance(node.parent, nodes.admonition) or
               isinstance(node.parent, nodes.sidebar)):
-            self.fallbacks['title'] = PreambleCmds.title
-            classes = ','.join(node.parent['classes'])
-            if not classes:
-                classes = node.parent.tagname
-            self.out.append('\n\\DUtitle[%s]{' % classes)
+            classes = node.parent['classes'] or [node.parent.tagname]
+            if self.settings.legacy_class_functions:
+                self.fallbacks['title'] = PreambleCmds.title_legacy
+                self.out.append('\n\\DUtitle[%s]{' % ','.join(classes))
+            else:
+                self.fallbacks['title'] = PreambleCmds.title
+                self.out.append('\n\\DUtitle{')
             self.context.append('}\n')
         # Table caption
         elif isinstance(node.parent, nodes.table):
@@ -3173,6 +3229,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
             # special topics:
             if 'abstract' in node['classes']:
                 self.fallbacks['abstract'] = PreambleCmds.abstract
+                if self.settings.legacy_class_functions:
+                    self.fallbacks['abstract'] = PreambleCmds.abstract_legacy
                 self.push_output_collector(self.abstract)
             elif 'dedication' in node['classes']:
                 self.fallbacks['dedication'] = PreambleCmds.dedication