8:58 a.m.
While checking API docs after recent migration to gitlab-pages I've
noticed that the footer is not properly rendered.
A deeper dig showed that the issue is that empty <div> elements, while
formatted by the XML output version of XSLT conversion is turned into
the non-pair empty variant. This contradicts the HTML standard which we
declare to use for our pages and thus is mis-parsed into dom, where
every empty div is treated as a start of a div, thus nesting everything.
This series fixes the above and also many other errors pointed out by
the HTML validator at:
https://validator.w3.org/
Compare:
https://libvirt.org/html/libvirt-libvirt-domain.html
vs
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/6288946946/artifacts/website/h...
and the validation:
https://validator.w3.org/nu/?doc=https%3A%2F%2Flibvirt.org%2Fhtml%2Flibvi...
vs
https://validator.w3.org/nu/?doc=https%3A%2F%2Fpipo.sk.gitlab.io%2F-%2Fli...
Also non-API pages validation:
https://validator.w3.org/nu/?doc=https%3A%2F%2Flibvirt.org%2Fdocs.html
vs
https://validator.w3.org/nu/?doc=https%3A%2F%2Fpipo.sk.gitlab.io%2F-%2Fli...
Peter Krempa (9):
docs: site: Don't generate '<?xml' header for HTML documents
docs: page: Add 'lang="en"' for all HTML output documents
docs: page: Fix declaration of main javascript source
docs: index: Fix import of blog planet javascript
docs: newapi: Don't generate empty <div> in template for ACL
permissions
docs: newapi: Avoid empty <div>s when there is no description
docs: newapi: Avoid table where every row has an cell with 'colspan'
docs: newapi: Properly skip ACL entries if empty
docs: newapi: Fix generation of type definition tables
docs/index.rst | 2 +-
docs/newapi.xsl | 158 ++++++++++++++++++++++++++----------------------
docs/page.xsl | 7 ++-
docs/site.xsl | 5 +-
4 files changed, 93 insertions(+), 79 deletions(-)
--
2.43.0
8:58 a.m.
New subject: [PATCH 1/9] docs: site: Don't generate '<?xml' header for HTML documents
Skip the XML header as it's invalid with <!DOCTYPE HTML> both for the
RST-generated pages and for the API docs generated from the API XML.
Additionally remove the spurious xsl:output directive from newapi.xsl
which is ignored and thus misleading.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/newapi.xsl | 7 +++----
docs/site.xsl | 5 +----
2 files changed, 4 insertions(+), 8 deletions(-)
diff --git a/docs/newapi.xsl b/docs/newapi.xsl
index d6f8d88170..38cefb2ca8 100644
--- a/docs/newapi.xsl
+++ b/docs/newapi.xsl
@@ -17,8 +17,6 @@
<!-- Import the main part of the site stylesheets -->
<xsl:import href="page.xsl"/>
- <xsl:output method="xml" encoding="UTF-8"
indent="yes"/>
-
<!-- Build keys for all symbols -->
<xsl:key name="symbols" match="/api/symbols/*"
use="@name"/>
@@ -811,8 +809,9 @@
<xsl:document
href="{concat($htmldir, '/libvirt-', @name, '.html')}"
method="xml"
- indent="yes"
- encoding="UTF-8">
+ omit-xml-declaration="yes"
+ encoding="UTF-8"
+ indent="yes">
<xsl:apply-templates select="exsl:node-set($subpage)"
mode="page">
<xsl:with-param name="timestamp"
select="$timestamp"/>
<xsl:with-param name="link_href_base"
select="$href_base"/>
diff --git a/docs/site.xsl b/docs/site.xsl
index c0b56be72f..5a5fea2350 100644
--- a/docs/site.xsl
+++ b/docs/site.xsl
@@ -22,10 +22,7 @@
<xsl:apply-templates
select="exsl:node-set($inchtml)/html:html/html:body/*"
mode="content"/>
</xsl:template>
- <xsl:output
- method="xml"
- encoding="UTF-8"
- indent="yes"/>
+ <xsl:output method="xml" omit-xml-declaration="yes"
encoding="UTF-8" indent="yes"/>
<xsl:template match="/">
<xsl:apply-templates select="." mode="page">
--
2.43.0
8:58 a.m.
New subject: [PATCH 2/9] docs: page: Add 'lang="en"' for all HTML output documents
Per the w3 HTML validator the 'lang' attribute is suggested.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/page.xsl | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/page.xsl b/docs/page.xsl
index a51587db6c..7dcbc2d7a4 100644
--- a/docs/page.xsl
+++ b/docs/page.xsl
@@ -21,7 +21,7 @@
<xsl:param name="asset_href_base"/>
<xsl:text disable-output-escaping="yes"><!DOCTYPE
html>
</xsl:text>
- <html data-sourcedoc="{$pagesrc}">
+ <html lang="en" data-sourcedoc="{$pagesrc}">
<xsl:comment>
This file is autogenerated from <xsl:value-of
select="$pagesrc"/>
Do not edit this file. Changes will be lost.
--
2.43.0
8:58 a.m.
New subject: [PATCH 3/9] docs: page: Fix declaration of main javascript source
Per the w3 html validator a HTML/XML comment is not allowed inside the
<script> tag, use a space instead as it must be a pair tag.
Additionally drop the 'type' attribute as it's not needed (validator
warns about it).
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/page.xsl | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/docs/page.xsl b/docs/page.xsl
index 7dcbc2d7a4..71c7cfba9d 100644
--- a/docs/page.xsl
+++ b/docs/page.xsl
@@ -44,8 +44,9 @@
<meta name="go-import"
content="{/html:html/html:head/html:meta[@name='go-import']/@content}"/>
</xsl:if>
- <script type="text/javascript"
src="{$asset_href_base}js/main.js">
- <xsl:comment>// forces non-empty element</xsl:comment>
+ <!-- force non-empty script tag -->
+ <script src="{$asset_href_base}js/main.js">
+ <xsl:text> </xsl:text>
</script>
</head>
<body onload="pageload()">
--
2.43.0
8:58 a.m.
New subject: [PATCH 4/9] docs: index: Fix import of blog planet javascript
Similarly to previous commit drop the 'type' attribute which is frowned
upon by the HTML standard.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/index.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/index.rst b/docs/index.rst
index 79afae65da..6b2f2386ee 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -65,7 +65,7 @@ Blog Planet
.. raw:: html
- <script type="text/javascript"
src="js/virt-tools-blog-planet.js">
+ <script src="js/virt-tools-blog-planet.js">
</script>
<div id="planet"> </div>
--
2.43.0
8:58 a.m.
New subject: [PATCH 5/9] docs: newapi: Don't generate empty <div> in template for ACL permissions
If an API has no ACLs an empty <div class='acl'/> would be generated
which is mis-interpreted by browsers when creating DOM to nest any
subsequent elements under it.
Don't generate the ACL section div unless it will be filled.
Best viewed with 'git show -w'
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/newapi.xsl | 60 +++++++++++++++++++++++++------------------------
1 file changed, 31 insertions(+), 29 deletions(-)
diff --git a/docs/newapi.xsl b/docs/newapi.xsl
index 38cefb2ca8..b60680ae97 100644
--- a/docs/newapi.xsl
+++ b/docs/newapi.xsl
@@ -26,30 +26,34 @@
<xsl:template name="aclinfo">
<xsl:param name="acl"/>
- <xsl:if test="count($acl/check) > 0">
- <h5>Access control parameter checks</h5>
- <table>
- <thead>
- <tr>
- <th>Object</th>
- <th>Permission</th>
- <th>Condition</th>
- </tr>
- </thead>
- <xsl:apply-templates select="$acl/check" mode="acl"/>
- </table>
- </xsl:if>
- <xsl:if test="count($acl/filter) > 0">
- <h5>Access control return value filters</h5>
- <table>
- <thead>
- <tr>
- <th>Object</th>
- <th>Permission</th>
- </tr>
- </thead>
- <xsl:apply-templates select="$acl/filter" mode="acl"/>
- </table>
+ <xsl:if test="count($acl/check) > 0 or count($acl/filter) >
0">
+ <div class="acl">
+ <xsl:if test="count($acl/check) > 0">
+ <h5>Access control parameter checks</h5>
+ <table>
+ <thead>
+ <tr>
+ <th>Object</th>
+ <th>Permission</th>
+ <th>Condition</th>
+ </tr>
+ </thead>
+ <xsl:apply-templates select="$acl/check"
mode="acl"/>
+ </table>
+ </xsl:if>
+ <xsl:if test="count($acl/filter) > 0">
+ <h5>Access control return value filters</h5>
+ <table>
+ <thead>
+ <tr>
+ <th>Object</th>
+ <th>Permission</th>
+ </tr>
+ </thead>
+ <xsl:apply-templates select="$acl/filter"
mode="acl"/>
+ </table>
+ </xsl:if>
+ </div>
</xsl:if>
</xsl:template>
@@ -702,11 +706,9 @@
</xsl:if>
</dl>
</xsl:if>
- <div class="acl">
- <xsl:call-template name="aclinfo">
- <xsl:with-param name="acl" select="acls"/>
- </xsl:call-template>
- </div>
+ <xsl:call-template name="aclinfo">
+ <xsl:with-param name="acl" select="acls"/>
+ </xsl:call-template>
</xsl:template>
<xsl:template match="exports" mode="toc">
--
2.43.0
8:58 a.m.
New subject: [PATCH 6/9] docs: newapi: Avoid empty <div>s when there is no description
The various objects we generate API for may have empty description in
which case an empty div would be generated when processing the API
description. As we're using XML output mode the generator would shorten
such divs to the non-pair empty element version, which doesn't work well
with HTML5 parsers requiring a pair tag for <div>
Avoid empty description <div> elements altogether by skipping it if the
description is empty.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/newapi.xsl | 40 +++++++++++++++++++++++++---------------
1 file changed, 25 insertions(+), 15 deletions(-)
diff --git a/docs/newapi.xsl b/docs/newapi.xsl
index b60680ae97..539e0a4175 100644
--- a/docs/newapi.xsl
+++ b/docs/newapi.xsl
@@ -222,6 +222,19 @@
</xsl:if>
</xsl:template>
+ <xsl:template name="formattextdiv">
+ <xsl:param name="text"/>
+ <xsl:param name="divclass"/>
+
+ <xsl:if test="$text">
+ <div class="{$divclass}">
+ <xsl:call-template name="formattext">
+ <xsl:with-param name="text" select="$text"/>
+ </xsl:call-template>
+ </div>
+ </xsl:if>
+ </xsl:template>
+
<xsl:template match="macro" mode="toc">
<span class="directive">#define</span><xsl:text>
</xsl:text>
<a href="#{@name}"><xsl:value-of
select="@name"/></a>
@@ -287,11 +300,10 @@
<xsl:template match="typedef[@type = 'enum']">
<xsl:variable name="name" select="string(@name)"/>
<h3><a id="{$name}"><code><xsl:value-of
select="$name"/></code></a></h3>
- <div class="description">
- <xsl:call-template name="formattext">
+ <xsl:call-template name="formattextdiv">
<xsl:with-param name="text" select="info"/>
+ <xsl:with-param name="divclass">description</xsl:with-param>
</xsl:call-template>
- </div>
<div class="api">
<pre>
<span class="keyword">enum</span><xsl:text>
</xsl:text>
@@ -343,11 +355,10 @@
<xsl:text>;</xsl:text>
</pre>
</div>
- <div class="description">
- <xsl:call-template name="formattext">
+ <xsl:call-template name="formattextdiv">
<xsl:with-param name="text" select="info"/>
+ <xsl:with-param name="divclass">description</xsl:with-param>
</xsl:call-template>
- </div>
</xsl:template>
<xsl:template match="struct" mode="toc">
@@ -452,11 +463,11 @@
<xsl:variable name="name" select="string(@name)"/>
<h3><a id="{$name}"><code><xsl:value-of
select="$name"/></code></a></h3>
<pre class="api"><span
class="directive">#define</span><xsl:text>
</xsl:text><xsl:value-of select="$name"/></pre>
- <div class="description">
- <xsl:call-template name="formattext">
+ <xsl:call-template name="formattextdiv">
<xsl:with-param name="text" select="info"/>
+ <xsl:with-param name="divclass">description</xsl:with-param>
</xsl:call-template>
- </div><xsl:text>
+ <xsl:text>
</xsl:text>
</xsl:template>
@@ -604,11 +615,10 @@
<xsl:text>)
</xsl:text>
</pre>
- <div class="description">
- <xsl:call-template name="formattext">
+ <xsl:call-template name="formattextdiv">
<xsl:with-param name="text" select="info"/>
+ <xsl:with-param name="divclass">description</xsl:with-param>
</xsl:call-template>
- </div>
<xsl:if test="arg | return">
<dl class="variablelist">
<xsl:for-each select="arg">
@@ -680,11 +690,11 @@
</xsl:for-each>
<xsl:text>)</xsl:text>
</pre>
- <div class="description">
- <xsl:call-template name="formattext">
+ <xsl:call-template name="formattextdiv">
<xsl:with-param name="text" select="info"/>
+ <xsl:with-param name="divclass">description</xsl:with-param>
</xsl:call-template>
- </div><xsl:text>
+ <xsl:text>
</xsl:text>
<xsl:if test="arg | return/@info">
<dl class="variablelist">
--
2.43.0
8:58 a.m.
New subject: [PATCH 7/9] docs: newapi: Avoid table where every row has an cell with 'colspan'
The HTML standard requires that a table column must include at least one
row which defines it exclusively, thus having a table where all rows
unite it via 'colspan' is illegal.
Modify the enum value generator to always output the description field
even when it's empty rather than uniting it, as in case when each value
doesn't have a description the generated document would violate the
standard.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/newapi.xsl | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/newapi.xsl b/docs/newapi.xsl
index 539e0a4175..36bb41c877 100644
--- a/docs/newapi.xsl
+++ b/docs/newapi.xsl
@@ -317,9 +317,9 @@
<tr>
<td><a id="{@name}"><xsl:value-of
select="@name"/></a></td>
<td><xsl:text> = </xsl:text></td>
+ <td class="enumvalue"><xsl:call-template
name="enumvalue"/></td>
<xsl:choose>
<xsl:when test="@info != ''">
- <td class="enumvalue"><xsl:call-template
name="enumvalue"/></td>
<td>
<div class="comment">
<xsl:call-template name="dumptext">
@@ -329,7 +329,7 @@
</td>
</xsl:when>
<xsl:otherwise>
- <td colspan="2"
class="enumvalue"><xsl:call-template
name="enumvalue"/></td>
+ <td><xsl:comment> </xsl:comment></td>
</xsl:otherwise>
</xsl:choose>
</tr>
--
2.43.0
8:58 a.m.
New subject: [PATCH 8/9] docs: newapi: Properly skip ACL entries if empty
The source document can contain an empty '@flags' attribute which passes
the test but generates an empty element. Check that flags is non-empty
to trigger the fallback.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/newapi.xsl | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/newapi.xsl b/docs/newapi.xsl
index 36bb41c877..51f159a2f8 100644
--- a/docs/newapi.xsl
+++ b/docs/newapi.xsl
@@ -62,7 +62,7 @@
<td><a href="../acl.html#object_{@object}"><xsl:value-of
select="@object"/></a></td>
<td><a
href="../acl.html#perm_{@object}_{@perm}"><xsl:value-of
select="@perm"/></a></td>
<xsl:choose>
- <xsl:when test="@flags">
+ <xsl:when test="@flags != ''">
<td><xsl:value-of select="@flags"/></td>
</xsl:when>
<xsl:otherwise>
--
2.43.0
8:58 a.m.
New subject: [PATCH 9/9] docs: newapi: Fix generation of type definition tables
Ensure that all rows have 3 columns and avoid generation of emtpy
elements which would be turned by the XML formatter into non-pair td/tr
tags which don't work properly with HTML5 parsers.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/newapi.xsl | 45 +++++++++++++++++++++++++--------------------
1 file changed, 25 insertions(+), 20 deletions(-)
diff --git a/docs/newapi.xsl b/docs/newapi.xsl
index 51f159a2f8..aff4cf0d4e 100644
--- a/docs/newapi.xsl
+++ b/docs/newapi.xsl
@@ -384,7 +384,7 @@
<xsl:for-each select="field">
<xsl:choose>
<xsl:when test='@type = "union"'>
- <tr><td><span
class="keyword">union</span> {</td></tr>
+ <tr><td colspan="3"><span
class="keyword">union</span> {</td></tr>
<tr>
<td><table>
<xsl:for-each select="union/field">
@@ -397,31 +397,35 @@
</span>
</td>
<td><xsl:value-of
select="@name"/></td>
- <xsl:if test="@info != ''">
- <td>
+ <td>
+ <xsl:if test="@info != ''">
<div class="comment">
<xsl:call-template name="dumptext">
<xsl:with-param name="text"
select="@info"/>
</xsl:call-template>
</div>
- </td>
- </xsl:if>
+ </xsl:if>
+ <xsl:comment> </xsl:comment>
+ </td>
</tr>
</xsl:for-each>
</table></td>
- <td></td></tr>
- <tr><td>}</td>
- <td><xsl:value-of select="@name"/></td>
- <xsl:if test="@info != ''">
+ <td colspan="2"><xsl:comment>
</xsl:comment></td>
+ </tr>
+ <tr>
+ <td>}</td>
+ <td><xsl:value-of select="@name"/></td>
<td>
- <div class="comment">
- <xsl:call-template name="dumptext">
- <xsl:with-param name="text"
select="@info"/>
- </xsl:call-template>
- </div>
+ <xsl:if test="@info != ''">
+ <div class="comment">
+ <xsl:call-template name="dumptext">
+ <xsl:with-param name="text"
select="@info"/>
+ </xsl:call-template>
+ </div>
+ </xsl:if>
+ <xsl:comment> </xsl:comment>
</td>
- </xsl:if>
- <td></td></tr>
+ </tr>
</xsl:when>
<xsl:otherwise>
<tr>
@@ -433,15 +437,16 @@
</span>
</td>
<td><xsl:value-of select="@name"/></td>
- <xsl:if test="@info != ''">
- <td>
+ <td>
+ <xsl:if test="@info != ''">
<div class="comment">
<xsl:call-template name="dumptext">
<xsl:with-param name="text"
select="@info"/>
</xsl:call-template>
</div>
- </td>
- </xsl:if>
+ </xsl:if>
+ <xsl:comment> </xsl:comment>
+ </td>
</tr>
</xsl:otherwise>
</xsl:choose>
--
2.43.0
2:31 a.m.
On Thu, Feb 29, 2024 at 03:58:14PM +0100, Peter Krempa wrote:
While checking API docs after recent migration to gitlab-pages
I've
noticed that the footer is not properly rendered.
A deeper dig showed that the issue is that empty <div> elements, while
formatted by the XML output version of XSLT conversion is turned into
the non-pair empty variant. This contradicts the HTML standard which we
declare to use for our pages and thus is mis-parsed into dom, where
every empty div is treated as a start of a div, thus nesting everything.
This series fixes the above and also many other errors pointed out by
the HTML validator at:
https://validator.w3.org/
Compare:
https://libvirt.org/html/libvirt-libvirt-domain.html
vs
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/6288946946/artifacts/website/h...
and the validation:
https://validator.w3.org/nu/?doc=https%3A%2F%2Flibvirt.org%2Fhtml%2Flibvi...
vs
https://validator.w3.org/nu/?doc=https%3A%2F%2Fpipo.sk.gitlab.io%2F-%2Fli...
Also non-API pages validation:
https://validator.w3.org/nu/?doc=https%3A%2F%2Flibvirt.org%2Fdocs.html
vs
https://validator.w3.org/nu/?doc=https%3A%2F%2Fpipo.sk.gitlab.io%2F-%2Fli...
Peter Krempa (9):
docs: site: Don't generate '<?xml' header for HTML documents
docs: page: Add 'lang="en"' for all HTML output documents
docs: page: Fix declaration of main javascript source
docs: index: Fix import of blog planet javascript
docs: newapi: Don't generate empty <div> in template for ACL
permissions
docs: newapi: Avoid empty <div>s when there is no description
docs: newapi: Avoid table where every row has an cell with 'colspan'
docs: newapi: Properly skip ACL entries if empty
docs: newapi: Fix generation of type definition tables
docs/index.rst | 2 +-
docs/newapi.xsl | 158 ++++++++++++++++++++++++++----------------------
docs/page.xsl | 7 ++-
docs/site.xsl | 5 +-
4 files changed, 93 insertions(+), 79 deletions(-)
Reviewed-by: Pavel Hrdina <phrdina(a)redhat.com>
300
days inactive
301
days old
10 comments
2 participants
participants (2)
-
Pavel Hrdina -
Peter Krempa