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

[Alan Jaffray]

On Mon, 12 Nov 2001, David Goodger wrote:
> Alan Jaffray wrote:
> > 1) Does the "indirect directive" have access to the substitution
> >    reference text?
> 
> I assume you mean the substitution name, the text between the "`/" and "/`"?
> Currently no, it doesn't. I don't see why it would need any such access.

Well, going back to that inline image example::

    The `/biohazard/` symbol is scary-looking.

    .. /biohazard/ image:: biohazard.png

The intended HTML output is::

    The <img src="biohazard.png" alt="biohazard"> symbol is scary-looking.

That alt text needs to come from somewhere.

> > 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.
> 
> Decent alternative. I'll take it under advisement. (Now I've got judiciary
> delusions!)

Delusions?  That's no delusion. :)

> Another possibility is `[name]`. Each of `/name/` and `[name]` and `|name|`
> effectively limit (albeit only slightly) interpreted text though. Other
> (more radical) alternatives?

I'm surprised you'd be willing to go for `` `[name]` ``.  That would be 
my preference, but I'm not sure what we'd do about the referent, since
``.. [name]`` is footnote syntax.

> > [...]
> > However, I expect everyone else will disagree. :-)
> 
> Bingo!

I'm getting used to it. :-)

Alan