Re: Documentation proposal

[Christian Lynbech <chl at tbit dot dk>]

>>>>> "Michael" == Michael Vanier <mvanier@bbb.caltech.edu> writes:

Michael> -- a detailed description of how the evaluator works.  Why
Michael> should everyone have to rediscover this for themselves?

But will everyone need to understand the internals? Since this is a
complex beast, it will be complex to do a proper description. I am not
saying the idea isn't good, but I suggest keeping this low on the list.

Michael> -- description of how to extend guile in C/C++, including
Michael> adding new data types;

Highly needed, but there already exists some docs in this area. Either
this resides in guile-core/doc or in the guile-doc module.

Michael> -- a texinfo version of the reference manual, with all
Michael> functions described.  IMO this is much more valuable than
Michael> docstrings, though of course the two aren't mutually
Michael> exclusive.

One could generate a texinfo manual from docstrings and have both. I
personally think that docstrings are pretty helpfull, but not
everybody feels that way. SCWM does it slightly different I think
(adding specially formatted comments to the code instead).

IMHO, this should be the top priority (autogenerating a reference
manual from sources). 

This would involve devising a proposal of how to integrate docstrings
into the source (comments or part of the definition, deciding how to
integrate this with the C source), writing the extraction tools and
integrating this into the build process. 

A side bonus to this process could be some way of getting online info
on parameters to primitive functions.

Anyway, checking up on how SCWM does it would be a logical first step.

Just for the fun of it, I have included some code I have written for
our project. This will work over scheme files and produce texinfo
output. Included is also the makefile driving the process and some
elisp to generate menus.

The code should general enough though it contains some specifics as
what sources to include and where they are situated.

generate texinfo documentation from docstrings

elisp for generating menus

makefile for driving info generation

---------------------------+--------------------------------------------------
Christian Lynbech          | Ericsson Telebit A/S                       
Fax:   +45 8628 8186       | Fabrikvej 11, DK-8260 Viby J
Phone: +45 8628 8177 + 28  | email: chl@tbit.dk --- URL: http://www.tbit.dk
---------------------------+--------------------------------------------------
Hit the philistines three times over the head with the Elisp reference manual.
                                        - petonic@hal.com (Michael A. Petonic)