Re: Guile documentation (was Re: [RFD] Guile projects page)

[Greg Harvey <Greg.Harvey@thezone.net>]

Greg Badros <gjb@cs.washington.edu> writes:

> thi <ttn@mingle.glug.org> writes:
> 
> > ok how about considering the inverse...  write good docs and then have
> > source code update to use those docs (extract source code docstrings
> > from the doc source file).  the process is simpler in this direction
> > because formatting cruft from docs can be removed rather than added.
> > this also encourages people to describe their interfaces before starting
> > to hack, an unpopular practice at this time...
> 
> It's easy enough to just put the prototypes and the documentation in a
> file before coding as a description of a new module.  I'm more
> interested in the documentation of the existing system, though embedded
> documentation certainly is a big win with new code, too.
> 

For future code or changes, there should definately be a forced doc
policy (document it or it doesn't go in). For producing docs for the
core now, I think the best way to approach it is probably to start
with what I've been doing with the qdocs, basically writing separate
documentation per file; this is easy to coordinate, and doesn't make
for an overwhelming task for anybody (basically, these should just
concentrate on the visible functions, and only mention the existance
of rnrs compliant bits, possibly describing any differences between
the two). 

These should probably be in texinfo... I know someone is going to say
docbook, but there are (at least) two reasons why not: 

1. sgmltools is a bitch to get working correctly (from personal
   experience).

2. docbook, in my experience, requires far too much markup for a human
   author (I rather liked the old linuxdoc dtd, actually... no, it
   couldn't slice, dice & chop, but it was simple, and mostly worked
   well for what it was intended for). 

Once that's finished (and these are really useful by themselves; I use
the qdocs I have finished all the time), it's much easier to build
tutorial and concept documentation from these (you can concentrate on
actually explaining concepts, rather than trying to figure out exactly
what a little bit of code is trying to do).

The most important thing, though, is to try and avoid the `deer in the
headlights' syndrome that seems to hit guile far too often (hey, that
would be cool, I sure can't wait 'til someone does it). If no one else
wants to, I'll set up a page to keep track of who's doing what
(hopefully the who's consist of more than me ;), and start working on
formating the qdocs I have right now in texinfo (and removing all the
concept and example stuff, which should be saved for later). 

-- 
Greg