[Doc-SIG] backslashing

[Edward Welbourne]

> Hm. Mind if I quote that in my PEP? ;)
coo - flattery ;^>
Be my guest.

> Instead of "python block," we have "python test case,"
Hmm.  To me that's a different (complementary) thing from what I want
the python block to be.  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'.

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.  To turn it into a workable
test which actually tests anything, you'd have to write such a class,
provide .state and .name attributes for its members, instanciate this
class and (possibly implicitly) call repr() on the resulting object.  If
you treat it, as given, as a test, all you'll do is verify that the
illustrative code gets past the python parser.  [Albeit finding that
fragment involved trawling through a lot of my code, noticing that for
the most part I do illustrations by saying `see class foo, below' or
similar; and the above class is purely a sketch I don't think I use.]

> In the description of class Foo, literals that say #Foo# shouldn't
> link to Foo (which you are already presumably looking at).  And If you
> talk about class #Bar# five times, there shouldn't be 5 xrefs.  But
> we'll leave this for the tools to deal with.

Yes, that's a tool issue: and my guess is that tool authors will agree
with you - Ping, what do you do ?  Tool authors should be *at liberty*
to do xrefs from the contents of python literals, or (without touching
the literals) to xref, in a `see also section', every identifier seen in
a literal, or to ... mutatis mutandis.

> I'll agree for now.  So no backslashes
Thank You.
Now I can get some sleep at last ...

	Eddy.