[libvirt] [PATCH] build: be smarter about building documentation

[Daniel P. Berrange]

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 :|