[Doc-SIG] backslashing

[Tony J Ibbs (Tibs)]

Edward Welbourne wrote:
> A test case should be written to actually run
> for real; a python block should just be illustrating use of
> the code and
> might, indeed, be deliberately broken, e.g. as an accompaniment to the
> explanation of why something is done the slightly odd way it
> is, so that
> maintainers will realise what would go horribly wrong if hey made the
> obvious `improvement'.

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

> Equally, plenty of the tools I write are intended to be used
> from within
> the implementations of other tools; having a test system `run' the
> illustrations I'd want to supply is pointless - e.g.::
>
>         class selfRepresenting:
>             def _emit(self, *bits):
>                 """Representation support method.
>                 ...
>                 for example:
>
>                  def __repr__(self):
>                         return self._emit(`self.state`,
>                                           'name=' + `self.name`)
>                 """
>                 return (_fullname(self.__class__) + '(' +
>                         string.joinfields(bits, ', ') + ')')
>
> in which the illustration only gives the __repr__ method of a class
> implicitly inheriting from selfRepresenting.

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.

Anwyay, we probably aren't disagreeing - the "job" of the '>>>'
paragraph is well delimited (and was introduced as an idea last time
round the Doc-SIG loop, of course), and it is not the same as the job of
the '::' paragraph.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)