[Doc-SIG] New document - pytext-fat
Guido van Rossum
guido@digicool.com
Fri, 30 Mar 2001 10:28:54 -0500
> It's required to begin a docstring (or section) with a literal block::
>
> """::
>
> s = "This is a literal block"
>
> That's how you assign a string...
> """
I see no need for this. According to the style guide, a docstring
should *always* begin with a one-line summary anyway.
> I inserted it in my reStructuredText spec for completeness, and it is
> consistent:
>
> A paragraph which which ends with two colons ('::') signifies that all
> following **indented** text blocks are code blocks. ...
>
> When '::' is immediately preceeded by whitespace, both colons will be
> removed from the output. When text immediately preceeds the '::', *one*
> colon will be removed from the output, leaving only one (i.e., '::' will
> be replaced by ':'). When '::' is alone on a line, it will be completely
> removed from the output; no empty paragraph will remain.
>
> The difference between 'text::' and 'text ::' is because sometimes we don't
> want a colon at the end of the preceeding paragraph. '::' all by itself in a
> paragraph is simply a degenerate case of '::' preceeded by whitespace.
Ah, I see. Can't say I like it very much though -- seems too subtle.
--Guido van Rossum (home page: http://www.python.org/~guido/)