[Doc-SIG] Inline Substitutions

[David Goodger]

.. 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