[Doc-SIG] New document - pytext-fat

[Goodger, David]

Guido van Rossum wrote:
> - The example with a paragraph consisting of *just* "::" should render
>   that as a single colon, to be consistent.  If you think this should
>   be special-cased, you need to explain why

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 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.

/DG