[Doc-SIG] Not escaping the escape leaves no escape ;)

[David Goodger]

[Tony]
>>> Well, my first guess would be ``\\*``

[Tony]
>> Aaargh - no, I *meant* ``\\\*`` - as in::
>>=20
>> This text contains \\\*, which should be
>> a backslash followed by an asterisk.

[J=FCrgen]
> No, your first guess was right. Since '\\' is not an escape sequence, the
> lexer would return '\', with '\*' remaining. And '\*' is a single asteris=
k.
> So the only problem remaining is that NOONE used to "normal" escaping wil=
l
> be able to grok this intuitively, which both of us just proved very nicel=
y.
> ;)

I don't know about proof, but there's some misconception going on here. A
single backslash always escapes the next character [1]_. When you use
backslash-escapes, the first backslash *always* disappears. If there are
multiple backslashes in a row, the first escapes the second, then we start
over. So::

    "\\"   -> "\"
    "\\\*" -> "\*"
    "\\\ " -> "\ " (in future, this may become "\ ")

.. _[1] The only exception to the escaping rules is inside
    literal blocks and inline literals, where the backslashes
    have no effect.

Now, the following is a bit tricky, not because of the escaping rules, but
because of the inline markup rules::

    " * "        -> " * "
    " (*) "      -> " (*) "
    " 2*3 "      -> " 2*3 "
    " *, ...* "  -> " <emphasis>, ...</emphasis> "
    " \*, ...* " -> " *, ...* "
    " *, ... "   -> " *, ... ",
        followed by a <system_warning>no end-string for emphasis</>

In other words, to get an asterisk, either escape it, or make sure there's
whitespace after it.

The inline markup rules are intentionally tricky, to allow 90% of legitimat=
e
uses of '*' and '`' *without* resorting to backslashes. For 9 of the
remaining 10%, use inline literals or literal blocks::

    "``\*``" -> "\*" (possibly in another font or quoted)

Only those who understand the escaping and inline markup rules may do the
remaining 1% of cases. ;-)

--=20
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net