[Doc-SIG] New document - pytext-fat

[Guido van Rossum]

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