9:27 a.m.
While working with the documentation, I found some issues I'd like to
improve.
Philipp Hahn (3):
Align table cells on top
Improve tokenizing of linkable terms
Fix references to self.warning()
docs/apibuild.py | 48 ++++++++++++++++++++++++++++++------------------
docs/libvirt.css | 4 ++++
docs/newapi.xsl | 9 ++++++---
3 files changed, 40 insertions(+), 21 deletions(-)
7:40 a.m.
New subject: [libvirt] [PATCH 1/3] Align table cells on top
When the description of an entry is too long and needs multiple lines,
all other table cells of the same row are currently vertically aligned
on center. Without row borders or different background colors for
alternating rows this is hard to read.
Change the style-sheet to align the table cells of a row on top.
Signed-off-by: Philipp Hahn <hahn(a)univention.de>
---
docs/libvirt.css | 4 ++++
1 files changed, 4 insertions(+), 0 deletions(-)
---
See
<http://libvirt.org/html/libvirt-libvirt.html#virDomainMemoryStatTags>
for example.
diff --git a/docs/libvirt.css b/docs/libvirt.css
index 049e332..6e54b73 100644
--- a/docs/libvirt.css
+++ b/docs/libvirt.css
@@ -199,6 +199,10 @@ div.api table {
whitespace: pre;
}
+div.api table td, div.variablelist table td {
+ vertical-align: top;
+}
+
h1 a, h2 a, h3 a, h4 a, h5 a {
color: inherit;
--
1.7.1
2:45 p.m.
New subject: [libvirt] [PATCH 1/3] Align table cells on top
On 08/11/2011 06:40 AM, Philipp Hahn wrote:
When the description of an entry is too long and needs multiple
lines,
all other table cells of the same row are currently vertically aligned
on center. Without row borders or different background colors for
alternating rows this is hard to read.
Change the style-sheet to align the table cells of a row on top.
Seems reasonable.
Signed-off-by: Philipp Hahn<hahn(a)univention.de>
---
docs/libvirt.css | 4 ++++
1 files changed, 4 insertions(+), 0 deletions(-)
---
See
<http://libvirt.org/html/libvirt-libvirt.html#virDomainMemoryStatTags>
for example.
That was the clincher for me :)
ACK and pushed.
--
Eric Blake eblake(a)redhat.com +1-801-349-2682
Libvirt virtualization library http://libvirt.org
7:44 a.m.
New subject: [libvirt] [PATCH 2/3] Improve tokenizing of linkable terms
Currently only tabs and blanks are used for tokenizing the description,
which breaks when a term is at the end of a line or has () appended to
it.
1. Use also other white space characters such as new-lines and carriage
return for splitting.
2. Remove some common non-word characters from the token before lookup.
Signed-off-by: Philipp Hahn <hahn(a)univention.de>
---
docs/newapi.xsl | 9 ++++++---
1 files changed, 6 insertions(+), 3 deletions(-)
diff --git a/docs/newapi.xsl b/docs/newapi.xsl
index 445a48c..6e1c646 100644
--- a/docs/newapi.xsl
+++ b/docs/newapi.xsl
@@ -54,10 +54,13 @@
because the keys are only defined on the main document -->
<xsl:template mode="dumptoken" match='*'>
<xsl:param name="token"/>
- <xsl:variable name="ref" select="key('symbols',
$token)"/>
+ <xsl:variable name="stem" select="translate($token,
'(),.:;@', '')"/>
+ <xsl:variable name="ref" select="key('symbols',
$stem)"/>
<xsl:choose>
<xsl:when test="$ref">
- <a href="libvirt-{$ref/@file}.html#{$ref/@name}"><xsl:value-of
select="$token"/></a>
+ <xsl:value-of select="substring-before($token, $stem)"/>
+ <a href="libvirt-{$ref/@file}.html#{$ref/@name}"><xsl:value-of
select="$stem"/></a>
+ <xsl:value-of select="substring-after($token, $stem)"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$token"/>
@@ -70,7 +73,7 @@
<xsl:param name="text"/>
<xsl:variable name="ctxt" select='.'/>
<!-- <xsl:value-of select="$text"/> -->
- <xsl:for-each select="str:tokenize($text, ' 	')">
+ <xsl:for-each select="str:tokenize($text, '
	 ')">
<xsl:apply-templates select="$ctxt" mode='dumptoken'>
<xsl:with-param name="token" select="string(.)"/>
</xsl:apply-templates>
--
1.7.1
2:45 p.m.
New subject: [libvirt] [PATCH 2/3] Improve tokenizing of linkable terms
On 08/11/2011 06:44 AM, Philipp Hahn wrote:
Currently only tabs and blanks are used for tokenizing the
description,
which breaks when a term is at the end of a line or has () appended to
it.
1. Use also other white space characters such as new-lines and carriage
return for splitting.
2. Remove some common non-word characters from the token before lookup.
Signed-off-by: Philipp Hahn<hahn(a)univention.de>
---
docs/newapi.xsl | 9 ++++++---
1 files changed, 6 insertions(+), 3 deletions(-)
I am not fluent in reading xsl files. How would I go about testing if
the output is more visually appealing? I can ack on the basis of
comparison on before vs. after appearance, but only if I figure out
which files are affected to compare a view in my browser of the
generated html.
My gut feel is that this is probably right, but unless someone more
familiar with the file format speaks up, or unless I can test the
results, I won't push this just yet.
--
Eric Blake eblake(a)redhat.com +1-801-349-2682
Libvirt virtualization library http://libvirt.org
1:03 a.m.
New subject: [libvirt] [PATCH 2/3] Improve tokenizing of linkable terms
Am Donnerstag 11 August 2011 21:45:18 schrieb Eric Blake:
On 08/11/2011 06:44 AM, Philipp Hahn wrote:
> Currently only tabs and blanks are used for tokenizing the description,
> which breaks when a term is at the end of a line or has () appended to
> it.
> 1. Use also other white space characters such as new-lines and carriage
> return for splitting.
> 2. Remove some common non-word characters from the token before lookup.
>
> Signed-off-by: Philipp Hahn<hahn(a)univention.de>
> ---
> docs/newapi.xsl | 9 ++++++---
> 1 files changed, 6 insertions(+), 3 deletions(-)
I am not fluent in reading xsl files. How would I go about testing if
the output is more visually appealing? I can ack on the basis of
comparison on before vs. after appearance, but only if I figure out
which files are affected to compare a view in my browser of the
generated html.
Go to <http://libvirt.org/html/libvirt-libvirt.html> at search for "()" or
strings starting with "VIR_": You'll notice lots of them, which aren't
links,
but many others are. This hapens because only space characters were used to
separate word, which then looked for "virDomainGetVcpus()" instead of
just "virDomainGetVcpus". The other case was the keywords were at the end on
line, where the "\n" wasn't used for word breaking, so the search went for
"VIR_DOMAIN_MEMORY_HARD_LIMIT\nsomething" instead of
just "VIR_DOMAIN_MEMORY_HARD_LIMIT".
It's still not perfect, because only "_function_()" is clickable and
not "function()", but at least it is. It would have been easier with RegExps
<http://www.exslt.org/regexp/> for stemming, but that isn't supported by
libxslt.
Sincerely
Philipp Hahn
--
Philipp Hahn Open Source Software Engineer hahn(a)univention.de
Univention GmbH Linux for Your Business fon: +49 421 22 232- 0
Mary-Somerville-Str.1 D-28359 Bremen fax: +49 421 22 232-99
http://www.univention.de/
10:18 p.m.
New subject: [libvirt] [PATCH 2/3] Improve tokenizing of linkable terms
On Thu, Aug 11, 2011 at 02:44:00PM +0200, Philipp Hahn wrote:
Currently only tabs and blanks are used for tokenizing the
description,
which breaks when a term is at the end of a line or has () appended to
it.
1. Use also other white space characters such as new-lines and carriage
return for splitting.
2. Remove some common non-word characters from the token before lookup.
Signed-off-by: Philipp Hahn <hahn(a)univention.de>
---
docs/newapi.xsl | 9 ++++++---
1 files changed, 6 insertions(+), 3 deletions(-)
diff --git a/docs/newapi.xsl b/docs/newapi.xsl
index 445a48c..6e1c646 100644
--- a/docs/newapi.xsl
+++ b/docs/newapi.xsl
@@ -54,10 +54,13 @@
because the keys are only defined on the main document -->
<xsl:template mode="dumptoken" match='*'>
<xsl:param name="token"/>
- <xsl:variable name="ref" select="key('symbols',
$token)"/>
+ <xsl:variable name="stem" select="translate($token,
'(),.:;@', '')"/>
+ <xsl:variable name="ref" select="key('symbols',
$stem)"/>
<xsl:choose>
<xsl:when test="$ref">
- <a
href="libvirt-{$ref/@file}.html#{$ref/@name}"><xsl:value-of
select="$token"/></a>
+ <xsl:value-of select="substring-before($token, $stem)"/>
+ <a
href="libvirt-{$ref/@file}.html#{$ref/@name}"><xsl:value-of
select="$stem"/></a>
+ <xsl:value-of select="substring-after($token, $stem)"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$token"/>
@@ -70,7 +73,7 @@
<xsl:param name="text"/>
<xsl:variable name="ctxt" select='.'/>
<!-- <xsl:value-of select="$text"/> -->
- <xsl:for-each select="str:tokenize($text, ' 	')">
+ <xsl:for-each select="str:tokenize($text, '
	 ')">
<xsl:apply-templates select="$ctxt" mode='dumptoken'>
<xsl:with-param name="token" select="string(.)"/>
</xsl:apply-templates>
ACK, that's good, thanks for digging and fixing this :-)
Daniel
--
Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/
daniel(a)veillard.com | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library http://libvirt.org/
8:37 a.m.
New subject: [libvirt] [PATCH 2/3] Improve tokenizing of linkable terms
On 08/11/2011 09:18 PM, Daniel Veillard wrote:
On Thu, Aug 11, 2011 at 02:44:00PM +0200, Philipp Hahn wrote:
> Currently only tabs and blanks are used for tokenizing the description,
> which breaks when a term is at the end of a line or has () appended to
> it.
> 1. Use also other white space characters such as new-lines and carriage
> return for splitting.
> 2. Remove some common non-word characters from the token before lookup.
>
ACK, that's good, thanks for digging and fixing this :-)
Pushed.
--
Eric Blake eblake(a)redhat.com +1-801-349-2682
Libvirt virtualization library http://libvirt.org
7:50 a.m.
New subject: [libvirt] [PATCH 3/3] Fix references to self.warning()
Only the class CParser declares a method warning(), but the other
classes still try to call their self.warning() method, which fails.
Move the warning() functions to its own base classe and inherit from
that in all other classes.
Signed-off-by: Philipp Hahn <hahn(a)univention.de>
---
docs/apibuild.py | 48 ++++++++++++++++++++++++++++++------------------
1 files changed, 30 insertions(+), 18 deletions(-)
diff --git a/docs/apibuild.py b/docs/apibuild.py
index 53b3421..d335ab1 100755
--- a/docs/apibuild.py
+++ b/docs/apibuild.py
@@ -173,8 +173,30 @@ class identifier:
if conditionals != None:
self.set_conditionals(conditionals)
-class index:
+class base(object):
+ """Base class providing common methods for printing
messages."""
+ def __init__(self):
+ self.no_error = False
+
+ def warning(self, msg):
+ """Print warning message."""
+ global warnings
+ warnings = warnings + 1
+ if self.no_error:
+ return
+ print msg
+
+ def stop_error(self):
+ """Stop printing error messages."""
+ self.no_error = True
+
+ def start_error(self):
+ """Re-start printing error messages."""
+ self.no_error = False
+
+class index(base):
def __init__(self, name = "noname"):
+ base.__init__(self)
self.name = name
self.identifiers = {}
self.functions = {}
@@ -366,10 +388,11 @@ class index:
self.analyze_dict("typedefs", self.typedefs)
self.analyze_dict("macros", self.macros)
-class CLexer:
+class CLexer(base):
"""A lexer for the C language, tokenize the input by reading and
analyzing it line by line"""
def __init__(self, input):
+ base.__init__(self)
self.input = input
self.tokens = []
self.line = ""
@@ -572,9 +595,10 @@ class CLexer:
self.last = tok
return tok
-class CParser:
+class CParser(base):
"""The C module parser"""
def __init__(self, filename, idx = None):
+ base.__init__(self)
self.filename = filename
if len(filename) > 2 and filename[-2:] == '.h':
self.is_header = 1
@@ -590,19 +614,12 @@ class CParser:
self.last_comment = ""
self.comment = None
self.collect_ref = 0
- self.no_error = 0
self.conditionals = []
self.defines = []
def collect_references(self):
self.collect_ref = 1
- def stop_error(self):
- self.no_error = 1
-
- def start_error(self):
- self.no_error = 0
-
def lineno(self):
return self.lexer.getlineno()
@@ -623,12 +640,6 @@ class CParser:
self.index.add_ref(name, None, module, static, type, self.lineno(),
info, extra, self.conditionals)
- def warning(self, msg):
- global warnings
- warnings = warnings + 1
- if self.no_error:
- return
- print msg
def error(self, msg, token=-1):
if self.no_error:
@@ -1825,9 +1836,10 @@ class CParser:
return self.index
-class docBuilder:
+class docBuilder(base):
"""A documentation builder"""
def __init__(self, name, path='.', directories=['.'], includes=[]):
+ base.__init__(self)
self.name = name
self.path = path
self.directories = directories
@@ -2363,7 +2375,7 @@ def rebuild():
["src", "src/util",
"include/libvirt"],
[])
else:
- self.warning("rebuild() failed, unable to guess the module")
+ base().warning("rebuild() failed, unable to guess the module")
return None
builder.scan()
builder.analyze()
--
1.7.1
2:50 p.m.
New subject: [libvirt] [PATCH 3/3] Fix references to self.warning()
On 08/11/2011 06:50 AM, Philipp Hahn wrote:
Only the class CParser declares a method warning(), but the other
classes still try to call their self.warning() method, which fails.
Move the warning() functions to its own base classe and inherit from
s/classe/class/
that in all other classes.
Signed-off-by: Philipp Hahn<hahn(a)univention.de>
---
docs/apibuild.py | 48 ++++++++++++++++++++++++++++++------------------
1 files changed, 30 insertions(+), 18 deletions(-)
First I claim ignorance with xslt, now I'm claiming ignorance with Python :)
However, this one looks easier to review by comparison to the rest of
the file, as well as by compilation smoke-tests, which promptly tripped
up 'make syntax-check':
error_message_period
docs/apibuild.py-190- """Stop printing error
messages."""
docs/apibuild.py-194- """Re-start printing error
messages."""
maint.mk: found error message ending in period
But those don't seem to be error messages, so much as self-documentation
strings. I don't know if the python needs to be tweaked, or if the real
problem is that cfg.mk should be exempting .py files from that
particular syntax check.
--
Eric Blake eblake(a)redhat.com +1-801-349-2682
Libvirt virtualization library http://libvirt.org
4851
days inactive
4852
days old
9 comments
3 participants
participants (3)
-
Daniel Veillard -
Eric Blake -
Philipp Hahn