Have to complain about building documentation

[Joel Feiner]

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
> characters.
>
> 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
> ./autogen.sh
> make sgml/ddx/foo.pdf


Doesn't work.

> 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....)
>
> 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.




See above


> 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.
> >
>
> Solving bug #647 is the big documentation hurdle, that bug has been open
> for years.
>
>
> --Eamon W.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.x.org/archives/xorg/attachments/20070429/60a10fc1/attachment.html>