[Doc-SIG] Use cases for inline directive references

Alan Jaffray jaffray@pobox.com
Sun, 18 Nov 2001 21:09:46 -0500 (EST)

On Sat, 17 Nov 2001, David Goodger wrote:
> At present, there is no way to do character-level inline markup; it's
> limited to word-level. A severe limitation, yes, but intentional: it
> allows text like "2*x" and "2 * x" and "*" (with or without quotes) to
> exist without causing parser errors.

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

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."
If that allows us to do character-level markup, so much the better.