[Doc-SIG] reStructuredText inline markup

Alan Jaffray jaffray@pobox.com
Mon, 29 Oct 2001 16:10:31 -0500 (EST)

On 29 Oct 2001, Ueli Schl=E4pfer wrote:
> Alan Jaffray <jaffray@pobox.com> writes:
> > Nesting is needed in some very simple cases::
> >=20
> >     Most recent interpretation of the Second Amendment has been based=
> >     on `*USA vs. Miller* (1939)`__.
> >=20
> >     __ http://caselaw.lp.findlaw.com/scripts/getcase.pl?court=3Dus&vo=
> >=20
> I'll keep out of this battle -- but you should find plenty of material
> in the archive.

The only comments I can find, searching on "nested inline doc-sig" or
"nested inline restructuredtext", are David's remark of "that way lies
madness" with no explanation and Tony's note that it'd be a pain to=20
implement and he wasn't certain how important it was.

> 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

Is that valid?  The reference processor says::

    Warning: [level 1] Hyperlink target at line 5 contains whitespace. Pe=
rhaps a footnote was intended?

> So nothing should keep you from supplying your own handler for the
> ``lj`` role and write::
>     I had lunch with `text=3DRachel user=3Dtikva`:lj: today.
> That's not more obtrusive than your example, ::
>     I had lunch with <lj user=3D"tikva" text=3D"Rachel"> today.
> or is it?

Indeed, but they're both awful. :-)

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

That works well in this case with only one argument that isn't too
distracting when placed inline and has an evocative shorthand.
But imagine::

    The `text=3D"biohazard" src=3D"biohazard.png" height=3D20 width=3D20`=
    symbol must be used on containers used to dispose of medical waste.

That really needs to get placed yanked out of the flow of text. ::

    The `biohazard`{_} symbol must be used on containers used to dispose
    of medical waste.

    .. _biohazard: {img src=3D"biohazard.png" height=3D20 width=3D20}

Alternately, if you prefer something directive-like::

    The `biohazard`:_: symbol must be used on containers used to dispose
    of medical waste.

    .. _biohazard:: img src=3D"biohazard.png" height=3D20 width=3D20

I don't like that for two reasons.  First, it doesn't obey the usual
``directive_name:: directive_args`` pattern.  Second, it looks odd=20
when you make the interpreted text into a hyperlink::

    The `biohazard`:_:_ symbol ...

My brain tokenizes that as ``:_ :_``, while it does the right thing
with ``{_}_``, turning it into ``{_} _``.

> How about::
>     I had lunch with `Rachel`_ today.
>     .. _Rachel:
> =09
> 	.. lj:: user=3Dtikva icon=3D"badger.png"

Now we're getting into using that target syntax for not only hrefs and
anchors, but also macro inclusion.  rST doesn't currently have anything
which includes referenced text at the current position in the document.
Not necessarily a bad idea, and macro-including directives would solve
the inline markup issue, but it's getting into new territory.