[Doc-SIG] suggestions for a PEP

[Tony J Ibbs (Tibs)]

Me, pulling things out at random...

Edward Loper wrote:
> 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>

Post-alpha docutils, we are definitely going to have to have a
discussion about what we want to use as terms in the DTD - which is
good, since I'm not convinced that the tags I've come up with are the
best possible choice.

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

Oh yes they are (chorus of "behind you" (obPanto reference)).

Well, actually, it's more complex than that.

The example is *either* similar to::

	Author: Person1 Person2

(but in which case it also isn't a labelled paragraph, because "Person1"
didn't start a new sub-paragraph, and non-subparagraphs labelled
paragraphs can't have more than one line, if you see what I mean), *or*
it is similar to::

	Author:

	   Person1 Person2

	   Person3

in which case Person3 *is* an author.

It will always be necessary to do::

     Heading

         Text...

to get a legacy-style ST heading, it would be too confusing otherwise.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"Bounce with the bunny. Strut with the duck.
 Spin with the chickens now - CLUCK CLUCK CLUCK!"
BARNYARD DANCE! by Sandra Boynton
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)