[Doc-SIG] Docststring markup process

[Edward D. Loper]

> Paul Prescod made an excellent meta-proposal for docstrings at the
> recent conference: rather than arguing endlessly about various
> markup formats, anyone who wants to propose a particular markup format
> should write a PEP describing that format in detail.  Only formats
> described in a PEP will be under serious consideration.  By an agreed
> deadline, we can vote on the PEPs, and then be done with it.

As far as I can tell, the current problems lie less in not being able
to agree on a markup format, and more in not being able to define
one.  STminus is working to fix that, but it will take several iterations
before we have something that would be worthy of putting in a PEP.

I myself am remaining as neutral as I can as to what the actual format
should be.  I figure that there are enough other people out there 
to make sure that it's simple, easy, etc..  But my two main concerns
are that the markup format be:
  1. Well defined -- i.e., there should be a "correct" parse for
     most strings.  The remaining strings should have *explicitly*
     "undefined" results.
  2. Safe -- there should be *no* "unexpected results," except in
     where the results are "undefined."  This means, for example,
     that the results of using a single '*' in a string should be
     undefined, because if it's defined to produce an asterisk, 
     then people will assume they can write 'x*y' that way, and
     later in the same document write 'y*z' and get very counter-
     intuitive results.

> Of course we can discuss the various proposals here, but it's a big
> step forward to get them written up and all in one place for comparison.
>
> I strongly support this process; let's pick a deadline.

I would appreciate it if we can make the deadline far away enough
that we can have a real formal definition for whatever it is
we're proposing.  

-Edward