[Doc-SIG] backslashing

[Edward D. Loper]

Hm.. I'm starting to get convinced that backslashing with backslashes
might not be optimal..

So, as a preface to what follows, I think of '...' and #...# as used
for in-line literals.  I.e., you can include them in sentences.
Literal blocks are used for blocks that are separated off from the
rest of the code.  Thus, there's an important *semantic* difference
between '...' and literal blocks.  Given that, I don't think it's
necessarily resonable to force people to put what really *should* be
an in-line literal into a literal block.

>> 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 ?  

You might mean two things, here. 
  1. Including the 2-character string '\n' in a literal, intending it
     to be rendered as a backslash followed by an n.
  2. Including an actual newline in a literal, intending it to be
     rendered as a line break.

If we assume that '...' is for in-line literals, (1) makes sense, but
(2) really doesn't; if you want line breaks in your literal, you
should be using a literal block.  If someone wants to discuss a 
string with a newline in it, they should probably use r"#'\n'#" (which
will be rendered as::

    '\n' 

in monospaced font).  Or, if we're backslashing things, they should
use r"#'\\n'#.

>> 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 assume that "script.write..." is in an r"..." string, otherwise
it would be indistinguishable from::

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

Which would be rendered as such..

In this case, I'd agree, and say to use a literal block.  But that's
because you wouldn't normally include the string you gave in a
sentence..  If we're talking about the string "x'", having to use
literal blocks may be unreasonable.  Consider the fictional example::

    If the user types::

        x'

    then the system should print the value of::

        x'(a)

    and return the value of::

        x'(b)

This really *should* be rendered as a single sentence, but by forcing
the doc writer to put everything in literal blocks, we force it to 
be rendered with each of those symbols in a separate display area...

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

I do agree.  But I'm not sure what the best thing to do is.  It's a 
little bit of a problem, *anyway*, because even if we ignore '\', 
doc writers have to think harder than they should if they want to use
backslashes in their docs. :)

>> Not even to save vertical space ;^|

If it were just an issue of saving vertical space, I'd agree.  But I
want to make sure that everything reasonable *can* be documented
s.t. it will look reasonable when formatted.. I'm less worried about
saying "the 0.5% of people using forms like XYZ will have to go to
extra trouble."  But I may end up agreeing anyway, that the confusion
is too much, and that those 0.5% will just have to deal using literal
blocks, and possibly with having ugly formatted docs. :)

We could also discuss ways of indicating that one-line literal blocks
are "really" inlines (::: or some such), but I'm currently loathe to
make ST even more complex. :)

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

So are you saying we'd have 2 different kinds of literal blocks?  We
hadn't really discussed that before..  I think that just having
literals, inlines, and literal blocks is probably enough, but if you
want to make a case, go ahead. :)

-Edward