[prev in list] [next in list] [prev in thread] [next in thread]
List: freedesktop-xorg
Subject: Re: Have to complain about building documentation
From: "Joel Feiner" <jafeiner () gmail ! com>
Date: 2007-04-29 22:00:49
Message-ID: 78dd15b90704291500q77d09be1l298a39799d101e60 () mail ! gmail ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
On 4/28/07, Eamon Walsh <efw@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.
>
[Attachment #5 (text/html)]
<br><br><div><span class="gmail_quote">On 4/28/07, <b class="gmail_sendername">Eamon \
Walsh</b> <<a href="mailto:efw@eamonwalsh.com">efw@eamonwalsh.com</a>> \
wrote:</span><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:<br>> \
In that it is nearly impossible. There was a discussion on this \
list<br>> previously about the difficulties involved with SGML and being able \
to<br>> actually read the documentation. He was told that it's \
really easy and <br>> it is automatically built, etc. Except that \
it's not. It took me a<br>> while to figure out exactly which \
packages I need to have installed and<br>> where to get xorg-docs to \
build. It didn't give me any error messages, <br>> it just \
wouldn't build the documentation. It never said why. When \
I<br>> finally got it working, half the documents wouldn't build because \
they<br>> have weird characters or something. Who knows how to fix \
that. That's <br>> really awesome, guys.<br><br>What are the \
errors? Specifics, please. You need the xmlto package \
on<br>your system and its dependences. Then it should just \
work.</blockquote><div><br>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.<br>
<br>
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><br><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<br> XML. Not too \
much different, but maybe that's what's causing the \
bad<br>characters.<br><br>There is a longstanding xorg bug #647 to convert all the \
old formats in<br>the specs directory of xorg-docs to DocBook.<br> \
<br><br><br>><br>> In one of the recent messages, there was a link to a Wiki \
page that<br>> described X and input events. It mentioned a DESIGN.sgml \
document<br>> inside the xserver tree. Of course it's sgml, so that \
means it has to <br>> be build. Well, apparently there's no way to \
tell the xserver<br>> ./configure script to build \
documentation. There's no make option to<br>> make it build that \
file. So there's this sgml file lying around in the <br>> tree \
that's practically useless to me, unless I know all the arcane<br>> command \
line options to whatever program it is (Jade?) that converts<br>> sgml to \
something useful. So I cannot use this document, basically. <br>> \
Wonderful.<br><br>That file is in LinuxDoc, not DocBook. Once it is \
converted to DocBook<br>it could be placed in the xorg-docs under \
sgml/ddx. I don't know what<br>else is in the xserver doc \
directory.<br> <br>IMHO everything should be in xorg-docs, but according to the \
xorg-docs<br>README the eventual plan is to move things back to doc/ directories \
in<br>the other packages.<br><br>><br>> This is a sorry state of things, \
guy. Something needs to be done. But, <br>> not to complain \
in vain, I am going to offer to fix the documentation<br>> problem if somebody can \
tell me how to make the sgml stuff work. There<br>> should be one or \
more of the following (in my uninformed, but <br>> frustrated, opinion):<br>> \
a) A script that will build documentation files. So I could run<br>> \
builddoc.sh somefile.sgml and as long as the sgml file belongs to the<br>> xorg \
docs, then it will build it and produce a pdf or whatever. No <br>> \
muss, no fuss.<br><br>You should be able to just run<br>./autogen.sh<br>make \
sgml/ddx/foo.pdf</blockquote><div><br>Doesn't work. <br></div><br><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<br>> packages other than xorg-docs (maybe there \
already is? I can't find it....)<br><br>First those docs should be \
converted to DocBook. However I think a <br>quick Google search should \
turn up hardcopies of most things, including<br>the \
DESIGN.sgml.</blockquote><div><br>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! \
<br></div><br><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<br>> builds. And if there are \
errors, it shouldn't stop the whole build...it <br>> should just skip that \
file.<br><br>Again, what are the specific \
errors.</blockquote><div><br> </div><br><div>See \
above<br> </div><br><blockquote class="gmail_quote" style="border-left: 1px \
solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"> > \
OR<br>> d) At the very least, have a wiki page that explains how to make \
things<br>> work they way they should. Maybe I'm just not doing \
things right, but I<br>> would have no way of knowing that because there's, \
ahem, no <br>> documentation for building the documentation.<br>><br>> \
Commentary is welcome. I might just be an idiot and this is really<br>> \
simple. Then again, I'm the second or more person to have \
complained<br> > about the documentation status on this list. I imagine \
there must be<br>> ten times as many out there who are frustrated and have given \
up, or not<br>> even tried. I know most of the devs don't have time \
to deal with <br>> documentation niggles, which is why I'm offering to try to \
do some of<br>> the work, if I could be pointed in the right \
direction.<br>><br><br>Solving bug #647 is the big documentation hurdle, that bug \
has been open <br>for years.<br><br><br>--Eamon W.<br></blockquote></div><br>
_______________________________________________
xorg mailing list
xorg@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/xorg
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic