[Doc-SIG] backslashing

[Edward Welbourne]

> You really should read the doctest documentation (see the chapter in the
> 2.1 docs for the best intro) - it *will* test broken examples as well

erm.  You've missed what I was trying to say.

I was considering the case of a piece of code which isn't consistent
with what's actually implemented, given in order to explain *why* it's
implemented the way it *is* rather than the way someone might think it
*should be*; the illustrated code is showing what would happen if things
were done the way the alleged *should be* would force them to be done.
If the doctest tool can manage to run the illustrative fragment against
an imaginary implementation, we can all retire and leave the industry to
it - it's AI complete already.

> 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
> 
> That's *why* the chosen "start of Python paragraph" thing is '>>>' -
> because it *is* what it looks like.

again, you've missed my point.  I was in no way suggesting that my
fragment be treated as part of an interactive session; I was, indeed,
bemoaning the fact that if I try to supply that fragment, I must supply
it wrongly marked up, in one of the two ways illustrated in your
response: either as a test case, which is wrong, or as a verbatim block
of *alien text*, which is wrong.  At least, assuming '::' introduces a
verbatim block of alien text.  If it introduces a python verbatim block,
then I need to know how to insert an alien verbatim block, because I
believe I should be able to distinguish the two kinds of verbatim block.

Just to be clear: the test-case markup mechanism is a totally different
beast from the four varieties of `literal' I was describing, which come
in four varieties because there are two independent binary choices:
  * is the fragment python or alien
  * do we inline it or is it a block
We have #python.code('inlines')#, we have 'alien inlines' but we have
only one variety of verbatim block (assuming you'll let me ignore the
test-case inline which isn't any of the cases being considered).

	Eddy.