[Doc-SIG] backslashing

Tony J Ibbs (Tibs) tony@lsl.co.uk
Thu, 22 Mar 2001 10:47:57 -0000


Edward D. Loper wrote:
> So currently, we do have 4, but they're not exactly the 4 you
> listed.  Instead of "python block," we have "python test case,"
> which is used by some an automated testing program.  You can
> use these to show code & its output, but not for exceptions,

No, exceptions do work now.

> and a number of other cases.  I'm still not sure I like this
> system, but it seems somewhat reasonable.

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.

> The syntax for these python test blocks is a paragraph starting
> with '>>>', and ending at the next blank line.  It should include
> both the input and the output of the commands you run, although
> no commands should output lines starting with '>>>' or '...'.

Well, that's not up to STpy to say - that's only true if you want to run
doctest on it (and may not be the exact rules required there either).

> I think we're going to want to be careful not to put xrefs all over
> in #literal# sections.. E.g., 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.

Agreed.

> Well, that's not currently what's done with the python test blocks..
> But that's because we're trying to be compatible with that automated
> testing program... (will this change if functions/methods get
> attributes, and test strings move out of doc strings?)

One of the points about doctest is that when you are describing how
something works (i.e., this *will* be in a docstring) it is useful to
*show* how it works (or, of course, doesn't). And if you're doing that,
then it makes sense to check that what is typed is correct (now who
could deny that). And if you're doing that, why, you're testing!

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.

I suggest you read the relevent chapter in the 2.1 documentation.

> It seems to me that if we're going to use #...# for python literals,
> then we should really use it for them.  I see a danger here of people
> using 'sock.out' if they don't want an xref, and #sock.out# if they
> do want an xref.  I'm not sure that's what we want people to
> be doing..
> But I'm not sure what the best thing to do about it is.

The case for how cross-referencing of Python quantities is done is not
yet decided - it hasn't been discussed (again) yet. One of the ways of
getting useful input to it will be to see what happens if (intelligent)
guessing is done by a tool.

It *may* be that we want to indicate which '#..#' things are to be
cross-referenced, and there are on-board suggestions for this (the
obvious one is to use '[..]' to indicate the desire - yuck - and another
idea is to use something like '^#..#').

But I see this as being a *later* discussion.

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