Re: primitive documentation conventions

[roland.kaufmann@hermes.space.at]

			      Hello all,
what's so bad about Emacs' approach for documentation strings?  If I
understand correctly, strings are attached to function and variable
definitions (both C and Lisp/Scheme) and extracted to a DOC file (we
would probably need one for each module).  They can be accessed from
the interpreter (which IMHO is highly desirable) and transformed to
Texinfo (the latter step could probably snarfed from Emacs, freeing us
from Perl ;-).

I don't think that the Emacs Lisp manual was generated from these
strings, though--I think that a manual is more than just a list of all
functions and their documentation strings.  Maybe it is possible to
write a document which includes automatically generated parts, but
the overall structure must be established by humans.

As for literate programming (LP), experienced users on
comp.programming.literate agree that it is not feasible to combine a
*user manual* with source code--LP is a method enhance the
documentation of the implementation (i.e. how does Guile work),
possibly for an interface specification.  Not a bad thing (I'm afraid
it is still practiced only by a very small minority), but different
from a user manual (which should decribe how to use Guile).  Take TeX,
the first literate program as example--``TeX the program'' is a
detailed description of the implementation and the (Pascal) code is
extracted from the same source--the ``TeXbook'', the user manual is a
traditional book.

>From my limited experience of using LP, I would recommend to use
noweb, but I am not sure how well LP and bazaar-style development fit
together--in any case converting Guile into a truly literate program
would be quite some work (more than adding docstrings to all
functions) and require agreement by all developers to switch to use
LP.

Just my $0.02.
Roland