[ANNOUNCE] xorg-sgml-doctools-1.2

[David Nusinow]

Hi Jeremy,

On Sat, Mar 03, 2007 at 04:05:46PM -0600, Jeremy C. Reed wrote:
> David,
> 
> Thanks for your work on the xorg docs.
> 
> Can you explain a little about your changes there?

Sure. The sgml docs that were in xorg-docs-1.3 were formatted using
linuxdoc, which had been abandoned for docbook in the late 90's. In
response to ajax's request for help with the 7.2 release notes I tried to
build the package, but couldn't with any version of the tools in Debian for
the past ~4 years. So I converted them to docbook sgml to allow them to
build. I used the docbook2x series of tools to actually do the building.

Eamon did a ton of great work reorganizing the docs more coherently and
improving the build system as well, so the infrastructure is really sound
now.

> What tools are needed to contribute or use the docs?

You'll need the docbook2x series of tools, located at
http://docbook2x.sourceforge.net/
and docbook itself. Other than that, a text editor should be enough.
There isn't a great sgml or xml editing tool that's free software right
now, although I hear great things about emacs' modes for them.

> What needs to be done?

A big issue is bug #647. I haven't taken a serious look at how to fix this
yet, but I want it fixed for the 7.3 katamari. Another thing is that the
general consensus was to convert the sgml to xml. There was a script
written to do this, but no one has actually transitioned the docs over to
xml yet. I may also roll the xorg-sgmldoctools package in to xorg-docs, or
at least add a .pc file for sgmldoctools.

The most important thing of all though is to write more and better docs,
and to improve the ones we've already got. The infrastructure is in place
to do it, we just need people to write. One interesting idea is to bundle
some useful docs that are on the wiki in to xorg-docs, so they can be used
without a web browser.

> And is there a wiki page so people can keep track or contribute?

Not yet, and I'm not really sure what would be on such a page. If you want
to make one though, let me know and I'll be happy to add what I can.

 - David Nusinow