LaTeX writer: Deprecation warning for ``\docutilsrole``-prefix.

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

12 files changed, 40 insertions, 9 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index a3b1f613e..85046057e 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -50,6 +50,7 @@ Changes Since 0.15
   - Make "rubric" bold-italic and left aligned.
   - Fix [ 339 ] don't use "alltt" or literal-block-environment
     in admonitions and footnotes.
+  - Deprecation warning for ``\docutilsrole``-prefixed styling commands.
 
 * docutils/writers/odf_odt/__init__.py:
 
diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt
index 940c5238d..3529b15f6 100644
--- a/docutils/RELEASE-NOTES.txt
+++ b/docutils/RELEASE-NOTES.txt
@@ -22,12 +22,13 @@ For a more detailed list of changes, please see the `Docutils History`_.
 Future changes
 ==============
 
-* The "latex" writer will handle admonitions like other block-level elements
-  and wrap them in a "DUclass" environment. The current implementation fails
-  with some content, see docs/user/latex.txt and
-  https://sourceforge.net/p/docutils/bugs/339/
+* The "latex" writer will wrap admonitions in a "DUclass" environment.
   If your custom stylesheets modify "\DUadmonition" to style admonitions,
-  you will need to adapt them after upgrading to versions > 0.15.
+  you will need to adapt them after upgrading to versions > 0.16.
+  Styling commands using ``\docutilsrole`` prefix will be ignored
+  in versions > 0.16 (see `Generating LaTeX with Docutils`__).
+  
+  __ docs/user/latex.html#classes
 
 * Remove the `handle_io_errors` option from io.FileInput/Output.
   Used by Sphinx up to version 1.3.1, fixed in 1.3.2 (Nov 29, 2015).
@@ -72,6 +73,12 @@ Release 0.16
 
   __ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism
 
+* LaTeX writer:
+
+  - Informal titles of type "rubric" default to bold-italic and left aligned.
+  - Deprecate ``\docutilsrole`` prefix for styling commands:
+    use ``\DUrole`` instead.
+
 
 Release 0.15
 ============
diff --git a/docutils/docs/user/latex.txt b/docutils/docs/user/latex.txt
index 03ff7639c..e44a7dcc4 100644
--- a/docutils/docs/user/latex.txt
+++ b/docutils/docs/user/latex.txt
@@ -468,17 +468,22 @@ Example 1:
    ../ref/rst/directives.html#specific-admonitions
 
 Example 2:
-  Use ``.. note::`` for a margin note::
+  Print admonitions in the margin::
+
+    \newcommand{\DUadmonition}[2][class-arg]{\marginpar{#2}}
+
+  Make sure there is enough space to fit the note.
+  See also the marginnote_ package.
+
+Example 3:
+  Use the ``.. note::`` admonition for a margin note::
 
     \newcommand{\DUadmonitionnote}[1]{\marginpar{#1}}
 
   Make sure there is enough space to fit the note.
-  See also the marginnote_ and pdfcomment_ packages.
 
 .. _marginnote:
    http://mirror.ctan.org/help/Catalogue/entries/marginnote.html
-.. _pdfcomment:
-   http://mirror.ctan.org/help/Catalogue/entries/pdfcomment.html
 
 
 .. _custom role:
diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py
index a9433aa98..f3e49ecd4 100644
--- a/docutils/docutils/writers/latex2e/__init__.py
+++ b/docutils/docutils/writers/latex2e/__init__.py
@@ -578,6 +578,8 @@ PreambleCmds.inline = r"""
   \else
     % backwards compatibility: try \docutilsrole#1{#2}
     \ifcsname docutilsrole#1\endcsname%
+      \PackageWarningNoLine{docutils}{Command prefix "docutilsrole" is
+         deprecated, \MessageBreak use `\protect\DUrole #1`}
       \csname docutilsrole#1\endcsname{#2}%
     \else%
       #2%
diff --git a/docutils/test/functional/expected/latex_literal_block.tex b/docutils/test/functional/expected/latex_literal_block.tex
index cdf5e4deb..e7934bcbe 100644
--- a/docutils/test/functional/expected/latex_literal_block.tex
+++ b/docutils/test/functional/expected/latex_literal_block.tex
@@ -64,6 +64,8 @@
   \else
     % backwards compatibility: try \docutilsrole#1{#2}
     \ifcsname docutilsrole#1\endcsname%
+      \PackageWarningNoLine{docutils}{Command prefix "docutilsrole" is
+         deprecated, \MessageBreak use `\protect\DUrole #1`}
       \csname docutilsrole#1\endcsname{#2}%
     \else%
       #2%
diff --git a/docutils/test/functional/expected/latex_literal_block_fancyvrb.tex b/docutils/test/functional/expected/latex_literal_block_fancyvrb.tex
index 74ed27872..becfeb351 100644
--- a/docutils/test/functional/expected/latex_literal_block_fancyvrb.tex
+++ b/docutils/test/functional/expected/latex_literal_block_fancyvrb.tex
@@ -64,6 +64,8 @@
   \else
     % backwards compatibility: try \docutilsrole#1{#2}
     \ifcsname docutilsrole#1\endcsname%
+      \PackageWarningNoLine{docutils}{Command prefix "docutilsrole" is
+         deprecated, \MessageBreak use `\protect\DUrole #1`}
       \csname docutilsrole#1\endcsname{#2}%
     \else%
       #2%
diff --git a/docutils/test/functional/expected/latex_literal_block_listings.tex b/docutils/test/functional/expected/latex_literal_block_listings.tex
index 5142b5667..f461089d4 100644
--- a/docutils/test/functional/expected/latex_literal_block_listings.tex
+++ b/docutils/test/functional/expected/latex_literal_block_listings.tex
@@ -70,6 +70,8 @@
   \else
     % backwards compatibility: try \docutilsrole#1{#2}
     \ifcsname docutilsrole#1\endcsname%
+      \PackageWarningNoLine{docutils}{Command prefix "docutilsrole" is
+         deprecated, \MessageBreak use `\protect\DUrole #1`}
       \csname docutilsrole#1\endcsname{#2}%
     \else%
       #2%
diff --git a/docutils/test/functional/expected/latex_literal_block_verbatim.tex b/docutils/test/functional/expected/latex_literal_block_verbatim.tex
index b77262626..124da0cc4 100644
--- a/docutils/test/functional/expected/latex_literal_block_verbatim.tex
+++ b/docutils/test/functional/expected/latex_literal_block_verbatim.tex
@@ -63,6 +63,8 @@
   \else
     % backwards compatibility: try \docutilsrole#1{#2}
     \ifcsname docutilsrole#1\endcsname%
+      \PackageWarningNoLine{docutils}{Command prefix "docutilsrole" is
+         deprecated, \MessageBreak use `\protect\DUrole #1`}
       \csname docutilsrole#1\endcsname{#2}%
     \else%
       #2%
diff --git a/docutils/test/functional/expected/latex_literal_block_verbatimtab.tex b/docutils/test/functional/expected/latex_literal_block_verbatimtab.tex
index 57ea0aaee..e66236452 100644
--- a/docutils/test/functional/expected/latex_literal_block_verbatimtab.tex
+++ b/docutils/test/functional/expected/latex_literal_block_verbatimtab.tex
@@ -64,6 +64,8 @@
   \else
     % backwards compatibility: try \docutilsrole#1{#2}
     \ifcsname docutilsrole#1\endcsname%
+      \PackageWarningNoLine{docutils}{Command prefix "docutilsrole" is
+         deprecated, \MessageBreak use `\protect\DUrole #1`}
       \csname docutilsrole#1\endcsname{#2}%
     \else%
       #2%
diff --git a/docutils/test/functional/expected/standalone_rst_latex.tex b/docutils/test/functional/expected/standalone_rst_latex.tex
index 280e3b21e..026b75a7d 100644
--- a/docutils/test/functional/expected/standalone_rst_latex.tex
+++ b/docutils/test/functional/expected/standalone_rst_latex.tex
@@ -109,6 +109,8 @@
   \else
     % backwards compatibility: try \docutilsrole#1{#2}
     \ifcsname docutilsrole#1\endcsname%
+      \PackageWarningNoLine{docutils}{Command prefix "docutilsrole" is
+         deprecated, \MessageBreak use `\protect\DUrole #1`}
       \csname docutilsrole#1\endcsname{#2}%
     \else%
       #2%
diff --git a/docutils/test/functional/expected/standalone_rst_xetex.tex b/docutils/test/functional/expected/standalone_rst_xetex.tex
index 4dcf6e2c2..b18f16849 100644
--- a/docutils/test/functional/expected/standalone_rst_xetex.tex
+++ b/docutils/test/functional/expected/standalone_rst_xetex.tex
@@ -108,6 +108,8 @@
   \else
     % backwards compatibility: try \docutilsrole#1{#2}
     \ifcsname docutilsrole#1\endcsname%
+      \PackageWarningNoLine{docutils}{Command prefix "docutilsrole" is
+         deprecated, \MessageBreak use `\protect\DUrole #1`}
       \csname docutilsrole#1\endcsname{#2}%
     \else%
       #2%
diff --git a/docutils/test/test_writers/test_latex2e.py b/docutils/test/test_writers/test_latex2e.py
index 9208bb73e..4e2de8dfa 100755
--- a/docutils/test/test_writers/test_latex2e.py
+++ b/docutils/test/test_writers/test_latex2e.py
@@ -84,6 +84,8 @@ fallbacks_highlight = r"""% basic code highlight:
   \else
     % backwards compatibility: try \docutilsrole#1{#2}
     \ifcsname docutilsrole#1\endcsname%
+      \PackageWarningNoLine{docutils}{Command prefix "docutilsrole" is
+         deprecated, \MessageBreak use `\protect\DUrole #1`}
       \csname docutilsrole#1\endcsname{#2}%
     \else%
       #2%