[Doc-SIG] Clarification: interpreted text vs. directives vs. substitutions

[Alan Jaffray]

I think my (now defunct) revised proposal and what you've done with
substitutions are pretty similar. :-)

1) Does the "indirect directive" have access to the substitution
   reference text?  Can it take a block argument?  How exactly does 
   this work?

2) I dislike the slashes.  To me they mean either "italics" or "path"
   or "regex".  The latter two are also sources of ambiguity.  I can't
   think of a *good* syntax, but I think `` `|text here|` `` and
   ``.. |text here| directive:: args`` would be better.

3) "Directive references" and "directive targets" were the terms I used
   in my revised proposal.  We're certainly way past "substitution" now.

4) I dislike the double-colon after the directive name - we already
   know that it's a directive name, it's part of a directive target.
   I'd remove it or make it optional.  However, I expect everyone else
   will disagree. :-)

Cheers,

Alan


On Fri, 9 Nov 2001, David Goodger wrote:
> "Substitutions" are a text-level (inline) construct, a way of getting
> a directive into the middle of some text. The substitution reference
> encloses a name, which must match with the name on the substitution
> itself. The substitution itself is a named, indirect directive, which
> must produce an inline-compatible object (text or inline elements)::
> 
>     The `/biohazard/` symbol must be used on containers used to
>     dispose of medical waste.
> 
>     .. /biohazard/ image:: biohazard.png
> 
> Note that I've dropped the "replacement text" aspect of substitutions.
> With this change, "substitution references" could be renamed "indirect
> inline directive references" (or "inline directive references" or
> "directive references" for short). "Substitutions" could be renamed
> "indirect directives" or "indirect directive definitions".
> 
> Again, I'm open to any better ideas for syntax out there. Lay 'em on me!