updated

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

2 files changed, 89 insertions, 30 deletions

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