docs/ref/: Update the description of class name transformation

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

3 files changed, 38 insertions, 18 deletions

diff --git a/docutils/docs/ref/doctree.txt b/docutils/docs/ref/doctree.txt
index 8c16a75ca..6627ed65c 100644
--- a/docutils/docs/ref/doctree.txt
+++ b/docutils/docs/ref/doctree.txt
@@ -4433,7 +4433,11 @@ The ``bullet`` attribute is used in the bullet_list_ element.
 `Attribute type`_: ``NMTOKENS``.  Default value: none.
 
 The ``classes`` attribute is a list containing zero or more names used
-to classify an element.  The purpose of the attribute is to indicate
+to classify an element. The names are converted to conform to the
+regular expression ``[a-z](-?[a-z0-9]+)*`` (see the `"class"
+directive`_ description for details and rationale_).
+
+The purpose of the attribute is to indicate
 an "is-a" variant relationship, to allow an extensible way of defining
 sub-classes of existing elements.  It can be used to carry context
 forward between a Docutils Reader and Writer, when a custom structure
@@ -4448,6 +4452,8 @@ the attribute.
 ``classes`` is one of the `common attributes`_, shared by all Docutils
 elements.
 
+.. _"class" directive: rst/directives.html#class
+.. _rationale: rst/directives.html#rationale
 
 ``delimiter``
 =============
diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt
index f99bcdd8a..3fb6df344 100644
--- a/docutils/docs/ref/rst/directives.txt
+++ b/docutils/docs/ref/rst/directives.txt
@@ -1479,10 +1479,19 @@ Class
 The "class" directive sets the "classes" attribute value on its content
 or on the first immediately following non-comment element [#]_.  For
 details of the "classes" attribute, see `its entry`__ in `The Docutils
-Document Tree`_.  The directive argument consists of one or more
-space-separated class names, which are converted to lowercase and all
-non-alphanumeric characters are converted to hyphens.  (For the
-rationale, see below.)
+Document Tree`_.
+
+The directive argument consists of one or more space-separated class
+names. The names are transformed to conform to the regular expression
+``[a-z](-?[a-z0-9]+)*`` by converting
+
+* alphabetic characters to lowercase,
+* accented characters to the base character,
+* non-alphanumeric characters to hyphens,
+* consecutive hyphens into one hyphen.
+
+For example "Rot-Gelb.Blau Grün:+2008" becomes "rot-gelb-blau grun-2008".
+(For the rationale_, see below.)
 
 __ ../doctree.html#classes
 
@@ -1534,10 +1543,13 @@ The text above is parsed and transformed into this doctree fragment::
    element (paragraphi, in this case) individually, instead of to the
    block quote as a whole.
 
+.. _rationale:
+
 .. topic:: Rationale for "classes" Attribute Value Conversion
 
+
     Docutils identifiers are converted to conform to the regular
-    expression ``[a-z](-?[a-z0-9]+)*``.  For CSS compatibility,
+    expression ``[a-z](-?[a-z0-9]+)*``.  For HTML + CSS compatibility,
     identifiers (the "classes" and "id" attributes) should have no
     underscores, colons, or periods.  Hyphens may be used.
 
@@ -1548,23 +1560,23 @@ The text above is parsed and transformed into this doctree fragment::
           hyphens ("-"), underscores ("_"), colons (":"), and periods
           (".").
 
-    - However the `CSS1 spec`_ defines identifiers based on the "name"
-      token, a tighter interpretation ("flex" tokenizer notation
-      below; "latin1" and "escape" 8-bit characters have been replaced
-      with XML entities)::
+    - The `CSS1 spec`_ defines identifiers based on the "name" token
+      ("flex" tokenizer notation below; "latin1" and "escape" 8-bit
+      characters have been replaced with XML entities)::
 
           unicode     \\[0-9a-f]{1,4}
           latin1      [¡-ÿ]
           escape      {unicode}|\\[ -~¡-ÿ]
-          nmchar      [-a-z0-9]|{latin1}|{escape}
+          nmchar      [-A-Za-z0-9]|{latin1}|{escape}
           name        {nmchar}+
 
-    The CSS1 "nmchar" rule does not include underscores ("_"), colons
-    (":"), or periods ("."), therefore "classes" and "id" attributes
-    should not contain these characters.  They should be replaced with
-    hyphens ("-").  Combined with HTML's requirements (the first
-    character must be a letter; no "unicode", "latin1", or "escape"
-    characters), this results in the ``[a-z](-?[a-z0-9]+)*`` pattern.
+    The CSS rule does not include underscores ("_"), colons (":"), or
+    periods ("."), therefore "classes" and "id" attributes should not
+    contain these characters.  Combined with HTML's requirements (the
+    first character must be a letter; no "unicode", "latin1", or
+    "escape" characters), this results in the regular expression
+    ``[A-Za-z][-A-Za-z0-9]*``. Docutils adds a normalisation by
+    downcasing and merge of consecutive hyphens.
 
     .. _HTML 4.01 spec: http://www.w3.org/TR/html401/
     .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1
diff --git a/docutils/docs/ref/rst/restructuredtext.txt b/docutils/docs/ref/rst/restructuredtext.txt
index 9b4cf7ff8..057731211 100644
--- a/docutils/docs/ref/rst/restructuredtext.txt
+++ b/docutils/docs/ref/rst/restructuredtext.txt
@@ -2583,7 +2583,8 @@ literals`_, and `hyperlink references`_, we can add "title reference",
 we want.  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.  In addition, applications may support
+individual descriptions.  The role_ directive can be used to define
+custom interpreted text roles.  In addition, applications may support
 specialized roles.
 
 
@@ -2953,6 +2954,7 @@ Markup errors are handled according to the specification in `PEP
 .. _meta: directives.html#meta
 .. _figure: directives.html#figure
 .. _admonition: directives.html#admonitions
+.. _role: directives.html#custom-interpreted-text-roles
 .. _reStructuredText Directives: directives.html
 .. _reStructuredText Interpreted Text Roles: roles.html
 .. _RFC2396: http://www.rfc-editor.org/rfc/rfc2396.txt