[libvirt] [PATCHv2 0/3] Colorize HTML documentation
Hi. In version 2 of this series I'm trying to fix some of those issues Jiri had with the initial version. Changes: + do not define a default set of fonts, just use monospace + use font-size: smaller instead of 80% This lets the browser choose a more optimal font size it "thinks" is "smaller" than the normal font size, instead of scaling to some arbitrarily chosen 80% + use dl, dt, dd elements instead of the obsolete tt tag + use CSS instead of tables for layout Claudio Bley (3): docs: Assign classes to documentation elements docs: don't use <i> and <tt> HTML tags docs: Add some style and color to the HTML documentation docs/generic.css | 4 +- docs/libvirt.css | 68 ++++++++++++++- docs/newapi.xsl | 249 +++++++++++++++++++++++++++++------------------------- 3 files changed, 202 insertions(+), 119 deletions(-) -- 1.7.9.5
In CSS the following class names are available: * keyword (keywords like "typedef", "struct") * type (types like "int", "void*") * comment (comments after members of enums or structs) * directive (preprocessor directives, #define) * undisclosed (text saying that the API is not public) Additionally, kill all of the left-over "programlisting" class assignments. There are no CSS rules for them. Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/newapi.xsl | 187 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 108 insertions(+), 79 deletions(-) diff --git a/docs/newapi.xsl b/docs/newapi.xsl index 24831ee..3982f8f 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -116,16 +116,18 @@ </xsl:template> <xsl:template match="macro" mode="toc"> - <xsl:text>#define </xsl:text> + <span class="directive">#define</span><xsl:text> </xsl:text> <a href="#{@name}"><xsl:value-of select="@name"/></a> <xsl:text> </xsl:text> </xsl:template> <xsl:template match="variable" mode="toc"> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="string(@type)"/> - </xsl:call-template> + <span class="type"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="string(@type)"/> + </xsl:call-template> + </span> <xsl:text> </xsl:text> <a name="{@name}"></a> <xsl:value-of select="@name"/> @@ -134,18 +136,21 @@ </xsl:template> <xsl:template match="typedef" mode="toc"> - <xsl:text>typedef </xsl:text><xsl:variable name="name" select="string(@name)"/> + <span class="keyword">typedef</span> + <xsl:text> </xsl:text><xsl:variable name="name" select="string(@name)"/> <xsl:choose> <xsl:when test="@type = 'enum'"> - <xsl:text>enum </xsl:text> + <span class="keyword">enum</span><xsl:text> </xsl:text> <a href="#{$name}"><xsl:value-of select="$name"/></a> <xsl:text> </xsl:text> </xsl:when> <xsl:otherwise> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@type"/> - </xsl:call-template> + <span class="type"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="@type"/> + </xsl:call-template> + </span> <xsl:text> </xsl:text> <a name="{$name}"><xsl:value-of select="$name"/></a> <xsl:text> @@ -159,7 +164,7 @@ <h3><a name="{$name}"><code><xsl:value-of select="$name"/></code></a></h3> <div class="api"> <pre> - <xsl:text>enum </xsl:text> + <span class="keyword">enum</span><xsl:text> </xsl:text> <xsl:value-of select="$name"/> <xsl:text> { </xsl:text> @@ -173,10 +178,11 @@ <td><xsl:value-of select="@value"/></td> <xsl:if test="@info != ''"> <td> - <xsl:text> : </xsl:text> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@info"/> - </xsl:call-template> + <div class="comment"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="@info"/> + </xsl:call-template> + </div> </td> </xsl:if> </tr> @@ -190,8 +196,8 @@ </xsl:template> <xsl:template match="struct" mode="toc"> - <xsl:text>typedef </xsl:text> - <xsl:value-of select="@type"/> + <span class="keyword">typedef</span><xsl:text> </xsl:text> + <span class="type"><xsl:value-of select="@type"/></span> <xsl:text> </xsl:text> <a href="#{@name}"><xsl:value-of select="@name"/></a> <xsl:text> @@ -202,32 +208,35 @@ <h3><a name="{@name}"><code><xsl:value-of select="@name"/></code></a></h3> <div class="api"> <pre> - <xsl:text>struct </xsl:text> + <span class="keyword">struct </span> <xsl:value-of select="@name"/> - <xsl:text>{ + <xsl:text> { </xsl:text> </pre> <table> <xsl:for-each select="field"> <xsl:choose> <xsl:when test='@type = "union"'> - <tr><td>union {</td></tr> + <tr><td><span class="keyword">union</span> {</td></tr> <tr> <td><table> <xsl:for-each select="union/field"> <tr> <td> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@type"/> - </xsl:call-template> + <span class="type"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="@type"/> + </xsl:call-template> + </span> </td> <td><xsl:value-of select="@name"/></td> <xsl:if test="@info != ''"> <td> - <xsl:text> : </xsl:text> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@info"/> - </xsl:call-template> + <div class="comment"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="@info"/> + </xsl:call-template> + </div> </td> </xsl:if> </tr> @@ -238,10 +247,11 @@ <td><xsl:value-of select="@name"/></td> <xsl:if test="@info != ''"> <td> - <xsl:text> : </xsl:text> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@info"/> - </xsl:call-template> + <div class="comment"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="@info"/> + </xsl:call-template> + </div> </td> </xsl:if> <td></td></tr> @@ -249,17 +259,20 @@ <xsl:otherwise> <tr> <td> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@type"/> - </xsl:call-template> + <span class="type"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="@type"/> + </xsl:call-template> + </span> </td> <td><xsl:value-of select="@name"/></td> <xsl:if test="@info != ''"> <td> - <xsl:text> : </xsl:text> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@info"/> - </xsl:call-template> + <div class="comment"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="@info"/> + </xsl:call-template> + </div> </td> </xsl:if> </tr> @@ -269,7 +282,7 @@ <xsl:if test="not(field)"> <tr> <td colspan="3"> - <xsl:text>The content of this structure is not made public by the API</xsl:text> + <span class="undisclosed">The content of this structure is not made public by the API</span> </td> </tr> </xsl:if> @@ -285,7 +298,7 @@ <xsl:template match="macro"> <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> + <pre class="api"><span class="directive">#define</span><xsl:text> </xsl:text><xsl:value-of select="$name"/></pre> <div> <xsl:call-template name="formattext"> <xsl:with-param name="text" select="info"/> @@ -299,9 +312,11 @@ <xsl:variable name="nlen" select="string-length($name)"/> <xsl:variable name="tlen" select="string-length(return/@type)"/> <xsl:variable name="blen" select="(($nlen + 8) - (($nlen + 8) mod 8)) + (($tlen + 8) - (($tlen + 8) mod 8))"/> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="return/@type"/> - </xsl:call-template> + <span class="type"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="return/@type"/> + </xsl:call-template> + </span> <xsl:text> </xsl:text> <a href="#{@name}"><xsl:value-of select="@name"/></a> <xsl:if test="$blen - 40 < -8"> @@ -312,12 +327,14 @@ </xsl:if> <xsl:text> (</xsl:text> <xsl:if test="not(arg)"> - <xsl:text>void</xsl:text> + <span class="type">void</span> </xsl:if> <xsl:for-each select="arg"> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@type"/> - </xsl:call-template> + <span class="type"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="@type"/> + </xsl:call-template> + </span> <xsl:text> </xsl:text> <xsl:value-of select="@name"/> <xsl:if test="position() != last()"> @@ -340,13 +357,15 @@ <xsl:variable name="nlen" select="string-length($name)"/> <xsl:variable name="tlen" select="string-length(return/@type)"/> <xsl:variable name="blen" select="(($nlen + 8) - (($nlen + 8) mod 8)) + (($tlen + 8) - (($tlen + 8) mod 8))"/> - <xsl:text>typedef </xsl:text> + <span class="keyword">typedef</span><xsl:text> </xsl:text> <a href="#{$name}"><xsl:value-of select="$name"/></a> <xsl:text> </xsl:text> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="return/@type"/> - </xsl:call-template> + <span class="type"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="return/@type"/> + </xsl:call-template> + </span> <xsl:text> </xsl:text> <a href="#{$name}"><xsl:value-of select="$name"/></a> <xsl:if test="$blen - 40 < -8"> @@ -357,12 +376,14 @@ </xsl:if> <xsl:text> (</xsl:text> <xsl:if test="not(arg)"> - <xsl:text>void</xsl:text> + <span class="type">void</span> </xsl:if> <xsl:for-each select="arg"> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@type"/> - </xsl:call-template> + <span class="type"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="@type"/> + </xsl:call-template> + </span> <xsl:text> </xsl:text> <xsl:value-of select="@name"/> <xsl:if test="position() != last()"> @@ -388,11 +409,13 @@ <xsl:variable name="tlen" select="string-length(return/@type)"/> <xsl:variable name="blen" select="(($nlen + 8) - (($nlen + 8) mod 8)) + (($tlen + 8) - (($tlen + 8) mod 8))"/> <h3><a name="{$name}"><code><xsl:value-of select="$name"/></code></a></h3> - <pre class="programlisting"> - <xsl:text>typedef </xsl:text> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="return/@type"/> - </xsl:call-template> + <pre class="api"> + <span class="keyword">typedef</span><xsl:text> </xsl:text> + <span class="type"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="return/@type"/> + </xsl:call-template> + </span> <xsl:text> (*</xsl:text> <xsl:value-of select="@name"/> <xsl:if test="$blen - 40 < -8"> @@ -403,16 +426,19 @@ </xsl:if> <xsl:text>) (</xsl:text> <xsl:if test="not(arg)"> - <xsl:text>void</xsl:text> + <span class="type">void</span> </xsl:if> <xsl:for-each select="arg"> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@type"/> - </xsl:call-template> + <span class="type"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="@type"/> + </xsl:call-template> + </span> <xsl:text> </xsl:text> <xsl:value-of select="@name"/> <xsl:if test="position() != last()"> - <xsl:text>, </xsl:text><br/> + <xsl:text>, +</xsl:text> <xsl:if test="$blen - 40 > 8"> <xsl:text> </xsl:text> </xsl:if> @@ -465,10 +491,12 @@ <xsl:variable name="tlen" select="string-length(return/@type)"/> <xsl:variable name="blen" select="(($nlen + 8) - (($nlen + 8) mod 8)) + (($tlen + 8) - (($tlen + 8) mod 8))"/> <h3><a name="{$name}"><code><xsl:value-of select="$name"/></code></a></h3> - <pre class="programlisting"> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="return/@type"/> - </xsl:call-template> + <pre class="api"> + <span class="type"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="return/@type"/> + </xsl:call-template> + </span> <xsl:text> </xsl:text> <xsl:value-of select="@name"/> <xsl:if test="$blen - 40 < -8"> @@ -479,16 +507,19 @@ </xsl:if> <xsl:text> (</xsl:text> <xsl:if test="not(arg)"> - <xsl:text>void</xsl:text> + <span class="type">void</span> </xsl:if> <xsl:for-each select="arg"> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@type"/> - </xsl:call-template> + <span class="type"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="@type"/> + </xsl:call-template> + </span> <xsl:text> </xsl:text> <xsl:value-of select="@name"/> <xsl:if test="position() != last()"> - <xsl:text>, </xsl:text><br/> + <xsl:text>, +</xsl:text> <xsl:if test="$blen - 40 > 8"> <xsl:text> </xsl:text> </xsl:if> @@ -498,9 +529,7 @@ <xsl:text> </xsl:text> </xsl:if> </xsl:for-each> - <xsl:text>)</xsl:text><br/> - <xsl:text> -</xsl:text> + <xsl:text>)</xsl:text> </pre> <div> <xsl:call-template name="formattext"> @@ -579,20 +608,20 @@ <h2>Table of Contents</h2> <xsl:if test="count(exports[@type='macro']) > 0"> <h3><a href="#macros">Macros</a></h3> - <pre> + <pre class="api"> <xsl:apply-templates select="exports[@type='macro']" mode="toc"> <xsl:sort select='@symbol'/> </xsl:apply-templates> </pre> </xsl:if> <h3><a href="#types">Types</a></h3> - <pre> + <pre class="api"> <xsl:apply-templates select="exports[@type='typedef']" mode="toc"> <xsl:sort select='@symbol'/> </xsl:apply-templates> </pre> <h3><a href="#functions">Functions</a></h3> - <pre> + <pre class="api"> <xsl:apply-templates select="exports[@type='function']" mode="toc"> <xsl:sort select='@symbol'/> </xsl:apply-templates> -- 1.7.9.5
Use of <tt> is discouraged in HTML 4.x and has finally been obsoleted in HTML 5. Likewise for the <i> tag. Using tables for layout is (widely) considered bad style, too. Use defintion lists, definition term and defintion description elements instead. Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/newapi.xsl | 62 ++++++++++++++++++++++++------------------------------- 1 file changed, 27 insertions(+), 35 deletions(-) diff --git a/docs/newapi.xsl b/docs/newapi.xsl index 3982f8f..0d32e55 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -457,28 +457,24 @@ </xsl:call-template> </div> <xsl:if test="arg | return"> - <div class="variablelist"><table border="0"><col align="left"/><tbody> + <dl class="variablelist"> <xsl:for-each select="arg"> - <tr> - <td><span class="term"><i><tt><xsl:value-of select="@name"/></tt></i>:</span></td> - <td> - <xsl:call-template name="dumptext"> + <dt><xsl:value-of select="@name"/></dt> + <dd> + <xsl:call-template name="dumptext"> <xsl:with-param name="text" select="@info"/> </xsl:call-template> - </td> - </tr> + </dd> </xsl:for-each> <xsl:if test="return/@info"> - <tr> - <td><span class="term"><i><tt>Returns</tt></i>:</span></td> - <td> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="return/@info"/> - </xsl:call-template> - </td> - </tr> + <dt>Returns</dt> + <dd> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="return/@info"/> + </xsl:call-template> + </dd> </xsl:if> - </tbody></table></div> + </dl> </xsl:if> <br/> <xsl:text> @@ -538,28 +534,24 @@ </div><xsl:text> </xsl:text> <xsl:if test="arg | return/@info"> - <div class="variablelist"><table border="0"><col align="left"/><tbody> - <xsl:for-each select="arg"> - <tr> - <td><span class="term"><i><tt><xsl:value-of select="@name"/></tt></i>:</span></td> - <td> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@info"/> - </xsl:call-template> - </td> - </tr> - </xsl:for-each> - <xsl:if test="return/@info"> - <tr> - <td><span class="term"><i><tt>Returns</tt></i>:</span></td> - <td> + <dl class="variablelist"> + <xsl:for-each select="arg"> + <dt><xsl:value-of select="@name"/></dt> + <dd> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="@info"/> + </xsl:call-template> + </dd> + </xsl:for-each> + <xsl:if test="return/@info"> + <dt>Returns</dt> + <dd> <xsl:call-template name="dumptext"> <xsl:with-param name="text" select="return/@info"/> </xsl:call-template> - </td> - </tr> - </xsl:if> - </tbody></table></div> + </dd> + </xsl:if> + </dl> </xsl:if> </xsl:template> -- 1.7.9.5
Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/generic.css | 4 +--- docs/libvirt.css | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 67 insertions(+), 5 deletions(-) diff --git a/docs/generic.css b/docs/generic.css index dbf7b56..4be5fa2 100644 --- a/docs/generic.css +++ b/docs/generic.css @@ -4,7 +4,7 @@ body { padding: 0px; color: rgb(0,0,0); font-family: Verdana, Arial, Helvetica, sans-serif; - font-size: 80%; + font-size: smaller; background: #ffffff; } @@ -64,8 +64,6 @@ h6 { dl dt { margin-left: 1em; margin-right: 2em; - font-weight: bold; - font-size: larger; } dl dd { diff --git a/docs/libvirt.css b/docs/libvirt.css index 5123ed6..5dc5d9b 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -184,23 +184,25 @@ div.api { border: 1px solid #999999; background: #eeeeee; color: black; + padding: 3px; } div.api pre { margin: 0px; border: 0px; background: inherit; + padding: inherit; } div.api table { margin: 0px; padding-left: 2em; - font-family: fixed; - whitespace: pre; + border-spacing: 0px; } div.api table td, div.variablelist table td { vertical-align: top; + padding-left: 1em; } @@ -412,3 +414,65 @@ table.data tbody td.n { background: rgb(255,220,220); text-align: center; } + +.api { + font-family: monospace; +} + +.api .type { + font-weight: bold; + white-space: nowrap; + color: darkslateblue; +} + +.api .keyword { + font-weight: bold; + color: #A2F; +} + +.api .comment { + color: #080; + margin-left: 2em; + position: relative; +} + +.api .comment:before { + content: ": "; + position: absolute; + left: -1.3em; +} + +.api .undisclosed { + font-style: italic; + letter-spacing: .3ex; + font-weight: bolder; + text-transform: uppercase; +} + +.api .directive { + color: teal; +} + +.api :link:hover, .api :link:focus { + color: blue; + border-color: blue; +} + +.api :link { + text-decoration: none; +} + +dl.variablelist > dt { + display: block; + float: left; + font-style: italic; + font-weight: inherit; +} + +.variablelist dd { + padding-left: 10em; +} + +dl.variablelist > dt:after { + content: ": "; +} -- 1.7.9.5
On Thu, Jan 17, 2013 at 04:00:09PM +0100, Claudio Bley wrote:
Hi.
In version 2 of this series I'm trying to fix some of those issues Jiri had with the initial version.
For those of us who are only tangentially following along, can you post a screenshot of something that doesn't render nicely on the existing pages, and then how it looks with these patches? I can't tell the difference on my browser, so I'm not sure I'm looking at the right place. (Or is that the point, that they should look basically identical and these are just modernization updates?) Dave
Changes:
+ do not define a default set of fonts, just use monospace
+ use font-size: smaller instead of 80%
This lets the browser choose a more optimal font size it "thinks" is "smaller" than the normal font size, instead of scaling to some arbitrarily chosen 80%
+ use dl, dt, dd elements instead of the obsolete tt tag
+ use CSS instead of tables for layout
Claudio Bley (3): docs: Assign classes to documentation elements docs: don't use <i> and <tt> HTML tags docs: Add some style and color to the HTML documentation
docs/generic.css | 4 +- docs/libvirt.css | 68 ++++++++++++++- docs/newapi.xsl | 249 +++++++++++++++++++++++++++++------------------------- 3 files changed, 202 insertions(+), 119 deletions(-)
-- 1.7.9.5
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On Thu, Jan 17, 2013 at 13:30:58 -0500, Dave Allan wrote:
On Thu, Jan 17, 2013 at 04:00:09PM +0100, Claudio Bley wrote:
Hi.
In version 2 of this series I'm trying to fix some of those issues Jiri had with the initial version.
For those of us who are only tangentially following along, can you post a screenshot of something that doesn't render nicely on the existing pages, and then how it looks with these patches? I can't tell the difference on my browser, so I'm not sure I'm looking at the right place. (Or is that the point, that they should look basically identical and these are just modernization updates?)
They are largely modernization updates but also make lots of things look better. First, try looking at the pages on a non-monochromatic monitor :-P Everything is now nicely printed in colors. Another ugliness can be spotted when looking at data structures, such as http://www.libvirt.org/html/libvirt-libvirt.html#virDomainJobInfo I'm too lazy to make screen shots :-) Jirka
On Thu, Jan 17, 2013 at 08:16:53PM +0100, Jiri Denemark wrote:
On Thu, Jan 17, 2013 at 13:30:58 -0500, Dave Allan wrote:
On Thu, Jan 17, 2013 at 04:00:09PM +0100, Claudio Bley wrote:
Hi.
In version 2 of this series I'm trying to fix some of those issues Jiri had with the initial version.
For those of us who are only tangentially following along, can you post a screenshot of something that doesn't render nicely on the existing pages, and then how it looks with these patches? I can't tell the difference on my browser, so I'm not sure I'm looking at the right place. (Or is that the point, that they should look basically identical and these are just modernization updates?)
They are largely modernization updates but also make lots of things look better. First, try looking at the pages on a non-monochromatic monitor :-P Everything is now nicely printed in colors. Another ugliness can be spotted when looking at data structures, such as http://www.libvirt.org/html/libvirt-libvirt.html#virDomainJobInfo
I use lynx on my Hercules you insensitive clod! ;)
I'm too lazy to make screen shots :-)
Jirka
Wow, that really does make a difference. ACK to the aesthetics. Dave
On Thu, Jan 17, 2013 at 16:00:09 +0100, Claudio Bley wrote:
Hi.
In version 2 of this series I'm trying to fix some of those issues Jiri had with the initial version.
Changes:
+ do not define a default set of fonts, just use monospace
+ use font-size: smaller instead of 80%
This lets the browser choose a more optimal font size it "thinks" is "smaller" than the normal font size, instead of scaling to some arbitrarily chosen 80%
+ use dl, dt, dd elements instead of the obsolete tt tag
+ use CSS instead of tables for layout
Very nice, I think it looks much better than what we have now. Especially when looking at data structures. Thanks for doing this. ACK series Jirka
On Thu, Jan 17, 2013 at 20:24:53 +0100, Jiri Denemark wrote:
On Thu, Jan 17, 2013 at 16:00:09 +0100, Claudio Bley wrote:
Hi.
In version 2 of this series I'm trying to fix some of those issues Jiri had with the initial version.
Changes:
+ do not define a default set of fonts, just use monospace
+ use font-size: smaller instead of 80%
This lets the browser choose a more optimal font size it "thinks" is "smaller" than the normal font size, instead of scaling to some arbitrarily chosen 80%
+ use dl, dt, dd elements instead of the obsolete tt tag
+ use CSS instead of tables for layout
Very nice, I think it looks much better than what we have now. Especially when looking at data structures. Thanks for doing this.
ACK series
Some people were anxious to see this change applied to the documentation at libvirt.org so a pushed this series for you :-) Jirka
At Fri, 18 Jan 2013 15:49:27 +0100, Jiri Denemark wrote:
On Thu, Jan 17, 2013 at 20:24:53 +0100, Jiri Denemark wrote:
On Thu, Jan 17, 2013 at 16:00:09 +0100, Claudio Bley wrote:
Hi.
In version 2 of this series I'm trying to fix some of those issues Jiri had with the initial version.
Changes:
+ do not define a default set of fonts, just use monospace
+ use font-size: smaller instead of 80%
This lets the browser choose a more optimal font size it "thinks" is "smaller" than the normal font size, instead of scaling to some arbitrarily chosen 80%
+ use dl, dt, dd elements instead of the obsolete tt tag
+ use CSS instead of tables for layout
Very nice, I think it looks much better than what we have now. Especially when looking at data structures. Thanks for doing this.
ACK series
Some people were anxious to see this change applied to the documentation at libvirt.org so a pushed this series for you :-)
Thanks! Just got back from (a short) vacation, would've been pushing right now. :) I did spot a small glitch right after looking at the site, however. All the virTypedParams* functions have no documentation attached to them. Do you happen to know why this is? 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
At Mon, 21 Jan 2013 15:59:12 +0100, Claudio Bley wrote:
I did spot a small glitch right after looking at the site, however.
All the virTypedParams* functions have no documentation attached to them. Do you happen to know why this is?
Oh, I see. That's because virtypedparam.c is not processed by apibuild.py. If it would be, you get a bunch of error messages about missing descriptions for arguments and return values among errors about misformatted function comments. Try for yourself: ---- 8< ---- >8 ---- diff --git a/docs/Makefile.am b/docs/Makefile.am index c95497f..78d72ac 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -251,7 +251,8 @@ $(APIBUILD_STAMP): $(srcdir)/apibuild.py \ $(srcdir)/../src/libvirt.c \ $(srcdir)/../src/libvirt-lxc.c \ $(srcdir)/../src/libvirt-qemu.c \ - $(srcdir)/../src/util/virerror.c + $(srcdir)/../src/util/virerror.c \ + $(srcdir)/../src/util/virtypedparam.c $(AM_V_GEN)srcdir=$(srcdir) $(PYTHON) $(APIBUILD) touch $@ diff --git a/docs/apibuild.py b/docs/apibuild.py index e24e42d..4d7b002 100755 --- a/docs/apibuild.py +++ b/docs/apibuild.py @@ -24,6 +24,7 @@ included_files = { "libvirt.h": "header with general libvirt API definitions", "virterror.h": "header with error specific API definitions", "libvirt.c": "Main interfaces for the libvirt library", + "virtypedparam.c": "implements helper functions for typed parameters", "virterror.c": "implements error handling and reporting code for libvirt", "event.c": "event loop for monitoring file handles", }
On Mon, Jan 21, 2013 at 17:23:32 +0100, Claudio Bley wrote:
At Mon, 21 Jan 2013 15:59:12 +0100, Claudio Bley wrote:
I did spot a small glitch right after looking at the site, however.
All the virTypedParams* functions have no documentation attached to them. Do you happen to know why this is?
Oh, I see. That's because virtypedparam.c is not processed by apibuild.py.
Exactly, I'll prepare a complete patch to fix this documentation. Jirka
participants (3)
-
Claudio Bley -
Dave Allan -
Jiri Denemark