This is the mail archive of the guile@cygnus.com mailing list for the guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: Automated Doc Extraction: A Premature Retrospective



Maciej Stachowiak writes:
> * The manual has no proper organization of any kind yet. You only get
> an alphabetical list of all the procedures, or a list by file where
> they are defined. It should be possible to impose a better organization

I think that this is absolutely fine for a hyperlinked reference
work. Alphabetical is what you *want* in such a thing.

However, what one might be able to do is add a "category hint" of some 
sort or other to each docstring if it is desired to do "alphabetical
by category" or some such.

For the tutorial manual or what have you, it will probably be
reasonable to hyperlink general descriptions to the reference manual
for detailed information.

> The doc extractor also proved to have benefits beyond just the
> documentation. Greg added features to it to warn if the C and Scheme
> names of a function did not match according to the usual conventions,
> or if the C functions formals did not match the number of different
> types of arguments as specified in SCM_PROC. This helped locate a
> number of latent bugs.

Cool!

> In fact, Guile's lack of good documentation has been a serious
> impediment to my attempts to evangelize Guile for all sorts of uses,

I strongly agree with this. I myself have not used it in several
projects because figuring things out without a good document is just
"too hard".

Perry