[libvirt] [RFC PATCH] build: detect doc build errors
Daniel Veillard
veillard at redhat.com
Mon Apr 4 03:11:23 UTC 2011
On Fri, Apr 01, 2011 at 04:06:50PM -0600, Eric Blake wrote:
> 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.
The only solution would be to add a DTD to the html.in which use
any entity beyond the 5 ones hardcoded in the parser (lt, gt, amp,
quot and apos.
> 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).
We would need to add
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
to all the .html.in for consistency, since we now expect them to be
well formed XML and possibly using html entities.
> * 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
I think I will check this in a few hours while preparing the release,
depending on the size of the resulting diff, I may put this in, as is,
add the DTD and go full XML or keep as-is ...
Daniel
--
Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/
daniel at veillard.com | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library http://libvirt.org/
More information about the libvir-list
mailing list