Re: [libvirt] [RFC PATCH] build: detect doc build errors

I'm still stumped by xsltproc complaining about   not being a valid XML entity, hence the (hackish) exemption in docs/Makefile.am that adds --html for a couple of .html.in files. But for the remaining files, this does make input validation stricter, and caught several bugs.

Hence, this is an RFC (either we live with my hack that caught all the issues in the prior patch, or someone with more xsltproc knowledge than me will step in and teach it how to resolve html entities while processing the documents as xml instead of html).

* docs/Makefile.am (maintainer-clean-local): Remove generated docs in VPATH build. (%.html.tmp): Don't use looser --html; our input should be strict xhtml. HACK - use --html when entities like &nbsp; are involved. (html/index.html): Exit on formatting problems. (rebuild): Run full doc build on request. --- docs/Makefile.am | 24 ++++++++++++++---------- 1 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index db4bc59..2d1afe4 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -123,7 +123,7 @@ internals/%.html.tmp: internals/%.html.in subsite.xsl page.xsl sitemap.html.in echo "Generating $@"; \ $(MKDIR_P) "$(builddir)/internals"; \ name=`echo $@ | sed -e 's/.tmp//'`; \ - $(XSLTPROC) --stringparam pagename $$name --nonet --html \ + $(XSLTPROC) --stringparam pagename $$name --nonet \ $(top_srcdir)/docs/subsite.xsl $< > $@ \ || { rm $@ && exit 1; }; fi @@ -131,7 +131,8 @@ internals/%.html.tmp: internals/%.html.in subsite.xsl page.xsl sitemap.html.in @if [ -x $(XSLTPROC) ] ; then \ echo "Generating $@"; \ name=`echo $@ | sed -e 's/.tmp//'`; \ - $(XSLTPROC) --stringparam pagename $$name --nonet --html \ + $(XSLTPROC) --stringparam pagename $$name --nonet \ + $$(grep -qE '&(nbsp|uuml|mdash);' $< && printf %s --html) \ $(top_srcdir)/docs/site.xsl $< > $@ \ || { rm $@ && exit 1; }; fi @@ -147,21 +148,22 @@ internals/%.html.tmp: internals/%.html.in subsite.xsl page.xsl sitemap.html.in html/index.html: libvirt-api.xml newapi.xsl page.xsl sitemap.html.in - -@if [ -x $(XSLTPROC) ] ; then \ + @if [ -x $(XSLTPROC) ] ; then \ echo "Rebuilding the HTML pages from the XML API" ; \ $(XSLTPROC) --nonet -o $(srcdir)/ \ $(srcdir)/newapi.xsl $(srcdir)/libvirt-api.xml ; fi - -@if test -x $(XMLLINT) && test -x $(XMLCATALOG) ; then \ - if $(XMLCATALOG) '$(XML_CATALOG_FILE)' "-//W3C//DTD XHTML 1.0 Strict//EN" \ - > /dev/null ; then \ + @if test -x $(XMLLINT) && test -x $(XMLCATALOG) ; then \ + if $(XMLCATALOG) '$(XML_CATALOG_FILE)' \ + "-//W3C//DTD XHTML 1.0 Strict//EN" > /dev/null ; then \ echo "Validating the resulting XHTML pages" ; \ SGML_CATALOG_FILES='$(XML_CATALOG_FILE)' \ - $(XMLLINT) --catalogs --nonet --valid --noout $(srcdir)/html/*.html ; \ + $(XMLLINT) --catalogs --nonet --valid --noout $(srcdir)/html/*.html \ + || { rm $(srcdir)/$@ && exit 1; }; \ else echo "missing XHTML1 DTD" ; fi ; fi $(addprefix $(srcdir)/,$(devhelphtml)): $(srcdir)/libvirt-api.xml $(devhelpxsl) -@echo Rebuilding devhelp files - -@if [ -x $(XSLTPROC) ] ; then \ + @if [ -x $(XSLTPROC) ] ; then \ $(XSLTPROC) --nonet -o $(srcdir)/devhelp/ \ $(top_srcdir)/docs/devhelp/devhelp.xsl $(srcdir)/libvirt-api.xml ; fi @@ -183,9 +185,11 @@ clean-local: rm -f *~ *.bak *.hierarchy *.signals *-unused.txt *.html maintainer-clean-local: clean-local - rm -rf $(srcdir)/libvirt-api.xml $(srcdir)/libvirt-refs.xml todo.html.in + rm -rf $(srcdir)/libvirt-api.xml $(srcdir)/libvirt-refs.xml \ + todo.html.in $(srcdir)/*.html $(srcdir)/devhelp/*.html \ + $(srcdir)/html/*.html $(srcdir)/internals/*.html -rebuild: api all +rebuild: maintainer-clean-local api all install-data-local: $(mkinstalldirs) $(DESTDIR)$(HTML_DIR) -- 1.7.4