[Doc-SIG] docstring grammar

[Robin Friedrich]

----- Original Message -----
From: David Ascher <da@ski.org>
To: <doc-sig@python.org>
Sent: Tuesday, November 30, 1999 12:02 PM
Subject: RE: [Doc-SIG] docstring grammar


> On Tue, 30 Nov 1999, Tim Peters wrote:
>
> > Luckily, it almost fits your definition of a paragraph already.  It
> > shouldn't be any real effort to declare that ">>>" introduces a
> > structureless code paragraph extending until the next all-whitespace
etc --
> > given that it's a format for Python docstrings, Python's own output
deserves
> > some special treatment <wink>.
>
> The only question I suppose is whether one should require a keyword (Test:
> or other) to keep the top-level syntax trivial, or special-case the
> recognition of >>>-beginning paragraphs.
>
> I'm leaning for the former, as it can evolve to the latter if there is
> sufficient call for it from the user base, and I think it does keep the
> code simpler.  But I'm willing to be swayed.
>
> --david
<sway>
I would rather minimize the invention (and consequential memorization) of
special keywords. Parsing them is not made quite as trivial as it seems
(especially when alternate languages are involved). Structured text had the
favorable trait of being very easy to remember. Parsers are built using
formal definition of special case rules anyway. Where special casing based
on context becomes non-obvious to remember is where I would draw the line
and resort to literal keywords.
</sway>
-Robin