Have to complain about building documentation
jafeiner at gmail.com
Sun Apr 29 15:00:49 PDT 2007
On 4/28/07, Eamon Walsh <efw at eamonwalsh.com> wrote:
> Joel Feiner wrote:
> > 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.
> What are the errors? Specifics, please. You need the xmlto package on
> your system and its dependences. Then it should just work.
The error is that character 65355 (or something very close to that) is not a
valid character. I guess I could hunt through the source and find those
characters, but that just shouldn't be a problem.
I have xmlto installed and its dependencies, so that shouldn't be an issue.
I should add that I can build SOME of the docs, just not all of them.
I think the plan is not to use SGML any more, but rather to use DocBook
> XML. Not too much different, but maybe that's what's causing the bad
> There is a longstanding xorg bug #647 to convert all the old formats in
> the specs directory of xorg-docs to DocBook.
> > 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.
> That file is in LinuxDoc, not DocBook. Once it is converted to DocBook
> it could be placed in the xorg-docs under sgml/ddx. I don't know what
> else is in the xserver doc directory.
> IMHO everything should be in xorg-docs, but according to the xorg-docs
> README the eventual plan is to move things back to doc/ directories in
> the other packages.
> > 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.
> You should be able to just run
> make sgml/ddx/foo.pdf
> b) A ./configure option to build the documentation that comes in
> > packages other than xorg-docs (maybe there already is? I can't find
> First those docs should be converted to DocBook. However I think a
> quick Google search should turn up hardcopies of most things, including
> the DESIGN.sgml.
I shouldn't have to do this. It should just *work* . I think it's funny
that compiling millions of lines of C code works, but converting some
documentation is nearly impossible. C'mon guys!
> 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.
> Again, what are the specific errors.
> > 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.
> Solving bug #647 is the big documentation hurdle, that bug has been open
> for years.
> --Eamon W.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the xorg