9:19 a.m.
Hi.
These patches try to improve the look and feel of the libvirt documentation.
Claudio Bley (2):
docs: break longer text into paragraphs in HTML
docs: Limit the maximum width of info text to 75em for better
readability
docs/libvirt.css | 4 ++++
docs/newapi.xsl | 50 +++++++++++++++++++++++++++++++++++++++++---------
2 files changed, 45 insertions(+), 9 deletions(-)
--
1.7.9.5
9:19 a.m.
New subject: [libvirt] [PATCH 1/2] docs: break longer text into paragraphs in HTML
Libvirt's HTML documentation is not as easy to the eyes as it could
be since long text has no visual breaks.
Take advantage of the formatting in documentation comments and wrap
each part separated by two consecutive \n into a HTML <p> element.
Signed-off-by: Claudio Bley <cbley(a)av-test.de>
---
docs/newapi.xsl | 50 +++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 41 insertions(+), 9 deletions(-)
diff --git a/docs/newapi.xsl b/docs/newapi.xsl
index 6e1c646..24831ee 100644
--- a/docs/newapi.xsl
+++ b/docs/newapi.xsl
@@ -83,6 +83,38 @@
</xsl:for-each>
</xsl:template>
+ <xsl:template name="formattext">
+ <xsl:param name="text" />
+
+ <xsl:if test="$text">
+ <xsl:variable name="head" select="substring-before($text,
'

')"/>
+ <xsl:variable name="rest" select="substring-after($text,
'

')"/>
+
+ <xsl:choose>
+ <xsl:when test="$head">
+ <p>
+ <xsl:call-template name="dumptext">
+ <xsl:with-param name="text" select="$head"/>
+ </xsl:call-template>
+ </p>
+ </xsl:when>
+ <xsl:when test="not($rest)">
+ <p>
+ <xsl:call-template name="dumptext">
+ <xsl:with-param name="text" select="$text"/>
+ </xsl:call-template>
+ </p>
+ </xsl:when>
+ </xsl:choose>
+
+ <xsl:if test="$rest">
+ <xsl:call-template name="formattext">
+ <xsl:with-param name="text" select="$rest"/>
+ </xsl:call-template>
+ </xsl:if>
+ </xsl:if>
+ </xsl:template>
+
<xsl:template match="macro" mode="toc">
<xsl:text>#define </xsl:text>
<a href="#{@name}"><xsl:value-of
select="@name"/></a>
@@ -254,11 +286,11 @@
<xsl:variable name="name" select="string(@name)"/>
<h3><a name="{$name}"><code><xsl:value-of
select="$name"/></code></a></h3>
<pre><xsl:text>#define </xsl:text><xsl:value-of
select="$name"/></pre>
- <p>
- <xsl:call-template name="dumptext">
+ <div>
+ <xsl:call-template name="formattext">
<xsl:with-param name="text" select="info"/>
</xsl:call-template>
- </p><xsl:text>
+ </div><xsl:text>
</xsl:text>
</xsl:template>
@@ -393,11 +425,11 @@
<xsl:text>)
</xsl:text>
</pre>
- <p>
- <xsl:call-template name="dumptext">
+ <div>
+ <xsl:call-template name="formattext">
<xsl:with-param name="text" select="info"/>
</xsl:call-template>
- </p>
+ </div>
<xsl:if test="arg | return">
<div class="variablelist"><table border="0"><col
align="left"/><tbody>
<xsl:for-each select="arg">
@@ -470,11 +502,11 @@
<xsl:text>
</xsl:text>
</pre>
- <p>
- <xsl:call-template name="dumptext">
+ <div>
+ <xsl:call-template name="formattext">
<xsl:with-param name="text" select="info"/>
</xsl:call-template>
- </p><xsl:text>
+ </div><xsl:text>
</xsl:text>
<xsl:if test="arg | return/@info">
<div class="variablelist"><table border="0"><col
align="left"/><tbody>
--
1.7.9.5
10:41 a.m.
New subject: [libvirt] [PATCH 1/2] docs: break longer text into paragraphs in HTML
On 01/08/2013 08:19 AM, Claudio Bley wrote:
Libvirt's HTML documentation is not as easy to the eyes as it
could
be since long text has no visual breaks.
Take advantage of the formatting in documentation comments and wrap
each part separated by two consecutive \n into a HTML <p> element.
Yay - I've been wanting that, but not knowing how to get it!
Signed-off-by: Claudio Bley <cbley(a)av-test.de>
---
docs/newapi.xsl | 50 +++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 41 insertions(+), 9 deletions(-)
I'm no .xsl expert, but what I _did_ do was check the resulting .html
files in my browser, and they do indeed look much nicer. ACK.
--
Eric Blake eblake redhat com +1-919-301-3266
Libvirt virtualization library http://libvirt.org
1:20 a.m.
New subject: [libvirt] [PATCH 1/2] docs: break longer text into paragraphs in HTML
At Tue, 08 Jan 2013 09:41:40 -0700,
Eric Blake wrote:
[1 <text/plain; UTF-8 (quoted-printable)>]
On 01/08/2013 08:19 AM, Claudio Bley wrote:
> Libvirt's HTML documentation is not as easy to the eyes as it could
> be since long text has no visual breaks.
>
> Take advantage of the formatting in documentation comments and wrap
> each part separated by two consecutive \n into a HTML <p> element.
Yay - I've been wanting that, but not knowing how to get it!
Here you are... :)
I'm no .xsl expert, but what I _did_ do was check the resulting
.html
files in my browser, and they do indeed look much nicer. ACK.
Thanks, pushed now.
Claudio
--
AV-Test GmbH, Henricistraße 20, 04155 Leipzig, Germany
Phone: +49 341 265 310 19
Web:<http://www.av-test.org>
Eingetragen am / Registered at: Amtsgericht Stendal (HRB 114076)
Geschaeftsfuehrer (CEO): Andreas Marx, Guido Habicht, Maik Morgenstern
9:19 a.m.
New subject: [libvirt] [PATCH 2/2] docs: Limit the maximum width of info text to 75em for better readability
Signed-off-by: Claudio Bley <cbley(a)av-test.de>
---
docs/libvirt.css | 4 ++++
docs/newapi.xsl | 6 +++---
2 files changed, 7 insertions(+), 3 deletions(-)
diff --git a/docs/libvirt.css b/docs/libvirt.css
index 5123ed6..b6f5c4b 100644
--- a/docs/libvirt.css
+++ b/docs/libvirt.css
@@ -412,3 +412,7 @@ table.data tbody td.n {
background: rgb(255,220,220);
text-align: center;
}
+
+div.info {
+ max-width: 75em;
+}
diff --git a/docs/newapi.xsl b/docs/newapi.xsl
index 24831ee..6b87682 100644
--- a/docs/newapi.xsl
+++ b/docs/newapi.xsl
@@ -286,7 +286,7 @@
<xsl:variable name="name" select="string(@name)"/>
<h3><a name="{$name}"><code><xsl:value-of
select="$name"/></code></a></h3>
<pre><xsl:text>#define </xsl:text><xsl:value-of
select="$name"/></pre>
- <div>
+ <div class='info'>
<xsl:call-template name="formattext">
<xsl:with-param name="text" select="info"/>
</xsl:call-template>
@@ -425,7 +425,7 @@
<xsl:text>)
</xsl:text>
</pre>
- <div>
+ <div class='info'>
<xsl:call-template name="formattext">
<xsl:with-param name="text" select="info"/>
</xsl:call-template>
@@ -502,7 +502,7 @@
<xsl:text>
</xsl:text>
</pre>
- <div>
+ <div class='info'>
<xsl:call-template name="formattext">
<xsl:with-param name="text" select="info"/>
</xsl:call-template>
--
1.7.9.5
10:43 a.m.
New subject: [libvirt] [PATCH 2/2] docs: Limit the maximum width of info text to 75em for better readability
On 01/08/2013 08:19 AM, Claudio Bley wrote:
Signed-off-by: Claudio Bley <cbley(a)av-test.de>
---
docs/libvirt.css | 4 ++++
docs/newapi.xsl | 6 +++---
2 files changed, 7 insertions(+), 3 deletions(-)
I'm not sure if I found a page where the rendering differed as a result
of this, but I also have no objections.
ACK.
--
Eric Blake eblake redhat com +1-919-301-3266
Libvirt virtualization library http://libvirt.org
4371
days inactive
4372
days old
5 comments
2 participants
participants (2)
-
Claudio Bley -
Eric Blake