[Python-Dev] Re: Docutils/reStructuredText is ready to process PEPs
Mon, 5 Aug 2002 17:06:50 +0200
> > have you tried it?
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?