[Doc-SIG] Re: Substitution syntax

David Goodger goodger@users.sourceforge.net
Thu, 15 Nov 2001 18:35:28 -0500

After I added a fourth syntax option ("|name|", option (d) below) for
substitution reference syntax alternative 4 (specialized), I
reexamined the keyboard for any and all other possible characters::

    (a) #name#
    (b) @name@
    (c) /name/
    (d) |name|
    (e) <<name>>
    (f) //name//
    (g) ||name||
    (h) ^name^
    (i) [[name]]
    (j) ~name~
    (k) !name!
    (l) =name=
    (m) ?name?
    (n) >name<

Looking back at http://structruedtext.sf.net/spec/problems.txt, I
recalled that I'd done the same type of search for the syntax of
inline literals. The "runner up" was carets (^), which look pretty
good for substitution syntax (option (h) above). I'd say they're at
least equal aesthetically, and suggestive of "insertion" (also
suggestive of a name for this thing...). Carets have no syntax
conflicts with tables or anything else, a bonus.

The resulting example looks like this::

    The ^biohazard^ symbol...

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

For comparison, here's the vertical bar syntax::

    The |biohazard| symbol...

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

Hmm. I like the carets better. Any objections or dissenting opinions?

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