New "name" directive option attaching a reference name.

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

23 files changed, 426 insertions, 145 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 59489e4f4..f5dc80f5b 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -34,7 +34,12 @@ Changes Since 0.7
 
   .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
   .. _COPYING: COPYING.html
-  
+
+* reStructuredText:
+
+  - most directives now support a "name" option that attaches a
+    reference name.
+
 * docs/dev/policies.txt:
 
   - Recommend the 2-Clause BSD license
diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt
index 8d1969bbb..8fe218477 100644
--- a/docutils/RELEASE-NOTES.txt
+++ b/docutils/RELEASE-NOTES.txt
@@ -23,14 +23,8 @@ Changes Since 0.7
 
 * COPYING:
 
-  The XeTeX writer and the math subpackage are, in accordance with the
-  `Docutils policies`_, licensed under the `Apache License version 2.0`_.
-  Note, that this license is `compatible with GPL`_ version 3, but not
-  GPL version 2.
-
-  .. _Docutils policies: docs/dev/policies.txt
-  .. _Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
-  .. _compatible with GPL: http://www.gnu.org/licenses/license-list.html
+  - Some additions to the Docutils core are released under the 2-Clause BSD
+    license.
 
 * General:
 
@@ -41,7 +35,22 @@ Changes Since 0.7
     ``math`` and ``math_block`` doctree elements.
   - Orphaned "python" reader and "newlatex2e" writer moved to the sandbox.
 
-.. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
+  .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
+
+* reStructuredText:
+
+  - most directives now support a "name" option that attaches a
+    reference name. So you can write ::
+
+      .. figure:: image.png
+         :name: figure name
+
+    as a short form of ::
+
+      .. _figure name:
+
+      .. figure:: image.png
+
 
 
 Release 0.7 (2010-07-07)
diff --git a/docutils/docs/dev/rst/alternatives.txt b/docutils/docs/dev/rst/alternatives.txt
index ba5c7f448..726b536fb 100644
--- a/docutils/docs/dev/rst/alternatives.txt
+++ b/docutils/docs/dev/rst/alternatives.txt
@@ -3134,6 +3134,33 @@ idea, and there is no "tool tip" in formats other than HTML.
 Add a "term" role for unfamiliar or specialized terminology?  Probably
 not; there is no real use case, and emphasis is enough for most cases.
 
+
+Object references
+=================
+
+We need syntax for `object references`_.
+
+  - Parameterized substitutions?  For example::
+
+        See |figure (figure name)| on |page (figure name)|.
+
+        .. |figure (name)| figure-ref:: (name)
+        .. |page (name)| page-ref:: (name)
+
+    The result would be::
+
+        See figure 3.11 on page 157.
+
+    But this would require substitution directives to be processed at
+    reference-time, not at definition-time as they are now.  Or,
+    perhaps the directives could just leave ``pending`` elements
+    behind, and the transforms do the work?  How to pass the data
+    through? Too complicated. Use interpreted text roles.
+
+.. _object references:
+   ../todo.html#object-numbering-and-object-references
+
+
 
 ..
    Local Variables:
diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index 2c636bc47..8a2c05b6f 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -42,6 +42,8 @@ Below are action items that must be added and issues that must be
 addressed before Docutils can be considered suitable to be proposed
 for inclusion in the Python standard library.
 
+Many of these are now handled by Sphinx_
+
 * Support for `document splitting`_.  May require some major code
   rework.
 
@@ -61,13 +63,10 @@ for inclusion in the Python standard library.
 
 * Plugin support.
 
-* A LaTeX writer making use of (La)TeX's power, so that the rendering
-  of the resulting documents is more easily customizable.  (Similar to
-  what you wrote about a new HTML Writer.)
-
 * Suitability for `Python module documentation
   <http://docutils.sf.net/sandbox/README.html#documenting-python>`_.
 
+.. _Sphinx: http://sphinx.pocoo.org/
 
 General
 =======
@@ -212,103 +211,6 @@ General
 * Perhaps the ``Component.supports`` method should deal with
   individual features ("meta" etc.) instead of formats ("html" etc.)?
 
-* Add _`object numbering and object references` (tables & figures).
-  These would be the equivalent of DocBook's "formal" elements.
-
-  We may need _`persistent sequences`, such as chapter numbers.  See
-  `OpenOffice.org XML`_ "fields".  Should the sequences be automatic
-  or manual (user-specifyable)?
-
-  We need to name the objects:
-
-  - "name" option for the "figure" directive? ::
-
-        .. figure:: image.png
-           :name: image's name
-
-    Same for the "table" directive::
-
-        .. table:: optional title here
-           :name: table's name
-
-           =====  =====
-             x    not x
-           =====  =====
-           True   False
-           False  True
-           =====  =====
-
-    This would also allow other options to be set, like border
-    styles.  The same technique could be used for other objects.
-
-    A preliminary "table" directive has been implemented, supporting
-    table titles.  Perhaps the name should derive from the title.
-
-  - The object could also be done this way::
-
-        .. _figure name:
-
-        .. figure:: image.png
-
-    This may be a more general solution, equally applicable to tables.
-    However, explicit naming using an option seems simpler to users.
-
-  - Perhaps the figure name could be incorporated into the figure
-    definition, as an optional inline target part of the directive
-    argument::
-
-        .. figure:: _`figure name` image.png
-
-    Maybe with a delimiter::
-
-        .. figure:: _`figure name`: image.png
-
-    Or some other, simpler syntax.
-
-  We'll also need syntax for object references.  See `OpenOffice.org
-  XML`_ "reference fields":
-
-  - Parameterized substitutions?  For example::
-
-        See |figure (figure name)| on |page (figure name)|.
-
-        .. |figure (name)| figure-ref:: (name)
-        .. |page (name)| page-ref:: (name)
-
-    The result would be::
-
-        See figure 3.11 on page 157.
-
-    But this would require substitution directives to be processed at
-    reference-time, not at definition-time as they are now.  Or,
-    perhaps the directives could just leave ``pending`` elements
-    behind, and the transforms do the work?  How to pass the data
-    through?  Too complicated.
-
-  - An interpreted text approach is simpler and better::
-
-        See :figure:`figure name` on :page:`figure name`.
-
-    The "figure" and "page" roles could generate appropriate
-    boilerplate text.  The position of the role (prefix or suffix)
-    could also be utilized.
-
-    See `Interpreted Text`_ below.
-
-  - We could leave the boilerplate text up to the document::
-
-        See Figure :fig:`figure name` on page :pg:`figure name`.
-
-  - Reference boilerplate could be specified in the document
-    (defaulting to nothing)::
-
-        .. fignum::
-           :prefix-ref: "Figure "
-           :prefix-caption: "Fig. "
-           :suffix-caption: :
-
-  .. _OpenOffice.org XML: http://xml.openoffice.org/
-
 * Think about _`large documents` made up of multiple subdocument
   files.  Issues: continuity (`persistent sequences`_ above),
   cross-references (`name-to-id mapping file`_ above and `targets in
@@ -581,6 +483,75 @@ General
   latex writer to switch to a LaTeX generated ToC (currently, the latex
   writer calls it "use_latex_toc").
 
+object numbering and object references
+--------------------------------------
+
+For equations, tables & figures.
+
+These would be the equivalent of DocBook's "formal" elements.
+
+In LaTeX, automatic counters are implemented for sections, equations and
+floats (figures, tables) (configurable via stylesheets or in the
+latex-preamble). Objects can be given `reference names`_ with the
+``\label{<refname}`` command, ``\ref{<refname>}`` inserts the
+corresponding number.
+
+No such mechanism exists in HTML.
+
+* We need _`persistent sequences`, similar to chapter and footnote
+  numbers. See `OpenOffice.org XML`_ "fields".
+
+  - Should the sequences be automatic or manual (user-specifyable)?
+
+* It is already possible to give `reference names`_ to objects via
+  internal hyperlink targets or the "name" directive option::
+
+      .. _figure name:
+
+      .. figure:: image.png
+
+  or ::
+
+      .. figure:: image.png
+         :name: figure name
+
+  A "table" directive has been implemented, supporting table titles.
+
+  Perhaps the name could derive from the title/caption?
+
+  .. _reference names: ../ref/rst/restructuredtext.html#reference-names
+
+* We need syntax for object references.  Cf. `OpenOffice.org XML`_
+  "reference fields":
+
+  - Parameterized substitutions are too complicated
+    (cf. `or not to do`: `object references`_)
+
+  - An interpreted text approach is simpler and better::
+
+      See Figure :ref:`figure name` and Equation :ref:`eq:identity`.
+
+  - "equation", "figure", and "page" roles could generate appropriate
+    boilerplate text::
+
+        See :figure:`figure name` on :page:`figure name`.
+
+    See `Interpreted Text`_ below.
+
+    Reference boilerplate could be specified in the document
+    (defaulting to nothing)::
+
+        .. fignum::
+           :prefix-ref: "Figure "
+           :prefix-caption: "Fig. "
+           :suffix-caption: :
+
+    The position of the role (prefix or suffix) could also be utilized
+
+  .. _OpenOffice.org XML: http://xml.openoffice.org/
+  .. _object references: rst/alternatives.html#object-references
+
+
 Documentation
 =============
 
@@ -1333,12 +1304,17 @@ images
 OpenOffice output
 `````````````````
 
-* MathML_ can be imported by the Math module.
+* The `OpenDocument standard`_ version 1.1 says:
+
+    Mathematical content is represented by MathML 2.0
 
-  However, putting MathML into an ODP file seems tricky:
+  However, putting MathML into an ODP file seems tricky as these
+  (maybe outdated) links suppose:
   http://idippedut.dk/post/2008/01/25/Do-your-math-ODF-and-MathML.aspx
   http://idippedut.dk/post/2008/03/03/Now-I-get-it-ODF-and-MathML.aspx
 
+  .. _OpenDocument standard:
+    http://www.oasis-open.org/standards#opendocumentv1.1
 
 * OOoLaTeX__:  "a set of macros designed to bring the power of LaTeX
   into OpenOffice."
diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt
index e46f22628..cba118406 100644
--- a/docutils/docs/ref/rst/directives.txt
+++ b/docutils/docs/ref/rst/directives.txt
@@ -231,12 +231,15 @@ The following options are recognized:
 ``target`` : text (URI or reference name)
     Makes the image into a hyperlink reference ("clickable").  The
     option argument may be a URI (relative or absolute), or a
-    reference name with underscore suffix (e.g. ``name_``).
+    `reference name`_ with underscore suffix (e.g. ```a name`_``).
 
 ``class`` : text
     Set a "classes" attribute value on the image element.  See the
     class_ directive below.
 
+``name`` : text
+    Attach text as a `reference name`_ to the image element. [#name-option]_
+
 
 Figure
 ======
@@ -353,12 +356,15 @@ interpreted as body elements.  For example::
         the body of the topic, and are
         interpreted as body elements.
 
-The following option is recognized:
+The following options are recognized:
 
 ``class`` : text
     Set a "classes" attribute value on the topic element.  See the
     class_ directive below.
 
+``name`` : text
+    Attach text as a `reference name`_ to the topic element. [#name-option]_
+
 
 Sidebar
 =======
@@ -400,6 +406,10 @@ The following options are recognized:
     Set a "classes" attribute value on the sidebar element.  See the
     class_ directive below.
 
+``name`` : text
+    Attach text as a `reference name`_ to the sidebar element.
+    [#name-option]_
+
 
 Line Block
 ==========
@@ -438,12 +448,16 @@ example, here's a classic::
                 as soon as it comes.
             Love, Ewan.
 
-The following option is recognized:
+The following options are recognized:
 
 ``class`` : text
     Set a "classes" attribute value on the line_block element.  See the
     class_ directive below.
 
+``name`` : text
+    Attach text as a `reference name`_ to the line_block element.
+    [#name-option]_
+
 
 .. _parsed-literal:
 
@@ -479,12 +493,16 @@ For example, all the element names in this content model are links::
          (docinfo_, transition_?)?,
          `%structure.model;`_ )
 
-The following option is recognized:
+The following options are recognized:
 
 ``class`` : text
     Set a "classes" attribute value on the literal_block element.  See
     the class_ directive below.
 
+``name`` : text
+    Attach text as a `reference name`_ to the literal_block element.
+    [#name-option]_
+
 
 Math
 ====
@@ -493,8 +511,8 @@ Math
 :Doctree Element: math-block
 :Directive Arguments: One, optional: prepended to content.
 :Directive Options: Possible.
-:Directive Content: Interpreted as math block(s). 
-                    Content blocks separated by a blank line are put in 
+:Directive Content: Interpreted as math block(s).
+                    Content blocks separated by a blank line are put in
                     separate math-block doctree elements.
 
 The "math" directive inserts block(s) with mathematical content
@@ -520,6 +538,10 @@ The following options are recognized:
     Set a "classes" attribute value on the block element.  See the
     class_ directive.
 
+``name`` : text
+    Attach text as a `reference name`_ to the math_block element.
+    [#name-option]_
+
 New in Docutils 0.8.
 
 .. _Short Math Guide: ftp://ftp.ams.org/ams/doc/amsmath/short-math-guide.pdf
@@ -547,12 +569,15 @@ The "rubric" directive inserts a "rubric" element into the document
 tree.  A rubric is like an informal heading that doesn't correspond to
 the document's structure.
 
-The following option is recognized:
+The following options are recognized:
 
 ``class`` : text
     Set a "classes" attribute value on the rubric element.  See the
     class_ directive below.
 
+``name`` : text
+    Attach text as a `reference name`_ to the rubric element. [#name-option]_
+
 
 Epigraph
 ========
@@ -669,12 +694,16 @@ unity:
 * vertical spacing between physical elements may be reduced;
 * and so on.
 
-The following option is recognized:
+The following options are recognized:
 
 ``class`` : text
     Set a "classes" attribute value on the compound element.  See the
     class_ directive below.
 
+``name`` : text
+    Attach text as a `reference name`_ to the compound element.
+    [#name-option]_
+
 
 Container
 =========
@@ -706,6 +735,12 @@ The "container" directive is the equivalent of HTML's ``<div>``
 element.  It may be used to group a sequence of elements for user- or
 application-specific purposes.
 
+The following option is recognized:
+
+``name`` : text
+    Attach text as a `reference name`_ to the container element.
+    [#name-option]_
+
 
 --------
  Tables
@@ -741,12 +776,15 @@ title with a table::
        True   False
        =====  =====
 
-The following option is recognized:
+The following options are recognized:
 
 ``class`` : text
     Set a "classes" attribute value on the table element.  See the
     class_ directive below.
 
+``name`` : text
+    Attach text as a `reference name`_ to the table element. [#name-option]_
+
 
 .. _csv-table:
 
@@ -804,6 +842,9 @@ The following options are recognized:
     Set a "classes" attribute value on the table element.  See the
     class_ directive below.
 
+``name`` : text
+    Attach text as a `reference name`_ to the table element. [#name-option]_
+
 ``widths`` : integer [, integer...]
     A comma- or space-separated list of relative column widths.  The
     default is equal-width columns (100%/#columns).
@@ -902,6 +943,9 @@ The following options are recognized:
     Set a "classes" attribute value on the table element.  See the
     class_ directive below.
 
+``name`` : text
+    Attach text as a `reference name`_ to the table element. [#name-option]_
+
 ``widths`` : integer [integer...]
     A comma- or space-separated list of relative column widths.  The
     default is equal-width columns (100%/#columns).
@@ -1105,12 +1149,16 @@ reference.  For every explicit target (of the form, ``.. _target name:
 URL``) in the text, a footnote will be generated containing the
 visible URL as content.
 
-The following option is recognized:
+The following options are recognized:
 
 ``class`` : text
     Set a "classes" attribute value on all footnote_reference elements.
     See the class_ directive below.
 
+``name`` : text
+    Attach text as a `reference name`_ to the first footnote_reference
+    element. [#name-option]_
+
 
 Footnotes
 =========
@@ -1794,6 +1842,28 @@ level-1 (info) system message showing the directive data, possibly
 followed by a literal block containing the rest of the directive
 block.
 
+.. _reference name: restructuredtext.html#reference-names
+.. _hyperlink target: restructuredtext.html#hyperlink-targets
+.. _hyperlink references: restructuredtext.html#hyperlink-references
+
+.. [#name-option] The `name` option adds its value to the "names"
+   attribute of the doctree element generated by the directive. This
+   allows `hyperlink references`_ to the element.
+
+   Specifying the `name` option of a directive like ::
+
+     .. image:: bild.png
+        :name: my picture
+
+   is a concise syntax alternative to preceding it with a `hyperlink
+   target`_ ::
+
+     .. _my picture:
+
+     .. image:: bild.png
+
+   New in Docutils 0.8.
+
 
 ..
    Local Variables:
diff --git a/docutils/docutils/parsers/rst/__init__.py b/docutils/docutils/parsers/rst/__init__.py
index 140fa364b..328ebd9ed 100644
--- a/docutils/docutils/parsers/rst/__init__.py
+++ b/docutils/docutils/parsers/rst/__init__.py
@@ -347,6 +347,18 @@ class Directive(object):
             raise self.error('Content block expected for the "%s" directive; '
                              'none found.' % self.name)
 
+    def add_name(self, node):
+        """Append self.options['name'] to node['names'] if it exists.
+
+        Also normalize the name string and register it as explicit target.
+        """
+        if 'name' in self.options:
+            name = nodes.fully_normalize_name(self.options.pop('name'))
+            if 'name' in node:
+                del(node['name'])
+            node['names'].append(name)
+            self.state.document.note_explicit_target(node, node)
+
 
 def convert_directive_function(directive_fn):
     """
diff --git a/docutils/docutils/parsers/rst/directives/body.py b/docutils/docutils/parsers/rst/directives/body.py
index e666ba29f..dd9b7be9c 100644
--- a/docutils/docutils/parsers/rst/directives/body.py
+++ b/docutils/docutils/parsers/rst/directives/body.py
@@ -23,7 +23,8 @@ class BasePseudoSection(Directive):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec = {'class': directives.class_option}
+    option_spec = {'class': directives.class_option,
+                   'name': directives.unchanged}
     has_content = True
 
     node_class = None
@@ -48,6 +49,7 @@ class BasePseudoSection(Directive):
         text = '\n'.join(self.content)
         node = self.node_class(text, *(titles + messages))
         node['classes'] += self.options.get('class', [])
+        self.add_name(node)
         if text:
             self.state.nested_parse(self.content, self.content_offset, node)
         return [node]
@@ -74,12 +76,14 @@ class Sidebar(BasePseudoSection):
 
 class LineBlock(Directive):
 
-    option_spec = {'class': directives.class_option}
+    option_spec = {'class': directives.class_option,
+                   'name': directives.unchanged}
     has_content = True
 
     def run(self):
         self.assert_has_content()
         block = nodes.line_block(classes=self.options.get('class', []))
+        self.add_name(block)
         node_list = [block]
         for line_text in self.content:
             text_nodes, messages = self.state.inline_text(
@@ -96,7 +100,8 @@ class LineBlock(Directive):
 
 class ParsedLiteral(Directive):
 
-    option_spec = {'class': directives.class_option}
+    option_spec = {'class': directives.class_option,
+                   'name': directives.unchanged}
     has_content = True
 
     def run(self):
@@ -106,20 +111,20 @@ class ParsedLiteral(Directive):
         text_nodes, messages = self.state.inline_text(text, self.lineno)
         node = nodes.literal_block(text, '', *text_nodes, **self.options)
         node.line = self.content_offset + 1
+        self.add_name(node)
         return [node] + messages
 
 
 class MathBlock(Directive):
 
-    has_content = True
     required_arguments = 0
     optional_arguments = 1
     final_argument_whitespace = True
-    option_spec = {'class': directives.class_option
-                   ## TODO: support Sphinx' ``mathbase.py`` options?
-                   # 'label': directives.unchanged,
+    option_spec = {'class': directives.class_option,
+                   'name': directives.unchanged}
+                   ## TODO: Add Sphinx' ``mathbase.py`` option 'nowrap'?
                    # 'nowrap': directives.flag,
-                  }
+    has_content = True
 
     def run(self):
         set_classes(self.options)
@@ -133,6 +138,7 @@ class MathBlock(Directive):
                 continue
             node = nodes.math_block(self.block_text, block, **self.options)
             node.line = self.content_offset + 1
+            self.add_name(node)
             _nodes.append(node)
         return _nodes
 
@@ -142,13 +148,15 @@ class Rubric(Directive):
     required_arguments = 1
     optional_arguments = 0
     final_argument_whitespace = True
-    option_spec = {'class': directives.class_option}
+    option_spec = {'class': directives.class_option,
+                   'name': directives.unchanged}
 
     def run(self):
         set_classes(self.options)
         rubric_text = self.arguments[0]
         textnodes, messages = self.state.inline_text(rubric_text, self.lineno)
         rubric = nodes.rubric(rubric_text, '', *textnodes, **self.options)
+        self.add_name(rubric)
         return [rubric] + messages
 
 
@@ -183,7 +191,8 @@ class PullQuote(BlockQuote):
 
 class Compound(Directive):
 
-    option_spec = {'class': directives.class_option}
+    option_spec = {'class': directives.class_option,
+                   'name': directives.unchanged}
     has_content = True
 
     def run(self):
@@ -191,6 +200,7 @@ class Compound(Directive):
         text = '\n'.join(self.content)
         node = nodes.compound(text)
         node['classes'] += self.options.get('class', [])
+        self.add_name(node)
         self.state.nested_parse(self.content, self.content_offset, node)
         return [node]
 
@@ -200,6 +210,7 @@ class Container(Directive):
     required_arguments = 0
     optional_arguments = 1
     final_argument_whitespace = True
+    option_spec = {'name': directives.unchanged}
     has_content = True
 
     def run(self):
@@ -216,5 +227,6 @@ class Container(Directive):
                 % (self.name, self.arguments[0]))
         node = nodes.container(text)
         node['classes'].extend(classes)
+        self.add_name(node)
         self.state.nested_parse(self.content, self.content_offset, node)
         return [node]
diff --git a/docutils/docutils/parsers/rst/directives/images.py b/docutils/docutils/parsers/rst/directives/images.py
index 3f5dd9bc4..7ac9d7768 100644
--- a/docutils/docutils/parsers/rst/directives/images.py
+++ b/docutils/docutils/parsers/rst/directives/images.py
@@ -42,6 +42,7 @@ class Image(Directive):
                    'width': directives.length_or_percentage_or_unitless,
                    'scale': directives.percentage,
                    'align': align,
+                   'name': directives.unchanged,
                    'target': directives.unchanged_required,
                    'class': directives.class_option}
 
@@ -85,6 +86,7 @@ class Image(Directive):
             del self.options['target']
         set_classes(self.options)
         image_node = nodes.image(self.block_text, **self.options)
+        self.add_name(image_node)
         if reference_node:
             reference_node += image_node
             return messages + [reference_node]
diff --git a/docutils/docutils/parsers/rst/directives/references.py b/docutils/docutils/parsers/rst/directives/references.py
index b086f0265..43d9f5751 100644
--- a/docutils/docutils/parsers/rst/directives/references.py
+++ b/docutils/docutils/parsers/rst/directives/references.py
@@ -18,11 +18,12 @@ class TargetNotes(Directive):
 
     """Target footnote generation."""
 
-    option_spec = {'class': directives.class_option}
+    option_spec = {'class': directives.class_option,
+                   'name': directives.unchanged}
 
     def run(self):
         pending = nodes.pending(references.TargetNotes)
+        self.add_name(pending)
         pending.details.update(self.options)
         self.state_machine.document.note_pending(pending)
-        nodelist = [pending]
-        return nodelist
+        return [pending]
diff --git a/docutils/docutils/parsers/rst/directives/tables.py b/docutils/docutils/parsers/rst/directives/tables.py
index 748557620..f8bb52add 100644
--- a/docutils/docutils/parsers/rst/directives/tables.py
+++ b/docutils/docutils/parsers/rst/directives/tables.py
@@ -29,7 +29,8 @@ class Table(Directive):
     required_arguments = 0
     optional_arguments = 1
     final_argument_whitespace = True
-    option_spec = {'class': directives.class_option}
+    option_spec = {'class': directives.class_option,
+                   'name': directives.unchanged}
     has_content = True
 
     def make_title(self):
@@ -130,6 +131,7 @@ class RSTTable(Table):
             return [error]
         table_node = node[0]
         table_node['classes'] += self.options.get('class', [])
+        self.add_name(table_node)
         if title:
             table_node.insert(0, title)
         return [table_node] + messages
@@ -145,6 +147,7 @@ class CSVTable(Table):
                    'url': directives.uri,
                    'encoding': directives.encoding,
                    'class': directives.class_option,
+                   'name': directives.unchanged,
                    # field delimiter char
                    'delim': directives.single_char_or_whitespace_or_unicode,
                    # treat whitespace after delimiter as significant
@@ -230,6 +233,7 @@ class CSVTable(Table):
         table_node = self.state.build_table(table, self.content_offset,
                                             stub_columns)
         table_node['classes'] += self.options.get('class', [])
+        self.add_name(table_node)
         if title:
             table_node.insert(0, title)
         return [table_node] + messages
@@ -354,7 +358,8 @@ class ListTable(Table):
     option_spec = {'header-rows': directives.nonnegative_int,
                    'stub-columns': directives.nonnegative_int,
                    'widths': directives.positive_int_list,
-                   'class': directives.class_option}
+                   'class': directives.class_option,
+                   'name': directives.unchanged}
 
     def run(self):
         if not self.content:
@@ -378,6 +383,7 @@ class ListTable(Table):
         table_node = self.build_table_from_list(table_data, col_widths,
                                                 header_rows, stub_columns)
         table_node['classes'] += self.options.get('class', [])
+        self.add_name(table_node)
         if title:
             table_node.insert(0, title)
         return [table_node] + messages
diff --git a/docutils/docutils/writers/latex2e/__init__.py b/docutils/docutils/writers/latex2e/__init__.py
index 66e2549bb..cc3471a9e 100644
--- a/docutils/docutils/writers/latex2e/__init__.py
+++ b/docutils/docutils/writers/latex2e/__init__.py
@@ -2431,7 +2431,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
             self.visit_inline(node)
         self.requirements['amsmath'] = r'\usepackage{amsmath}'
         math_code = node.astext().translate(unimathsymbols2tex.uni2tex_table)
-        if node.get('id') == node.get('name'):  # explicite label
+        if node.get('ids'):
             math_code = '\n'.join([math_code] + self.ids_to_labels(node))
         if math_env == '$':
             wrapper = u'$%s$'
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_container.py b/docutils/test/test_parsers/test_rst/test_directives/test_container.py
index 72f35ae5b..a97a02061 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_container.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_container.py
@@ -66,6 +66,21 @@ totest['container'] = [
         <paragraph>
             Multiple paragraphs in the container.
 """],
+["""\
+.. container::
+   :name: my name
+
+   The name argument allows hyperlinks to `my name`_.
+""",
+"""\
+<document source="test data">
+    <container ids="my-name" names="my\ name">
+        <paragraph>
+            The name argument allows hyperlinks to 
+            <reference name="my name" refname="my name">
+                my name
+            .
+"""],
 ]
 
 
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_figures.py b/docutils/test/test_parsers/test_rst/test_directives/test_figures.py
index 196329885..56544ec3c 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_figures.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_figures.py
@@ -93,13 +93,14 @@ totest['figures'] = [
    :scale: 50
    :figwidth: 300
    :figclass: class1 class2
+   :name: fig:pix
 
    A picture with image options on individual lines, and this caption.
 """,
 """\
 <document source="test data">
     <figure classes="class1 class2" width="300px">
-        <image alt="alternate text" height="100" scale="50" uri="picture.png" width="200">
+        <image alt="alternate text" height="100" ids="fig-pix" names="fig:pix" scale="50" uri="picture.png" width="200">
         <caption>
             A picture with image options on individual lines, and this caption.
 """],
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_images.py b/docutils/test/test_parsers/test_rst/test_directives/test_images.py
index bd6de06c8..0fb21a0bf 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_images.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_images.py
@@ -283,11 +283,12 @@ totest['images'] = [
 ["""\
 .. image:: picture.png
    :target: bigpicture.png
+   :name: fig:pix
 """,
 """\
 <document source="test data">
     <reference refuri="bigpicture.png">
-        <image uri="picture.png">
+        <image ids="fig-pix" names="fig:pix" uri="picture.png">
 """],
 ["""\
 .. image:: picture.png
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_line_blocks.py b/docutils/test/test_parsers/test_rst/test_directives/test_line_blocks.py
index bd8e67fc8..289fd6741 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_line_blocks.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_line_blocks.py
@@ -41,6 +41,19 @@ totest['line_blocks'] = [
 """],
 ["""\
 .. line-block::
+   :class: linear
+   :name:  cit:short
+   
+   This is a line block with options.
+""",
+"""\
+<document source="test data">
+    <line_block classes="linear" ids="cit-short" names="cit:short">
+        <line>
+            This is a line block with options.
+"""],
+["""\
+.. line-block::
 
    Inline markup *may not span
        multiple lines* of a line block.
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_math.py b/docutils/test/test_parsers/test_rst/test_directives/test_math.py
index 00e56c7e6..f115aee09 100644
--- a/docutils/test/test_parsers/test_rst/test_directives/test_math.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_math.py
@@ -41,6 +41,21 @@ totest['content'] = [
 """],
 ]
 
+totest['options'] = [
+["""\
+.. math::
+  :class: new
+  :name: eq:Eulers law
+
+  e^i*2*\pi = 1
+""",
+"""\
+<document source="test data">
+    <math_block classes="new" ids="eq-eulers-law" names="eq:eulers\ law" xml:space="preserve">
+        e^i*2*\pi = 1
+"""],
+]
+
 totest['argument_and_content'] = [
 ["""\
 .. math:: y = f(x)
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 50b8303bf..61c12ad42 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
@@ -35,6 +35,18 @@ totest['parsed_literals'] = [
             spanning lines.
 """],
 ["""\
+.. parsed-literal::
+  :class: myliteral
+  :name: example: parsed
+
+   This is a parsed literal block with options.
+""",
+"""\
+<document source="test data">
+    <literal_block classes="myliteral" ids="example-parsed" names="example:\ parsed" xml:space="preserve">
+         This is a parsed literal block with options.
+"""],
+["""\
 .. parsed-literal:: argument
 """,
 """\
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_rubrics.py b/docutils/test/test_parsers/test_rst/test_directives/test_rubrics.py
index e01551fd8..8601a2fbc 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_rubrics.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_rubrics.py
@@ -67,10 +67,11 @@ totest['rubrics'] = [
 ["""\
 .. rubric:: A Rubric
    :class: foo bar
+   :name: Foo Rubric
 """,
 """\
 <document source="test data">
-    <rubric classes="foo bar">
+    <rubric classes="foo bar" ids="foo-rubric" names="foo\ rubric">
         A Rubric
 """],
 ]
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_sidebars.py b/docutils/test/test_parsers/test_rst/test_directives/test_sidebars.py
index 71e95ed56..dc614a85c 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_sidebars.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_sidebars.py
@@ -39,6 +39,24 @@ totest['sidebars'] = [
                    Body.
 """],
 ["""\
+.. sidebar:: Margin Notes
+   :subtitle: with options
+   :class: margin
+   :name: note:Options
+
+   Body.
+""",
+"""\
+<document source="test data">
+    <sidebar classes="margin" ids="note-options" names="note:options">
+        <title>
+            Margin Notes
+        <subtitle>
+            with options
+        <paragraph>
+            Body.
+"""],
+["""\
 .. sidebar:: Outer
 
    .. topic:: Topic
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_tables.py b/docutils/test/test_parsers/test_rst/test_directives/test_tables.py
index 587ff70eb..0ae1e00e7 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_tables.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_tables.py
@@ -49,6 +49,7 @@ totest['table'] = [
 ["""\
 .. table:: Truth table for "not"
    :class: custom
+   :name:  tab:truth.not
 
    =====  =====
      A    not A
@@ -59,7 +60,7 @@ totest['table'] = [
 """,
 """\
 <document source="test data">
-    <table classes="custom">
+    <table classes="custom" ids="tab-truth-not" names="tab:truth.not">
         <title>
             Truth table for "not"
         <tgroup cols="2">
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_target_notes.py b/docutils/test/test_parsers/test_rst/test_directives/test_target_notes.py
index efef623a8..2991a5996 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_target_notes.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_target_notes.py
@@ -40,6 +40,19 @@ totest['target-notes'] = [
                class: ['custom']
 """],
 ["""\
+.. target-notes:: 
+   :class: custom
+   :name: targets
+""",
+"""\
+<document source="test data">
+    <pending ids="targets" names="targets">
+        .. internal attributes:
+             .transform: docutils.transforms.references.TargetNotes
+             .details:
+               class: ['custom']
+"""],
+["""\
 .. target-notes::
    :class:
 """,
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_topics.py b/docutils/test/test_parsers/test_rst/test_directives/test_topics.py
index 43dc96c8c..789c0eba0 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_topics.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_topics.py
@@ -55,6 +55,21 @@ totest['topics'] = [
             Body.
 """],
 ["""\
+.. topic:: With Options
+   :class: custom
+   :name: my point
+
+   Body.
+""",
+"""\
+<document source="test data">
+    <topic classes="custom" ids="my-point" names="my\ point">
+        <title>
+            With Options
+        <paragraph>
+            Body.
+"""],
+["""\
 .. topic::
 
    Title
diff --git a/docutils/test/test_parsers/test_rst/test_targets.py b/docutils/test/test_parsers/test_rst/test_targets.py
index 1afaaef8e..56358357b 100755
--- a/docutils/test/test_parsers/test_rst/test_targets.py
+++ b/docutils/test/test_parsers/test_rst/test_targets.py
@@ -249,6 +249,30 @@ Paragraph.
             Paragraph.
 """],
 ["""\
+Duplicate implicit/directive targets.
+
+Title
+=====
+
+.. target-notes::
+   :name: title
+""",
+"""\
+<document source="test data">
+    <paragraph>
+        Duplicate implicit/directive targets.
+    <section dupnames="title" ids="title">
+        <title>
+            Title
+        <pending ids="id1" names="title">
+            <system_message backrefs="id1" level="1" line="4" source="test data" type="INFO">
+                <paragraph>
+                    Duplicate implicit target name: "title".
+            .. internal attributes:
+                 .transform: docutils.transforms.references.TargetNotes
+                 .details:
+"""],
+["""\
 Duplicate explicit targets.
 
 .. _title:
@@ -284,6 +308,30 @@ Third.
         Third.
 """],
 ["""\
+Duplicate explicit/directive targets.
+
+.. _title:
+
+First.
+
+.. rubric:: this is a title too
+   :name: title
+
+""",
+"""\
+<document source="test data">
+    <paragraph>
+        Duplicate explicit/directive targets.
+    <target dupnames="title" ids="title">
+    <paragraph>
+        First.
+    <rubric dupnames="title" ids="id1">
+        this is a title too
+        <system_message backrefs="id1" level="2" line="9" source="test data" type="WARNING">
+            <paragraph>
+                Duplicate explicit target name: "title".
+"""],
+["""\
 Duplicate targets:
 
 Target
@@ -291,7 +339,7 @@ Target
 
 Implicit section header target.
 
-.. [target] Citation target.
+.. [TARGET] Citation target.
 
 .. [#target] Autonumber-labeled footnote target.
 
@@ -300,6 +348,9 @@ Implicit section header target.
 Explicit internal target.
 
 .. _target: Explicit_external_target
+
+.. rubric:: directive with target
+   :name: Target
 """,
 """\
 <document source="test data">
@@ -312,7 +363,7 @@ Explicit internal target.
             Implicit section header target.
         <citation dupnames="target" ids="id1">
             <label>
-                target
+                TARGET
             <system_message backrefs="id1" level="1" line="8" source="test data" type="INFO">
                 <paragraph>
                     Duplicate implicit target name: "target".
@@ -334,6 +385,11 @@ Explicit internal target.
             <paragraph>
                 Duplicate explicit target name: "target".
         <target dupnames="target" ids="id4" refuri="Explicit_external_target">
+        <rubric dupnames="target" ids="id5">
+            directive with target
+            <system_message backrefs="id5" level="2" line="4" source="test data" type="WARNING">
+                <paragraph>
+                    Duplicate explicit target name: "target".
 """],
 ["""\
 .. _unescaped colon at end:: no good