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

[Tony J Ibbs (Tibs)]

Edward Welbourne (hi Eddy) wrote:
> Hi Tibs
[..deletia..]
> but the backslash stuff has me a bit confused
> ... partly because the illustrations didn't appear
> to be using r'...' strings.
>
> In non-raw strings, a backslash followed by
> something it doesn't find interesting is just
> an ordinary character
>
>    >>> 'hell\o there'
>    'hell\\o
>    >>> 'h\appy birthday'
>    'h\007ppy birthday'
>    >>> # (James Bond escapes as an alert character ;^)
>
> but a backslash is, itself, interesting to a backslash;
> so (changing one of your ' pairs to a ` pair so I can
> enclose in a ' pair)
>
>    >>> '\*escape* \`with` "\\"'
>    '\\*escape* \\`with` "\\"'
>    >>> '\\*escape* \\`with` "\\"'
>    '\\*escape* \\`with` "\\"'
>
> your parser isn't going to be able to distinguish
> whether the source contained doubled or single
> backslashes, except when the following character
> is one that backslash finds interesting ... but
> your rules seem to depend on your parser knowing
> this.
>
> I may be worrying needlessly, but just thought I'd
> better throw a sanity-check `\007' !

He also said:
> Feel free to forward to doc-sig if novel and interesting
> enough ;^>

so I am doing so...


Ah - it may be necessary to beware that DPS/reST is not only aimed at
docstrings, so almost all of the examples are going to assume "plain
text" as the input - i.e., some form of non-Pythonic text file - and
leave the "docstring-isation" up to the user ('cos that's easier to do -
it also (personal opinion!) makes it easier to ignore how, erm, rather
hard it is to use backslashes as escape characters within Python
strings...

Indeed, your choice of example shows that you've been reading the
quickref, and it is also talking about "bare" text - so that sounds like
I need to add a small section on embedding reST within *actual*
docstrings. I'll try to get around to amending the quickref to mention
something along those lines.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)