[Doc-SIG] suggestions for a PEP

Tony J Ibbs (Tibs) tony@lsl.co.uk
Fri, 16 Mar 2001 11:04:35 -0000

Me, pulling things out at random...

Edward Loper wrote:
> I would interpret that as:
>     <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>

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


	   Person1 Person2


in which case Person3 *is* an author.

It will always be necessary to do::



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


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