[libvirt] [PATCH] build: Fix API docs generation in VPATH build

[Jiri Denemark]

On Fri, Feb 18, 2011 at 20:42:10 +0800, Daniel Veillard wrote:
> >  $(addprefix $(srcdir)/,$(devhelphtml)): $(srcdir)/libvirt-api.xml $(devhelpxsl)
> >  	- at echo Rebuilding devhelp files
> >  	- at 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