[Doc-SIG] reStructuredText inline markup

[Garth T Kidd]

Yaaargh. Messy messy messy.

I haven't read the spec for a while. What's wrong with user:`uid`? The
filter/patterner/munger/renderer/whatever can substitute the full text
for an appropriate link, right?

> -----Original Message-----
> From: doc-sig-admin@python.org [mailto:doc-sig-admin@python.org]On
> Behalf Of Alan Jaffray
> Sent: Tuesday, 30 October 2001 8:11 AM
> To: usc@ieee.org
> Cc: Alan Jaffray; Doc-SIG@python.org
> Subject: Re: [Doc-SIG] reStructuredText inline markup
>
>
> On 29 Oct 2001, Ueli Schläpfer wrote:
> > Alan Jaffray <jaffray@pobox.com> writes:
> >
> > > 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.
>
> 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
> 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. Perhaps 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=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?
>
> 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="biohazard" src="biohazard.png" height=20 width=20`:img:
>     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="biohazard.png" height=20 width=20}
>
> Alternately, if you prefer something directive-like::
>
>     The `biohazard`:_: symbol must be used on containers used
> to dispose
>     of medical waste.
>
>     .. _biohazard:: img src="biohazard.png" height=20 width=20
>
> I don't like that for two reasons.  First, it doesn't obey the usual
> ``directive_name:: directive_args`` pattern.  Second, it looks odd
> 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:
> >
> > 	.. lj:: user=tikva icon="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.
>
> Alan
>
>
>
>
> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG@python.org
> http://mail.python.org/mailman/listinfo/doc-sig