[libvirt] [PATCH 0/2] Improve readability of generated HTML documenation
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
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@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
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@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
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
Signed-off-by: Claudio Bley <cbley@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
On 01/08/2013 08:19 AM, Claudio Bley wrote:
Signed-off-by: Claudio Bley <cbley@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
participants (2)
-
Claudio Bley -
Eric Blake