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

[Peter Funk]

Hi!

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

[Moshe Zadka]:
> 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>)

Do you really mean, you actually want to change the markup of already
doc string'ed Lib/... modules by encrypting^H^H^H^H^H^H^H^Hediting
their current doc-strings? ;-)

Or should we better look at existing doc-string'ed Lib/... modules 
(most of them got doc string'ed in the CVS last weekend) and look, whether 
a clever tool (something like 'pythondoc/gendoc/manpy') could possibly 
gather enough information without special markup, which is sufficient 
enough "most" of the time?

Or should we first have a look at the rich set of LaTeX macros described 
in Freds .../Doc/doc/doc.tex and run a histogram analysis script over 
.../Doc/lib/...*tex and count, which of them are really regulary used?
The current style files define some very esoteric markup tags.  Others 
are used often, like section headings, nested lists, \code, 
verbatim-environment ....

I guess, that an enhanced 'StructuredText' approach augmented with
a identifier reference analysis similar to this suggested by ping
today will be able to tag the most often used elements in doc-strings
without the need to heavily modify any existing doc strings.

Okay.  ASCII graphics like this seen in ping's example 'SocketServer.py' 
will be very difficult.  But those are rare in doc-strings anyway.

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60