[Doc-SIG] PEP-0216

[Moshe Zadka]

On Thu, 9 Nov 2000, Tony J Ibbs (Tibs) wrote:

> We can guarantee that no solution will satisfy
> everyone (I can be awkward on demand if it looked like it would), so an
> existing solution that gets most of the way and that we have some chance of
> modifying if we're willing to help sounds like a Good Thing to me.

Right on! 

> Meanwhile, if people can be a *little* patient, I'm writing up a summary of
> what the (in general, pedantic) worries about StructuredText were (NG
> addresses some of them already),

So please leave those worries out! We're going with ST-NG unless

1) Someone finds a *big* problem with it.
2) Guido dislikes it, and his coworkers don't physically beat him into
   silence

At the moment, there are problems with ST-NG, which I've already
written about in a previous e-mail.

> and also trying to firm up the *definition*
> of StructuredText

That would help a lot! I would like to include a definitive reference
inside the PEP itself, so it could be integrated into Fred's "Documenting
Python".

BTW, the current output format should be th Pythonish LaTeX which is
already used. A future additional output format is whetever is used for
external documentation (probably XML/SGML application). 

> BTW, it's not as if we're short of tools:
> 
> 	StructuredText itself
> 	pythondoc (when Starship is up)
> 	Crystal
> 	Happy-Doc

We're short on *one* tool, which is strong enough to be "the" answer.

In short, I'd love to see some definitive Python-extension of ST-NG,
which would let us write documentation! If you can do a specification,
that would be great!

patient-is-no-different-then-lazy-here-ly y'rs, Z.
--
Moshe Zadka <moshez@math.huji.ac.il> -- 95855124
http://advogato.org/person/moshez