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

[Aahz]

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?

Yes.

> 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
> minutes.

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 (aahz@pythoncraft.com)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/