Have to complain about building documentation

[Joel Feiner]

In that it is nearly impossible.  There was a discussion on this list
previously about the difficulties involved with SGML and being able to
actually read the documentation.  He was told that it's really easy and it
is automatically built, etc.  Except that it's not.  It took me a while to
figure out exactly which packages I need to have installed and where to get
xorg-docs to build.  It didn't give me any error messages, it just wouldn't
build the documentation.  It never said why.  When I finally got it working,
half the documents wouldn't build because they have weird characters or
something.  Who knows how to fix that.  That's really awesome, guys.

In one of the recent messages, there was a link to a Wiki page that
described X and input events.  It mentioned a DESIGN.sgml document inside
the xserver tree.  Of course it's sgml, so that means it has to be build.
Well, apparently there's no way to tell the xserver ./configure script to
build documentation.  There's no make option to make it build that file.  So
there's this sgml file lying around in the tree that's practically useless
to me, unless I know all the arcane command line options to whatever program
it is (Jade?) that converts sgml to something useful.  So I cannot use this
document, basically.  Wonderful.

This is a sorry state of things, guy.  Something needs to be done.  But, not
to complain in vain, I am going to offer to fix the documentation problem if
somebody can tell me how to make the sgml stuff work.  There should be one
or more of the following (in my uninformed, but frustrated, opinion):
a) A script that will build documentation files.  So I could run builddoc.sh
somefile.sgml and as long as the sgml file belongs to the xorg docs, then it
will build it and produce a pdf or whatever.  No muss, no fuss.
b) A ./configure option to build the documentation that comes in packages
other than xorg-docs (maybe there already is?  I can't find it....)
c) All the errors need to be fixed so the documentation actually builds.
And if there are errors, it shouldn't stop the whole build...it should just
skip that file.
OR
d) At the very least, have a wiki page that explains how to make things work
they way they should.  Maybe I'm just not doing things right, but I would
have no way of knowing that because there's, ahem, no documentation for
building the documentation.

Commentary is welcome.  I might just be an idiot and this is really simple.
Then again, I'm the second or more person to have complained about the
documentation status on this list.  I imagine there must be ten times as
many out there who are frustrated and have given up, or not even tried.  I
know most of the devs don't have time to deal with documentation niggles,
which is why I'm offering to try to do some of the work, if I could be
pointed in the right direction.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.x.org/archives/xorg/attachments/20070427/d1a57687/attachment.html>