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

["Reynolds, Gregg" <greynolds at datalogics dot com>]

> -----Original Message-----
> From: Telford Tendys [mailto:telford@eng.uts.edu.au]
> Sent: Thursday, December 16, 1999 6:47 PM
> 
> 
> > 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 

What's wrong with this picture?  A non-profit, international consortium of
many vendors puts together a sophisticated DTD for technical documentation,
it becomes widely adopted and easily available via the net, a couple of
people thoroughly document it, a publisher widely known for supporting free
stuff publishes not only a paper version but a freely available html
version.

Now, how exactly is that non-free?

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

It's not really a question of whether texinfo is nice or not.  I happen to
like using the emacs help system, so I want the doc to end up in that form,
but the original should be maintained in the format most conducive to
freedom.  Look at the world: it's already full of tools designed
specifically to manipulate XML, many of which are free, many of which are
easy to use, and many more are on the way.  How many tools are available
specifically designed to handle texinfo?  XML, for these purely practical
reasons, liberates the data from its format; texinfo, today, must be
considered a limiting form.

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

Depends on how extensively marked up the doc is.  If we force people to use
texinfo, we limit the freedom they have to add intelligence to the markup.
That's a real contribution that should not be treated lightly.  You never
know when somebody non-technical will be smitten by Guile and decide to
fancy-up the documentation *semantically*.  Actually, the same goes for the
stylesheet - with a standard free data format, anybody can come along and
contribute a new, more powerful or beautiful stylesheet.

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

I hope I answered that.

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

Right, my point was simply that documentation can be placed anywhere in the
file.  And no, it's not that hard to document source code in Docbook -
that's what it was designed for.

It sounds to me like you should take another look at Docbook (and XML in
particular).  This is coming from a guy who is not that crazy about SGML and
XML in the first place, for reasons of design aesthetics more than anything
else.  But the case for adopting it is pretty much a no-brainer.  As for
fear-of-software-hoarding, even in the worst-case scenario, where the
nefarious evil geniuses behind OASIS decide that everybody who uses Docbook
must pay, XML's openness and the plethora of XML tools makes it relatively
easy to transform your documents into another XML language.  So I don't see
that using Docbook puts us in anybody's pocket.

-gregg