Common directive options:

Add "name" and "class" options to admonition directives.

Directive content may start on the first line also when the directive
type accepts options.

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

9 files changed, 58 insertions, 38 deletions

diff --git a/docutils/test/functional/expected/math_output_html.html b/docutils/test/functional/expected/math_output_html.html
index aac8b3ba4..7c9c72b4e 100644
--- a/docutils/test/functional/expected/math_output_html.html
+++ b/docutils/test/functional/expected/math_output_html.html
@@ -22,12 +22,14 @@ role specificator, <span class="formula">
 <div class="formula">
 <i>f</i>(<i>ϵ</i>) = <span class="fraction"><span class="ignored">(</span><span class="numerator">1</span><span class="ignored">)/(</span><span class="denominator">1 + exp<span class="array"><span class="arrayrow"><span class="bracket align-left">⎛</span></span><span class="arrayrow"><span class="bracket align-left">⎝</span></span></span><span class="fraction"><span class="ignored">(</span><span class="numerator"><i>ε</i></span><span class="ignored">)/(</span><span class="denominator"><i>k</i><sub><span class="text">B</span></sub><i>T</i></span><span class="ignored">)</span></span><span class="array"><span class="arrayrow"><span class="bracket align-right">⎞</span></span><span class="arrayrow"><span class="bracket align-right">⎠</span></span></span></span><span class="ignored">)</span></span>
 </div>
-<p>A display formula can also be given as directive argument, e.g.</p>
+<p>Content may start on the first line of the directive, e.g.</p>
 <div class="formula">
 <i>N</i> = <span class="fraction"><span class="ignored">(</span><span class="numerator"><span class="text">number of apples</span></span><span class="ignored">)/(</span><span class="denominator">7</span><span class="ignored">)</span></span>
 </div>
+<p>Equations can be labeled with a reference name using the <tt class="docutils literal">:name:</tt> option.
+See <a class="reference internal" href="#eq-m">eq:M</a> and <a class="reference internal" href="#eq-schrodinger">eq:schrödinger</a> below.</p>
 <p>The determinant of the matrix</p>
-<div class="formula">
+<div class="formula" id="eq-m">
 <b>M</b> = <span class="array"><span class="arrayrow"><span class="bracket align-left">⎛</span></span><span class="arrayrow"><span class="bracket align-left">⎜</span></span><span class="arrayrow"><span class="bracket align-left">⎝</span></span></span><span class="array"><span class="arrayrow">
 <span class="arraycell align-c">
 <i>a</i>
@@ -71,7 +73,7 @@ For example, the following sum and integral with limits:</p>
 <p>LaTeX-supported Unicode math symbols can be used in math roles and
 directives:</p>
 <p>The Schrödinger equation</p>
-<div class="formula">
+<div class="formula" id="eq-schrodinger">
 <i>i</i>ℏ<span class="fraction"><span class="ignored">(</span><span class="numerator">∂</span><span class="ignored">)/(</span><span class="denominator">∂<i>t</i></span><span class="ignored">)</span></span>Ψ = <i>Ĥ</i>Ψ, 
 </div>
 <p>with the <em>wave function</em> <span class="formula">
diff --git a/docutils/test/functional/expected/math_output_latex.html b/docutils/test/functional/expected/math_output_latex.html
index d9aa8ba45..54050f347 100644
--- a/docutils/test/functional/expected/math_output_latex.html
+++ b/docutils/test/functional/expected/math_output_latex.html
@@ -22,12 +22,14 @@ A_\text{c} =
 <pre class="math">
 f(\epsilon) = \frac{1}{1 + \exp\left(\frac{\varepsilon}{k_\text{B}T}\right)}
 </pre>
-<p>A display formula can also be given as directive argument, e.g.</p>
+<p>Content may start on the first line of the directive, e.g.</p>
 <pre class="math">
 N = \frac{\text{number of apples}}{7}
 </pre>
+<p>Equations can be labeled with a reference name using the <tt class="docutils literal">:name:</tt> option.
+See <a class="reference internal" href="#eq-m">eq:M</a> and <a class="reference internal" href="#eq-schrodinger">eq:schrödinger</a> below.</p>
 <p>The determinant of the matrix</p>
-<pre class="math">
+<pre class="math" id="eq-m">
 \mathbf{M} = \left(\begin{matrix}a&amp;b\\c&amp;d\end{matrix}\right)
 </pre>
 <p>is <tt class="math">
@@ -44,7 +46,7 @@ For example, the following sum and integral with limits:</p>
 <p>LaTeX-supported Unicode math symbols can be used in math roles and
 directives:</p>
 <p>The Schrödinger equation</p>
-<pre class="math">
+<pre class="math" id="eq-schrodinger">
 i\hbar \frac{\partial }{\partial t}\Psi  = \hat{H}\Psi ,
 </pre>
 <p>with the <em>wave function</em> <tt class="math">
diff --git a/docutils/test/functional/expected/math_output_mathjax.html b/docutils/test/functional/expected/math_output_mathjax.html
index 011697c73..b4e6b114b 100644
--- a/docutils/test/functional/expected/math_output_mathjax.html
+++ b/docutils/test/functional/expected/math_output_mathjax.html
@@ -25,14 +25,16 @@ role specificator, <span class="math">
 f(\epsilon) = \frac{1}{1 + \exp\left(\frac{\varepsilon}{k_\text{B}T}\right)}
 \end{equation*}
 </div>
-<p>A display formula can also be given as directive argument, e.g.</p>
+<p>Content may start on the first line of the directive, e.g.</p>
 <div class="math">
 \begin{equation*}
 N = \frac{\text{number of apples}}{7}
 \end{equation*}
 </div>
+<p>Equations can be labeled with a reference name using the <tt class="docutils literal">:name:</tt> option.
+See <a class="reference internal" href="#eq-m">eq:M</a> and <a class="reference internal" href="#eq-schrodinger">eq:schrödinger</a> below.</p>
 <p>The determinant of the matrix</p>
-<div class="math">
+<div class="math" id="eq-m">
 \begin{equation*}
 \mathbf{M} = \left(\begin{matrix}a&amp;b\\c&amp;d\end{matrix}\right)
 \end{equation*}
@@ -55,7 +57,7 @@ For example, the following sum and integral with limits:</p>
 <p>LaTeX-supported Unicode math symbols can be used in math roles and
 directives:</p>
 <p>The Schrödinger equation</p>
-<div class="math">
+<div class="math" id="eq-schrodinger">
 \begin{equation*}
 i\hbar \frac{\partial }{\partial t}\Psi  = \hat{H}\Psi ,
 \end{equation*}
diff --git a/docutils/test/functional/expected/math_output_mathml.xhtml b/docutils/test/functional/expected/math_output_mathml.xhtml
index 1e949a0a5..1298d349d 100644
--- a/docutils/test/functional/expected/math_output_mathml.xhtml
+++ b/docutils/test/functional/expected/math_output_mathml.xhtml
@@ -29,7 +29,7 @@ role specificator, <math xmlns="http://www.w3.org/1998/Math/MathML">
 <mrow><mi>ε</mi></mrow>
 <mrow><msub><mi>k</mi><mtext>B</mtext></msub><mi>T</mi></mrow></mfrac></mrow></mfenced></mrow></mfrac></mtd></mtr></mtable></math>
 </div>
-<p>A display formula can also be given as directive argument, e.g.</p>
+<p>Content may start on the first line of the directive, e.g.</p>
 <div>
 <math xmlns="http://www.w3.org/1998/Math/MathML" mode="display">
 <mtable>
@@ -38,8 +38,10 @@ role specificator, <math xmlns="http://www.w3.org/1998/Math/MathML">
 <mrow><mtext>number of apples</mtext></mrow>
 <mrow><mn>7</mn></mrow></mfrac></mtd></mtr></mtable></math>
 </div>
+<p>Equations can be labeled with a reference name using the <tt class="docutils literal">:name:</tt> option.
+See <a class="reference internal" href="#eq-m">eq:M</a> and <a class="reference internal" href="#eq-schrodinger">eq:schrödinger</a> below.</p>
 <p>The determinant of the matrix</p>
-<div>
+<div id="eq-m">
 <math xmlns="http://www.w3.org/1998/Math/MathML" mode="display">
 <mtable>
 <mtr>
@@ -79,7 +81,7 @@ For example, the following sum and integral with limits:</p>
 <p>LaTeX-supported Unicode math symbols can be used in math roles and
 directives:</p>
 <p>The Schrödinger equation</p>
-<div>
+<div id="eq-schrodinger">
 <math xmlns="http://www.w3.org/1998/Math/MathML" mode="display">
 <mtable>
 <mtr>
@@ -203,7 +205,7 @@ physical system changes in time.</p>
 <p>Cases with the <a class="reference external" href="ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf">AMSmath</a> <tt class="docutils literal">cases</tt> environment (not (yet) supported by
 HTML writers with <tt class="docutils literal"><span class="pre">--math-output=MathML</span></tt>):</p>
 <div class="system-message">
-<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/math.txt</tt>, line 102)</p>
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">functional/input/data/math.txt</tt>, line 108)</p>
 <p>
 Environment not supported! Supported environment: "matrix".</p>
 <pre class="literal-block">
diff --git a/docutils/test/functional/expected/standalone_rst_latex.tex b/docutils/test/functional/expected/standalone_rst_latex.tex
index b5ff60f1f..2db3ff0cb 100644
--- a/docutils/test/functional/expected/standalone_rst_latex.tex
+++ b/docutils/test/functional/expected/standalone_rst_latex.tex
@@ -1646,15 +1646,20 @@ role specificator, $n! + \sin(x_n^2)$ and $A_\text{c} =
 \begin{equation*}
 f(\epsilon) = \frac{1}{1 + \exp\left(\frac{\varepsilon}{k_\text{B}T}\right)}
 \end{equation*}
-A display formula can also be given as directive argument, e.g.
+Content may start on the first line of the directive, e.g.
 %
 \begin{equation*}
 N = \frac{\text{number of apples}}{7}
 \end{equation*}
+Equations can be labeled with a reference name using the \texttt{:name:} option.
+See \hyperref[eq-m]{eq:M} and \hyperref[eq-schrodinger]{eq:schrödinger} below.
+
 The determinant of the matrix
 %
 \begin{equation*}
 \mathbf{M} = \left(\begin{matrix}a&b\\c&d\end{matrix}\right)
+\phantomsection
+\label{eq-m}
 \end{equation*}
 is $|\mathbf{M}| = ad - bc$.
 
@@ -1674,6 +1679,8 @@ The Schrödinger equation
 %
 \begin{equation*}
 i\hbar \frac{\partial }{\partial t}\Psi  = \hat{H}\Psi ,
+\phantomsection
+\label{eq-schrodinger}
 \end{equation*}
 with the \emph{wave function} $\Psi $, describes how the quantum state of a
 physical system changes in time.
diff --git a/docutils/test/functional/input/data/math.txt b/docutils/test/functional/input/data/math.txt
index bd2190aad..15acdcdd0 100644
--- a/docutils/test/functional/input/data/math.txt
+++ b/docutils/test/functional/input/data/math.txt
@@ -10,13 +10,16 @@ role specificator, :math:`n! + \sin(x_n^2)` and `A_\text{c} =
 
    f(\epsilon) = \frac{1}{1 + \exp\left(\frac{\varepsilon}{k_\text{B}T}\right)}
 
-A display formula can also be given as directive argument, e.g.
+Content may start on the first line of the directive, e.g.
 
 .. math:: N = \frac{\text{number of apples}}{7}
 
+Equations can be labeled with a reference name using the ``:name:`` option.
+See `eq:M`_ and `eq:schrödinger`_ below.
+
 The determinant of the matrix
 
-.. math::
+.. math:: :name: eq:M
 
    \mathbf{M} = \left(\begin{matrix}a&b\\c&d\end{matrix}\right)
 
@@ -36,7 +39,10 @@ directives:
 
 The Schrödinger equation
 
-.. math:: i\hbar \frac{∂}{∂t}Ψ = \hat{H}Ψ,
+.. math:: :name: eq:schrödinger
+
+   i\hbar \frac{∂}{∂t}Ψ = \hat{H}Ψ,
+   
 
 with the *wave function* :math:`Ψ`, describes how the quantum state of a
 physical system changes in time.
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_admonitions.py b/docutils/test/test_parsers/test_rst/test_directives/test_admonitions.py
index 30870f3d5..c4a01800d 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_admonitions.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_admonitions.py
@@ -21,7 +21,10 @@ totest['admonitions'] = [
 ["""\
 .. Attention:: Directives at large.
 
-.. Note:: This is a note.
+.. Note:: :name: mynote
+   :class: testnote
+
+   Admonitions support the generic "name" and "class" options.
 
 .. Tip:: 15% if the
    service is good.
@@ -49,9 +52,9 @@ totest['admonitions'] = [
     <attention>
         <paragraph>
             Directives at large.
-    <note>
+    <note classes="testnote" ids="mynote" names="mynote">
         <paragraph>
-            This is a note.
+            Admonitions support the generic "name" and "class" options.
     <tip>
         <paragraph>
             15% if the
@@ -147,12 +150,13 @@ totest['admonitions'] = [
 ["""\
 .. admonition:: Admonition
    :class: emergency
+   :name: reference name
 
    Test the "class" override.
 """,
 """\
 <document source="test data">
-    <admonition classes="emergency">
+    <admonition classes="emergency" ids="reference-name" names="reference\ name">
         <title>
             Admonition
         <paragraph>
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_compound.py b/docutils/test/test_parsers/test_rst/test_directives/test_compound.py
index 0b7ba6eee..c27030fb0 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_compound.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_compound.py
@@ -55,6 +55,8 @@ totest['compound'] = [
 """],
 ["""\
 .. compound::
+   :name: interesting
+   :class: log
 
    This is an extremely interesting compound paragraph containing a
    simple paragraph, a literal block with some useless log messages::
@@ -68,7 +70,7 @@ totest['compound'] = [
 """,
 """\
 <document source="test data">
-    <compound>
+    <compound classes="log" ids="interesting" names="interesting">
         <paragraph>
             This is an extremely interesting compound paragraph containing a
             simple paragraph, a literal block with some useless log messages:
@@ -81,20 +83,17 @@ totest['compound'] = [
             of the first simple paragraph, with the literal block in between.
 """],
 ["""\
-.. compound:: arg1 arg2
+.. compound:: content may start on same line
 
-   text
+   second paragraph
 """,
 """\
 <document source="test data">
-    <system_message level="3" line="1" source="test data" type="ERROR">
+    <compound>
         <paragraph>
-            Error in "compound" directive:
-            no arguments permitted; blank line required before content block.
-        <literal_block xml:space="preserve">
-            .. compound:: arg1 arg2
-            \n\
-               text
+            content may start on same line
+        <paragraph>
+            second paragraph
 """],
 ]
 
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_parsed_literals.py b/docutils/test/test_parsers/test_rst/test_directives/test_parsed_literals.py
index 61c12ad42..6cfefeaa7 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_parsed_literals.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_parsed_literals.py
@@ -47,16 +47,12 @@ totest['parsed_literals'] = [
          This is a parsed literal block with options.
 """],
 ["""\
-.. parsed-literal:: argument
+.. parsed-literal:: content may start on same line
 """,
 """\
 <document source="test data">
-    <system_message level="3" line="1" source="test data" type="ERROR">
-        <paragraph>
-            Error in "parsed-literal" directive:
-            no arguments permitted; blank line required before content block.
-        <literal_block xml:space="preserve">
-            .. parsed-literal:: argument
+    <literal_block xml:space="preserve">
+        content may start on same line
 """],
 ["""\
 .. parsed-literal::