Re: Make of docs and other stuff
Hi,
On Thu, May 10, 2007 at 13:52:06 +1000, Brian Salter-Duke wrote:
> > On Wednesday, May 9 at 05:32 PM, quoth Brian Salter-Duke:
> > This is explained in mutt/doc/devel-notes.txt. Essentially, you need
> > to export some environment variables to tell it where the XML catalog
> > files are.
> OK, this works, but I had to download the two distributions and one is
> over 2Mb. It seems overkill. The devel-notes.txt is pretty obscure. It
> used to be for developers, not for Joe Blow just trying to compile from
> sources. Thanks for drawing my attention it.
I would guess this is just required for the development versions and
for CVS um HG, right? The final version (did anyone say "one dot six"
yet?) should habe the documentation pre-built. "Should" means: I am
assuming this is the case, but if not, "should" means I demand this.
;-)
BTW, this build process with the extra XML packages did _not_ work for
me on SLES9. I figured out that xsltproc from libxslt-1.1.2-58.7 is not
handling $XML_CATALOG_FILES correctly. I do this as a workaround (sorry
for the long lines):
mkdir -p ${BUILDROOT}/instroot/share
(cd ${BUILDROOT}/instroot/share && unzip -d docbook-xml-4.2
${SOURCEROOT}/docbook/docbook-xml-4.2.zip)
(cd ${BUILDROOT}/instroot/share && unzip
${SOURCEROOT}/docbook/docbook-xsl-1.70.1.zip)
XML_CATALOG_FILES="${BUILDROOT}/instroot/share/docbook-xml-4.2/catalog.xml
${BUILDROOT}/instroot/share/docbook-xsl-1.70.1/catalog.xml"
# fix xsltproc (doesn't parse $XML_CATALOG_FILES correctly)
echo '#!/bin/sh -x' > ${BUILDROOT}/instroot/bin/xsltproc
echo 'exec '`which xsltproc`' --path
${BUILDROOT}/instroot/share/docbook-xsl-1.70.1/xhtml "$@"' >>
${BUILDROOT}/instroot/bin/xsltproc
chmod +x ${BUILDROOT}/instroot/bin/xsltproc
> > >2. Why do we even need to make the documents. They are on the main
> > >site or they can just be added to the release.
> >
> > The idea, I believe, is that we only want to write one set of
> > documents, and have them built into both html and man pages. Otherwise
> > it becomes a "you updated it here, did you update it there too?"
> > thing.
And this process being in place is quite handy for any patches (and
there are so many ;->). They just need to drop their text in in one
place, and presto. (Otherwise, patches will keep conflicting on the
docs.)
> If the appropriate makefile for the documents was available to those who
> release a new release, they could run it and put the documents on the
> web page where the release is announced.
As I wrote above, like configure from configure.ac, a release should
also build the documenation from doc/ before packaging. Now, you may
want to extend this to beta (1.5.x) releases. It would be nice, I
guess.
> > Hm. It doesn't stop *my* build. I wonder why it stops yours...?
> I have no idea, but I later realised that it was hanging leaving lynx,
> make and various thinks still running. It is certainly OK now.
Parallel build is still insanely broken on doc/. a bug is open on that
(I'm too lazy to figure out its ID right now).
Moritz