[Python-Dev] Re: Docutils/reStructuredText is ready to process PEPs
Mon, 5 Aug 2002 10:15:24 -0400
On Mon, Aug 05, 2002, Fredrik Lundh wrote:
> Ka-Ping Yee wrote:
>> I would be very unhappy about having to enter and edit inline
>> documentation in an XML-based markup language.
> have you tried it?
> I suggest taking a look at 2.3's xmlrpclib.py module.
> does the comments that start with a single ## line look scary
> to you?
> 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
That's not XML, and I wouldn't even call it XML-based. It's yet another
structured text markup that includes bits of XML (or HTML or whatever)
and can be converted to XML. I don't know what exactly you're using in
xmlrpclib.py, but I took a look at the javadoc docs when the discussion
of reST came up because I wanted to know what reST had that javadoc
didn't (and vice-versa) -- it's clear to me that javadoc is at least
somewhat limited compared to reST, and that using javadoc for any kind of
heavily marked-up docs looks far uglier than reST.
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.
Aahz (email@example.com) <*> http://www.pythoncraft.com/
Project Vote Smart: http://www.vote-smart.org/