[Doc-SIG] docstring grammar

[Tim Peters]

[Fred L. Drake, Jr.]
>   I think anything that starts ">>>" or "..." should automagically be
> a verbatim-thingy.  This is easy enough to implement and avoids excess
> cruft in docstrings.

Don't jinx it, Fred!  David already caved in on this one -- and seemed very
happy to get his child back <wink>.

Note that I was pushing for less and more than that:  did not ask for "..."
to be special (for all I know, it's someone's ellipsis attempt), but did ask
for leading ">>>" to mean that the entire *paragraph* starting there be
treated verbatim(*).  Where "a paragraph" means "all lines up to but not
including the next all-whitespace line, or end of docstring, whichever comes
first".

That's meant to cover pasted-in interactive shell sessions (which my
doctest.py makes heavy use of).  I don't think it's enough to supply
<PRE>...</PRE> functionality, if for no other reason than that an empty line
ends it.  But then I'm not sure I've seen
anything else proposed that can span embedded whitespace lines either.

computers-suck-ly y'rs  - tim


(*) "Verbatim" meaning, of course, not verbatim, but with leading whitespace
equal to the leading whitespace of the initial >>> line stripped.