[Doc-SIG] Use cases for inline directive references

[David Goodger]

Alan Jaffray wrote:
> I'm uncomfortable with the current "forgiving" rules.  It's clear that
> you've put a lot of thought into them, and they're clever, and they
> handle many cases well.  But they're not clever enough to prevent
> the user from being surprised if they use unquoted characters without
> knowing the rules, and they're sufficiently complicated and ad-hoc
> that knowing all the rules is difficult. ::
> 
>     Then delete *.bak and *~ to clean up the backup files.
> 
>     Instead of **argv, Python uses sys.argv.

Each of these will generate level-1 system warnings, which ought to be
reported to stderr but filtered out of the final output. I consider such
processing behavior successful. We may change the system warnings to level-0
if they pop up too often or are too distracting (level-0 warnings are
intended to be silently discarded unless a "verbose" or "strict" option is
in effect).

The "*" in ``*.bak`` is not ended by the "*" in ``*~`` (there's whitespace
before it, and non-whitespace after), so there will be no inline elements at
all. In order to get such unintended inline elements, you'd need something
like this::

    Then delete *.bak and backup.* to clean up the backup files.

I would suggest that those ought to be literals anyhow.

>     The anonymous phrase link syntax is `` `text text text`__ ``.
> 
> (I used that last one recently, despite having read the inline markup
> rules a couple of times already.  I only realized it wasn't legal when
> I reread them again while writing this message.)

Not recognized because of whitespace. Simply add "no whitespace just inside
the delimiters" to the explanation.

> I would prefer a simpler, more consistent set of rules, something I can
> explain in a short sentence.  "Backquote and asterisk and non-internal
> underscores are magic, escape or quote them if you want them literally."

This explanation is fine, if over-protective. It won't cause any surprises,
but doesn't inform of the context that allows for the "exceptions" that make
life easier and avoid nasty surprises when you're not expecting them. For a
beginner's intro, how about:

    Non-internal asterisk, backquote, vertical bar [#]_, and underscore
    are inline magic delimiters, ``\`` escape or `` quote them if you
    want them literally. Asterisk, backquote, and vertical bar act like
    quote marks; matching delimiters are required at each end of the
    marked-up text, you need whitespace or other quoting outside them,
    and you can't have whitespace just inside them.

Two (OK, maybe three) sentences, yes, but they say a lot more. The quickref
will have examples, a better description, and a link to the spec itself for
those who require the gory details. Don't forget, the quickref is the only
attempt so far at user documentation; the spec is not.

.. [#] Yes, I've given in to the vertical bar syntax. I took a look at the
   two side by side and carets do lose aesthetically. The likelihood of
   unintended interaction with table syntax is acceptably small, especially
   since it requires quite a fancy and unlikely table structure. The
   potential interaction is well explained in the spec.

   Also, I've settled on the names: "substitution references" and
   "substitution definitions". See the latest alternatives.txt for a
   lengthy discussion of all the alternatives I considered.

   I'm beyond embarrassment discussing punctuation in public. It comes
   with the territory. This project is an enormous pedantic exercise.
   It has to be. :-)

> If that allows us to do character-level markup, so much the better.

Removing the context would allow character-level markup, but I believe that
it would also increase both the likelihood of surprising output and the
requirement for escaping to unacceptable levels. I haven't done any research
to back up this belief, which is partly based on the way StructuredText
handled inline markup. I'd be interested to see proof one way or the other,
such as the results of a survey of a large and varied body of applicable
texts.

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