Re: [Chicken-users] egg documentation

[Vincent Manis]

On 2008 Feb 21, at 23:57, Alejandro Forero Cuervo wrote:

> As such, I will need more convincing before implementing support for
> <indexentry>.  I don't see what it adds that we can't already do.  Ok,
> I see that it would allow arbitrary pages to declare sub-topics of a
> given topic, but I don't think that should be supported.

I fully agree that much of the indexing can be done automatically, but
a good index also includes entries that can't be generated  
automatically.
Again, taking my append example, we might be documenting SRFI-1, in  
which
case we might want concatenate to have an index entry for append.

Truthfully, the indexing facility is going to be more useful for the
Chicken manual itself, but I do think that a complicated egg might also
benefit from it.

As for bold-facing entries, sometimes that can be done from section
headings, but sometimes that isn't practical. Consider documenting the
tinyclos egg, where you might find that the main index entry for
`method resolution order' may or may not be in a section with that name.

> > These entries would just be written to a file, and external code
> > would then process them to produce index pages or whatever.
>
> I think an index of the entire wiki would be way too big to be useful.
> If there's interest in this, I could generate it.  Keep in mind that
> the wiki currently has 300+ files.
Ulp. That requires more thought on my part. Again, I was mostly thinking
in terms of an index database for the manual, or for a small locally-
developed set of eggs.

> > Perhaps Alejandro's database of `where symbols in the wiki are
> > documented' could also be added to this external file?
>
> I like this idea.  I'll probably do it. :-)
>
> Thanks for the suggestions, Vincent.
My pleasure! -- v