Re: primitive documentation conventions

[Maciej Stachowiak <mstachow@mit.edu>]

jimb@red-bean.com writes:
> 
> Note that, contrary to Knuth's claims, you can't generate decent
> internals documentation by extracting stuff from the source.  Source
> code and manuals are laid out differently.  This system is only going
> to be providing point documentation, not a full manual.
> 
> That is, the FSF does the right thing in providing *both* docstrings
> and a full Emacs Lisp manual, and having them be separate.  A manual
> entry knows a lot more about its context than a docstring does, so the
> best docstrings rely little on context, while the best manuals have
> overview sections, explanations of common concepts, and then function
> descriptions which operate in that context.
> 

I think the goal is to provide something more like a reference manual
than either a user manual or internals documentation. Whatever else
the documentation contains, it should certainly provide documentation
of each exported procedure, it's arguments, and a description
something like an over-detailed docstring. If this information is
organized conceptually, i.e. by file boundaries; has documentation of
broader concepts that apply to many different primitives or to the
program as a whole; documents distinguished variables; and allows for
cross-references from each procedure's documentation to related
procedures and concepts; then you have a start on a very good
reference manual. And these are all things I envision for the
doc-extraction system. 

A user manual is still necessary, of course. You can't learn how to
use a program with just a reference manual (or at least you shouldn't
have to).

Also, it may be necessary to impose some kind of hierarchical
structure externally to even have a good reference manual. Another
potential problem is how to provide the concept documentation
interactively from within the program. Perhaps an eventual
`concept-documentation' procedure similar to `procedure-documentation'
would be useful.

 - Maciej Stachowiak