[Doc-SIG] suggestions for a PEP

[Edward Welbourne]

Edward said:
> I agree with the idea, but I strongly think that things like author
> should be description list items.
...
> Unless you can come up with a compelling reason for using::
>
>   Author: Guido
>
> instead of::
>
>   Author -- Guido
>
> I think we should go with the latter.

Hmm.  There are more things in heaven and earth than are dreamed of in
your philosophy, Horatio.  Dunno if this compels but here I go.
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

This is gibberish.  However, it appears to be called for in Edward's
scheme of things, in the places where Tibs' calls for the same with the
` --' replaced by a `:'.  The Tibs-form would be::

    Author: Guido

    Version: 3.14

    A random paragraph as before.

which works out less like gibberish when my brain's parser comes to try
to work out what it means - substantially because I'm reading a *python*
program, in which : has the kind of meaning that this usage is asking it
to have.  I would be more in sympathy with Edward's account of the
matter if it proposed::

    Document information

        Author -- Guido

        Version -- 3.14

    A random paragraph which isn't a sub-paragraph of the document
    information.

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

    Document information
        Author -- Guido
        Version -- 3.14

    A random paragraph which isn't a sub-paragraph of the document
    information.

and believe I shall not be alone (among python programmers) in tending
to neglect those blank lines (in *all* descriptive lists) and being
irritated by any tool which insists on me adding them.  Gratuitous
whitespace `halves' the amount of information I can fit in front of my
eyeballs at a given moment and that *matters* to the *maintainability*
of my code - an issue which I take very seriously.

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 - substantially because I'm
likely to be the maintainer, and I'm no more likely to remember what I
was thinking when I wrote the code than is anyone else, even though they
didn't write it and I did - I don't use my wetware for *memory*, that's
what silicon and ferrite are for.

	Eddy.