[Doc-SIG] Re: docstring signatures

[Edward Welbourne]

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

Yes (on that assumption).

As Guido said:
> ...  There basically are two options I like: nicely laid out plain
> text, or a real markup language like Latex or DocBook.
and the first option is blatantly the correct one for doc strings (as
in: you won't see enough folk using LaTeX systematically and you won't
see *anyone* using DocBook).  Oh, I think I'm meant to say `IMO' at
about this point.

A while ago Guido was reasonably emphatic against HTML (in doc-strings).
I suspect I'd written more HTML-based docstrings by then than everyone
else put together, and when I turned them into something resembling a
proto-ST, I was happier with the result and glad that Guido had rejected
HTML.  (Sorry, Tibs, I might not have converted all of them ...)

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

Yes.  While I'm still giggling (largely due to released stress) about
Guido's magnificent intervention, it doesn't explicitly rule out `were
ST a real markup language it would be OK', only you *really* want to
talk to Guido about what `real markup language' means in this context.
Clearly he'll allow that indentation-based structure is real structure
(since python *is* a real programming language), but equally clearly
he's not enamoured of the ST family.  This *might* just be because
they're all so damnably ad hoc, in which case your clean-up project
*might* be a winner; but please have a chat with Guido some how.
What *are* his objections to the ST family ?

Edward [tweaked] by Eddy in the process of echoing:
> I'm also thinking of putting together a "minimal" ST-like language,
> that would include markup for:
>     * lists [three flavours ?]
>     * emph [presumably no strong]
>     * urls (using '<>' delimiters)
>     * [inline] literals (one type, probably using '#' as delimiters)
>     * literal blocks [presumably one type, again]

Some of us would use it if it were 
  * very simple (you're doing fairly well above)
  * so nearly plain text that just printing it verbatim would work fine
but then at least one of us is of debatable sanity ;^>

Something in the spirit of ST but done properly would have a better
chance than something striving to be ST without its warts, IMO.

> But maybe we'd be better off just using XML.. :)  
IIRC, Guido's reasons against HTML in doc strings will take out XML
also.  But ask him.

> or something like javadoc ('@param(x) foo..', etc.)..
OK, ignorance speaks: what's javadoc like, could it be classed as a
`real markup language', are there compatibility issues (like it depending
on the code it decorates being in a language which uses punctuation,
rather than indentation, to delimit structure), where's a good URL for
an idiot introduction, why aren't we using it already ?

Don't feel that only Edward is allowed to answer those, folks ;^>
I suspect he'll say `don't know' to at least the last, and several of
you will give better answers than him on the rest.

Clearly a markup language specified by someone we can't persuade to
change has one humungous advantage: I'd never again spend an entire
month's free time fretting about whether some proposed changes were a
good idea and how to make them better.  If, say, we used javadoc we'd
just be stuck with whatever Sun have specified, so even if we don't like
some bits of it we'd just knuckle down and get over it.  There may be
better things for us to channel our energy towards ... especially if no
cousin of ST is ever going to find favour with Guido.

	Eddy.
--
Not that I'm grumbling, just knackered,
    at least largely for other reasons.