[Doc-SIG] Alternative inline markup

[Alan Jaffray]

Here are my suggested changes to the current inline markup system.

1) Inline markup can be nested:
   ::

      `*US vs. Miller* (1939)`_

   does what you expect.  Ambiguity is resolved with close tags first,
   then maximal munch.  Simple.  If you are sick enough to try::

      ***Strong enclosing emphasis***
      **Strong enclosing *emphasis***
      *Emphasis enclosing **strong***

   then the first two will work and the third won't.  If the user expects
   any of them to work without consulting documentation, they're foolish.
   Besides, if you want the third, you can do::

      `Emphasis enclosing **strong**`__

       __ emphasis

   See below.

2) An underscore suffix currently modifies the preceding text by 
   making it a link.  This notion is extended - the suffix indicates
   that the text is to be tagged in some way, indicated by a directive
   or destination URL in the target::

      I had lunch with Jonathan_ today.  We talked about Zope_.

      .. _Jonathan: lj [user=jhl]
      .. _Zope: http://www.zope.org/

   becomes the equivalent of::

      I had lunch with
      .. lj:: [user=jhl]
         Jonathan
      today.  We talked about
      .. link:: [refuri=`http://www.zope.org/`]
         Zope
      .

   in the current syntax (if directives inlined, which they don't).
   Link targets which are also legal directive names must be enclosed
   in backquotes.

3) Substitution becomes a directive:
   ::

      +----------------+
      |      TOP_      |
      +-------+--------+
      | LEFT_ | RIGHT_ |
      +-------+--------+

      .. _top: sub
         My First Playbook

      .. _left: sub
         Hail Mary

      .. _right: sub
         - 16!
         - 4!
         - 23!
         - hut!

   is equivalent to::

      +--------------------+
      | My First Playbook  |
      +-----------+--------+
      | Hail Mary | - 16!  |
      |           | - 4!   |
      |           | - 23!  |
      |           | - hut! |
      +-----------+--------+

4) Inside markup delimited by backquotes or curly braces, curly braces
   may be used as delimiters equivalent to backquotes::

      `Photos of {Bob Johnson}_ and {Sue Fernandez}_ dancing`__

      .. _Bob Johnson: grad 1989
      .. _Sue Fernandez: grad 1991
      __ images/dscn0018.jpg

   This is because backquotes don't nest.  Open-curly-brace must be
   escaped to be literal in single-backquoted text.

5) Roles can go away.  We don't need them.  Optionally if we want
   the ability to put short directive names inline, we could declare ::

      `foo:: bar bar bar`

   to be the equivalent of ::

      `bar bar bar`__

      __ foo

   Compared to the current options ::

      `bar bar bar`:foo:
      :foo:`bar bar bar`

   we're way ahead on both readability and lack of ambiguity either way.

Summary:

- We gain nesting.
- We gain arbitrary extensibility of inline markup.
- We gain substitutions.
- We retain unobtrusive markup.
- We lose by occasionally having to escape a curly brace inside
  backquotes, or quote a hyperlink target with no ``/`` or ``#``
  characters to distinguish it from a directive name.

Alan