On Fri, Oct 04, 2013 at 05:14:00PM -0600, Eric Blake wrote:
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}.ent} 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?
Or could we just skip the XMLLINT step on BSD/Cygwin. eg still generate the docs, but don't validate for HTML schema compliance. As long as we are validating HTML compliance on Linux I think that would be sufficient to stop problems. We already have logic to skip XMLLINT, but it does not create the HTML output file. Could we just turn the 'echo missing XHMTL1 DTD' into a 'cat $< > $@' ?
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.
Daniel -- |: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :|