[Doc-SIG] Use cases for inline directive references

[Alan Jaffray]

On Fri, 16 Nov 2001, Moore, Paul wrote:
> I'm happy with most of this - the only one I dislike is the last one (your
> "replace" directive), which offers scope for the sort of abuse I pointed out
> earlier, which prompted David to remove the "replacement text" part of the
> construct. But you can't avoid allowing this, as processors can implement
> any directives they like, I guess - so it's just something that *can* be
> abused, but *shouldn't* be.

Yeah.  I wasn't especially happy with my first example - but it's
difficult to come up with a *short* example using "boilerplate text"
in any reasonable way.

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

The block argument to "replace" can be any valid RST.  In this case, 
it's a single directive, a hypothetical "link" directive, which takes
a URL argument (the link target) and a block argument (the link text).
That block argument can then be any valid RST; in this case it included
hypothetical "super" interpreted text role to make "TM" a superscript.

> I can't parse that so it works.
> Which means that it isn't readable (to me, at least) in "raw" form, so
> there's some form of issue here (if only that directive implementers should
> exercise restraint in what they allow...)

Well, if you need to write nested inline markup, you gotta do it somehow;
and if it's complicated markup, it's gonna look complicated.

It'd be more readable to do it entirely with nested inline directive
references, but those have been vetoed.  So instead we do the nesting
in a block, where there are no issues with syntactic ambiguity, and
substitute it into the inline text.

You certainly don't want to do this often, I agree.  But having it as
a fallback is useful, and it's consistent with the rest of the language.

Alan