Re: Automated Doc Extraction: A Premature Retrospective

[Maciej Stachowiak <mstachow@mit.edu>]

I noticed belatedly that I adressed the initial post to
`scwmm-discuss' among other places, a misspelling of `scwm-discuss'. I
have corrected it here and would appreciate if others would do the
same when replying on this thread.

perry@piermont.com writes:
> 
> 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.
> 

Well, for one thing, we also want this to be able to turn into nice
printed output. For another, alphabetical is _one_ thing you want
(same purpose as the index), but you probably also want more of a
conceptual organization.

> 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.
> 

We have documentation of concepts in the source already, I think a
good plan would be to attach procedure documentation to the nearest
concept and put them on one page. Obviously there must be ways to
break that convention for the sake of code organization.

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

That's what I expect.

> > 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".
> 


I've been using it long enough now that the source is sufficient
documentation for most things, but there are unfortunately very few
people in that category.

One thing I thought of since when I posted last night is that for
Guile, it is as important, if not more important, to document the C
API as well as the Scheme API. This was not a concern for
scwm. However, just by adding C function signatures as well as Scheme
ones to the documentation output, you can document (in a reference
sense) almost all of the scm_ API for free just by documenting the
Scheme primitives.

 - Maciej