[Doc-SIG] backslashing

[Edward Welbourne]

hmm.  I don't like backslash.  I know you can use r'''...''' but I still
don't like it.  Sort of because I'm not guaranteed that I can see the
start of a long doc string when I'm editing it, but partly because
python's reading of \ in strings is already (... how shall I say this
politely ...) sophisticated enough.

However, I can add to your list of places where it's `needed': \n is
needed in embedded literals because ... we aren't allowing them to span
multiple lines, right ?  But we have to allow doc-string authors to
discuss strings with newlines in them (just like we have to allow them
to discuss strings with ' and # in them - and, of course, with \ in
them).

<aside> Another approach to avoiding backslashes is to exploit having
two different quoting enclosures; thus, in shell scripts, I only ever
use backslash where I want a program to see a backslash in one of its
arguments, because I never need it to escape a ' or " - I just abut two
strings with different enclosures, like:

eddy:vortex> echo 'the double quote, ", and'" single quote, ', characters"
the double quote, ", and single quote, ', characters

but I doubt we can get away with this in the docstring case because
'verbatim texts' and #code.fragments in ( 'python', )# are different
(semantically).
</aside>

Someone who wants to include a code fragment including a comment can
perfectly easily put it into one of the block-style structures for
enclosing non-plaintext, as I argued when proposing #...# for this role;
I'm inclined to apply the same ruling to code fragments like::

   script.write('echo HTTP/1.1 200 OK\n# no headers\necho')

which describe python code which uses a # other than as a (python)
comment character.  If you decide you want to let me discuss, inline, a
shorter cousin of this: I'll point at my uses of \n in it and ask
whether you really want me to reactivate perverse counterexample mode.

I realise it'll be mildly irritating (and add to vertical space use) to
have to go into a block to say a code fragment any time it's got a # in
it; or a verbatim text any time it's got a ' in it (indeed, the latter
is the more serious issue); at least when it's such a short fragment one
wants it to be inline.  But inline fragments are a luxury.

Adding an escape character requires us to make provision for escaping
the escape (else, as Edward pointed out, we can't *end* a fragment with
the escape character).  At which point the ability of folk to work out
how many backslashes they're looking at depends not only on counting the
backslashes they can see, and on working out whether the string is
r'...' or not, but also on whether they're inside an inline fragment
right now.  This *will* confuse pythoneers.

Confusion is worse than mild irritation.  Ergo, don't do it.

Not even to save vertical space ;^|
(and, as some earlier cross-talk between myself and Tibs might clue you
to notice, I consider vertical space a big sacrifice).

Oblige doc-strings which want to talk about a fragment, using the
delimiter ST* uses for the relevant kind of inline fragment, to do the
fragment as a block, not an inline.  This is an easy rule with no fancy
repercussions.  It doesn't collide with the already sophisticated
reading of \ in strings: and it's easy to describe and understand.
Ergo it is the Right Thing To Do.

Please ?

	Eddy.