[Doc-SIG] backslashing

[Edward D. Loper]

Tibs said:
> Given the attraction of doctest, it seemed sensible to allow its code
> blocks to be treated as such. And given its now in the standard Python
> package, we'd do well not to ignore it.

Agreed.  I think that we should reiterate in our own docs that 
the test cases in the doc strings should be for illustrative
purposes, and that extensive unit testing should be put in 
__test__.

Tibs also said:
> So whilst doctest does support "out of line" test strings, it will
> always be the case that it will run on docstrings as well - by original
> intent.
> 

Well, if you ask it nicely, it won't.  But in general it should,
and certainly will by default. :)

Tibs later said (in a different email):
> But as you've presented it, that wouldn't naturally be presented as an
> interatice session at all - one wouldn't write it as::
> 
> 	for example:
> 
> 	   >>> def __repr__(self):
> 	      and so on
> 
> but rather as::
> 
> 	for example::
> 
> 	    def __repr__(self):
> 	      and so on

But then Eddy still wants to know whether the literal block is python
code or not (for some of the same reasons that we want to have
separate #...# and '...' forms, instead of just one of them).

I don't see encoding this information as essential.  But if we *do*
want to encode it, we have to have some way of distinguishing 
python literal blocks from vanilla literal blocks (so we'll have
5 different literalish types: literals; inlines; literal blocks;
doctest blocks; and python literal blocks).

-Edward