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.