[Doc-SIG] Re: docstring signatures

Edward D. Loper edloper@gradient.cis.upenn.edu
Sat, 24 Mar 2001 14:52:39 EST

> Don't spend too much time trying to make StructuredText or some
> variation thereof work.  In my experience with systems that use ST
> (like ZWiki), it sucks.  There basically are two options I like:
> nicely laid out plain text, or a real markup language like Latex or
> DocBook.
> --Guido van Rossum (home page: http://www.python.org/~guido/)

Hm.  I guess I should have thought to ask the BDFL about all this 
before now. :)  Makes me wonder if he'll like/accpet *any* of the
stuff we've been talking about.  But it's interesting to hear 
that Guido is ok with a real markup language.

So are there any vocal opponents of using a real markup language
on doc-sig right now?  (Assuming that Guido doesn't want us
to use something like ST)..

Of course, on the other hand, if we can clean ST up enough, and
make it formal, maybe he'll be ok with it.

I'm going to put my PEP on hold for now, until we figure this stuff
out.. (if anyone wants to see what I've written so far, though,
I'll be happy to send you a copy -- just email me).  

I'm also thinking of putting together a "minimal" ST-like language,
that would include markup for:
    * lists
    * emph
    * literals (one type, probably using '#' as delimiters)
    * urls (using '<>' delimiters)
    * literal blocks

But maybe we'd be better off just using XML.. :)  or something like
javadoc ('@param(x) foo..', etc.)..