Re: [libvirt] [PATCH] build: Fix API docs generation in VPATH build
On Fri, Feb 18, 2011 at 20:42:10 +0800, Daniel Veillard wrote:
> $(addprefix $(srcdir)/,$(devhelphtml)):
$(srcdir)/libvirt-api.xml $(devhelpxsl)
> -@echo Rebuilding devhelp files
> -@if [ -x $(XSLTPROC) ] ; then \
> - $(XSLTPROC) --nonet -o devhelp/libvirt.devhelp \
> + $(XSLTPROC) --nonet -o $(srcdir)/devhelp/ \
> $(top_srcdir)/docs/devhelp/devhelp.xsl $(srcdir)/libvirt-api.xml ; fi
> diff --git a/docs/devhelp/devhelp.xsl
b/docs/devhelp/devhelp.xsl
> index 6600f5f..add5794 100644
> --- a/docs/devhelp/devhelp.xsl
> +++ b/docs/devhelp/devhelp.xsl
> @@ -13,6 +13,13 @@
> <!-- Build keys for all symbols -->
> <xsl:key name="symbols" match="/api/symbols/*"
use="@name"/>
>
> + <xsl:template match="/">
> + <xsl:document xmlns="http://www.devhelp.net/book"
href="libvirt.devhelp"
> + method="xml" encoding="UTF-8"
indent="yes">
> + <xsl:apply-templates/>
> + </xsl:document>
> + </xsl:template>
> +
> <xsl:template match="/api">
> <book title="{@name} Reference Manual" link="index.html"
author="" name="{@name}">
> <xsl:apply-templates select="files"/>
But that chunk is far from clear, why are you doing this ?
Ah, the reasoning was in a different email, I should have copied at least part
of it into the commit message for this patch:
xsltproc --nonet -o ./ ./newapi.xsl ./libvirt-api.xml
works (outputs 4 *.html files into ./), while:
xsltproc --nonet -o ./devhelp/ ./devhelp/devhelp.xsl ./libvirt-api.xml
outputs 4 *.html files into ./devhelp but then tries to write to
./devhelp/ as a file (hence the I/O error) rather than writing output to
the fifth file devhelp/libvirt.devhelp.
That's because XSLT allows for two ways of generating the output of
transformation. Either implicit, which xsltproc prints to stdout and can be
redirected to a file using -o file. Or explicit, which means the stylesheet
contains <xsl:document> element(s) which specifies where the output should be
saved. This can be used for generating more files by a single run of xsltproc
and -o directory/ can change the directory where the output files will be
stored. And since this is cool, why not combine these two approaches in a
single file? And that's exactly what happened in devhelp.xsl. It generates 4
html files explicitly and one xml file implicitly. So -o can't ever work for
this.
Jirka