Edward D. Loper
Wed, 14 Mar 2001 10:31:35 EST
> I'll have a quick try, although it is actually the intersection of
> several reasons.
> First, practical. In a docstring, you can't just type '\', you'll have
> to type at least '\\', and maybe even more. This is a pain.
You can always use r""..."""
> Secondly, in ST *text* (and all of the ST family are intended for
> writing plain text as well, including STpy), it doesn't read well - it's
> not something one would naturally type, unlike '...' which *is*, well,
So basically it seems like the question comes down to "can we get
away with quoting."
For most things, we can. But if we're proposing a standard markup
for documenting python, I think it would be very bad if we designed
it such that some programs could not be reasonably documented
You can quote most things with '...'. Disadvantages:
1. everything in '...' is monospace, so there's no way to produce
a "normal" '*'. This may not be a problem.
2. '...' must be preceeded and followed by whitespace, so
the entire ws-delimited token containing the symbol we want
to quote must be quoted. In turn, this means that the entire
symbol containing a special character must be rendered in
monospace, and can't use any coloring (emph, strong, hrefs).
You can't quote "'" with '...'. But you can with #'#.
1. This seems to get very confusing and non-intuitive, to me anyway.
2. There are strange interactions.. For example, you can't
quote the symbol "#'", and a number of others. But if a
python program happens to use that, they can't reasonably
use STfoo for documenting their code..
Backslashing is more powerful in some sense than quoting.. A single
backslash character will let you say anything.. A quoting mechanism
will always have cases left out.
> Thirdly, I actually have a gut feeling that using the same escape
> character for ST text as one uses for strings is going to be awkward
> anwyay (it *does* tend to lead to the "four backslashes means one"
> phenomenon, and it's just rather awkward to handle mentally).
We shouldn't ever get more than 2 backslashes for this problem, and
it should just be one if people use r""...""", which they can do
unless they're planning on inserting strange characters in their
documentation string (presumably a bad idea anyway?).
> Fourthly, I think it is instructive to note that there has never been
> much demand in the STClassic world to solve this, and even STNG isn't
> worrying about it too hard - that means that most people, most of the
> time, have managed either not to care or to work around the problem.
They're in a very different world than we are. When you try to
describe an algorithm that processes text, you sometimes really need
to be able to use "'" and '#' and '*', and maybe even "#'".
I'm still not convinced either way (that we definitely need backslashing
or that we definitely don't). So I'll keep brooding on it..