Edward D. Loper
Sun, 18 Mar 2001 22:19:55 EST
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::
in monospaced font). Or, if we're backslashing things, they should
>> 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
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::
then the system should print the value of::
and return the value of::
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. :)