Volunteering to assist with documentation docbook conversion.

[Wichmann, Mats D]

Alan Coopersmith wrote:
> Peter Hutterer wrote:
>> On Wed, May 21, 2008 at 10:49:36AM -0500, Michael Verret wrote:
>>> I would like to assist in converting the X docs to Docbook as
>>> mentioned here: http://www.freedesktop.org/wiki/FreedesktopProjects
>>> however I do not see a name of a contact. If there is anyone
>>> currently working on this project I would like to help. If not I
>>> will gladly do what it takes to get it started. I have experience
>>> as a Webmaster for all of Zenwalk Linux's websites and I am the
>>> sole maintainer of their X11 binary packages. Whomever is
>>> interested please feel free to reply and I'll gladly do what I can.
>> 
>> Just go for it. AFAIK, doc conversion is mostly done on a need+time
>> basis, so you might be the only one working on it right now.
> 
> I did a couple man pages, and Eamon & Peter have done a couple larger
> docs. For examples of what we did, see:
> 	lib/libXcomposite/man/   (but note bug #12725)
> 	lib/libXtst/man/
> 	doc/xorg-docs/sgml/core/Xserver-spec.sgml
> 	doc/xorg-docs/specs/Xi/protocol.xml
> 
> Obviously it would be good to establish some conventions for
> consistency (sgml or xml for instance).

doclifter can do a reasonable job turning "manpages" into docbook,
if that's what is wanted. I don't know what the rest of the X docs
are in, doclifter is basically troff->docbook.  it should certainly
be experimented with before doing a lot of manual conversions.
I've had moderately good luck with it, except....

Do use xml for new stuff, all the tools development is happening 
there and docbook sgml is starting to fall behind (as I'm painfully
aware, having to drag along a large body of docbook sgml stuff that
is staying that way for legacy reasons, or rather, because-nobody-
has-time-to-convert reasons). And doclifter (for me) is producing 
stuff that works right with docbook-xml, but may need a couple of 
fixups for docbook-sgml.

-- mats