[Doc-SIG] backslashing

[Tony J Ibbs (Tibs)]

Edward D. Loper wrote:
> 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__.

Well, I think we should say what they *are*, which is that they are
strings that represent Python code that doctest will happily find
(modulo the place the docstring is) and process - that's *not* the same
as "illustrative", which implies "not very important" - the point is
that they may well be pedagogic...

On the pursuit of extensive unit testing and where strings shoul go, I
think we should be silent, and leave it to doctest and the unit test
software (whichever it is - pyunit?) to say...

> 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).

That way lies madness, 'cos what about C code, oh, and maybe some
Haskell is very important, and...

I think this is too big a task for ST<whatever> itself - maybe a later
job for @ escapes (ducks and covers).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)