updated

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

6 files changed, 230 insertions, 32 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 9039a2a5f..8dcd8fd01 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -283,6 +283,11 @@ Specific:
     parser strategy and short titles (<= 3 char-long over- &
     underlines).  Fixes SF bug #738803 "infinite loop with multiple
     titles" submitted by Jason Diamond.
+  - Added explicit interpreted text roles for standard inline markup:
+    "emphasis", "strong", "literal".
+  - Implemented "superscript" and "subscript" interpreted text roles.
+  - Added initial support for "abbreviation" and "acronym" roles;
+    incomplete.
 
 * docutils/parsers/rst/tableparser.py:
 
@@ -470,6 +475,9 @@ Specific:
   - Added support for "title_reference", "sidebar", "attribution",
     "rubric", and generic "admonition" elements.
   - Added "--attribution" option.
+  - Added support for "inline", "subscript", "superscript" elements.
+  - Added initial support for "abbreviation" and "acronym";
+    incomplete.
 
 * docutils/writers/latex2e.py: LaTeX Writer, added by Engelbert Gruber
   (from the sandbox).
diff --git a/docutils/docs/dev/rst/alternatives.txt b/docutils/docs/dev/rst/alternatives.txt
index 0208e3c0e..a6eaca41d 100644
--- a/docutils/docs/dev/rst/alternatives.txt
+++ b/docutils/docs/dev/rst/alternatives.txt
@@ -205,9 +205,10 @@ Parameterized Interpreted Text
 ------------------------------
 
 In some cases it may be expedient to pass parameters to interpreted
-text roles, analogous to function calls.  Ideas:
+text, analogous to function calls.  Ideas:
 
-1. Suggested by Jason Diamond::
+1. Parameterize the interpreted text role itself (suggested by Jason
+   Diamond)::
 
        `interpreted text`:role1(foo=bar):
 
@@ -216,12 +217,30 @@ text roles, analogous to function calls.  Ideas:
        `CSS`:acronym(Cascading Style Sheets): is used for HTML, and
        `CSS`:acronym(Content Scrambling System): is used for DVDs.
 
-   Problem: current interpreted text syntax does not recognize roles
-   containing whitespace.
+   Technical problem: current interpreted text syntax does not
+   recognize roles containing whitespace.  Design problem: this smells
+   like programming language syntax, but reStructuredText is not a
+   programming language.
 
-This pushes inline markup too far; readability becomes a serious
-issue.  Substitutions may provide a better alternative by pulling the
-details out of the text flow::
+2. Put the parameters inside the interpreted text::
+
+       `CSS (Cascading Style Sheets)`:acronym: is used for HTML, and
+       `CSS (Content Scrambling System)`:acronym: is used for DVDs.
+
+   Although this could be defined on an individual basis (per role),
+   we ought to have a standard.  Hyperlinks with embedded URIs already
+   use angle brackets; perhaps they could be used here too::
+
+       `CSS <Cascading Style Sheets>`:acronym: is used for HTML, and
+       `CSS <Content Scrambling System>`:acronym: is used for DVDs.
+
+   Do angle brackets connote URLs too much for this to be acceptable?
+   How about the "tag" connotation -- does it save them or doom them?
+
+Does this push inline markup too far?  Readability becomes a serious
+issue.  Substitutions may provide a better alternative (at the expense
+of verbosity and duplication) by pulling the details out of the text
+flow::
 
     |CSS| is used for HTML, and |CSS-DVD| is used for DVDs.
 
@@ -229,9 +248,18 @@ details out of the text flow::
     .. |CSS-DVD| acronym:: Content Scrambling System
        :text: CSS
 
-This is going beyond the scope of reStructuredText though.  Documents
-requiring this functionality may be better off using XML or another
-markup system.
+----------------------------------------------------------------------
+
+This whole idea may be going beyond the scope of reStructuredText.
+Documents requiring this functionality may be better off using XML or
+another markup system.
+
+This argument comes up regularly when pushing the envelope of
+reStructuredText syntax.  I think it's a useful argument in that it
+provides a check on creeping featurism.  In many cases, the resulting
+verbosity produces such unreadable plaintext that there's a natural
+desire *not* to use it unless absolutely necessary.  It's a matter of
+finding the right balance.
 
 
 Character Processing
@@ -262,6 +290,11 @@ the copyright symbol character.  If this is not possible in an
 authoring environment, a pre-processing stage can be added, or a table
 of substitution definitions can be devised.
 
+A "unicode" directive has been implemented to allow direct
+specification of esoteric characters.  In combination with the
+substitution construct, "include" files defining common sets of
+character entities can be defined and used.
+
 To allow for `character-level inline markup`_, a limited form of
 character processing has been added to the spec and parser: escaped
 whitespace characters are removed from the processed document.  Any
diff --git a/docutils/docs/dev/todo.txt b/docutils/docs/dev/todo.txt
index accc4cd7a..83a3c8461 100644
--- a/docutils/docs/dev/todo.txt
+++ b/docutils/docs/dev/todo.txt
@@ -1237,13 +1237,6 @@ references, which will be processed by the various Writers.  No Writer
 will need to have any knowledge of the Python-Reader origin of these
 elements.
 
-* Add interpreted text support code. (Done)
-
-  Ideally and eventually, the "interpreted" element will disappear
-  from the Docutils doctree.  In its place will be a customizable set
-  of inline elements including "acronym" and "index_entry", directly
-  created by the parser.
-
 * Add a test for language mappings.
 
 * Alan Jaffray suggested (and I agree) that it would be sensible to:
@@ -1257,22 +1250,15 @@ elements.
     which contain interpreted text with no explicitly specified role
     (there will always be a default role, so this won't happen)
 
-* Perhaps the default implicit role for interpreted text could be
-  "title", as in, "title of a book".  It'd be a text-only reference,
-  no hyperlink.  Idea from Aahz' 2002-05-09 Doc-SIG post.  (Done)
-
 * Add a directive establishing a mapping of interpreted text role
   aliases?  A set of default roles (index, acronym, etc.) could exist,
   and the directive could assign abbreviations (i, a, etc.) or other
   alternatives.
 
-* Explicitly add inline markup roles (emphasis, strong, literal) to
-  the built-in list of interpreted text roles?  Useful for
-  completeness, and potentially useful if `multiple roles`_ ever
-  become possible.
-
-  .. _multiple roles:
-     rst/alternatives.html#multiple-roles-in-interpreted-text
+* Add explicit interpreted text roles for the rest of the implicit
+  inline markup constructs: named-reference, anonymous-reference,
+  footnote-reference, citation-reference, substitution-reference,
+  target, uri-riference (& synonyms).
 
 * Add directives for each role as well?  This would allow indirect
   nested markup::
@@ -1349,9 +1335,49 @@ elements.
         separate file but I'm experimenting with creating a directive
         that will use some form of reST syntax to let you define them.
 
-    What to do with an undefined acronym or abbreviation?
+    Should Docutils complain about undefined acronyms or
+    abbreviations?
+
+    What to do if there are multiple definitions?  How to
+    differentiate between CSS (Content Scrambling System) and CSS
+    (Cascading Style Sheets) in a single document?
+
+    How to define the full text?  Possibilities:
+
+    1. With a directive and a definition list? ::
+
+           .. acronyms::
+
+              reST
+                  reStructuredText
+              DPS
+                  Docstring Processing System
+
+       Would this list remain in the document as a glossary, or would
+       it simply build an internal lookup table?  A "glossary"
+       directive could be used to make the intention clear.
+       Acronyms/abbreviations and glossaries could work together.
+
+       Then again, a glossary could be formed by gathering individual
+       definitions from around the document.
+
+    2. Some kind of `inline parameter syntax`__? ::
+
+           `reST <reStructuredText>`:acronym: is `WYSIWYG <what you
+           see is what you get>`:acronym: plaintext markup.
+
+       __ rst/alternatives.html#parameterized-interpreted-text
+
+    3. A combination of 1 & 2?
+
+       The multiple definitions issue could be handled by establishing
+       rules of priority.  For example, directive-based lookup tables
+       have highest priority, followed by the first inline definition.
+       Multiple definitions in directive-based lookup tables would
+       trigger warnings, similar to the rules of `implicit hyperlink
+       targets`__.
 
-  - "superscript" and "subscript" (synonyms "sup" and "sub").
+       __ rst/reStructuredText.html#implicit-hyperlink-targets
 
   - "annotation": The equivalent of the HTML "title" attribute.  This
     is secondary information that may "pop up" when the pointer hovers
diff --git a/docutils/docs/ref/rst/roles.txt b/docutils/docs/ref/rst/roles.txt
index 9a720eff0..d65750df6 100644
--- a/docutils/docs/ref/rst/roles.txt
+++ b/docutils/docs/ref/rst/roles.txt
@@ -31,6 +31,40 @@ Specification`_ for syntax details.
 .. contents::
 
 
+``:emphasis:``
+==============
+
+:Aliases: None
+:DTD Element: emphasis
+
+Implements emphasis.  These are equivalent::
+
+    *text*
+    :emphasis:`text`
+
+
+``:literal:``
+==============
+
+:Aliases: None
+:DTD Element: literal
+
+Implements inline literal text.  These are equivalent::
+
+    ``text``
+    :literal:`text`
+
+Care must be taken with backslash-escapes though.  These are *not*
+equivalent::
+
+    ``text \ and \ backslashes``
+    :literal:`text \ and \ backslashes`
+
+The backslashes in the first line are preserved (and do nothing),
+whereas the backslashes in the second line escape the following
+spaces.
+
+
 ``:pep-reference:``
 ===================
 
@@ -69,6 +103,36 @@ This is equivalent to::
     __ http://www.faqs.org/rfcs/rfc2822.html
 
 
+``:strong:``
+============
+
+:Aliases: None
+:DTD Element: strong
+
+Implements strong emphasis.  These are equivalent::
+
+    **text**
+    :strong:`text`
+
+
+``:subscript:``
+===============
+
+:Aliases: ``:sub:``
+:DTD Element: subscript
+
+Implements subscripts.
+
+
+``:superscript:``
+=================
+
+:Aliases: ``:sup:``
+:DTD Element: superscript
+
+Implements superscripts.
+
+
 ``:title-reference:``
 =====================
 
diff --git a/docutils/docutils/parsers/rst/languages/en.py b/docutils/docutils/parsers/rst/languages/en.py
index cb3ec000d..bc488a53e 100644
--- a/docutils/docutils/parsers/rst/languages/en.py
+++ b/docutils/docutils/parsers/rst/languages/en.py
@@ -60,6 +60,10 @@ roles = {
     'ac': 'acronym',
     'index': 'index',
     'i': 'index',
+    'subscript': 'subscript',
+    'sub': 'subscript',
+    'superscript': 'superscript',
+    'sup': 'superscript',
     'title-reference': 'title-reference',
     'title': 'title-reference',
     't': 'title-reference',
@@ -78,7 +82,6 @@ roles = {
     'target': 'target',
     'uri-reference': 'uri-reference',
     'uri': 'uri-reference',
-    'url': 'uri-reference',
-    }
+    'url': 'uri-reference',}
 """Mapping of English role names to canonical role names for interpreted text.
 """
diff --git a/docutils/test/test_parsers/test_rst/test_interpreted.py b/docutils/test/test_parsers/test_rst/test_interpreted.py
index b96caa293..6c0d30ac0 100644
--- a/docutils/test/test_parsers/test_rst/test_interpreted.py
+++ b/docutils/test/test_parsers/test_rst/test_interpreted.py
@@ -125,6 +125,54 @@ totest['basics'] = [
     <paragraph>
         :title:`` (empty interpteted text not recognized)
 """],
+["""\
+Explicit roles for standard inline markup:
+:emphasis:`emphasis`,
+:strong:`strong`,
+:literal:`inline literal text`.
+""",
+"""\
+<document source="test data">
+    <paragraph>
+        Explicit roles for standard inline markup:
+        <emphasis>
+            emphasis
+        ,
+        <strong>
+            strong
+        ,
+        <literal>
+            inline literal text
+        .
+"""],
+["""\
+Simple explicit roles:
+:ab:`abbreviation`,
+:ac:`acronym`,
+:sup:`superscript`,
+:sub:`subscript`,
+:title:`title reference`.
+""",
+"""\
+<document source="test data">
+    <paragraph>
+        Simple explicit roles:
+        <abbreviation>
+            abbreviation
+        ,
+        <acronym>
+            acronym
+        ,
+        <superscript>
+            superscript
+        ,
+        <subscript>
+            subscript
+        ,
+        <title_reference>
+            title reference
+        .
+"""],
 ]
 
 totest['references'] = [
@@ -233,6 +281,22 @@ totest['unknown_roles'] = [
         <paragraph>
             Unknown interpreted text role "very.long-role_name".
 """],
+["""\
+:restructuredtext-unimplemented-role:`interpreted`
+""",
+"""\
+<document source="test data">
+    <paragraph>
+        <problematic id="id2" refid="id1">
+            :restructuredtext-unimplemented-role:`interpreted`
+    <system_message level="1" line="1" source="test data" type="INFO">
+        <paragraph>
+            No role entry for "restructuredtext-unimplemented-role" in module "docutils.parsers.rst.languages.en".
+            Trying "restructuredtext-unimplemented-role" as canonical role name.
+    <system_message backrefs="id2" id="id1" level="3" line="1" source="test data" type="ERROR">
+        <paragraph>
+            Interpreted text role "restructuredtext-unimplemented-role" not implemented.
+"""],
 ]