[Doc-SIG] Not escaping the escape leaves no escape ;)
David Goodger
dgoodger@bigfoot.com
Tue, 14 Aug 2001 08:23:36 -0400
[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