[Doc-SIG] backslashing

[Edward D. Loper]

Basically what I'm trying to avoid here is having the escaping
mechanism itself be responsible for most of the cases where we need
to use escaping.  I would argue that with the following rules, you
almost never need escaping.  Of course, this is only relevant if
we end up using colorizing like C{this}; if we decide on some other
colorizing mechanism, then the following is moot..
    1. All curley braces ({}) *must* be properly nested
    2. If an open curly brace is preceeded by a capital letter,
       then it and its matching brace signify colorizing.
    3. If an open curly brace is not preceeded by a capital letter,
       then it and its matching brace should be rendered as braces.

Given these rules, when do we need to do escaping?
    1. If we want to use unmatched curly braces.  Generally this is
       only true when we're talking about the braces themselves, not
       when we're using them to talk about something else (e.g.,
       using them to write a Python dictionary).
    2. If we want to preceed an open brace by a capital letter.  I
       can't think of any case where this would be necessary, other
       than when you're talking about the markup language itself,
       or something similar?

How can we escape in these situations?
    1. By putting the entity in a literal block.  This seems to me
       more applicable to (2) above than to (1).
    2. By using an escape like E{lb}.

How do we evaluate whether this is a good solution?
    1. How ugly is it to do escaping?
    2. How often do we need to do escaping?

I would argue that this solution has a relatively high value for (1)
(higher than backslashing, anyway), but a very low value for (2).  In
particular, I was unable to find *any* occurances in the docstrings
in the standard library of characters that needed to be escaped..

Now compare to backslashes.  There are 2 possible ways to do 
backslashing:
    1. Preceeding anything by a backslash escapes it.
    2. Preceeding any escapable character by a backslash escapes it.
       Preceeding anything else by a backslash gives a literal
       backslash (similar to Python's way of doing things).  Note,
       however, that the stated reasons for Python doing it that
       way have to do with making it easier to see mistakes in your
       strings.

My problem with (2) is that it taxes my brain to remember which
characters I can put one backslash before, and which I have to 
put two backslashes before.  But in any case, for both (1) and (2),
"\\" translates to a single backslash.  I believe (though I haven't
yet had time to check) that "\\" does occur in docstrings.  It
certainly wouldn't be that uncommon if one wanted to talk about
regexps, or to use regexps to talk about something else, for example.

So now, we evaluate backslashing as an escaping solution, using the
same criteria:
    1. How ugly is it to do escaping?
    2. How often do we need to do escaping?

I believe that backslashing has a lower value for (1), but a 
higher value for (2).

So how do we decide?  Well, not it's objective, because we need to
decide how much we care about each criteria, how *much* higher/lower
we think backslashing scores, etc.  But in my opinion, I'd rather
use the {} solution..

But again, as I said, all this is moot if we're not using {} to do
colorizing.

> > I guess I'm trying to go on the principle of keeping the need to
> > escape characters to a minimum, because whatever escaping mechanism we
> > have, it'll be somewhat ugly/difficult to read.
> 
> I think that's inevitable. Please prove me wrong!

I don't know whether this was a coinvincing enough case, but I tried
to show that escaping is needed *less* often with the E{} approach
than with backslashing..

> However, although I'm sure an escape mechanism is needed, I'm also sure it
> will only rarely be needed.

I agree, which is why I want to be wary about the escape mechanism itself
becoming the major reason for using the escape mechanism (backslashing
backslashes, etc).

-Edward