[Doc-SIG] backslashing

Edward D. Loper edloper@gradient.cis.upenn.edu
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
deal with.

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