<div>On 4/28/07, Eamon Walsh <<a href="mailto:efw@eamonwalsh.com">efw@eamonwalsh.com</a>> wrote:<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"> 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.</blockquote><div> 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. </div> <blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">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</blockquote><div> Doesn't work. </div> <blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"> > 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.</blockquote><div> 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! </div> <blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">> 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.</blockquote><div> </div> <div>See above </div> <blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"> > 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. </blockquote></div>