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

[Telford Tendys <telford at eng dot uts dot edu dot au>]

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

That's a non-free documentation owned by a publishing company. It is exactly
the sort of thing that the GNU project does not need. I hate to be rude but
the texinfo format has some nice things about it, one of which is that you
can learn it in an hour using only free-software tools and free-software
documentation. OK, it doesn't support a lot of fancy features but what it does
it does well, and it does enough for my documentation needs.

>  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 bet it wouldn't be too hard to transfer backwards too <shrug>.

>  I haven't looked at it very hard yet,
> but using XML seems like a big win.

why?

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

Triggering the snarfer on the <metasnarf> tag has the problem that
it could trigger on:

	char *a = "<metasnarf">;

So you have to trigger on the comment introducer plus the metasnarf
tag which is always safe but at that point why make the tag an XML style
tag when it can equally be ANY other string that gets dropped after the
comment introduction? I guess a lot of people see XML tags as the answer
to everything but the < and > symbols get used a fair bit in programming
so you get things like:

	(blurg X Y Z)

	Note that this will generate an error unless X < Y < Z

and:

	(snorple W)

	This function cannot be called from C but users can get away
	with ((( fargle * )W )->snorple ) which should suffice.

Maybe docbook has a neat way to cope with these issues, but in HTML
you need horrible & sequences which I cannot read or write in a hurry,
then I have to remember if the & sequences absorb the space after them
like TeX macros do and then test to see if it does actually look like
what I expect, by which time I've forgotten what it was that I was writing
about.

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

Then again, as was mentioned earlier, any docco is good whatever format
it happens to be in.

	- Tel