[Doc-SIG] Re: Substitution syntax

[David Goodger]

[Alan, re the `/subname/` syntax]
> IMHO the intended association is more misleading than useful.

I understand your concern. That alone wouldn't necessarily sway the
decision though.

> Using pipes instead of slashes would be a less ugly wart, as they
> rarely start text.  In contrast, absolute paths are quite common.

I'm beginning to be swayed. Vertical bars ('|') instead of slashes
do solve the problem of confusion with absolute POSIX paths. They
don't solve the problem of limiting interpreted text though (can't
begin with a vertical bar).

Thinking about removing this limitation brought me back to reference
syntax alternative 4. I had three alternatives already::

    (a) #name#
    (b) @name@
    (c) /name/

To which I have added a fourth::

    (d) |name|

The resulting example looks like this::

    The |biohazard| symbol...

    .. |biohazard| image:: biohazard.png
       [height=20 width=20]

Simpler and doesn't comflict with interpreted text in any way. I can't
think of any significant conflicts that shouldn't be in inline literals
anyhow (such as shell command pipelines). The only example of a
problem that I can come up with on short notice is contrived, and
involves tables::

    +--------------+----------+------------+------------+
    | row 1, col 1 | column 2 | column 3   | column 4   |
    +--------------+----------+------------+------------+
    | row 2        | This cell and the one below span   |
    |              | from column 2 to column 4.         |
    +--------------+----------+------------+------------+
    | row 3        | Here's a |substitution|; or is it? |
    +--------------+----------+------------+------------+
    | row 4        |          |            |            |
    +--------------+----------+------------+------------+

The cell in row 3 spanning columns 2 through 4 contains
``|substitution|``, but because of the way the vertical bars line up
with the cell corner markers ("+"), it would be recognized as three
cells (pretend row 2 isn't there). There is no requirement in tables
for left or right margins (the margins that are there are just my
preference), and adding such a requirement would be onerous.

The vertical bar syntax is not too obtrusive; is it obtrusive enough?
Is it aesthetically pleasing? Is the table issue a showstopper? (Note
that the same table issue would also exist for "`|" syntax.)

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