[Doc-SIG] Docstrings Format

[Ken Manheimer]

On Mon, 6 Nov 2000, my doc-sig digest included this message from Moshe
Zadka <moshez@math.huji.ac.il>:

> There's a new version of PEP-0216 (docstring format) in the CVS
> repository. I would love to hear comments.

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.

It seems that a 1/2 year or so ago (?), david ascher was on the verge
of endorsing the StructuredText approach as the markup, provided some
tailoring could be done, but moshe dismissed it, in pursuit of a new
markup that failed to be accepted by many folks.  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.  (It
so happens i'm going to be working up a simple cheat sheet, and
probably fixing some problems, for wiki use, so that may be helpful.)

Out of curiousity, is it worth talking about StructuredText at this point,
or would it still be considered unacceptable?  If it does seem
unacceptable, could you reiterate the objections?  I don't promise a quick
reply, but i think it would be a major win, and would be willing to expend
some effort to see it find its place.

-- 
Ken
klm@digicool.com