This is the mail archive of the
guile@sourceware.cygnus.com
mailing list for the Guile project.
Doc Tasks (was RE: docstrings in Guile!)
- To: "'Greg J. Badros'" <gjb at cs dot washington dot edu>, Maciej Jennifer Stachowiak <mstachow at alum dot mit dot edu>
- Subject: Doc Tasks (was RE: docstrings in Guile!)
- From: "Reynolds, Gregg" <greynolds at datalogics dot com>
- Date: Thu, 16 Dec 1999 12:21:45 -0600
- Cc: guile at sourceware dot cygnus dot com
> -----Original Message-----
> From: Greg J. Badros [mailto:gjb@cs.washington.edu]
> Sent: Tuesday, December 14, 1999 12:41 PM
>
> > > I've moved all the documentation for primitives from
> > > guile-doc/ref/{appendices,posix,scheme}.texi into the
> source code. This
> > > leaves about half of the primitives undocumented. Also,
> all the markup
> > > is currently still texinfo. I don't have a problem with
> texinfo per se,
> > > but the markup is not very descriptive or accurate.
> >
> > I hope people can volunteer to go over the code and fix/add
> docstrings.
> > Just pick a file and do it (or half a file, or whatever). No doc
> > improvement
> > is too small to be useful.
>
> It might be useful to coordinate this effort; if you're going to be
> submitting patches for a file, post it here before you start
> working on
> it, and try to post the patches within a couple days (or give us what
> you've got when your time disappears).
>
> > > I'm sure there will be build problems, etc. Please
> report them here,
> > > but *first* tell me how great this is! :-) I've literally
> spent 20 hours
> > > in the last two days trying to make Guile ready for the
> 21st century! :-)
> >
> > This is really, really great!
>
Really, really great this is! Ok, tell me where I should start. Last
night/this morning I checked out the whole bucket and built guile and goops
(no problem: brand X hardware with newly installed Redhat 6.1; much much
better than trying it with OS/2 ;), and read through the snarf stuff in the
libguile directory, so now I see how it works. Pretty cool. (Although I
think "metasnarf" would be more accurate for the doc stuff. ;) I'm planning
on using guile to do some XMLly things after the holidays, and the way
you've set it up should make it easy to contribute doco as I take notes. So
I'm prepared to start writing up docstrings, but I want to avoid overlap, so
if anybody out there has staked out an area to work on please let me know:
email me at greynolds@enteract.com (my home address, not my work address),
and/or post something to the list under the heading "Doc Tasks".
A few questions. What do you think about using Docbook instead of texinfo
markup? The official documentation is now out (available on the web!
http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html;
but you should buy a copy so Norm gets money!) and I'll bet it wouldn't be
too hard to use docbook tags in docstrings in such a way that they could be
easily transformed to texinfo syntax. I haven't looked at it very hard yet,
but using XML seems like a big win.
File-level documentation etc. It didn't take all that long to figure out
how the docstrings mechanism works, but then I do a fair amount of shell
programming and stuff. If I write up some notes on how it all fits together
would I be wasting my time, or is that something appropriate for file-level
docstrings? No reason your docstrings strategy couldn't be used to snarf
chunks of doco in c comments, like
/*<metasnarf> blah <emph>BLAH</emph> ... blah </metasnarf>*/
I'll probably do this in any case for my own notetaking, but if you think it
would be useful, I'll do so with an eye toward contributing real doco.
- the other gregg