Documentation conversion status [was: Re: companies contributing to X]

Matt Dew matt at osource.org
Sat Nov 27 12:24:57 PST 2010


As many of you know, with some guidance from Alan, Gaetan and I have
been quietly slugging through converting the in-tree documentation to
docbook/xml.  With the goal of having attractive, usable documentation
that's easy to edit and generate html,pdf,ps and text, with an
emphasis on consistency across it all.

I can speak just to the conversion:
There are roughly 2200 pages of documentation in the tree, written in
5 different formats (SGML, troff, Framemaker, tek, asciidoc)
by multiple people across multiple years. This means the conversion
must be done in a couple steps.  One of the purposes of the first step
is just to get an idea of what has been done so that we can get a list
of xml tags used in all the docs.  We can then pair down this list to
remove redundant tags.
  From this smaller list, we'll generate an example document from
which we can apply tags across all the documents consistently.  The
xorg.css and Xorg_profile-mode.xsl stylesheets use those xml tags to
control presentation.
  One thing that some have noticed.  The documentation that has been
converted is ugly. It has the content but lacks the formatting. That
is step 2.

Normal spiel:
Having consistent documentation that's easy to edit and generate will
make it easier to create new and update existing documentation as well
as help new people find information.

I'm happy to report that this initial conversion is almost done.
 2000 pages have been converted, with another 200 to go. Step 2 will begin soon.

Happy Thanksgiving,
Matt



More information about the xorg mailing list