Re: [libvirt] [PATCH] build: be smarter about building documentation
On 09/27/2013 09:48 AM, Daniel P. Berrange wrote:
On Thu, Sep 19, 2013 at 04:27:41PM -0600, Eric Blake wrote:
> I'm tired of cryptic reports on IRC from people who build from
> git, then type 'make install' and have it fail quite a ways down
> the road because the documentation wasn't built. It's a feature
> that documentation is not built during development if the toolchain
> is not present (not all git developers build tarballs, and the
> tarballs already contain pre-built docs); but this only works as
> long as you don't try to install or make a tarball from that
> setup. With this patch in place, and without xhtml1-dtds, I now
> get this nice failure:
>
> $ make install
> cfg.mk:109: *** ERROR: missing doc toolchain (install xhtml1-dtds and xmllint).
Stop.
>
Can't we just make our existing rules fatal. I really don't see the point
in treating docs errors as non-fatal. If the docs are not built, or are
outdated, we should try to build them and fail if the tools aren't present.
This matches my reasoning behind my patch to ditch automake's maintainer
mode:
https://www.redhat.com/archives/libvir-list/2013-October/msg00226.html
We already require libxml.so be present, so requiring the
libxml/libxslt
cli tools really isn't a burden in the great scheme of things.
xsltproc and xmllint are easy to come by (it seems that every distro has
a way to download them), but having the xhtml dtds is a bit harder (I
couldn't find whether FreeBSD supports them by default, and I know that
cygwin does not have them available in the distro yet). I can easily
make bootstrap fail if the tools aren't present, but I don't know how to
make it fail if the dtds are missing.
On the other hand, I also just proved to myself that it is fairly easy
to get the dtds set up in a local catalog. A single wget of 4 files
from w3c, followed by a few xmlcatalog calls, is sufficient:
cd docs
wget http://www.w3.org/TR/xhtml1/DTD/xhtml{1-strict.dtd,-{lat1,special,symbol}...
xmlcatalog --noout --create catalog
xmlcatalog --noout --add public "-//W3C//DTD XHTML 1.0 Strict//EN"
xhtml1-strict.dtd catalog
xmlcatalog --noout --add public "-//W3C//ENTITIES Latin 1 for XHTML//EN"
xhtml-lat1.dtd catalog
xmlcatalog --noout --add public "-//W3C//ENTITIES Special for XHTML//EN"
xhtml-special.dtd catalog
xmlcatalog --noout --add public "-//W3C//ENTITIES Symbols for XHTML//EN"
xhtml-symbol.dtd catalog
cd ..
./configure --with-xml-catalog-file=$PWD/docs/catalog
Would it be appropriate to create a local catalog on any system where
xhtml1-dtds is not already present as part of the distro, during the
bootstrap phase, to make it much easier to continue to build from git on
FreeBSD and Cygwin?
IOW, we should remove all the
@if test -x $(XMLLINT) && test -x $(XMLCATALOG) ; then \
@if [ -x $(XSLTPROC) ] ; then \
conditionals, and just let 'make' do its normal deps calculation and
errore reporting.
Yes, I'd still like to do this, but only if I can get consensus on how
to handle development on platforms that don't ship xhtml dtds in an
easy-to-access distro location.
As long as the docs are included in the tar.gz people building fro mthe
tar.gz will still not build the docs.
Yes, I still plan on ensuring that this works.
--
Eric Blake eblake redhat com +1-919-301-3266
Libvirt virtualization library http://libvirt.org
Attachments:
- signature.asc (application/pgp-signature — 621 bytes)