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

Eric Blake eblake at redhat.com
Fri Apr 1 22:06:50 UTC 2011


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   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
-	- at 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
-	- at 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)
 	- at echo Rebuilding devhelp files
-	- at 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




More information about the libvir-list mailing list