added comments to "unicode" directive

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

4 files changed, 68 insertions, 10 deletions

diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt
index 0761e21bb..0dd63e154 100644
--- a/docutils/docs/ref/rst/directives.txt
+++ b/docutils/docs/ref/rst/directives.txt
@@ -846,23 +846,27 @@ Unicode Character Codes
 
 :Directive Type: "unicode"
 :Doctree Element: Text
-:Directive Arguments: One or more, required (Unicode character codes
-                      & text).
+:Directive Arguments: One or more, required (Unicode character codes,
+                      optional text, and comments).
 :Directive Options: None.
 :Directive Content: None.
 
 The "unicode" directive converts Unicode character codes (numerical
 values) to characters, and may be used in substitution definitions
 only.  Codes may be decimal numbers, hexadecimal numbers (prefixed by
-``0x``, ``x``, ``\x``, ``u``, or ``\u``), or XML-style numbered
-character entities (e.g. ``ᨫ``).  Codes may be upper- or
-lowercase.  Spaces are ignored, and any other text remains as-is.
+``0x``, ``x``, ``\x``, ``u``, or ``\u``), or XML-style numeric
+character entities (e.g. ``ᨫ``).  Codes are case-insensitive.
+
+Text following " .. " is a comment and is ignored.  Spaces are
+ignored, and any other text remains as-is.
 
 Example::
 
-    "|copy|" is the copyright symbol.
+    Copyright |copy| 2003, |BogusMegaCorp (TM)|.
 
-    .. |copy| unicode:: 0xA9
+    .. |copy| unicode:: 0xA9 .. copyright sign
+    .. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
+       .. with trademark sign
 
 
 Class
diff --git a/docutils/docutils/parsers/rst/directives/misc.py b/docutils/docutils/parsers/rst/directives/misc.py
index c220c84cb..581c10269 100644
--- a/docutils/docutils/parsers/rst/directives/misc.py
+++ b/docutils/docutils/parsers/rst/directives/misc.py
@@ -158,8 +158,9 @@ def unicode_directive(name, arguments, options, content, lineno,
     r"""
     Convert Unicode character codes (numbers) to characters.  Codes may be
     decimal numbers, hexadecimal numbers (prefixed by ``0x``, ``x``, ``\x``,
-    ``u``, or ``\u``), or XML-style numbered character entities (e.g.
-    ``ᨫ``).
+    ``U+``, ``u``, or ``\u``; e.g. ``U+262E``), or XML-style numeric character
+    entities (e.g. ``☮``).  Text following ".." is a comment and is
+    ignored.  Spaces are ignored, and any other text remains as-is.
     """
     if not isinstance(state, states.SubstitutionDef):
         error = state_machine.reporter.error(
@@ -167,7 +168,7 @@ def unicode_directive(name, arguments, options, content, lineno,
             'substitution definition.' % (name),
             nodes.literal_block(block_text, block_text), line=lineno)
         return [error]
-    codes = arguments[0].split()
+    codes = arguments[0].split('.. ')[0].split()
     element = nodes.Element()
     for code in codes:
         try:
diff --git a/docutils/test/test_parsers/test_rst/test_directives/test_unicode.py b/docutils/test/test_parsers/test_rst/test_directives/test_unicode.py
index e3964dab5..704c13fa5 100755
--- a/docutils/test/test_parsers/test_rst/test_directives/test_unicode.py
+++ b/docutils/test/test_parsers/test_rst/test_directives/test_unicode.py
@@ -96,6 +96,33 @@ Bad input:
         <literal_block xml:space="preserve">
             .. unicode:: not in a substitution definition
 """],
+["""
+Testing comments and extra text.
+
+Copyright |copy| 2003, |BogusMegaCorp (TM)|.
+
+.. |copy| unicode:: 0xA9 .. copyright sign
+.. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
+   .. with trademark sign
+""",
+u"""\
+<document source="test data">
+    <paragraph>
+        Testing comments and extra text.
+    <paragraph>
+        Copyright 
+        <substitution_reference refname="copy">
+            copy
+         2003, 
+        <substitution_reference refname="BogusMegaCorp (TM)">
+            BogusMegaCorp (TM)
+        .
+    <substitution_definition name="copy">
+        \u00A9
+    <substitution_definition name="BogusMegaCorp (TM)">
+        BogusMegaCorp
+        \u2122
+"""],
 ]
 
 
diff --git a/docutils/test/test_transforms/test_substitutions.py b/docutils/test/test_transforms/test_substitutions.py
index 46c36dd9c..503dfba40 100755
--- a/docutils/test/test_transforms/test_substitutions.py
+++ b/docutils/test/test_transforms/test_substitutions.py
@@ -117,6 +117,32 @@ u"""\
     <substitution_definition name="Omega">
         \u03a9
 """],
+["""
+Testing comments and extra text.
+
+Copyright |copy| 2003, |BogusMegaCorp (TM)|.
+
+.. |copy| unicode:: 0xA9 .. copyright sign
+.. |BogusMegaCorp (TM)| unicode:: BogusMegaCorp U+2122
+   .. with trademark sign
+""",
+u"""\
+<document source="test data">
+    <paragraph>
+        Testing comments and extra text.
+    <paragraph>
+        Copyright \n\
+        \u00a9
+         2003, \n\
+        BogusMegaCorp
+        \u2122
+        .
+    <substitution_definition name="copy">
+        \u00a9
+    <substitution_definition name="BogusMegaCorp (TM)">
+        BogusMegaCorp
+        \u2122
+"""],
 ])