[Python-Dev] Re: Docutils/reStructuredText is ready to process PEPs

[Fredrik Lundh]

Aahz wrote:

> > have you tried it?
> 
> Yes.

Details, please.

We've recently used javadoc/pythondoc in a relatively large Python
project (currently 30ksloc python, about 350 pages extracted docs)
with good results.  Most people involved had some exposure to html,
but not javadoc.  I don't think we've seen any markup errors at all.

> > it's javadoc-style markup, which is based on HTML.  if you've
> > ever written a webpage, you can learn the rest in a couple of
> > minutes.
> 
> That's not XML, and I wouldn't even call it XML-based.

It all ends up in an XML infoset, and the mapping is can be
described in a single sentence.  Close enough for me.

> using javadoc for any kind of heavily marked-up docs looks far
> uglier than reST.

Why would anyone put heavily marked-up documentation in
docstrings?  Are you doing that?  Any reason you cannot use
a word processor (interactive or batch) for those parts?

> The part of reST that's as limited as what you're using in xmlrpclib.py
> can also be learned in a couple of minutes.

Perhaps, but I already know HTML and JavaDoc; why waste brain
cells on learning yet another homebrewn markup language?  

</F>