Re: Guile documentation

[Greg Badros <gjb@cs.washington.edu>]

Christian Lynbech <chl@tbit.dk> writes:

<good ideas elided>

> None of all this is rocket-science, but if we can agree on some sort
> of conventions, I think it can help us improving the overall quality
> of the documentation in the long run.

We've been having a similar discussion on scwm-discuss.  See our archive 
at:

http://huis-clos.mit.edu/scwm-discuss.1998/

In particular, we've got macros SCWM_PROC, SCWM_DEFINE_HOOK, etc. that
better encapsulate what SCM_PROC does, but do not include the
documentation for the primitive -- that is done in a /**
stylized-comment */ immediately after the SCWM_PROC.  Then we plan to
use a documentation extraction (somewhat like a literate programming
tool, really) that will write DocBook-compliant output to then be
generated into HTML, texinfo, man, etc.  The extractor is just a simple
prototype now that does the extraction but no markup.

Ideally we (the guile and scwm developers) could come to some agreement
so we can reuse tools as much as possible.

A while ago when this came up, I was encouraged *not* to use the
documentation strings at the scheme level because they were incredibly
inefficient (in space, I believe -- they were always loaded).  We were
planning on using a similar, comment-based documentation method for
scheme procedures, and do extraction there, too.  Then
procedure-documentation could look up the documentation in some external 
index file instead of right out of the memory image.

We're starting to add documentation to scwm, so would really like to
come to some consensus on how this should be done for both guile and
scwm in the near future....

Greg