Edward D. Loper
Wed, 21 Mar 2001 13:49:53 EST
> OK, two orthogonal questions about a verbatim fragment:
> * inline or block
> * python code or `alien text'
> giving us four kinds of `verbatim' fragment in doc-strings.
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,
and a number of other cases. I'm still not sure I like this
system, but it seems somewhat reasonable.
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 '...'.
> The python/alien distinction is important, because a python fragment is
> worth the renderer scanning for identifiers it knows about, so may wish
> to render as xrefs to pertinent documentation
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
> (however, this is the
> *only* processing the renderer should be doing to it);
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?)
> I regard layout-control as a luxury, subordinate to keeping the markup
> language simple.
I'll agree for now. So no backslashes, and if someone really wants
to use "#" in a python literal, or "'" in a literal, then they have
to use a separate block.
> Out-of-source documentation should provide the means for folk to say
> things the way they want and have it displayed the way they want: for
> in-code ST docs, simplicity of markup language is *more important* than
> making it look nice. It suffices that we ensure that the author can
> express the information the reader needs. A few rare cases where this
> will merely be ugly are not worth extra complexity.
Hm. Mind if I quote that in my PEP? ;)
> the send method writes one '#' character to #sock.control# for every
> #chunk# bytes it writes to #sock.out#.
> albeit I may be marking more things with #...# than I need to (am I ?).
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.