[Doc-SIG] backslashing

[Goodger, David]

> I can see this getting rediculously complicated if we're talking
> about any regexps inline..  And regexps are hard enough to read 
> anyway.. :)  

Any inline regexps will be complicated, no matter what escaping mechanism
you choose. It's the nature of the beast!

> Although I would still be worried that
> people would get confused with regexps::
> 
>   >>> print another_confusing_docstring
>   ...
>   The regexp r"\\." matches a literal period.

Inline literals would be better::

    The regexp `r"\."` matches a literal period.

Or a literal block::

    The regexp::
        r"\."
    matches a literal period.

Two ways to look at backslash escapes (i.e., a way to selectively suppress
markup recognition): as an occasional tool, or as a horrible wart. You seem
to be looking at it as a wart: how ugly can it get? Very ugly, indeed. Try
looking at it the other way: use it only when necessary, which should be
quite infrequently.

> So, for example, in::
> 
>   Find the value of C{x
>   - y}.

I haven't spoken up about this, but: ugh! Somewhat dismayed to see the X<>
type of construct being taken seriously. It works fine for POD: long live
POD! Want to use it in docstrings? Implement a POD parser for HappyDoc or
pydoc. In my estimation, readability is the most important criterion; X<>
fails miserably.

> The second line wouldn't be a list item because it's in a colored
> region..  We might also need a new "null" coloring that could be used
> in examples like::
> 
>   This is a sentence that ends in the number
>   N{1.}  

(Let's not get ridiculous here.)

> Is this better or worse than::
> 
>   This is a sentence that ends in the number
>   \1.

Recently, I've come to the conclusion that requiring a blank line before the
start of a list is reasonable and correct, even if we don't require blank
lines between items. Minimizing ambiguity trumps minimizing vertical space.

/DG