M.Z. assumptions (was Re: [Doc-SIG] Re: Ease of use is #1)

[Moshe Zadka]

On Mon, 7 Feb 2000, Fred L. Drake, Jr. wrote:

>   Ok, guys, I think this points out where the communications failure
> is (what other kind is there?).

Which was the purpose of my "assumptions" mail <wink>

>   Docstrings, combined with language information obtained from the
> parse tree or reflection, should be sufficient to generate "usable"
> documentation "most" of the time.

OK, that sounds like a good goal for the doc-string grammar proposal. As
a way to make it a bit less vague let me suggest one criterion for any
doc-string syntax: pick any 2-3 doc-string'ed modules from the standard
library, and mark them up so the resulting documentation will be just as
good as what is currently in the library reference. Any suggestion which
doesn't meet this criterion will surely fail whatever vague notion Fred
has (unless it is vague enough <wink>)

>   (Moshe:  Please don't think I meant that *you* really had to do
> *everything* with the documentation!  I was just joking about that at
> the IPC8 Doc-SIG session!  We welcome your participation, but it's up
> to me to act as channel for the BDFL here; keeps the hate mail in my
> box rather than yours. ;)

if-I-wouldn't-want-to-take-you-seriously-I-wouldn't-ly y'rs, Z.
--
Moshe Zadka <mzadka@geocities.com>. 
INTERNET: Learn what you know.
Share what you don't.