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

[David Goodger]

[Tony]
> Hmm. To me, the slashes remind me of something like::
> 
>     s/this/that/g
> 
> (I've probably got that slightly wrong)  in ed-like languages

Me too. (You got it right.) The only disadvantage with using this
syntax is that interpreted text and phrase-hyperlink references can't
start with an unescaped slash. That's a bit of a wart.

[Alan]
> > > 1) Does the "indirect directive" have access to the substitution
> > >    reference text?

[David]
> > 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.

[Alan]
> 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.

I remember shelving fleeting thoughts about the "alt" text; time to
revisit them. OK, there are three possible sources for the alt text:

1. The substitution name.
2. The source URI or file name.
3. Explicit text in the "image" directive.

I think (2) is the worst option, (3) is the best, and (1) is
in-between. (1) and/or (2) could be fallbacks when (3) isn't given.
(3) will require support from the "image" directive; I'll add it. (1)
would also require changes, and would only be applicable to inline
images (block-level images won't have a substitution name).

> > Another possibility is `[name]`.
> 
> 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.

True. That rules out that syntax. Didn't think it through.

> > > However, I expect everyone else will disagree. :-)
> > 
> > Bingo!
> 
> I'm getting used to it. :-)

The suggestions *are* useful. You've managed to get several ideas
adopted, although not always with your suggested syntax. Thanks for
helping to make reStructuredText more complete!

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net