[Doc-SIG] Clarification: interpreted text vs. directives
Tue, 13 Nov 2001 21:59:36 -0500
> Hmm. To me, the slashes remind me of something like::
> (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.
> > > 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
> 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 email@example.com Open-source projects:
- Python Docstring Processing System: http://docstring.sourceforge.net
- reStructuredText: http://structuredtext.sourceforge.net
- The Go Tools Project: http://gotools.sourceforge.net