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

Eric Blake eblake at redhat.com
Fri Oct 4 23:14:00 UTC 2013


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?

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 621 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20131004/c7fe11a0/attachment-0001.sig>


More information about the libvir-list mailing list