[Doc-SIG] Use cases for inline directive references

[Moore, Paul]

From: Alan Jaffray [mailto:jaffray@pobox.com]
> I'm playing fast and loose with the hypothetical directive names
> and syntax; this is just intended to get the ideas across.

Thank you for putting the effort in to produce these! You have me convinced
- I see the need, and I understand how the syntax is going to achieve it,
now. (BTW, I think I prefer |...| over ^...^, as well.)

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.

But your "j2ee-cas" example confuses me - a "replace" directive with an
embedded "link" directive plus some text? 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...)

I'm +1 on most of this, and even +0 on the borderline cases (I favour
consistency and generality over special-casing them out of existence)...

Paul.