[libvirt] [PATCH 0/7] documentation improvements - again
Hi. The first two patches are aimed at avoiding generation of empty argument description lists, which might happen if a function has no documentation for some argument or its return type. This was happening with virTypedParams* functions (see https://www.redhat.com/archives/libvir-list/2013-January/msg01428.html) Patch #3 is just a small cleanup, since a table is not the right thing to use and it looks better in some circumstances. Patch #4 sports processing of code blocks embedded into comments. Basically, it is similar to markdown syntax, except that you only need to indent your code with 2 spaces. Patch #5 prepares for the later patches being able to distinguish between different <pre> blocks. Patch #6 and #7 are pretty much self explanatory, I guess. Note, that SHJS's license is GPLv3. Claudio Bley (7): docs: don't write out empty info attributes for function arguments docs: only generate function argument info for args with a description docs: use a div instead of a 3 column table for undisclosed notices docs: process code blocks similar to markdown docs: add class "description" to div's containing descriptions docs: define style of code blocks inside descriptions docs: syntax highlight code blocks using SHJS docs/apibuild.py | 8 +- docs/libvirt.css | 8 ++ docs/newapi.xsl | 209 +++++++++++++++++++++++++++++-------------------- docs/page.xsl | 5 +- docs/sh_c.min.js | 1 + docs/sh_emacs.min.css | 1 + docs/sh_main.min.js | 4 + 7 files changed, 148 insertions(+), 88 deletions(-) create mode 100644 docs/sh_c.min.js create mode 100644 docs/sh_emacs.min.css create mode 100644 docs/sh_main.min.js -- 1.7.9.5
Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/apibuild.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/apibuild.py b/docs/apibuild.py index 9a29c42..f9500b1 100755 --- a/docs/apibuild.py +++ b/docs/apibuild.py @@ -2183,8 +2183,8 @@ class docBuilder: output.write(" <info><![CDATA[%s]]></info>\n" % (desc)) self.indexString(name, desc) if ret[0] != None: - if ret[0] == "void": - output.write(" <return type='void'/>\n") + if ret[0] == "void" or ret[1] == None or ret[1] == '': + output.write(" <return type='%s'/>\n" % ret[0]) else: output.write(" <return type='%s' info='%s'/>\n" % ( ret[0], escape(ret[1]))) @@ -2192,8 +2192,8 @@ class docBuilder: for param in params: if param[0] == 'void': continue - if param[2] == None: - output.write(" <arg name='%s' type='%s' info=''/>\n" % (param[1], param[0])) + if param[2] == None or param[2] == '': + output.write(" <arg name='%s' type='%s' />\n" % (param[1], param[0])) else: output.write(" <arg name='%s' type='%s' info='%s'/>\n" % (param[1], param[0], escape(param[2]))) self.indexString(name, param[2]) -- 1.7.9.5
On 01/22/2013 07:31 AM, Claudio Bley wrote:
Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/apibuild.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/apibuild.py b/docs/apibuild.py index 9a29c42..f9500b1 100755 --- a/docs/apibuild.py +++ b/docs/apibuild.py @@ -2183,8 +2183,8 @@ class docBuilder: output.write(" <info><![CDATA[%s]]></info>\n" % (desc)) self.indexString(name, desc) if ret[0] != None: - if ret[0] == "void": - output.write(" <return type='void'/>\n") + if ret[0] == "void" or ret[1] == None or ret[1] == '': + output.write(" <return type='%s'/>\n" % ret[0])
Can we instead make it a fatal error if ret[1] == None or ret[1] == '', to force 'make' to fail and point out the missing documentation?
else: output.write(" <return type='%s' info='%s'/>\n" % ( ret[0], escape(ret[1]))) @@ -2192,8 +2192,8 @@ class docBuilder: for param in params: if param[0] == 'void': continue - if param[2] == None: - output.write(" <arg name='%s' type='%s' info=''/>\n" % (param[1], param[0])) + if param[2] == None or param[2] == '': + output.write(" <arg name='%s' type='%s' />\n" % (param[1], param[0])) else: output.write(" <arg name='%s' type='%s' info='%s'/>\n" % (param[1], param[0], escape(param[2]))) self.indexString(name, param[2])
-- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
At Mon, 28 Jan 2013 17:36:08 -0700, Eric Blake wrote:
[1 <text/plain; UTF-8 (quoted-printable)>] On 01/22/2013 07:31 AM, Claudio Bley wrote:
Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/apibuild.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/docs/apibuild.py b/docs/apibuild.py index 9a29c42..f9500b1 100755 --- a/docs/apibuild.py +++ b/docs/apibuild.py @@ -2183,8 +2183,8 @@ class docBuilder: output.write(" <info><![CDATA[%s]]></info>\n" % (desc)) self.indexString(name, desc) if ret[0] != None: - if ret[0] == "void": - output.write(" <return type='void'/>\n") + if ret[0] == "void" or ret[1] == None or ret[1] == '': + output.write(" <return type='%s'/>\n" % ret[0])
Can we instead make it a fatal error if ret[1] == None or ret[1] == '', to force 'make' to fail and point out the missing documentation?
Sounds good to me. Follow-up patch is coming. 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
When function arguments or return values lack a description there's no use in generating a meaningless "ARG1: " stanza. Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/newapi.xsl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/newapi.xsl b/docs/newapi.xsl index 0d32e55..fb95c44 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -533,9 +533,9 @@ </xsl:call-template> </div><xsl:text> </xsl:text> - <xsl:if test="arg | return/@info"> + <xsl:if test="arg[@info] | return/@info"> <dl class="variablelist"> - <xsl:for-each select="arg"> + <xsl:for-each select="arg[@info]"> <dt><xsl:value-of select="@name"/></dt> <dd> <xsl:call-template name="dumptext"> -- 1.7.9.5
On 01/22/2013 07:31 AM, Claudio Bley wrote:
When function arguments or return values lack a description there's no use in generating a meaningless "ARG1: " stanza.
Again, can we instead tweak this to cause 'make' to fail if there is missing documentation?
Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/newapi.xsl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/newapi.xsl b/docs/newapi.xsl index 0d32e55..fb95c44 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -533,9 +533,9 @@ </xsl:call-template> </div><xsl:text> </xsl:text> - <xsl:if test="arg | return/@info"> + <xsl:if test="arg[@info] | return/@info"> <dl class="variablelist"> - <xsl:for-each select="arg"> + <xsl:for-each select="arg[@info]"> <dt><xsl:value-of select="@name"/></dt> <dd> <xsl:call-template name="dumptext">
-- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
At Mon, 28 Jan 2013 17:45:41 -0700, Eric Blake wrote:
On 01/22/2013 07:31 AM, Claudio Bley wrote:
When function arguments or return values lack a description there's no use in generating a meaningless "ARG1: " stanza.
Again, can we instead tweak this to cause 'make' to fail if there is missing documentation?
You mean to make this entirely bullet-proof? I'm a bit reluctant as to double checking this requirement. 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
It's simpler to render and it prevents wrapping the line too early because of the table spacing, border et cetera. Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/libvirt.css | 1 + docs/newapi.xsl | 110 +++++++++++++++++++++++++++--------------------------- 2 files changed, 55 insertions(+), 56 deletions(-) diff --git a/docs/libvirt.css b/docs/libvirt.css index 5dc5d9b..8a00d12 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -447,6 +447,7 @@ table.data tbody td.n { letter-spacing: .3ex; font-weight: bolder; text-transform: uppercase; + margin-left: 2em; } .api .directive { diff --git a/docs/newapi.xsl b/docs/newapi.xsl index fb95c44..09395ea 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -213,14 +213,51 @@ <xsl:text> { </xsl:text> </pre> - <table> - <xsl:for-each select="field"> - <xsl:choose> - <xsl:when test='@type = "union"'> - <tr><td><span class="keyword">union</span> {</td></tr> - <tr> - <td><table> - <xsl:for-each select="union/field"> + <xsl:if test="field"> + <table> + <xsl:for-each select="field"> + <xsl:choose> + <xsl:when test='@type = "union"'> + <tr><td><span class="keyword">union</span> {</td></tr> + <tr> + <td><table> + <xsl:for-each select="union/field"> + <tr> + <td> + <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> + <div class="comment"> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="@info"/> + </xsl:call-template> + </div> + </td> + </xsl:if> + </tr> + </xsl:for-each> + </table></td> + <td></td></tr> + <tr><td>}</td> + <td><xsl:value-of select="@name"/></td> + <xsl:if test="@info != ''"> + <td> + <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> + </xsl:when> + <xsl:otherwise> <tr> <td> <span class="type"> @@ -234,59 +271,20 @@ <td> <div class="comment"> <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@info"/> + <xsl:with-param name="text" select="@info"/> </xsl:call-template> </div> </td> </xsl:if> </tr> - </xsl:for-each> - </table></td> - <td></td></tr> - <tr><td>}</td> - <td><xsl:value-of select="@name"/></td> - <xsl:if test="@info != ''"> - <td> - <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> - </xsl:when> - <xsl:otherwise> - <tr> - <td> - <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> - <div class="comment"> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="@info"/> - </xsl:call-template> - </div> - </td> - </xsl:if> - </tr> - </xsl:otherwise> - </xsl:choose> - </xsl:for-each> - <xsl:if test="not(field)"> - <tr> - <td colspan="3"> - <span class="undisclosed">The content of this structure is not made public by the API</span> - </td> - </tr> - </xsl:if> - </table> + </xsl:otherwise> + </xsl:choose> + </xsl:for-each> + </table> + </xsl:if> + <xsl:if test="not(field)"> + <div class="undisclosed">The content of this structure is not made public by the API</div> + </xsl:if> <pre> <xsl:text> } -- 1.7.9.5
On 01/22/2013 07:31 AM, Claudio Bley wrote:
It's simpler to render and it prevents wrapping the line too early because of the table spacing, border et cetera.
Subject line was a bit long; also, on my first read, I misread it as notices that were not disclosed to the reader (why are we worried about how to render something the reader won't see?). Maybe this is better: docs: use div, not table, for notices on opaque types
Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/libvirt.css | 1 + docs/newapi.xsl | 110 +++++++++++++++++++++++++++--------------------------- 2 files changed, 55 insertions(+), 56 deletions(-)
diff --git a/docs/libvirt.css b/docs/libvirt.css index 5dc5d9b..8a00d12 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -447,6 +447,7 @@ table.data tbody td.n { letter-spacing: .3ex; font-weight: bolder; text-transform: uppercase; + margin-left: 2em; }
I have no idea how to tell if the css and xsl makes sense as written; but I was able to apply the patch and view a slight difference in the current: http://libvirt.org/html/libvirt-libvirt.html#virConnect vs. your patched version as I shrunk the width of my window. I like it, so ACK. -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
At Mon, 28 Jan 2013 17:55:10 -0700, Eric Blake wrote:
On 01/22/2013 07:31 AM, Claudio Bley wrote:
It's simpler to render and it prevents wrapping the line too early because of the table spacing, border et cetera.
Subject line was a bit long; also, on my first read, I misread it as notices that were not disclosed to the reader (why are we worried about how to render something the reader won't see?). Maybe this is better:
docs: use div, not table, for notices on opaque types
OK, will do. Thanks for your review thus far, btw. 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
Wrap pre-formatted example code in <code> elements. This works similar to markdown code blocks. Every line indented with at least 2 spaces is considered a code block and gets wrapped in <pre> and <code> tags. Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/newapi.xsl | 89 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 67 insertions(+), 22 deletions(-) diff --git a/docs/newapi.xsl b/docs/newapi.xsl index 09395ea..b11ce9c 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -83,6 +83,60 @@ </xsl:for-each> </xsl:template> + + <!-- process blocks of text. blocks are separated by two consecutive line --> + <!-- breaks. --> + <!-- --> + <!-- blocks indented with at least 2 spaces are considered code blocks. --> + <!-- --> + <!-- consecutive code blocks are collapsed into a single code block. --> + <xsl:template name="formatblock"> + <xsl:param name="block"/> + <xsl:param name="rest"/> + + <xsl:variable name="multipleCodeBlocks" + select="starts-with($block, ' ') and starts-with($rest, ' ')"/> + + <xsl:choose> + <xsl:when test="$multipleCodeBlocks"> + <xsl:call-template name="formatblock"> + <xsl:with-param name="block"> + <xsl:choose> + <xsl:when test="contains($rest, ' ')"> + <xsl:value-of select="concat($block, ' ', + substring-before($rest, ' '))" /> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat($block, ' ', $rest)" /> + </xsl:otherwise> + </xsl:choose> + </xsl:with-param> + <xsl:with-param name="rest" select="substring-after($rest, ' ')"/> + </xsl:call-template> + </xsl:when> + <xsl:when test="starts-with($block, ' ')"> + <pre class="code"><xsl:for-each select="str:tokenize($block, ' ')"> + <xsl:value-of select="substring(., 3)"/> + <xsl:if test="position() != last()"> + <xsl:text> </xsl:text> + </xsl:if> + </xsl:for-each></pre> + </xsl:when> + <xsl:otherwise> + <p> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="$block"/> + </xsl:call-template> + </p> + </xsl:otherwise> + </xsl:choose> + <xsl:if test="not($multipleCodeBlocks)"> + <xsl:call-template name="formattext"> + <xsl:with-param name="text" select="$rest"/> + </xsl:call-template> + </xsl:if> + </xsl:template> + <xsl:template name="formattext"> <xsl:param name="text" /> @@ -90,28 +144,19 @@ <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:call-template name="formatblock"> + <xsl:with-param name="block"> + <xsl:choose> + <xsl:when test="contains($text, ' ')"> + <xsl:value-of select="$head"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$text"/> + </xsl:otherwise> + </xsl:choose> + </xsl:with-param> + <xsl:with-param name="rest" select="$rest"/> + </xsl:call-template> </xsl:if> </xsl:template> -- 1.7.9.5
On 01/22/2013 07:31 AM, Claudio Bley wrote:
Wrap pre-formatted example code in <code> elements. This works similar to markdown code blocks.
Every line indented with at least 2 spaces is considered a code block and gets wrapped in <pre> and <code> tags.
Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/newapi.xsl | 89 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 67 insertions(+), 22 deletions(-)
I tried to see a page where this would make a difference; but http://libvirt.org/html/libvirt-libvirt.html#virDomainGetMemoryParameters didn't pick up any new formatting in my local version. For these patches, calling out an anchor where the differences can be visually inspected will make review much easier. Or is this a case where we also need to touch up src/libvirt.c to actually provide the indentation that this xsl patch is looking for? At any rate, I don't feel comfortable acking until I can see the improvement (since I am not fluent in xsl); but if the idea works, it makes total sense (as the current code chunks on the web page render quite horribly). -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
At Tue, 29 Jan 2013 11:23:24 -0700, Eric Blake wrote:
On 01/22/2013 07:31 AM, Claudio Bley wrote:
Wrap pre-formatted example code in <code> elements. This works similar to markdown code blocks.
Every line indented with at least 2 spaces is considered a code block and gets wrapped in <pre> and <code> tags.
Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/newapi.xsl | 89 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 67 insertions(+), 22 deletions(-)
I tried to see a page where this would make a difference; but http://libvirt.org/html/libvirt-libvirt.html#virDomainGetMemoryParameters didn't pick up any new formatting in my local version.
Sorry for not providing this before, but for me #virStreamRecv works, as does #virStreamRecvAll.
For these patches, calling out an anchor where the differences can be visually inspected will make review much easier. Or is this a case where we also need to touch up src/libvirt.c to actually provide the indentation that this xsl patch is looking for?
Yes, the code in virDomainGetMemoryParameters isn't indented, ie. it is not recognized as a code block. And there's a glitch in virStreamRecv's code block too, the label on the third from last line is not indented and hence got its first two characters cut off.
At any rate, I don't feel comfortable acking until I can see the improvement (since I am not fluent in xsl); but if the idea works, it makes total sense (as the current code chunks on the web page render quite horribly).
Yes, I totally agree. 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/newapi.xsl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/newapi.xsl b/docs/newapi.xsl index b11ce9c..29ed94f 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -342,7 +342,7 @@ <xsl:variable name="name" select="string(@name)"/> <h3><a name="{$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> + <div class="description"> <xsl:call-template name="formattext"> <xsl:with-param name="text" select="info"/> </xsl:call-template> @@ -494,7 +494,7 @@ <xsl:text>) </xsl:text> </pre> - <div> + <div class="description"> <xsl:call-template name="formattext"> <xsl:with-param name="text" select="info"/> </xsl:call-template> @@ -570,7 +570,7 @@ </xsl:for-each> <xsl:text>)</xsl:text> </pre> - <div> + <div class="description"> <xsl:call-template name="formattext"> <xsl:with-param name="text" select="info"/> </xsl:call-template> -- 1.7.9.5
Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/libvirt.css | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/libvirt.css b/docs/libvirt.css index 8a00d12..c9e8beb 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -477,3 +477,10 @@ dl.variablelist > dt { dl.variablelist > dt:after { content: ": "; } + +div.description pre.code { + border: 1px dashed grey; + background-color: inherit; + padding: 5px 10px 5px 10px; + margin-left: 2.5em; +} -- 1.7.9.5
Add minimized CSS and Javascript files of SHJS (http://shjs.sourceforge.net/) required for highlighting C code. Call sh_highlightDocument() in onload event handler. Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/newapi.xsl | 2 +- docs/page.xsl | 5 ++++- docs/sh_c.min.js | 1 + docs/sh_emacs.min.css | 1 + docs/sh_main.min.js | 4 ++++ 5 files changed, 11 insertions(+), 2 deletions(-) create mode 100644 docs/sh_c.min.js create mode 100644 docs/sh_emacs.min.css create mode 100644 docs/sh_main.min.js diff --git a/docs/newapi.xsl b/docs/newapi.xsl index 29ed94f..a975ba8 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -115,7 +115,7 @@ </xsl:call-template> </xsl:when> <xsl:when test="starts-with($block, ' ')"> - <pre class="code"><xsl:for-each select="str:tokenize($block, ' ')"> + <pre class="code sh_c"><xsl:for-each select="str:tokenize($block, ' ')"> <xsl:value-of select="substring(., 3)"/> <xsl:if test="position() != last()"> <xsl:text> </xsl:text> diff --git a/docs/page.xsl b/docs/page.xsl index bc8ea2a..bf7c446 100644 --- a/docs/page.xsl +++ b/docs/page.xsl @@ -136,10 +136,13 @@ <head> <link rel="stylesheet" type="text/css" href="{$href_base}main.css"/> <link rel="SHORTCUT ICON" href="{$href_base}32favicon.png"/> + <script type="text/javascript" src="{$href_base}sh_main.min.js"/> + <script type="text/javascript" src="{$href_base}sh_c.min.js"/> + <link rel="stylesheet" type="text/css" href="{$href_base}sh_emacs.min.css"/> <title>libvirt: <xsl:value-of select="html/body/h1"/></title> <meta name="description" content="libvirt, virtualization, virtualization API"/> </head> - <body> + <body onload="sh_highlightDocument();"> <div id="header"> <div id="headerLogo"/> <div id="headerSearch"> diff --git a/docs/sh_c.min.js b/docs/sh_c.min.js new file mode 100644 index 0000000..fd91118 --- /dev/null +++ b/docs/sh_c.min.js @@ -0,0 +1 @@ +if(!this.sh_languages){this.sh_languages={}}sh_languages.c=[[[/\/\/\//g,"sh_comment",1],[/\/\//g,"sh_comment",7],[/\/\*\*/g,"sh_comment",8],[/\/\*/g,"sh_comment",9],[/(\bstruct)([ \t]+)([A-Za-z0-9_]+)/g,["sh_keyword","sh_normal","sh_classname"],-1],[/^[ \t]*#(?:[ \t]*include)/g,"sh_preproc",10,1],[/^[ \t]*#(?:[ \t]*[A-Za-z0-9_]*)/g,"sh_preproc",-1],[/\b[+-]?(?:(?:0x[A-Fa-f0-9]+)|(?:(?:[\d]*\.)?[\d]+(?:[eE][+-]?[\d]+)?))u?(?:(?:int(?:8|16|32|64))|L)?\b/g,"sh_number",-1],[/"/g,"sh_string",13],[/'/g,"sh_string",14],[/\b(?:__asm|__cdecl|__declspec|__export|__far16|__fastcall|__fortran|__import|__pascal|__rtti|__stdcall|_asm|_cdecl|__except|_export|_far16|_fastcall|__finally|_fortran|_import|_pascal|_stdcall|__thread|__try|asm|auto|break|case|catch|cdecl|const|continue|default|do|else|enum|extern|for|goto|if|pascal|register|return|sizeof|static|struct|switch|typedef|union|volatile|while)\b/g,"sh_keyword",-1],[/\b(?:bool|char|double|float|int|long|short|signed|unsigned|void|wchar_ t)\b/g,"sh_type",-1],[/~|!|%|\^|\*|\(|\)|-|\+|=|\[|\]|\\|:|;|,|\.|\/|\?|&|<|>|\|/g,"sh_symbol",-1],[/\{|\}/g,"sh_cbracket",-1],[/(?:[A-Za-z]|_)[A-Za-z0-9_]*(?=[ \t]*\()/g,"sh_function",-1],[/([A-Za-z](?:[^`~!@#$%&*()_=+{}|;:",<.>\/?'\\[\]\^\-\s]|[_])*)((?:<.*>)?)(\s+(?=[*&]*[A-Za-z][^`~!@#$%&*()_=+{}|;:",<.>\/?'\\[\]\^\-\s]*\s*[`~!@#$%&*()_=+{}|;:",<.>\/?'\\[\]\^\-\[\]]+))/g,["sh_usertype","sh_usertype","sh_normal"],-1]],[[/$/g,null,-2],[/(?:<?)[A-Za-z0-9_\.\/\-_~]+@[A-Za-z0-9_\.\/\-_~]+(?:>?)|(?:<?)[A-Za-z0-9_]+:\/\/[A-Za-z0-9_\.\/\-_~]+(?:>?)/g,"sh_url",-1],[/<\?xml/g,"sh_preproc",2,1],[/<!DOCTYPE/g,"sh_preproc",4,1],[/<!--/g,"sh_comment",5],[/<(?:\/)?[A-Za-z](?:[A-Za-z0-9_:.-]*)(?:\/)?>/g,"sh_keyword",-1],[/<(?:\/)?[A-Za-z](?:[A-Za-z0-9_:.-]*)/g,"sh_keyword",6,1],[/&(?:[A-Za-z0-9]+);/g,"sh_preproc",-1],[/<(?:\/)?[A-Za-z][A-Za-z0-9]*(?:\/)?>/g,"sh_keyword",-1],[/<(?:\/)?[A-Za-z][A-Za-z0-9]*/g,"sh_keyword",6,1],[/@[A-Za-z]+/g,"sh_type",-1],[/(?:TODO|FIXME|BUG)(?:[:]?)/g,"sh _todo",-1]],[[/\?>/g,"sh_preproc",-2],[/([^=" \t>]+)([ \t]*)(=?)/g,["sh_type","sh_normal","sh_symbol"],-1],[/"/g,"sh_string",3]],[[/\\(?:\\|")/g,null,-1],[/"/g,"sh_string",-2]],[[/>/g,"sh_preproc",-2],[/([^=" \t>]+)([ \t]*)(=?)/g,["sh_type","sh_normal","sh_symbol"],-1],[/"/g,"sh_string",3]],[[/-->/g,"sh_comment",-2],[/<!--/g,"sh_comment",5]],[[/(?:\/)?>/g,"sh_keyword",-2],[/([^=" \t>]+)([ \t]*)(=?)/g,["sh_type","sh_normal","sh_symbol"],-1],[/"/g,"sh_string",3]],[[/$/g,null,-2]],[[/\*\//g,"sh_comment",-2],[/(?:<?)[A-Za-z0-9_\.\/\-_~]+@[A-Za-z0-9_\.\/\-_~]+(?:>?)|(?:<?)[A-Za-z0-9_]+:\/\/[A-Za-z0-9_\.\/\-_~]+(?:>?)/g,"sh_url",-1],[/<\?xml/g,"sh_preproc",2,1],[/<!DOCTYPE/g,"sh_preproc",4,1],[/<!--/g,"sh_comment",5],[/<(?:\/)?[A-Za-z](?:[A-Za-z0-9_:.-]*)(?:\/)?>/g,"sh_keyword",-1],[/<(?:\/)?[A-Za-z](?:[A-Za-z0-9_:.-]*)/g,"sh_keyword",6,1],[/&(?:[A-Za-z0-9]+);/g,"sh_preproc",-1],[/<(?:\/)?[A-Za-z][A-Za-z0-9]*(?:\/)?>/g,"sh_keyword",-1],[/<(?:\/)?[A-Za-z][A-Za-z0-9]*/g,"sh_keyword" ,6,1],[/@[A-Za-z]+/g,"sh_type",-1],[/(?:TODO|FIXME|BUG)(?:[:]?)/g,"sh_todo",-1]],[[/\*\//g,"sh_comment",-2],[/(?:<?)[A-Za-z0-9_\.\/\-_~]+@[A-Za-z0-9_\.\/\-_~]+(?:>?)|(?:<?)[A-Za-z0-9_]+:\/\/[A-Za-z0-9_\.\/\-_~]+(?:>?)/g,"sh_url",-1],[/(?:TODO|FIXME|BUG)(?:[:]?)/g,"sh_todo",-1]],[[/$/g,null,-2],[/</g,"sh_string",11],[/"/g,"sh_string",12],[/\/\/\//g,"sh_comment",1],[/\/\//g,"sh_comment",7],[/\/\*\*/g,"sh_comment",8],[/\/\*/g,"sh_comment",9]],[[/$/g,null,-2],[/>/g,"sh_string",-2]],[[/$/g,null,-2],[/\\(?:\\|")/g,null,-1],[/"/g,"sh_string",-2]],[[/"/g,"sh_string",-2],[/\\./g,"sh_specialchar",-1]],[[/'/g,"sh_string",-2],[/\\./g,"sh_specialchar",-1]]]; \ No newline at end of file diff --git a/docs/sh_emacs.min.css b/docs/sh_emacs.min.css new file mode 100644 index 0000000..b7aed87 --- /dev/null +++ b/docs/sh_emacs.min.css @@ -0,0 +1 @@ +pre.sh_sourceCode{background-color:#fff;color:#000;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_keyword{color:#9c20ee;font-weight:bold;font-style:normal;}pre.sh_sourceCode .sh_type{color:#208920;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_string{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_regexp{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_specialchar{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_comment{color:#ac2020;font-weight:normal;font-style:italic;}pre.sh_sourceCode .sh_number{color:#000;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_preproc{color:#000;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_function{color:#000;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_url{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_date{color:#9c20ee;font-weight:bold;font-style:normal;}pre.sh_sourceCode . sh_time{color:#9c20ee;font-weight:bold;font-style:normal;}pre.sh_sourceCode .sh_file{color:#9c20ee;font-weight:bold;font-style:normal;}pre.sh_sourceCode .sh_ip{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_name{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_variable{color:#00f;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_oldfile{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_newfile{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_difflines{color:#9c20ee;font-weight:bold;font-style:normal;}pre.sh_sourceCode .sh_selector{color:#00f;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_property{color:#9c20ee;font-weight:bold;font-style:normal;}pre.sh_sourceCode .sh_value{color:#bd8d8b;font-weight:normal;font-style:normal;} \ No newline at end of file diff --git a/docs/sh_main.min.js b/docs/sh_main.min.js new file mode 100644 index 0000000..31d1ba0 --- /dev/null +++ b/docs/sh_main.min.js @@ -0,0 +1,4 @@ +/* Copyright (C) 2007, 2008 gnombat@users.sourceforge.net */ +/* License: http://shjs.sourceforge.net/doc/gplv3.html */ + +if(!this.sh_languages){this.sh_languages={}}var sh_requests={};function sh_isEmailAddress(a){if(/^mailto:/.test(a)){return false}return a.indexOf("@")!==-1}function sh_setHref(b,c,d){var a=d.substring(b[c-2].pos,b[c-1].pos);if(a.length>=2&&a.charAt(0)==="<"&&a.charAt(a.length-1)===">"){a=a.substr(1,a.length-2)}if(sh_isEmailAddress(a)){a="mailto:"+a}b[c-2].node.href=a}function sh_konquerorExec(b){var a=[""];a.index=b.length;a.input=b;return a}function sh_highlightString(B,o){if(/Konqueror/.test(navigator.userAgent)){if(!o.konquered){for(var F=0;F<o.length;F++){for(var H=0;H<o[F].length;H++){var G=o[F][H][0];if(G.source==="$"){G.exec=sh_konquerorExec}}}o.konquered=true}}var N=document.createElement("a");var q=document.createElement("span");var A=[];var j=0;var n=[];var C=0;var k=null;var x=function(i,a){var p=i.length;if(p===0){return}if(!a){var Q=n.length;if(Q!==0){var r=n[Q-1];if(!r[3]){a=r[1]}}}if(k!==a){if(k){A[j++]={pos:C};if(k==="sh_url"){sh_setHref(A,j,B)}}if(a){var P;i f(a==="sh_url"){P=N.cloneNode(false)}else{P=q.cloneNode(false)}P.className=a;A[j++]={node:P,pos:C}}}C+=p;k=a};var t=/\r\n|\r|\n/g;t.lastIndex=0;var d=B.length;while(C<d){var v=C;var l;var w;var h=t.exec(B);if(h===null){l=d;w=d}else{l=h.index;w=t.lastIndex}var g=B.substring(v,l);var M=[];for(;;){var I=C-v;var D;var y=n.length;if(y===0){D=0}else{D=n[y-1][2]}var O=o[D];var z=O.length;var m=M[D];if(!m){m=M[D]=[]}var E=null;var u=-1;for(var K=0;K<z;K++){var f;if(K<m.length&&(m[K]===null||I<=m[K].index)){f=m[K]}else{var c=O[K][0];c.lastIndex=I;f=c.exec(g);m[K]=f}if(f!==null&&(E===null||f.index<E.index)){E=f;u=K;if(f.index===I){break}}}if(E===null){x(g.substring(I),null);break}else{if(E.index>I){x(g.substring(I,E.index),null)}var e=O[u];var J=e[1];var b;if(J instanceof Array){for(var L=0;L<J.length;L++){b=E[L+1];x(b,J[L])}}else{b=E[0];x(b,J)}switch(e[2]){case -1:break;case -2:n.pop();break;case -3:n.length=0;break;default:n.push(e);break}}}if(k){A[j++]={pos:C};if(k==="sh_url"){sh_s etHref(A,j,B)}k=null}C=w}return A}function sh_getClasses(d){var a=[];var b=d.className;if(b&&b.length>0){var e=b.split(" ");for(var c=0;c<e.length;c++){if(e[c].length>0){a.push(e[c])}}}return a}function sh_addClass(c,a){var d=sh_getClasses(c);for(var b=0;b<d.length;b++){if(a.toLowerCase()===d[b].toLowerCase()){return}}d.push(a);c.className=d.join(" ")}function sh_extractTagsFromNodeList(c,a){var f=c.length;for(var d=0;d<f;d++){var e=c.item(d);switch(e.nodeType){case 1:if(e.nodeName.toLowerCase()==="br"){var b;if(/MSIE/.test(navigator.userAgent)){b="\r"}else{b="\n"}a.text.push(b);a.pos++}else{a.tags.push({node:e.cloneNode(false),pos:a.pos});sh_extractTagsFromNodeList(e.childNodes,a);a.tags.push({pos:a.pos})}break;case 3:case 4:a.text.push(e.data);a.pos+=e.length;break}}}function sh_extractTags(c,b){var a={};a.text=[];a.tags=b;a.pos=0;sh_extractTagsFromNodeList(c.childNodes,a);return a.text.join("")}function sh_mergeTags(d,f){var a=d.length;if(a===0){return f}var c=f.length;if (c===0){return d}var i=[];var e=0;var b=0;while(e<a&&b<c){var h=d[e];var g=f[b];if(h.pos<=g.pos){i.push(h);e++}else{i.push(g);if(f[b+1].pos<=h.pos){b++;i.push(f[b]);b++}else{i.push({pos:h.pos});f[b]={node:g.node.cloneNode(false),pos:h.pos}}}}while(e<a){i.push(d[e]);e++}while(b<c){i.push(f[b]);b++}return i}function sh_insertTags(k,h){var g=document;var l=document.createDocumentFragment();var e=0;var d=k.length;var b=0;var j=h.length;var c=l;while(b<j||e<d){var i;var a;if(e<d){i=k[e];a=i.pos}else{a=j}if(a<=b){if(i.node){var f=i.node;c.appendChild(f);c=f}else{c=c.parentNode}e++}else{c.appendChild(g.createTextNode(h.substring(b,a)));b=a}}return l}function sh_highlightElement(d,g){sh_addClass(d,"sh_sourceCode");var c=[];var e=sh_extractTags(d,c);var f=sh_highlightString(e,g);var b=sh_mergeTags(c,f);var a=sh_insertTags(b,e);while(d.hasChildNodes()){d.removeChild(d.firstChild)}d.appendChild(a)}function sh_getXMLHttpRequest(){if(window.ActiveXObject){return new ActiveXObject("Msxml2 .XMLHTTP")}else{if(window.XMLHttpRequest){return new XMLHttpRequest()}}throw"No XMLHttpRequest implementation available"}function sh_load(language,element,prefix,suffix){if(language in sh_requests){sh_requests[language].push(element);return}sh_requests[language]=[element];var request=sh_getXMLHttpRequest();var url=prefix+"sh_"+language+suffix;request.open("GET",url,true);request.onreadystatechange=function(){if(request.readyState===4){try{if(!request.status||request.status===200){eval(request.responseText);var elements=sh_requests[language];for(var i=0;i<elements.length;i++){sh_highlightElement(elements[i],sh_languages[language])}}else{throw"HTTP error: status "+request.status}}finally{request=null}}};request.send(null)}function sh_highlightDocument(g,k){var b=document.getElementsByTagName("pre");for(var e=0;e<b.length;e++){var f=b.item(e);var a=sh_getClasses(f);for(var c=0;c<a.length;c++){var h=a[c].toLowerCase();if(h==="sh_sourcecode"){continue}if(h.substr(0,3)==="sh_"){va r d=h.substring(3);if(d in sh_languages){sh_highlightElement(f,sh_languages[d])}else{if(typeof(g)==="string"&&typeof(k)==="string"){sh_load(d,f,g,k)}else{throw'Found <pre> element with class="'+h+'", but no such language exists'}}break}}}}; \ No newline at end of file -- 1.7.9.5
On 01/22/2013 07:31 AM, Claudio Bley wrote:
Add minimized CSS and Javascript files of SHJS (http://shjs.sourceforge.net/) required for highlighting C code.
Call sh_highlightDocument() in onload event handler.
Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/newapi.xsl | 2 +- docs/page.xsl | 5 ++++- docs/sh_c.min.js | 1 +
Just one line? Eww. Can we add some whitespace to make it legible?
docs/sh_emacs.min.css | 1 +
Likewise.
docs/sh_main.min.js | 4 ++++ 5 files changed, 11 insertions(+), 2 deletions(-) create mode 100644 docs/sh_c.min.js create mode 100644 docs/sh_emacs.min.css create mode 100644 docs/sh_main.min.js
Are these .js files used only during generation of the html pages (that is, only important for the person creating the rpm), or are they intended to be installed alongside the html files (all end users end up downloading them)? At any rate, this patch is missing patches to docs/Makefile.am, so I can't reproduce the build from a 'make dist' tarball.
+++ b/docs/page.xsl @@ -136,10 +136,13 @@ <head> <link rel="stylesheet" type="text/css" href="{$href_base}main.css"/> <link rel="SHORTCUT ICON" href="{$href_base}32favicon.png"/> + <script type="text/javascript" src="{$href_base}sh_main.min.js"/> + <script type="text/javascript" src="{$href_base}sh_c.min.js"/> + <link rel="stylesheet" type="text/css" href="{$href_base}sh_emacs.min.css"/> <title>libvirt: <xsl:value-of select="html/body/h1"/></title> <meta name="description" content="libvirt, virtualization, virtualization API"/> </head> - <body> + <body onload="sh_highlightDocument();">
Oh, it looks like you are actually installing the .js files alongside the .html, and that end users would be required to run javascript to see the benefits. Have you tested that things still render nicely when scripts are disabled in the user's browser? Can we avoid user-side scripting, and instead get the coloration done at 'make dist' time?
<div id="header"> <div id="headerLogo"/> <div id="headerSearch"> diff --git a/docs/sh_c.min.js b/docs/sh_c.min.js new file mode 100644 index 0000000..fd91118 --- /dev/null +++ b/docs/sh_c.min.js @@ -0,0 +1 @@ +if(!this.sh_languages){this.sh_languages={}}sh_languages.c=[[[/\/\/\//g,"sh_comment",1],[/\/\//g,"sh_comment",7],[/\/\*\*/g,"sh_comment",8],[/\/\*/g,"sh_comment",9],[/(\bstruct)([ \t]+)([A-Za-z0-9_]+)/g,["sh_keyword","sh_normal","sh_classname"],-1],[/^[ \t]*#(?:[ \t]*include)/g,"sh_preproc",10,1],[/^[ \t]*#(?:[ \t]*[A-Za-z0-9_]*)/g,"sh_preproc",-1],[/\b[+-]?(?:(?:0x[A-Fa-f0-9]+)|(?:(?:[\d]*\.)?[\d]+(?:[eE][+-]?[\d]+)?))u?(?:(?:int(?:8|16|32|64))|L)?\b/g,"sh_number",-1],[/"/g,"sh_string",13],[/'/g,"sh_string",14],[/\b(?:__asm|__cdecl|__declspec|__export|__far16|__fastcall|__fortran|__import|__pascal|__rtti|__stdcall|_asm|_cdecl|__except|_export|_far16|_fastcall|__finally|_fortran|_import|_pascal|_stdcall|__thread|__try|asm|auto|break|case|catch|cdecl|const|continue|default|do|else|enum|extern|for|goto|if|pascal|register|return|sizeof|static|struct|switch|typedef|union|volatile|while)\b/g,"sh_keyword",-1],[/\b(?:bool|char|double|float|int|long|short|signed|unsigned|void|wchar_ t)\b/g,"sh_type",-1],[/~|!|%|\^|\*|\(|\)|-|\+|=|\[|\]|\\|:|;|,|\.|\/|\?|&|<|>|\|/g,"sh_symbol",-1],[/\{|\}/g,"sh_cbracket",-1],[/(?:[A-Za-z]|_)[A-Za-z0-9_]*(?=[ \t]*\()/g,"sh_function",-1],[/([A-Za-z](?:[^`~!@#$%&*()_=+{}|;:",<.>\/?'\\[\]\^\-\s]|[_])*)((?:<.*>)?)(\s+(?=[*&]*[A-Za-z][^`~!@#$%&*()_=+{}|;:",<.>\/?'\\[\]\^\-\s]*\s*[`~!@#$%&*()_=+{}|;:",<.>\/?'\\[\]\^\-\[\]]+))/g,["sh_usertype","sh_usertype","sh_normal"],-1]],[[/$/g,null,-2],[/(?:<?)[A-Za-z0-9_\.\/\-_~]+@[A-Za-z0-9_\.\/\-_~]+(?:>?)|(?:<?)[A-Za-z0-9_]+:\/\/[A-Za-z0-9_\.\/\-_~]+(?:>?)/g,"sh_url",-1],[/<\?xml/g,"sh_preproc",2,1],[/<!DOCTYPE/g,"sh_preproc",4,1],[/<!--/g,"sh_comment",5],[/<(?:\/)?[A-Za-z](?:[A-Za-z0-9_:.-]*)(?:\/)?>/g,"sh_keyword",-1],[/<(?:\/)?[A-Za-z](?:[A-Za-z0-9_:.-]*)/g,"sh_keyword",6,1],[/&(?:[A-Za-z0-9]+);/g,"sh_preproc",-1],[/<(?:\/)?[A-Za-z][A-Za-z0-9]*(?:\/)?>/g,"sh_keyword",-1],[/<(?:\/)?[A-Za-z][A-Za-z0-9]*/g,"sh_keyword",6,1],[/@[A-Za-z]+/g,"sh_type",-1],[/(?:TODO|FIXME|BUG)(?:[:]?)/g,"sh _todo",-1]],[[/\?>/g,"sh_preproc",-2],[/([^=" \t>]+)([ \t]*)(=?)/g,["sh_type","sh_normal","sh_symbol"],-1],[/"/g,"sh_string",3]],[[/\\(?:\\|")/g,null,-1],[/"/g,"sh_string",-2]],[[/>/g,"sh_preproc",-2],[/([^=" \t>]+)([ \t]*)(=?)/g,["sh_type","sh_normal","sh_symbol"],-1],[/"/g,"sh_string",3]],[[/-->/g,"sh_comment",-2],[/<!--/g,"sh_comment",5]],[[/(?:\/)?>/g,"sh_keyword",-2],[/([^=" \t>]+)([ \t]*)(=?)/g,["sh_type","sh_normal","sh_symbol"],-1],[/"/g,"sh_string",3]],[[/$/g,null,-2]],[[/\*\//g,"sh_comment",-2],[/(?:<?)[A-Za-z0-9_\.\/\-_~]+@[A-Za-z0-9_\.\/\-_~]+(?:>?)|(?:<?)[A-Za-z0-9_]+:\/\/[A-Za-z0-9_\.\/\-_~]+(?:>?)/g,"sh_url",-1],[/<\?xml/g,"sh_preproc",2,1],[/<!DOCTYPE/g,"sh_preproc",4,1],[/<!--/g,"sh_comment",5],[/<(?:\/)?[A-Za-z](?:[A-Za-z0-9_:.-]*)(?:\/)?>/g,"sh_keyword",-1],[/<(?:\/)?[A-Za-z](?:[A-Za-z0-9_:.-]*)/g,"sh_keyword",6,1],[/&(?:[A-Za-z0-9]+);/g,"sh_preproc",-1],[/<(?:\/)?[A-Za-z][A-Za-z0-9]*(?:\/)?>/g,"sh_keyword",-1],[/<(?:\/)?[A-Za-z][A-Za-z0-9]*/g,"sh_keyword" ,6,1],[/@[A-Za-z]+/g,"sh_type",-1],[/(?:TODO|FIXME|BUG)(?:[:]?)/g,"sh_todo",-1]],[[/\*\//g,"sh_comment",-2],[/(?:<?)[A-Za-z0-9_\.\/\-_~]+@[A-Za-z0-9_\.\/\-_~]+(?:>?)|(?:<?)[A-Za-z0-9_]+:\/\/[A-Za-z0-9_\.\/\-_~]+(?:>?)/g,"sh_url",-1],[/(?:TODO|FIXME|BUG)(?:[:]?)/g,"sh_todo",-1]],[[/$/g,null,-2],[/</g,"sh_string",11],[/"/g,"sh_string",12],[/\/\/\//g,"sh_comment",1],[/\/\//g,"sh_comment",7],[/\/\*\*/g,"sh_comment",8],[/\/\*/g,"sh_comment",9]],[[/$/g,null,-2],[/>/g,"sh_string",-2]],[[/$/g,null,-2],[/\\(?:\\|")/g,null,-1],[/"/g,"sh_string",-2]],[[/"/g,"sh_string",-2],[/\\./g,"sh_specialchar",-1]],[[/'/g,"sh_string",-2],[/\\./g,"sh_specialchar",-1]]]; \ No newline at end of file
This file needs a newline at the end; and whitespace would help immensely. Keeping it at 80 columns is a good goal. This patch probably fails 'make syntax-check'. This file is missing a copyright and license statement; this is particularly important if it is going to be shipped alongside .html and used client-side.
diff --git a/docs/sh_emacs.min.css b/docs/sh_emacs.min.css new file mode 100644 index 0000000..b7aed87 --- /dev/null +++ b/docs/sh_emacs.min.css @@ -0,0 +1 @@ +pre.sh_sourceCode{background-color:#fff;color:#000;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_keyword{color:#9c20ee;font-weight:bold;font-style:normal;}pre.sh_sourceCode .sh_type{color:#208920;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_string{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_regexp{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_specialchar{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_comment{color:#ac2020;font-weight:normal;font-style:italic;}pre.sh_sourceCode .sh_number{color:#000;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_preproc{color:#000;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_function{color:#000;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_url{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_date{color:#9c20ee;font-weight:bold;font-style:normal;}pre.sh_sourceCode . sh_time{color:#9c20ee;font-weight:bold;font-style:normal;}pre.sh_sourceCode .sh_file{color:#9c20ee;font-weight:bold;font-style:normal;}pre.sh_sourceCode .sh_ip{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_name{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_variable{color:#00f;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_oldfile{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_newfile{color:#bd8d8b;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_difflines{color:#9c20ee;font-weight:bold;font-style:normal;}pre.sh_sourceCode .sh_selector{color:#00f;font-weight:normal;font-style:normal;}pre.sh_sourceCode .sh_property{color:#9c20ee;font-weight:bold;font-style:normal;}pre.sh_sourceCode .sh_value{color:#bd8d8b;font-weight:normal;font-style:normal;} \ No newline at end of file
Again, adding whitespace and a trailing newline would help, and it needs a copyright and license. Also, since you are copying from somewhere else, a comment about the original source would be appropriate.
diff --git a/docs/sh_main.min.js b/docs/sh_main.min.js new file mode 100644 index 0000000..31d1ba0 --- /dev/null +++ b/docs/sh_main.min.js @@ -0,0 +1,4 @@ +/* Copyright (C) 2007, 2008 gnombat@users.sourceforge.net */ +/* License: http://shjs.sourceforge.net/doc/gplv3.html */
This has a copyright, but the license is incomplete - the FSF states that it is insufficient to point to a URL when using the GPLv3 (and a non-canonical URL at that); while a URL is helpful, any package shipping a GPLv3 file must also ship the full GPLv3 text as part of the package.
+ +if(!this.sh_languages){this.sh_languages={}}var sh_requests={};function sh_isEmailAddress(a){if(/^mailto:/.test(a)){return false}return a.indexOf("@")!==-1}function sh_setHref(b,c,d){var a=d.substring(b[c-2].pos,b[c-1].pos);if(a.length>=2&&a.charAt(0)==="<"&&a.charAt(a.length-1)===">"){a=a.substr(1,a.length-2)}if(sh_isEmailAddress(a)){a="mailto:"+a}b[c-2].node.href=a}function sh_konquerorExec(b){var a=[""];a.index=b.length;a.input=b;return a}function sh_highlightString(B,o){if(/Konqueror/.test(navigator.userAgent)){if(!o.konquered){for(var F=0;F<o.length;F++){for(var H=0;H<o[F].length;H++){var G=o[F][H][0];if(G.source==="$"){G.exec=sh_konquerorExec}}}o.konquered=true}}var N=document.createElement("a");var q=document.createElement("span");var A=[];var j=0;var n=[];var C=0;var k=null;var x=function(i,a){var p=i.length;if(p===0){return}if(!a){var Q=n.length;if(Q!==0){var r=n[Q-1];if(!r[3]){a=r[1]}}}if(k!==a){if(k){A[j++]={pos:C};if(k==="sh_url"){sh_setHref(A,j,B)}}if(a){var P;i f(a==="sh_url"){P=N.cloneNode(false)}else{P=q.cloneNode(false)}P.className=a;A[j++]={node:P,pos:C}}}C+=p;k=a};var t=/\r\n|\r|\n/g;t.lastIndex=0;var d=B.length;while(C<d){var v=C;var l;var w;var h=t.exec(B);if(h===null){l=d;w=d}else{l=h.index;w=t.lastIndex}var g=B.substring(v,l);var M=[];for(;;){var I=C-v;var D;var y=n.length;if(y===0){D=0}else{D=n[y-1][2]}var O=o[D];var z=O.length;var m=M[D];if(!m){m=M[D]=[]}var E=null;var u=-1;for(var K=0;K<z;K++){var f;if(K<m.length&&(m[K]===null||I<=m[K].index)){f=m[K]}else{var c=O[K][0];c.lastIndex=I;f=c.exec(g);m[K]=f}if(f!==null&&(E===null||f.index<E.index)){E=f;u=K;if(f.index===I){break}}}if(E===null){x(g.substring(I),null);break}else{if(E.index>I){x(g.substring(I,E.index),null)}var e=O[u];var J=e[1];var b;if(J instanceof Array){for(var L=0;L<J.length;L++){b=E[L+1];x(b,J[L])}}else{b=E[0];x(b,J)}switch(e[2]){case -1:break;case -2:n.pop();break;case -3:n.length=0;break;default:n.push(e);break}}}if(k){A[j++]={pos:C};if(k==="sh_url"){sh_s etHref(A,j,B)}k=null}C=w}return A}function sh_getClasses(d){var a=[];var b=d.className;if(b&&b.length>0){var e=b.split(" ");for(var c=0;c<e.length;c++){if(e[c].length>0){a.push(e[c])}}}return a}function sh_addClass(c,a){var d=sh_getClasses(c);for(var b=0;b<d.length;b++){if(a.toLowerCase()===d[b].toLowerCase()){return}}d.push(a);c.className=d.join(" ")}function sh_extractTagsFromNodeList(c,a){var f=c.length;for(var d=0;d<f;d++){var e=c.item(d);switch(e.nodeType){case 1:if(e.nodeName.toLowerCase()==="br"){var b;if(/MSIE/.test(navigator.userAgent)){b="\r"}else{b="\n"}a.text.push(b);a.pos++}else{a.tags.push({node:e.cloneNode(false),pos:a.pos});sh_extractTagsFromNodeList(e.childNodes,a);a.tags.push({pos:a.pos})}break;case 3:case 4:a.text.push(e.data);a.pos+=e.length;break}}}function sh_extractTags(c,b){var a={};a.text=[];a.tags=b;a.pos=0;sh_extractTagsFromNodeList(c.childNodes,a);return a.text.join("")}function sh_mergeTags(d,f){var a=d.length;if(a===0){return f}var c=f.length;if (c===0){return d}var i=[];var e=0;var b=0;while(e<a&&b<c){var h=d[e];var g=f[b];if(h.pos<=g.pos){i.push(h);e++}else{i.push(g);if(f[b+1].pos<=h.pos){b++;i.push(f[b]);b++}else{i.push({pos:h.pos});f[b]={node:g.node.cloneNode(false),pos:h.pos}}}}while(e<a){i.push(d[e]);e++}while(b<c){i.push(f[b]);b++}return i}function sh_insertTags(k,h){var g=document;var l=document.createDocumentFragment();var e=0;var d=k.length;var b=0;var j=h.length;var c=l;while(b<j||e<d){var i;var a;if(e<d){i=k[e];a=i.pos}else{a=j}if(a<=b){if(i.node){var f=i.node;c.appendChild(f);c=f}else{c=c.parentNode}e++}else{c.appendChild(g.createTextNode(h.substring(b,a)));b=a}}return l}function sh_highlightElement(d,g){sh_addClass(d,"sh_sourceCode");var c=[];var e=sh_extractTags(d,c);var f=sh_highlightString(e,g);var b=sh_mergeTags(c,f);var a=sh_insertTags(b,e);while(d.hasChildNodes()){d.removeChild(d.firstChild)}d.appendChild(a)}function sh_getXMLHttpRequest(){if(window.ActiveXObject){return new ActiveXObject("Msxml2 .XMLHTTP")}else{if(window.XMLHttpRequest){return new XMLHttpRequest()}}throw"No XMLHttpRequest implementation available"}function sh_load(language,element,prefix,suffix){if(language in sh_requests){sh_requests[language].push(element);return}sh_requests[language]=[element];var request=sh_getXMLHttpRequest();var url=prefix+"sh_"+language+suffix;request.open("GET",url,true);request.onreadystatechange=function(){if(request.readyState===4){try{if(!request.status||request.status===200){eval(request.responseText);var elements=sh_requests[language];for(var i=0;i<elements.length;i++){sh_highlightElement(elements[i],sh_languages[language])}}else{throw"HTTP error: status "+request.status}}finally{request=null}}};request.send(null)}function sh_highlightDocument(g,k){var b=document.getElementsByTagName("pre");for(var e=0;e<b.length;e++){var f=b.item(e);var a=sh_getClasses(f);for(var c=0;c<a.length;c++){var h=a[c].toLowerCase();if(h==="sh_sourcecode"){continue}if(h.substr(0,3)==="sh_"){va r d=h.substring(3);if(d in sh_languages){sh_highlightElement(f,sh_languages[d])}else{if(typeof(g)==="string"&&typeof(k)==="string"){sh_load(d,f,g,k)}else{throw'Found <pre> element with class="'+h+'", but no such language exists'}}break}}}}; \ No newline at end of file
What does upstream have against whitespace? -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
I missed this reply of yours the first time. Let's see. At Tue, 29 Jan 2013 11:38:41 -0700, Eric Blake wrote:
On 01/22/2013 07:31 AM, Claudio Bley wrote:
Add minimized CSS and Javascript files of SHJS (http://shjs.sourceforge.net/) required for highlighting C code.
Call sh_highlightDocument() in onload event handler.
Signed-off-by: Claudio Bley <cbley@av-test.de> --- docs/newapi.xsl | 2 +- docs/page.xsl | 5 ++++- docs/sh_c.min.js | 1 +
Just one line? Eww. Can we add some whitespace to make it legible?
It's not intended to be legible, and it is not inteded to be edited. It's just output produced by a compiler.
docs/sh_emacs.min.css | 1 +
Likewise.
Likewise.
docs/sh_main.min.js | 4 ++++ 5 files changed, 11 insertions(+), 2 deletions(-) create mode 100644 docs/sh_c.min.js create mode 100644 docs/sh_emacs.min.css create mode 100644 docs/sh_main.min.js
Are these .js files used only during generation of the html pages (that is, only important for the person creating the rpm), or are they intended to be installed alongside the html files (all end users end up downloading them)?
These files are to be installed along with the HTML files.
At any rate, this patch is missing patches to docs/Makefile.am, so I can't reproduce the build from a 'make dist' tarball.
I see. I'll address that.
+++ b/docs/page.xsl @@ -136,10 +136,13 @@ <head> <link rel="stylesheet" type="text/css" href="{$href_base}main.css"/> <link rel="SHORTCUT ICON" href="{$href_base}32favicon.png"/> + <script type="text/javascript" src="{$href_base}sh_main.min.js"/> + <script type="text/javascript" src="{$href_base}sh_c.min.js"/> + <link rel="stylesheet" type="text/css" href="{$href_base}sh_emacs.min.css"/> <title>libvirt: <xsl:value-of select="html/body/h1"/></title> <meta name="description" content="libvirt, virtualization, virtualization API"/> </head> - <body> + <body onload="sh_highlightDocument();">
Oh, it looks like you are actually installing the .js files alongside the .html, and that end users would be required to run javascript to see the benefits. Have you tested that things still render nicely when scripts are disabled in the user's browser?
Yes, it just doesn't get highlighted then.
Can we avoid user-side scripting, and instead get the coloration done at 'make dist' time?
It would be possible, no doubt. But it would further complicate things since we either would have to pre-process the libvirt-api.xml file into some intermediate format, looking for code blocks and feeding them to a code highlighter and afterwards XSL process this file OR post-process the HTML output file extracting code blocks, feeding them into a source code highlighter and splicing them back in. Then we'd require an external highlighting tool as part of the build to begin with.
<div id="header"> <div id="headerLogo"/> <div id="headerSearch"> diff --git a/docs/sh_c.min.js b/docs/sh_c.min.js new file mode 100644 index 0000000..fd91118 --- /dev/null +++ b/docs/sh_c.min.js @@ -0,0 +1 @@ +if(!this.sh_languages) [...] \ No newline at end of file
This file needs a newline at the end; and whitespace would help immensely. Keeping it at 80 columns is a good goal. This patch probably fails 'make syntax-check'.
It did. I've added an exception to the syntax check rules. See the new patch at https://www.redhat.com/archives/libvir-list/2013-January/msg02104.html
This file is missing a copyright and license statement; this is particularly important if it is going to be shipped alongside .html and used client-side.
diff --git a/docs/sh_emacs.min.css b/docs/sh_emacs.min.css new file mode 100644 index 0000000..b7aed87 --- /dev/null +++ b/docs/sh_emacs.min.css @@ -0,0 +1 @@ +pre.sh_sourceCode [...] \ No newline at end of file
Again, adding whitespace and a trailing newline would help, and it needs a copyright and license.
IMO, these files are "object files", as far as the GPL v3 is concerned. ,----[ GPL v3 1. Source Code ] | The "source code" for a work means the preferred form of the work | for making modifications to it. "Object code" means any non-source | form of a work. `----
Also, since you are copying from somewhere else, a comment about the original source would be appropriate.
Fair enough, where should I put it?
diff --git a/docs/sh_main.min.js b/docs/sh_main.min.js new file mode 100644 index 0000000..31d1ba0 --- /dev/null +++ b/docs/sh_main.min.js @@ -0,0 +1,4 @@ +/* Copyright (C) 2007, 2008 gnombat@users.sourceforge.net */ +/* License: http://shjs.sourceforge.net/doc/gplv3.html */
This has a copyright, but the license is incomplete - the FSF states that it is insufficient to point to a URL when using the GPLv3 (and a non-canonical URL at that); while a URL is helpful, any package shipping a GPLv3 file must also ship the full GPLv3 text as part of the package.
OK, I'll add a GPLv3 license file.
+ +if(!this.sh_languag [...] \ No newline at end of file
What does upstream have against whitespace?
It is a compressed version of the original code. Intended to cut down on download time, snappier page loading. 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
On 01/31/2013 02:47 AM, Claudio Bley wrote:
IMO, these files are "object files", as far as the GPL v3 is concerned.
,----[ GPL v3 1. Source Code ] | The "source code" for a work means the preferred form of the work | for making modifications to it. "Object code" means any non-source | form of a work. `----
That sets off alarm bells in my head. Doesn't GPL require that if we distribute binary files, then WE are responsible for shipping the source used to produce those binaries? That is, we can't offload our obligation onto a third-party project - if we are going to ship binary css and js pages, then the libvirt-1.x.x.tar.gz tarball must include the source code that produces those binaries. And if the source code is more legible, and the formula for generating the minimal size binary is simple enough, then libvirt.git should just store the source files and the creation rules, not the binary files.
Also, since you are copying from somewhere else, a comment about the original source would be appropriate.
Fair enough, where should I put it?
Again, if we copy the original source files, rather than a compiled minimal generated version, then the attribution would go as a comment in the copied source file. And if the generated compiled version is not shipped in the tarball, then not having a copyright disclaimer/license in the .js file _might_ be okay. Then again, it might not be: the FSF LibreJS project exists to reject execution of any javascript files that do not contain a clear license. https://www.gnu.org/software/librejs/ https://www.gnu.org/software/librejs/free-your-javascript.html
diff --git a/docs/sh_main.min.js b/docs/sh_main.min.js new file mode 100644 index 0000000..31d1ba0 --- /dev/null +++ b/docs/sh_main.min.js @@ -0,0 +1,4 @@ +/* Copyright (C) 2007, 2008 gnombat@users.sourceforge.net */ +/* License: http://shjs.sourceforge.net/doc/gplv3.html */
This has a copyright, but the license is incomplete - the FSF states that it is insufficient to point to a URL when using the GPLv3 (and a non-canonical URL at that); while a URL is helpful, any package shipping a GPLv3 file must also ship the full GPLv3 text as part of the package.
OK, I'll add a GPLv3 license file.
The more you explain what this commit is trying to add, the more I'm worried that we are getting ourselves into legal hot water. People downloading libvirt.git and seeing GPLv3 COPYING might be worried that we have changed the license of overall libvirt (although our goal is to avoid that, and leave most things at LGPLv2+, and some of the built executables at GPLv2 or GPLv3 depending on libraries that they were linked with). Is source code highlighting on the web page documentation really worth the hassles?
What does upstream have against whitespace?
It is a compressed version of the original code. Intended to cut down on download time, snappier page loading.
I'm not sure whether to believe their claim, though. sh_emacs.min.css already weighs about 1800 bytes, so it already transmits as 2 packets with an MTU of 1500. Upstream is arguing that shaving 30 or so strategic newlines would cause a noticeable speedup? I would have been more impressed if the compression cut a file from 2 TCP packets down to 1. Unless someone else can chime in and defend the wisdom of this patch, I'm inclined to NACK this portion of the series. -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
At Thu, 31 Jan 2013 09:20:28 -0700, Eric Blake wrote:
On 01/31/2013 02:47 AM, Claudio Bley wrote:
IMO, these files are "object files", as far as the GPL v3 is concerned.
,----[ GPL v3 1. Source Code ] | The "source code" for a work means the preferred form of the work | for making modifications to it. "Object code" means any non-source | form of a work. `----
That sets off alarm bells in my head. Doesn't GPL require that if we distribute binary files, then WE are responsible for shipping the source used to produce those binaries?
Responsible, yes. But shipping it, no.
That is, we can't offload our obligation onto a third-party project - if we are going to ship binary css and js pages, then the libvirt-1.x.x.tar.gz tarball must include the source code that produces those binaries.
No, not AFAICS but IANAL. ,----[ GPL v3 1. Source Code ] | The "Corresponding Source" for a work in object code form means all | the source code needed to generate, install, and (for an executable | work) run the object code and to modify the work, including scripts to | control those activities. However, it does not include the work's | System Libraries, or general-purpose tools or *generally* *available* *free* | *programs* which are used unmodified in performing those activities but | which are not part of the work. `---- The compression was done using the YUI Compressor (https://github.com/yui/yuicompressor) which is a free tool and we don't have to ship that. ,----[ GPL v3 6. Conveying Non-Source Forms. ] | d) [...] If the place to | copy the object code is a network server, the *Corresponding Source* | may be on a different server (operated by you or a third party) | that supports equivalent copying facilities, provided you maintain | clear directions next to the object code saying where to find the | Corresponding Source. `---- So, all we'd have to do is adding a file with directions on how to obtain the Corresponding Source. This would have to be distributed with a libvirt tarball. Remains only this paragraph to comply to: ,---- | Regardless of what server hosts the Corresponding Source, you remain | obligated to ensure that it is available for as long as needed to | satisfy these requirements. `---- Probably the easiest way would be to add it to the repo.
And if the source code is more legible, and the formula for generating the minimal size binary is simple enough, then libvirt.git should just store the source files and the creation rules, not the binary files.
No, I'd say it's not that simple. At least not when it comes to ECMAScript.
Also, since you are copying from somewhere else, a comment about the original source would be appropriate.
Fair enough, where should I put it?
Again, if we copy the original source files, rather than a compiled minimal generated version, then the attribution would go as a comment in the copied source file. And if the generated compiled version is not shipped in the tarball, then not having a copyright disclaimer/license in the .js file _might_ be okay. Then again, it might not be: the FSF LibreJS project exists to reject execution of any javascript files that do not contain a clear license.
https://www.gnu.org/software/librejs/ https://www.gnu.org/software/librejs/free-your-javascript.html
I haven't read the whole text, but I found this section in Appendix A: ,---- | As additional permission under GNU GPL version 3 section 7, you may | distribute non-source (e.g., minimized or compacted) forms of code | without the copy of the GNU GPL normally required by section 4, | provided you include this license notice and a URL through which | recipients can access the Corresponding Source. `---- Too bad SHJS doesn't have this added to its source code. Maybe I can get this added...
diff --git a/docs/sh_main.min.js b/docs/sh_main.min.js new file mode 100644 index 0000000..31d1ba0 --- /dev/null +++ b/docs/sh_main.min.js @@ -0,0 +1,4 @@ +/* Copyright (C) 2007, 2008 gnombat@users.sourceforge.net */ +/* License: http://shjs.sourceforge.net/doc/gplv3.html */
This has a copyright, but the license is incomplete - the FSF states that it is insufficient to point to a URL when using the GPLv3 (and a non-canonical URL at that); while a URL is helpful, any package shipping a GPLv3 file must also ship the full GPLv3 text as part of the package.
OK, I'll add a GPLv3 license file.
The more you explain what this commit is trying to add, the more I'm worried that we are getting ourselves into legal hot water. People downloading libvirt.git and seeing GPLv3 COPYING might be worried that we have changed the license of overall libvirt (although our goal is to avoid that, and leave most things at LGPLv2+, and some of the built executables at GPLv2 or GPLv3 depending on libraries that they were linked with).
We could move the SHJS files into docs/shjs with an accompanying LICENSE.txt. I guess that would make it sufficiently clear which files it applies to.
Is source code highlighting on the web page documentation really worth the hassles?
Having written all that above, I'm not entirely sure, anymore. I chose SHJS just because it had a GNU license, who would have known it would cause so much hassle by itself... But besides, arguing with you is always worthwhile. ;)
What does upstream have against whitespace?
It is a compressed version of the original code. Intended to cut down on download time, snappier page loading.
I'm not sure whether to believe their claim, though. sh_emacs.min.css already weighs about 1800 bytes, so it already transmits as 2 packets with an MTU of 1500. Upstream is arguing that shaving 30 or so strategic newlines would cause a noticeable speedup? I would have been more impressed if the compression cut a file from 2 TCP packets down to 1.
Granted, CSS compression tends not to have great potential for compression. Removal of comments, color compression, semicolon reduction and - well - removal of newlines doesn't buy you that much (especially when there are no comments in the source file to begin with). But, in general, it makes a huge difference for ECMAScript files. sh_main.js is reduced to 35% of the original size (15 to 5 KB). In summary, this would be required for inclusion of SHJS for rendering: - compressed files (if we want to use them) - doc/shjs/LICENSE.txt - source code of the compressed files - edit source code of SHJS in order to have it include a copyright - doc/shjs/ABOUT.txt explaining where the files have been obtained 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
On 01/22/2013 07:31 AM, Claudio Bley wrote:
Hi.
The first two patches are aimed at avoiding generation of empty argument description lists, which might happen if a function has no documentation for some argument or its return type.
I'd rather see us fail 'make' if we detect missing documentation, to force developers to add it in, rather than skipping over the generation. I'll review the series to see what we can still push before the 1.0.2 release.
This was happening with virTypedParams* functions (see https://www.redhat.com/archives/libvir-list/2013-January/msg01428.html)
Patch #3 is just a small cleanup, since a table is not the right thing to use and it looks better in some circumstances.
Patch #4 sports processing of code blocks embedded into comments.
Basically, it is similar to markdown syntax, except that you only need to indent your code with 2 spaces.
Patch #5 prepares for the later patches being able to distinguish between different <pre> blocks.
Patch #6 and #7 are pretty much self explanatory, I guess.
Note, that SHJS's license is GPLv3.
As in, we're adding an (optional) dependency on another build tool, but the resulting output doesn't change in licensing? That should be okay, as long as we gracefully succeed even when SHJS is not present. But I guess I'll see when I get to that patch.
Claudio Bley (7): docs: don't write out empty info attributes for function arguments docs: only generate function argument info for args with a description docs: use a div instead of a 3 column table for undisclosed notices docs: process code blocks similar to markdown docs: add class "description" to div's containing descriptions docs: define style of code blocks inside descriptions docs: syntax highlight code blocks using SHJS
docs/apibuild.py | 8 +- docs/libvirt.css | 8 ++ docs/newapi.xsl | 209 +++++++++++++++++++++++++++++-------------------- docs/page.xsl | 5 +- docs/sh_c.min.js | 1 + docs/sh_emacs.min.css | 1 + docs/sh_main.min.js | 4 + 7 files changed, 148 insertions(+), 88 deletions(-) create mode 100644 docs/sh_c.min.js create mode 100644 docs/sh_emacs.min.css create mode 100644 docs/sh_main.min.js
-- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
participants (2)
-
Claudio Bley -
Eric Blake