Apply patch #174 Lowercase new role names on registration

and document that role names are case insensitive.

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

2 files changed, 13 insertions, 4 deletions

diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt
index 146450605..7ff8717d2 100644
--- a/docutils/docs/ref/rst/directives.txt
+++ b/docutils/docs/ref/rst/directives.txt
@@ -1775,7 +1775,7 @@ Custom Interpreted Text Roles
 
 :Directive Type: "role"
 :Doctree Element: None; affects subsequent parsing.
-:Directive Arguments: Two; one required (new role name), one optional
+:Directive Arguments: Two; one required (new `role name`_), one optional
                       (base role name, in parentheses).
 :Directive Options: Possible (depends on base role).
 :Directive Content: depends on base role.
@@ -1801,6 +1801,12 @@ This will be parsed into the following document tree fragment::
 
 The role must be declared in a document before it can be used.
 
+.. _role name:
+
+Role names are case insensitive and must conform to the rules of
+simple `reference names`_ (but do not share a namespace with
+hyperlinks, footnotes, and citations).
+
 The new role may be based on an existing role, specified as a second
 argument in parentheses (whitespace optional)::
 
@@ -1966,7 +1972,8 @@ _`:name:` : text
     New in Docutils 0.8.
 
 
-.. _reference name: restructuredtext.html#reference-names
+.. _reference name:
+.. _reference names: restructuredtext.html#reference-names
 .. _hyperlink target: restructuredtext.html#hyperlink-targets
 .. _hyperlink references: restructuredtext.html#hyperlink-references
 .. _class names: ../doctree.html#classnames-type
diff --git a/docutils/docs/ref/rst/restructuredtext.txt b/docutils/docs/ref/rst/restructuredtext.txt
index bfb0a4f89..a350ef090 100644
--- a/docutils/docs/ref/rst/restructuredtext.txt
+++ b/docutils/docs/ref/rst/restructuredtext.txt
@@ -372,6 +372,7 @@ appear in Python docstrings is to use raw docstrings::
 
     r"""This is a raw docstring.  Backslashes (\) are not touched."""
 
+.. _reference name:
 
 Reference Names
 ===============
@@ -2669,7 +2670,8 @@ Interpreted text allows extensions to the available inline descriptive
 markup constructs.  To emphasis_, `strong emphasis`_, `inline
 literals`_, and `hyperlink references`_, we can add "title reference",
 "index entry", "acronym", "class", "red", "blinking" or anything else
-we want.  Only pre-determined roles are recognized; unknown roles will
+we want (as long as it is a simple `reference name`_).
+Only pre-determined roles are recognized; unknown roles will
 generate errors.  A core set of standard roles is implemented in the
 reference parser; see `reStructuredText Interpreted Text Roles`_ for
 individual descriptions.  The role_ directive can be used to define
@@ -2888,7 +2890,7 @@ by a trailing underscore.  Footnote labels are one of:
 
 - a single "#" (denoting `auto-numbered footnotes`_),
 
-- a "#" followed by a simple reference name (an `autonumber label`_),
+- a "#" followed by a simple `reference name`_ (an `autonumber label`_),
   or
 
 - a single "*" (denoting `auto-symbol footnotes`_).