Guestions & Observations on Docs (1.9.0)

[Chris Lyttle]

David V Herman wrote:
> Question - is this tweek still relevant? It would be a small diff for
> most chapter files.
>
>   
To be honest, I'm not at all interested in keeping the sgml files up to 
date or even usable. To me sgml was abandoned for making docs some years 
ago and the only reason I agreed to it going into the 1.8 docs was 
because of the complaint that there was no way to make pdf's without it. 
I am working on alternatives to once again have pdf generation be 
possible with the docbook-xml, but this wont be ready at all for the 
release. In my mind its up to you if you want to follow this guideline.
> 2) The Help documentation "needs updating".
>   
Yep, it needs a fair bit of work. This was part of the reason for 
releasing the tarball so it would be easier to see what needed to be done.
> 3) I believe there are many out-of-date files in the docs tree - are
> they there for a reason other than historical?
>   
Yeah, there are a few files that I'll probably be deleting before the 
2.0 release. I'm concentrating on getting the build system in shape atm.
>
> General questions;
>
> 1) I have been "Building" the documentation for some time using the
> "make all install" command at the top level directory of the
> documentation tree.
>
> I have several doc trees, working, and standard base.  Since I built
> 1.9.0 I have not been able to build the working documents. No error
> messages, just "nothing to do".  I have made modification to several
> source XML files in both the "guide" and "help" branches of the working
> tree and the docs do not get built.
>
> Have performed "make distclean", "make clean", no effect.
> I even tried the "make all install --always-make" this resulted in what
> appeared to be an endless loop (stopped after only 15 min.).
Well, I altered the build system quite a bit in getting the 1.9.0 
release ready. Basically right now by default _no_ docs get converted to 
html as this isn't needed for Yelp support. there is a new 'make html' 
that will build the html docs for you, but I haven't figured out how to 
get a 'make html-install' to work. I'm not quite sure what you mean by 
not being able to build working documents though. Nothing is needed to 
'build' the docs, most of what the build system does is just install the 
docs in the right places on a users system so it can be seem by yelp. 
For development work all you should need to do to view your work is to 
run 'yelp <docname>'
PS When I'm testing the building of tarballs I use './autogen && 
configure && make && make distcheck'

Chris