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

[Maciej Stachowiak <mstachow at alum dot mit dot edu>]

"Dale P. Smith" wrote:
> 
> When scwm went with a sgml style markup, I wanted to say something, but since
> I am basically incoherent I didn't.  I don't want to make the same mistake.
> 
> Please use texinfo.  Besides the above arguments, it just looks nicer.  There
> is good support for it in emacs.  I believe it has grown over time, features
> being added as they were needed.
> 

I think the primary reason for preferring DocBook is that the documentation
people of the world generally like it better. This means that long-term,
the tools for processing DocBook will continue to improve at a much faster
rate, and that people who are good at writing and dealing with documenation
will have an easier time working with DocBook. DocBook can also leverage
the growing body of general-purpose SGML/XML tools.

I can sympathize with the complaints about the way the markup looks, but I
think that's something we can live with. Docstrings don't need a huge
amount of markup internally.

Of course, TexInfo is the official documentation format of the GNU project,
so we must ensure that the tools we believe will do the conversion work as
expected.

 - Maciej