[libvirt] [PATCH] Fix several formatting mistakes in doc
--- docs/formatdomain.html.in | 2 +- docs/hooks.html.in | 6 +++--- src/libvirt.c | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 8b50814..438cbf0 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -353,7 +353,7 @@ <dd> The optional <code>vcpupin</code> element specifies which of host physical CPUS the domain VCPU will be pinned to. If this is ommited, each VCPU pinned to all the physical CPUS by default. It contains two - required attributes, the attribute <code>vcpu</vcpu> specifies vcpu id, + required attributes, the attribute <code>vcpu</code> specifies vcpu id, and the attribute <code>cpuset</code> is same as attribute <code>cpuset</code> of element <code>vcpu</code>. NB, Only qemu driver supports</dd> <dt><code>shares</code></dt> diff --git a/docs/hooks.html.in b/docs/hooks.html.in index eec7a6a..890359e 100644 --- a/docs/hooks.html.in +++ b/docs/hooks.html.in @@ -105,16 +105,16 @@ is not started. The first location, <span class="since">since 0.9.0</span>, is before libvirt performs any resource labeling, and the hook can allocate resources not managed by - libvirt such as DRBD or missing bridges. This is called as:</br> + libvirt such as DRBD or missing bridges. This is called as:<br/> <pre>/etc/libvirt/hooks/qemu guest_name prepare begin -</pre> The second location, available <span class="since">Since 0.8.0</span>, occurs after libvirt has finished labeling - all resources, but has not yet started the guest, called as:</br> + all resources, but has not yet started the guest, called as:<br/> <pre>/etc/libvirt/hooks/qemu guest_name start begin -</pre></li> <li>When a QEMU guest is stopped, the qemu hook script is called in two locations, to match the startup. First, <span class="since">since 0.8.0</span>, the hook is - called before libvirt restores any labels:</br> + called before libvirt restores any labels:<br/> <pre>/etc/libvirt/hooks/qemu guest_name stopped end -</pre> Then, after libvirt has released all resources, the hook is called again, <span class="since">since 0.9.0</span>, to allow diff --git a/src/libvirt.c b/src/libvirt.c index 9bdb4c8..8be18d4 100644 --- a/src/libvirt.c +++ b/src/libvirt.c @@ -2852,7 +2852,7 @@ error: } /* - * virDomainSetMemoryFlags + * virDomainSetMemoryFlags: * @domain: a domain object or NULL * @memory: the memory size in kilobytes * @flags: an OR'ed set of virDomainMemoryModFlags -- 1.7.4
On Thu, Mar 31, 2011 at 01:14:03PM +0200, Michal Privoznik wrote:
--- docs/formatdomain.html.in | 2 +- docs/hooks.html.in | 6 +++--- src/libvirt.c | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 8b50814..438cbf0 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -353,7 +353,7 @@ <dd> The optional <code>vcpupin</code> element specifies which of host physical CPUS the domain VCPU will be pinned to. If this is ommited, each VCPU pinned to all the physical CPUS by default. It contains two - required attributes, the attribute <code>vcpu</vcpu> specifies vcpu id, + required attributes, the attribute <code>vcpu</code> specifies vcpu id, and the attribute <code>cpuset</code> is same as attribute <code>cpuset</code> of element <code>vcpu</code>. NB, Only qemu driver supports</dd> <dt><code>shares</code></dt> diff --git a/docs/hooks.html.in b/docs/hooks.html.in index eec7a6a..890359e 100644 --- a/docs/hooks.html.in +++ b/docs/hooks.html.in @@ -105,16 +105,16 @@ is not started. The first location, <span class="since">since 0.9.0</span>, is before libvirt performs any resource labeling, and the hook can allocate resources not managed by - libvirt such as DRBD or missing bridges. This is called as:</br> + libvirt such as DRBD or missing bridges. This is called as:<br/> <pre>/etc/libvirt/hooks/qemu guest_name prepare begin -</pre> The second location, available <span class="since">Since 0.8.0</span>, occurs after libvirt has finished labeling - all resources, but has not yet started the guest, called as:</br> + all resources, but has not yet started the guest, called as:<br/> <pre>/etc/libvirt/hooks/qemu guest_name start begin -</pre></li> <li>When a QEMU guest is stopped, the qemu hook script is called in two locations, to match the startup. First, <span class="since">since 0.8.0</span>, the hook is - called before libvirt restores any labels:</br> + called before libvirt restores any labels:<br/> <pre>/etc/libvirt/hooks/qemu guest_name stopped end -</pre> Then, after libvirt has released all resources, the hook is called again, <span class="since">since 0.9.0</span>, to allow
This exposes several problems in the docs/Makefile.am - make clean doesn't work in a VPATH build because for some reason the HTML is generated in the $srcdir and so 'rm -f *.html' misses the files - We run xmllint, but failures in xmllint validation are not causing a build failure If both of these are fixed, then the automated build would detect this in the future.
diff --git a/src/libvirt.c b/src/libvirt.c index 9bdb4c8..8be18d4 100644 --- a/src/libvirt.c +++ b/src/libvirt.c @@ -2852,7 +2852,7 @@ error: }
/* - * virDomainSetMemoryFlags + * virDomainSetMemoryFlags: * @domain: a domain object or NULL * @memory: the memory size in kilobytes * @flags: an OR'ed set of virDomainMemoryModFlags -- 1.7.4
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
ACK 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 :|
On 03/31/2011 07:58 AM, Daniel P. Berrange wrote:
<li>When a QEMU guest is stopped, the qemu hook script is called in two locations, to match the startup. First, <span class="since">since 0.8.0</span>, the hook is - called before libvirt restores any labels:</br> + called before libvirt restores any labels:<br/>
Oh my, showing off all my recent typos. Sorry!
<pre>/etc/libvirt/hooks/qemu guest_name stopped end -</pre> Then, after libvirt has released all resources, the hook is called again, <span class="since">since 0.9.0</span>, to allow
This exposes several problems in the docs/Makefile.am
- make clean doesn't work in a VPATH build because for some reason the HTML is generated in the $srcdir
Intentional - docs are machine independent and therefore may be distributed, and by distributing them, others don't have to have the tools to rebuild them. Distributed files should generally be built in srcdir
and so 'rm -f *.html' misses the files
So that's the real bug - the clean hook needs to be prefixed with $(srcdir).
- We run xmllint, but failures in xmllint validation are not causing a build failure
Yeah, I've complained about that before, but haven't done anything about it yet. I guess I know what I'll be doing today as followups to this :) -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On 03/31/2011 08:13 AM, Eric Blake wrote:
This exposes several problems in the docs/Makefile.am
- make clean doesn't work in a VPATH build because for some reason the HTML is generated in the $srcdir
Intentional - docs are machine independent and therefore may be distributed, and by distributing them, others don't have to have the tools to rebuild them. Distributed files should generally be built in srcdir
and so 'rm -f *.html' misses the files
So that's the real bug - the clean hook needs to be prefixed with $(srcdir).
Actually, 'make clean' must _not_ remove generated files. Otherwise, there's no point in shipping them pre-generated - the first 'make clean' would nuke them and the user without the tools to regenerate them would be stuck. Rather, 'make maintainer-clean' should be taught how to remove them, since the maintainer is expected to have the necessary extra prerequisite tools. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On 03/31/2011 07:58 AM, Daniel P. Berrange wrote:
- We run xmllint, but failures in xmllint validation are not causing a build failure
We already have code in place to call 'exit 1' on xmllint failure (but not in all places). However, in my testing, it was xsltproc that is not throwing an error: $ /usr/bin/xsltproc --stringparam pagename $name --nonet --html ../docs/site.xsl formatdomain.html.in > formatdomain.html.tmp formatdomain.html.in:356: HTML parser error : Unexpected end tag : vcpu required attributes, the attribute <code>vcpu</vcpu> specifies vcpu id, ^ $ echo $? 0 That looks like a bug in xsltproc (here from Fedora libxslt-1.1.26-3.fc14.x86_64), since the man page states that $? should be 6 when there is an error in the document. I can work around it by sniffing for non-empty stderr; that will look yucky in the makefile, but is probably worth doing. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On Thu, Mar 31, 2011 at 11:15:34AM -0600, Eric Blake wrote:
On 03/31/2011 07:58 AM, Daniel P. Berrange wrote:
- We run xmllint, but failures in xmllint validation are not causing a build failure
We already have code in place to call 'exit 1' on xmllint failure (but not in all places). However, in my testing, it was xsltproc that is not throwing an error:
$ /usr/bin/xsltproc --stringparam pagename $name --nonet --html ../docs/site.xsl formatdomain.html.in > formatdomain.html.tmp formatdomain.html.in:356: HTML parser error : Unexpected end tag : vcpu required attributes, the attribute <code>vcpu</vcpu> specifies vcpu id, ^ $ echo $? 0
That looks like a bug in xsltproc (here from Fedora libxslt-1.1.26-3.fc14.x86_64), since the man page states that $? should be 6 when there is an error in the document.
I can work around it by sniffing for non-empty stderr; that will look yucky in the makefile, but is probably worth doing.
Hmm, so we've actually got two things to validate - Welformed XML - HTML schema compliance The current xmllint run is doing the latter. We should also run xmllint before xsltproc, so we can validate wellformedness of the input HTML files. Thus avoiding reliance of xsltproc exit status 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 :|
On 03/31/2011 11:18 AM, Daniel P. Berrange wrote:
That looks like a bug in xsltproc (here from Fedora libxslt-1.1.26-3.fc14.x86_64), since the man page states that $? should be 6 when there is an error in the document.
I can work around it by sniffing for non-empty stderr; that will look yucky in the makefile, but is probably worth doing.
Hmm, so we've actually got two things to validate
- Welformed XML - HTML schema compliance
The current xmllint run is doing the latter. We should also run xmllint before xsltproc, so we can validate wellformedness of the input HTML files. Thus avoiding reliance of xsltproc exit status
Do you have a sample command line for how to make xmllint check that the html.in file is well-formed XML? I just tried: $ SGML_CATALOG_FILES='/etc/xml/catalog' /usr/bin/xmllint --catalogs --nonet --format --valid formatcaps.html.in >/dev/null formatcaps.html.in:1: validity error : Validation failed: no DTD found ! <html> ^ but that's obviously not right (it works on the post-processed generated html document, but that's why we're generating the document, to add in the rest of the boilerplate to the xml shell that makes it valid html). -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
This fixes more cases of xmllint not detecting errors. HOWEVER - xsltproc mistakenly exits with $? of 0 even when encountering problems. It's probably better to run a separate xmllint before xsltproc to ensure the input file is well-formed xml (not just that the output file was well-formed html), but I'm not sure how to do that. We could also get away with checking if xsltproc stderr is empty. * docs/Makefile.am (maintainer-clean-local): Remove generated docs in VPATH build. (html/index.html): Exit on formatting problems. (rebuild): Run full doc build on request. --- Since we already gate the conditions on whether the tools exist, we should not ever fail, so we don't want the - prefix. One of the two xmllint invocations forced 'exit 1' on validation failure; make the other do likewise. 'make -C docs rebuild' can help check for errors. docs/Makefile.am | 19 +++++++++++-------- 1 files changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index db4bc59..8ea9eb8 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -147,21 +147,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 - -@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 - -@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) -@echo Rebuilding devhelp files - -@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 +184,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
On Thu, Mar 31, 2011 at 01:23:01PM -0600, Eric Blake wrote:
On 03/31/2011 11:18 AM, Daniel P. Berrange wrote:
That looks like a bug in xsltproc (here from Fedora libxslt-1.1.26-3.fc14.x86_64), since the man page states that $? should be 6 when there is an error in the document.
I can work around it by sniffing for non-empty stderr; that will look yucky in the makefile, but is probably worth doing.
Hmm, so we've actually got two things to validate
- Welformed XML - HTML schema compliance
The current xmllint run is doing the latter. We should also run xmllint before xsltproc, so we can validate wellformedness of the input HTML files. Thus avoiding reliance of xsltproc exit status
Do you have a sample command line for how to make xmllint check that the html.in file is well-formed XML? I just tried:
$ SGML_CATALOG_FILES='/etc/xml/catalog' /usr/bin/xmllint --catalogs --nonet --format --valid formatcaps.html.in >/dev/null formatcaps.html.in:1: validity error : Validation failed: no DTD found ! <html> ^
just drop --valid from the command line, xmllint usually doesn't check validity. But IMHO it's simpler to just drop the --html flag from xsltproc as suggestedon previous mail
but that's obviously not right (it works on the post-processed generated html document, but that's why we're generating the document, to add in the rest of the boilerplate to the xml shell that makes it valid html).
Yup the input should just be expected to be well-formed not valid, Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
On 03/31/2011 07:27 PM, Daniel Veillard wrote:
$ SGML_CATALOG_FILES='/etc/xml/catalog' /usr/bin/xmllint --catalogs --nonet --format --valid formatcaps.html.in >/dev/null formatcaps.html.in:1: validity error : Validation failed: no DTD found ! <html> ^
just drop --valid from the command line, xmllint usually doesn't check validity. But IMHO it's simpler to just drop the --html flag from xsltproc as suggestedon previous mail
Almost, it definitely caught some more bugs. But it's not perfect; now I'm getting: Generating csharp.html.tmp csharp.html.in:21: parser error : Entity 'nbsp' not defined <p> </p> ^ ... csharp.html.in:125: parser error : Entity 'iacute' not defined based upon the previous work of Jaromír Červenka. ^ when make tries: name=`echo csharp.html.tmp | sed -e 's/.tmp//'`; \ /usr/bin/xsltproc --stringparam pagename $name --nonet \ ../docs/site.xsl csharp.html.in > csharp.html.tmp How do I make xsltproc recognize html entities without using --html? -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On Fri, Apr 01, 2011 at 12:04:04PM -0600, Eric Blake wrote:
On 03/31/2011 07:27 PM, Daniel Veillard wrote:
$ SGML_CATALOG_FILES='/etc/xml/catalog' /usr/bin/xmllint --catalogs --nonet --format --valid formatcaps.html.in >/dev/null formatcaps.html.in:1: validity error : Validation failed: no DTD found ! <html> ^
just drop --valid from the command line, xmllint usually doesn't check validity. But IMHO it's simpler to just drop the --html flag from xsltproc as suggestedon previous mail
Almost, it definitely caught some more bugs. But it's not perfect; now I'm getting:
Generating csharp.html.tmp csharp.html.in:21: parser error : Entity 'nbsp' not defined <p> </p> ^ ... csharp.html.in:125: parser error : Entity 'iacute' not defined based upon the previous work of Jaromír Červenka. ^
Ah, that normal, it's an error but not a fatal error, the nbsp entity is available from the DTD but since we didn't asked for validation libxml2 didn't try to fetch it. Note it's an error, not a fatal error, i.e. processing continues, as the prser can't guess if the entity was in the (not loaded) DTD or not. You can add the --loaddtd to xmllint command line to ask it to load the DTd while just checking the well-formedness of the document
when make tries:
name=`echo csharp.html.tmp | sed -e 's/.tmp//'`; \ /usr/bin/xsltproc --stringparam pagename $name --nonet \ ../docs/site.xsl csharp.html.in > csharp.html.tmp
How do I make xsltproc recognize html entities without using --html?
xsltproc will load the DTD, so there should be no problem there. Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
On 03/31/2011 11:15 AM, Eric Blake wrote:
We already have code in place to call 'exit 1' on xmllint failure (but not in all places). However, in my testing, it was xsltproc that is not throwing an error:
$ /usr/bin/xsltproc --stringparam pagename $name --nonet --html ../docs/site.xsl formatdomain.html.in > formatdomain.html.tmp formatdomain.html.in:356: HTML parser error : Unexpected end tag : vcpu required attributes, the attribute <code>vcpu</vcpu> specifies vcpu id, ^ $ echo $? 0
That looks like a bug in xsltproc (here from Fedora libxslt-1.1.26-3.fc14.x86_64), since the man page states that $? should be 6 when there is an error in the document.
Now tracked as https://bugzilla.redhat.com/show_bug.cgi?id=692671 -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On Thu, Mar 31, 2011 at 11:15:34AM -0600, Eric Blake wrote:
On 03/31/2011 07:58 AM, Daniel P. Berrange wrote:
- We run xmllint, but failures in xmllint validation are not causing a build failure
We already have code in place to call 'exit 1' on xmllint failure (but not in all places). However, in my testing, it was xsltproc that is not throwing an error:
$ /usr/bin/xsltproc --stringparam pagename $name --nonet --html ../docs/site.xsl formatdomain.html.in > formatdomain.html.tmp formatdomain.html.in:356: HTML parser error : Unexpected end tag : vcpu required attributes, the attribute <code>vcpu</vcpu> specifies vcpu id, ^ $ echo $? 0
it's because we are using --html, instructing libxml2 underneath to use teh HTML parser to load the .html.in . And the HTML parser is just reporting errors, not failing on them (as 99% of the HTML around is just buggy).
That looks like a bug in xsltproc (here from Fedora libxslt-1.1.26-3.fc14.x86_64), since the man page states that $? should be 6 when there is an error in the document.
Well except for HTML input, remove the --html and see, maybe we could do that in the Makefile and insist on the .html.in being well formed in the first place.
I can work around it by sniffing for non-empty stderr; that will look yucky in the makefile, but is probably worth doing.
Doesn't sound that great honnestly, try dropping --html instead and see how it goes Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
On Fri, Apr 01, 2011 at 09:25:45AM +0800, Daniel Veillard wrote:
On Thu, Mar 31, 2011 at 11:15:34AM -0600, Eric Blake wrote:
On 03/31/2011 07:58 AM, Daniel P. Berrange wrote:
- We run xmllint, but failures in xmllint validation are not causing a build failure
We already have code in place to call 'exit 1' on xmllint failure (but not in all places). However, in my testing, it was xsltproc that is not throwing an error:
$ /usr/bin/xsltproc --stringparam pagename $name --nonet --html ../docs/site.xsl formatdomain.html.in > formatdomain.html.tmp formatdomain.html.in:356: HTML parser error : Unexpected end tag : vcpu required attributes, the attribute <code>vcpu</vcpu> specifies vcpu id, ^ $ echo $? 0
it's because we are using --html, instructing libxml2 underneath to use teh HTML parser to load the .html.in . And the HTML parser is just reporting errors, not failing on them (as 99% of the HTML around is just buggy).
That looks like a bug in xsltproc (here from Fedora libxslt-1.1.26-3.fc14.x86_64), since the man page states that $? should be 6 when there is an error in the document.
Well except for HTML input, remove the --html and see, maybe we could do that in the Makefile and insist on the .html.in being well formed in the first place.
I can work around it by sniffing for non-empty stderr; that will look yucky in the makefile, but is probably worth doing.
Doesn't sound that great honnestly, try dropping --html instead and see how it goes
Yes, that sounds reasonable. Our site.xsl file is already setup to output XHTML, so we should treat our input as wellformed XHTML too, rather than loose HTML. 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 :|
participants (4)
-
Daniel P. Berrange -
Daniel Veillard -
Eric Blake -
Michal Privoznik