[Doc-SIG] Use cases for inline directive references

[David Goodger]

[Paul]
>> But your "j2ee-cas" example confuses me - a "replace" directive with an
>> embedded "link" directive plus some text?

[Alan]
> The block argument to "replace" can be any valid RST.

Maybe so, but there are easier ways to do it. Here's the original example::

    But still, that's nothing compared to a name like |j2ee-cas|.

    .. |j2ee-cas| replace::
       .. link:: http://developer.java.sun.com/developer/earlyAccess/
          j2eecas/
          the Java`TM`:super: 2 Platform,
          Enterprise Edition Client Access Services

I had to split up the URI; Outlook Express wouldn't allow such a long line.
Which shows why a construct like that "link" directive wouldn't work as is:
in many cases, URIs will need to be split across lines. How do you tell the
difference between URI continuation and the link text? It would need some
added syntax (like a blank line in-between).

Anyhow, the example above can be represented much more easily as follows::

    But still, that's nothing compared to a name like |j2ee-cas|__.

    .. |j2ee-cas| replace::
          the Java`TM`:super: 2 Platform,
          Enterprise Edition Client Access Services
    __ http://developer.java.sun.com/developer/earlyAccess/j2eecas/

Substitution references are allowed to be hyperlink references too. That
removes the need for a "link" directive, simplifying the construct greatly.

But the above still won't work. All inline markup needs to begin after
whitespace or a quote or one of "([{<". The "Java`TM`:super:" won't work,
becaue the initial backquote is not in start-string context.

A work-around would be to add a space::

    .. |j2ee-cas| replace::
          the Java `TM`:super: 2 Platform,
          Enterprise Edition Client Access Services

But this is probably not acceptable. At present, there is no way to do
character-level inline markup; it's limited to word-level. A severe
limitation, yes, but intentional: it allows text like "2*x" and "2 * x" and
"*" (with or without quotes) to exist without causing parser errors.

This certainly would create problems for a Japanese or Chinese application
of reStructuredText, since these languages do not use spaces between words.

Put on your thinking caps, everybody! Any way to allow character-level
inline markup without sacrificing the parser's current forgiving nature?
[#]_

If not, then we'll just have to live with the limitation.

.. [#] I have one (somewhat ugly) idea, but I'll keep it to myself
   for now to avoid contaminating the creative process.

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net