On Mon, May 13, 2013 at 04:44:00PM +0200, Claudio Bley wrote: > At Mon, 13 May 2013 21:17:35 +0800, > Daniel Veillard wrote: > > > > On Mon, May 13, 2013 at 02:30:41PM +0200, Claudio Bley wrote: > > > Hi. > > > > > > Sometimes, it's a bit hard to determine when exactly a function, flag > > > or macro appeared in libvirt, ie. whether it will be supported on my > > > target machine having a specific version of libvirt or not. > > > > > > So, I have created an enriched version of the API docs, using a XSL > > > stylesheet enumerating the libvirt?-api.xml files of all libvirt > > > releases. > > > > > > For an example, you can have a look here: > > > > > > http://avdv.github.io/libvirt/html/libvirt-libvirt.html#virVcpuState > > > > > > Hovering over an enum value displays version information in a tooltip. > > > > > > What do you think? Should this information be included by default in > > > the API docs? > > > > Sounds a rather good idea to me, adding an extra attribute for each > > entry should not break anything. But I don't understand why you would > > need a libvirt-api-0.xml and libvirt-api-1.xml. > > Since apibuild.py always generates a fresh libvirt-api file, version > information for all symbols will be lost. > > So, I need to keep the info somewhere else; merging the information > for the old and newly added symbols into the final libvirt-api.xml. > > At least, that's how it'd work using the stylesheet I put together for > that matter. > > For the sake of completeness, here's the XSL stylesheet: > > <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform";> > > <xsl:output method="xml" > indent="yes" > encoding="ISO-8859-1" > cdata-section-elements="info" /> > > <!-- the current version of the libvirt API --> > <xsl:param name="version"/> > > <!-- build up a lookup table for existing symbols from an older --> > <!-- libvirt-api.xml file. Any newly introduced symbols are then --> > <!-- tagged with a since="$version" attribute. --> > <xsl:variable name="symbols" select="document('libvirt-api.0.xml')/api/symbols/*"/> > > <xsl:template match="/api/symbols/node()"> > <xsl:variable name="name" select="string(@name)"/> > > <xsl:copy> > <xsl:apply-templates select="@*"/> > <xsl:attribute name="since"> > <xsl:choose> > <xsl:when test="not($symbols[@name = $name])"> > <xsl:value-of select="$version"/> > </xsl:when> > <xsl:otherwise> > <xsl:value-of select="$symbols[@name = $name]/@since"/> > </xsl:otherwise> > </xsl:choose> > </xsl:attribute> > <xsl:apply-templates select="node()"/> > </xsl:copy> > </xsl:template> > > <xsl:template match="node() | @*"> > <xsl:copy> > <xsl:apply-templates select="@*"/> > <xsl:apply-templates select="node()"/> > </xsl:copy> > </xsl:template> > > </xsl:stylesheet> > > > Alternatively, we could just as well do this directly in apibuild.py, > but this requires version information in, say, apiversion.py which I > could generate using the enriched libvirt-api.xml. What we should do is this - Take the bit of hvsupport.pl which extracts the version data for each API and make it generate a libvirt-api-versions.xml file - Make hvsupport.pl read data from that XML file when generating the HTML - Make apibuild.py read data from that XML file when generating the API XML files, and include this version data into the libvirt-api.xml files Daniel -- |: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :| |: http://libvirt.org -o- http://virt-manager.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: http://entangle-photo.org -o- http://live.gnome.org/gtk-vnc :| -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list