[Doc-SIG] suggestions for a PEP

[Edward D. Loper]

> Consider::
> 
>     Author -- Guido
> 
>     Version -- 3.14
> 
>     A random paragraph at the same indentation level, so it *isn't* a
>     sub-paragraph of the Version list item; but it equally isn't a list
>     item in the implied descriptive list

I would interpret that as:
 <STRUCTURED_TEXT>
    <DESCR_LIST> 
       <DL_ITEM><KEY>Author</KEY><VAL>Guido</VAL></DL_ITEM>
       <DL_ITEM><KEY>Version</KEY><VAL>3.14</VAL></DL_ITEM>
    </DESCR_LIST>
    <PARA> ... </PARA>
 </STRUCTURED_TEXT>

But I can see how it might be confusing.  

> which works out less like gibberish when my brain's parser comes to try
> to work out what it means 

Which is what is really important; if others agree, then I'll be
convinced. 

> substantially because I'm reading a *python*
> program, in which : has the kind of meaning that this usage is asking it
> to have.  

But we have to be careful here, since the analogy doesn't completely
carry over.  Notably, this isn't what most Python programmers would
think it is::

    Author:
        Person1
        Person2

        Person3

The 3rd person is not part of the author list; it's some sort of
subparagraph of it, which doesn't make much sense to me..  

> While I'm at it: I loathe and despise the apparent demand (seemingly
> from both schools - Tibs: does your form require the space between the
> Author and Version lines ?) for blank lines in various places which feel
> (to me) just plain wrong; I want to write (descriptive lists and, in
> particular, ...) the Edward-form of the last as

Neither STpy (Tibs' version) nor whatever version of STminus I end up 
proposing for docstrings will require blank lines before list items.
STNG and "vanilla" variants of STminus will be the only ones that
require blank lines before list items.  Note that blank lines *are*
currently needed in all other places, though.. so, for example, if you
want to use headings, you must say::

    Heading

        Text...

And not::

    Heading
        Text...

> Given the choice between
>   pandering to the tastes of a tool for extracting the documents and
>   being kind to the poor sod who has to maintain the code
> I am typically going to side with the latter 

I definitely agree.  But of course, there's always something to be 
said for simplicity too..  If someone writing documentation has
to remember too many rules, they may get confused..

-Edward