[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/)