[Doc-SIG] reStructuredText inline markup

[Alan Jaffray]

In the current reStructuredText specification, inline markup can't be
nested and is not extensible.  IMHO this is a problem.

Nesting is needed in some very simple cases::

    Most recent interpretation of the Second Amendment has been based 
    on `*USA vs. Miller* (1939)`__.

    __ http://caselaw.lp.findlaw.com/scripts/getcase.pl?court=us&vol=307&invol=174

Extensibility beyond the current "roles" mechanism is also necessary.
For example, one of my intended applications for rST currently has a 
frequently-used tag to refer to another user of the system::

    I had lunch with <lj user="tikva" text="Rachel"> today.

It's a nice semantically meaningful output-format-neutral element.
I don't know how I'd do something equivalent in rST.  If it weren't
inline, I'd use a directive, and if it didn't have an argument, I'd
use a role, but as it is, I think I'm stuck.


The extensibility problem is relatively easy to address if you allow
attributes or arguments in roles::

    I had lunch with :lj user=tikva:`Rachel` today.

But to me, that syntax looks confusing.  I was never too fond of the
`` :rolename:`text` `` syntax in the first place, and adding spaces
makes it more confusing.  I'd like to get something more block-looking
to go around the rolename and arguments.  I'd also like to require
that it be postfix, both for simplicity, and to follow the general
principle that the text should be primary and the way it's marked
up should be an aside. ::

    I had lunch with `Rachel`{lj user=tikva} today.

My guess is that most non-markup uses for braces are in programming
language examples, and most of those will be in literal blocks or
inline literals or interpreted text, so stealing the braces won't
lead to too much extra escaping.

The other problem is that lots of inline markup is obtrusive and ugly::

    I had lunch with `Rachel`{lj user=tikva icon="badger.png"} today.

If we think of these as inline directives, we can steal a play from
the hyperlink book, and drag the role out-of-line::

    I had lunch with `Rachel`{_} today.

    .. _Rachel: {lj user=tikva icon="badger.png"}

There's even the possibility of::

    I had lunch with `Rachel`{__} today.

    __ {lj user=tikva icon="badger.png"}


I'm not sure about nesting.  Some cases are easy, but any time you have
two constructs that involve backquotes, problems will ensue because
backquotes don't nest.  But backquotes are a really nice unobtrusive
delimiter for sections of text, and it'd be a shame to replace them
with braces or angle brackets or something.  I have some bad ideas.
Anyone have some good ideas?

Alan