[Doc-SIG] Docstrings Format

[Moshe Zadka]

On Mon, 6 Nov 2000, Ken Manheimer wrote:

> We seem to have made little progress on any fronts on this docstring
> stuff.  I'm exasperated that StructuredText was dismissed, because i think
> it was the best candidate as the basis for the docstring
> format.  Several of pep-0216's docstring format goals are chief among
> StructuredText's motivating principles, and i think it does a better job
> of satisfying them, as is, than any other format i've encountered:
> 
>     1. It must be easy to type with any standard text editor.
>     2. It must be readable to the casual observer.
>     4. It must contain sufficient information so it can be converted
>        to any reasonable markup format.

I disagree with "4": I cannot mark up things like "this is a Python
variable". If you show me how to extend StructuredText for these
kind of things, it would definitely get a chance. Please have
a look at the PEP and see the exact markup goals I've outlined. Of 
course, if you do not agree with the goals, you can say that too...

> Now, even if
> StructuredText were to be put back on the table, it's not clear if i
> or someone else at dc would have time to adapt it to the purpose.

Well, if these are just tailorings and we have the proposal ready,
it might be that people outside DC can help.

> Out of curiousity, is it worth talking about StructuredText at this point,
> or would it still be considered unacceptable?

Nothing is "unacceptable", but as I've explained earlier, StructuredText
as is has not enough strength to do arbitrary Python-specific markup.

> i think it would be a major win, and would be willing to expend
> some effort to see it find its place.

I'm happy to hear that. I'm not against any markup. Though of course
I originally had in mind something closer to my original proposal, I'm
aware of the feelings that it generated, and if there is something
better the rest of the world likes, I'll live with it.

--
Moshe Zadka <moshez@math.huji.ac.il> -- 95855124
http://advogato.org/person/moshez