Documentation suggestions

[rurpy at yahoo.com]

"Michael Spencer" <mahs at telcopartners.com> wrote:
> A.M. Kuchling wrote:
> > On Tue, 06 Dec 2005 10:29:33 -0800,
> > Michael Spencer <mahs at telcopartners.com> wrote:
> >> not that helpful.  "Miscellaneous Services", in particular, gives no clue to
> >> treasures it contains.  I would prefer, for example, to see the data
> >> structure modules: collections, heapq, array etc... given their own section.
> >> Documentation/testing, cmd/options might be other candidates to draw together
> >> currently related material more meaningfully.
> >
> > You're right; "Miscellaneous Services" is a grab-bag of stuff, and so
> > are 'Generic OS Services' and 'Optional OS Services'.  These chapters
> > should be rearranged into more, smaller chapters.
> >
> > A patch for a draft reorganization is at http://www.python.org/sf/1375417
> >
> > --amk
> Thanks!  That looks like a good start.
>
> I experimented with some more re-organization, but I don't see away to attach
> the resulting file in the SF comments, so I'll post it here instead.
>
> Michael
--snip--
> % =============
> % BUILT-INs
> % =============
>
> \input{libobjs}                 % Built-in Types, Exceptions and Functions
> \input{libfuncs}
> \input{libstdtypes}
> \input{libexcs}
> \input{libconsts}
--snip--

Is this intended as a standalone short term bandaid, or as
part of a more serious attempt to fix the doc problems?

The builtins section should be moved to the language
reference manual.  The material it documents is part
of the language definition, not part of an add-on library.

Worse, if it stays in the library reference manual, it will
make it very difficult to fix the language reference manual,
since core parts of the discussion of the language need
to reference these builtins.  Rather like a book on the
history of World War 2 saying "For information on the
D-day invasion, please refer to ...".  Workable perhaps
but not likely to impress anyone with the competance
of its authors.

There is long history of established prior art when it
comes to documenting computer languages.  Is it
really necessary for Python to blaze new ground here?