diff options
| -rw-r--r-- | docutils/docs/ref/doctree.txt | 8 | ||||
| -rw-r--r-- | docutils/docs/ref/rst/directives.txt | 44 | ||||
| -rw-r--r-- | docutils/docs/ref/rst/restructuredtext.txt | 4 |
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 |