[Doc-SIG] reStructuredText inline markup

[Ueli Schläpfer]

Alan Jaffray <jaffray@pobox.com> writes:

> 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
> 

I'll keep out of this battle -- but you should find plenty of material
in the archive.

> 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.

[...]

Doesn't the current spec_ cover your wishes better than you seem to
think?  The spec says clearly that the role may be prefix or postfix,
and that the interpretation is domain-dependent.

.. _spec: *reStructuredText Markup Specification*, CVS version 1.22 of
          2001/10/27

So nothing should keep you from supplying your own handler for the
``lj`` role and write::

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

That's not more obtrusive than your example, ::

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

or is it?

And it would be entirely up to you to use some mail-header inspired
quoting mechanism, i.e.::

    I had lunch with `Rachel <tikva>`:lj: today.

All that you'd need to do in this case is to write a layer that
interfaces with the rfc822 module!  (Actually, to me this looks like a
nice solution for your case, but there are obvious limits as to how
much data you can stuff inline without getting something very
obtrusive.)

>     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"}

How about::

    I had lunch with `Rachel`_ today.

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

I'm not sure about the idented directive -- I could find no explicit
exclusion, so I assume that it is correct syntax.  But is it
necessary, or would this do as well (similar to multiple targets for a
hyperlink)::

    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"}
> 

[...]

Just my 2 cents,

Ueli