Re: Doc Tasks (was RE: docstrings in Guile!)

["Greg J. Badros" <gjb at cs dot washington dot edu>]

"Reynolds, Gregg" <greynolds@datalogics.com> writes:

<snip>

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

I'm setting up a web page to manage this stuff.  For now, AFAIK, no one
has claimed anything.  It'd be great if you'd just post which file(s)
you're working on and go for it.  Be sure to cut and paste from existing 
(external) documentation where possible -- e.g., R[45]RS, Greg Harvey's
quick and dirty docs:

http://home.thezone.net/~gharvey/guile/qdocs/

etc.

I'll post a URL once I get the web page up, but please do not wait for
it as now is the time for action!

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

I'm all for DocBook instead, and if you write new stuff, then by all
means use it.  It won't be that hard to convert the TeXinfo stuff to
docbook later, and it sounds like we'll be able to convert from DocBook
to TeXInfo before too long (and we might even be able to now).

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

I'm planning on using Scwm style in-file markup and extracting it:

/** CONCEPT: Foo
   info about concept foo using <emph>docbook</emph> markup
  */

Please use this format for now; we can change later if there's a good
enough reason to.

Greg Badros