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