[Doc-SIG] quoting

[Edward D. Loper]

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

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

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 #'#.  
Disadvantages:
  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..

-Edward