This is the mail archive of the guile@sourceware.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]

Doc Tasks (was RE: docstrings in Guile!)


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

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]