[Doc-SIG] Inline Substitutions
David Goodger
goodger@users.sourceforge.net
Wed, 31 Oct 2001 23:08:20 -0500
.. Here's another essay, excerpted from
http://structuredtext.sourceforge.net/spec/alternatives.txt.
Comments, criticism, alternatives, suggestions welcome.
Inline Substitutions
====================
Inline substitutions arose out of a Doc-SIG thread begun on 2001-10-28
by Alan Jaffray, "reStructuredText inline markup". It reminded me of
a missing piece of the reStructuredText puzzle, first referred to in
my contribution to "Documentation markup & processing / PEPs" (Doc-SIG
2001-06-21).
Inline substitutions allow the power and flexibility of directives to
be shared by inline text. They are a way to allow arbitrarily complex
inline objects, while keeping the details out of the flow of text.
They are the equivalent of SGML/XML's named entities. For example, an
inline image (using inline syntax alternative 1 & substitution
alternative 1)::
The `biohazard`:sub: symbol must be used on containers used to
dispose of medical waste.
.. sub:: biohazard
.. image:: biohazard.png
[height=20 width=20]
```biohazard`:sub:`` would be replaced in-line by whatever the ``sub::
biohazard`` directive generates. A "sub" or "substitution" directive
would contain the substitution name as the directive's data, followed
by a directive block containing either replacement text (one
paragraph) or a nested inline-compatible directive, such as "image".
A transform would be required to handle the substitution itself.
Syntax alternatives for the inline part:
1. Use the existing interpreted text syntax, with a predefined role
such as "sub"::
The `biohazard`:sub: symbol...
Advantages: existing syntax, explicit. Disadvantages: verbose,
obtrusive.
2. Use a variant of the interpreted text syntax, with a new suffix
akin to the underscore in phrase-link references::
`name`@ or `name`# or `name`& or `name`/ or `name`<
Due to incompatibility with other constructs and ordinary text
usage, the following are not possible::
`name`:: and `name`:
3. Use interpreted text syntax with a fixed internal format::
`:name:` or `name:` or `name::` or `::name::` or `%name%` or
`#name#` or `/name/` or `&name&` or even `<name>` or `&name;`
(To avoid ML confusion those last two are definitely out.)
The ```/name/``` syntax is reminiscent of substitution.
4. Use specialized syntax, something new::
#name# or @name@ or /name/ or...
"#" and "@" are obtrusive. "/" without backquotes looks just like
a POSIX path; it is likely for such usage to appear in text.
Syntax alternatives for the substitution part::
1. Use the existing directive syntax, with a predefined directive
such as "sub". It contains either replacement text or another
directive resolving to an inline-compatible object::
.. sub:: biohazard
.. image:: biohazard.png
[height=20 width=20]
.. sub:: parrot
That bird wouldn't *voom* if you put 10,000,000 volts
through it!
The advantages and disadvantages are the same as in inline
alternative 1.
2. Use syntax as in #1, but compressed. If the substitution contents
is a directive, append it to the substitution directive marker::
.. sub:: biohazard image:: biohazard.png
[height=20 width=20]
Replacement text could also be (optionally) compressed::
.. sub:: parrot That bird wouldn't *voom* if you put
10,000,000 volts through it!
This is a bit better than alternative 1, but still too much.
3. Use a variant of directive syntax, incorporating the substitution
name, obviating the need for a directive name. If we assume inline
alternative 3 (slashes), the matching substitutions would look like
this::
.. /biohazard/ image:: biohazard.png
[height=20 width=20]
.. /parrot/ That bird wouldn't *voom* if you put
10,000,000 volts through it!
There is potential conflict with short paths in comments, but
that can be safely ignored.
At first blush, my favorite combination is inline alternative 3
(slashes) with substitution alternative 3::
The `/biohazard/` symbol...
.. /biohazard/ image:: biohazard.png
[height=20 width=20]
This syntax seems consistent and suggestive of its intended purpose.
I imagine that the next question might be: can we combine inline
substitutions with hyperlinks, so that we could click on an
image-link? Let's try::
The `/biohazard/`_ symbol...
.. /biohazard/ image:: biohazard.png
[height=20 width=20]
.. _biohazard: http://www.cdc.gov/
That seems to work well. Anonymous hyperlinks would also work. I
don't know about "anonymous substitutions" though; it seems that
substitutions ought to be fully spelled out, always.
--
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