started work needed to generate devhelp content, not too hard based on the

* configure.in doc/Makefile.am doc/apibuild.py doc/libxml2-api.xml doc/devhelp/*: started work needed to generate devhelp content, not too hard based on the existing format and extractor. Daniel
2025-03-28 21:33:13 +00:00 · 2005-09-11 22:04:08 +00:00 · 2005-09-11 22:04:08 +00:00 · 99b78502b6
commit 99b78502b6
parent eca59a25f7
12 changed files with 573 additions and 16 deletions
--- a/6
+++ b/6
@ -1,3 +1,9 @@
+Mon Sep 12 00:03:27 CEST 2005 Daniel Veillard <daniel@veillard.com>
+
+	* configure.in doc/Makefile.am doc/apibuild.py doc/libxml2-api.xml
+	  doc/devhelp/*: started work needed to generate devhelp content,
+	  not too hard based on the existing format and extractor.
+
 Fri Sep  9 12:56:19 CEST 2005 Daniel Veillard <daniel@veillard.com>

 	* parser.c: fixes bug #315617 when using push CDATA in some cases.
--- a/configure.in
+++ b/configure.in
@ -1317,6 +1317,6 @@ rm -f COPYING.LIB COPYING
 ln -s Copyright COPYING

 # keep on one line for cygwin c.f. #130896
-AC_OUTPUT(libxml2.spec:libxml.spec.in Makefile include/Makefile include/libxml/Makefile doc/Makefile doc/examples/Makefile example/Makefile python/Makefile python/tests/Makefile xstc/Makefile include/libxml/xmlversion.h xml2-config libxml-2.0.pc libxml-2.0-uninstalled.pc python/setup.py)
+AC_OUTPUT(libxml2.spec:libxml.spec.in Makefile include/Makefile include/libxml/Makefile doc/Makefile doc/examples/Makefile doc/devhelp/Makefile example/Makefile python/Makefile python/tests/Makefile xstc/Makefile include/libxml/xmlversion.h xml2-config libxml-2.0.pc libxml-2.0-uninstalled.pc python/setup.py)

 chmod +x xml2-config python/setup.py
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@ -1,5 +1,5 @@
 ## Process this file with automake to produce Makefile.in
-SUBDIRS=examples
+SUBDIRS=examples devhelp

 # The top-level SGML file.
 DOC_MAIN_XML_FILE=gnome-xml.xml
--- a/doc/apibuild.py
+++ b/doc/apibuild.py
@ -679,9 +679,54 @@ class CParser:

 	return token

-     #
-     # Parse a comment block associate to a macro
-     #
+    #
+    # Parse a comment block associate to a typedef
+    #
+    def parseTypeComment(self, name, quiet = 0):
+        if name[0:2] == '__':
+	    quiet = 1
+
+        args = []
+	desc = ""
+
+        if self.comment == None:
+	    if not quiet:
+		self.warning("Missing comment for type %s" % (name))
+	    return((args, desc))
+        if self.comment[0] != '*':
+	    if not quiet:
+		self.warning("Missing * in type comment for %s" % (name))
+	    return((args, desc))
+	lines = string.split(self.comment, '\n')
+	if lines[0] == '*':
+	    del lines[0]
+	if lines[0] != "* %s:" % (name):
+	    if not quiet:
+		self.warning("Misformatted type comment for %s" % (name))
+		self.warning("  Expecting '* %s:' got '%s'" % (name, lines[0]))
+	    return((args, desc))
+	del lines[0]
+	while len(lines) > 0 and lines[0] == '*':
+	    del lines[0]
+	desc = ""
+	while len(lines) > 0:
+	    l = lines[0]
+	    while len(l) > 0 and l[0] == '*':
+	        l = l[1:]
+	    l = string.strip(l)
+	    desc = desc + " " + l
+	    del lines[0]
+		     
+	desc = string.strip(desc)
+
+	if quiet == 0:
+	    if desc == "":
+	        self.warning("Type comment for %s lack description of the macro" % (name))
+
+	return(desc)
+    #
+    # Parse a comment block associate to a macro
+    #
    def parseMacroComment(self, name, quiet = 0):
        if name[0:2] == '__':
 	    quiet = 1
@ -1025,8 +1070,10 @@ class CParser:
 					"struct", type)
 			base_type = "struct " + name
 	            else:
+			# TODO report missing or misformatted comments
+			info = self.parseTypeComment(name, 1)
 			self.index_add(name, self.filename, not self.is_header,
-		                    "typedef", type)
+		                    "typedef", type, info)
 		token = self.token()
 	    else:
 		self.error("parsing typedef: expecting a name")
@ -1690,6 +1737,8 @@ class docBuilder:

    def serialize_typedef(self, output, name):
        id = self.idx.typedefs[name]
+	if name == 'xmlChar':
+	    print id
 	if id.info[0:7] == 'struct ':
 	    output.write("    <struct name='%s' file='%s' type='%s'" % (
 	             name, self.modulename_file(id.header), id.info))
@ -1713,8 +1762,17 @@ class docBuilder:
 	    else:
 	        output.write("/>\n");
 	else :
-	    output.write("    <typedef name='%s' file='%s' type='%s'/>\n" % (
-	             name, self.modulename_file(id.header), id.info))
+	    output.write("    <typedef name='%s' file='%s' type='%s'" % (
+	                 name, self.modulename_file(id.header), id.info))
+            try:
+		desc = id.extra
+		if desc != None and desc != "":
+		    output.write(">\n      <info>%s</info>\n" % (escape(desc)))
+		    output.write("    </typedef>\n")
+		else:
+		    output.write("/>\n")
+	    except:
+		output.write("/>\n")

    def serialize_variable(self, output, name):
        id = self.idx.variables[name]
--- a/doc/devhelp/Makefile.am
+++ b/doc/devhelp/Makefile.am
@ -0,0 +1,7 @@
+EXTRA_DIST=devhelp.xsl
+
+libxml2.devhelp: devhelp.xsl $(top_srcdir)/doc/libxml2-api.xml
+	-@(if [ -x $(XSLTPROC) ] ; then \
+	  $(XSLTPROC) --nonet -o $(srcdir)/libxml2.devhelp devhelp.xsl $(top_srcdir)/doc/libxml2-api.xml ; fi );
+
+all: libxml2.devhelp
--- a/doc/devhelp/devhelp.xsl
+++ b/doc/devhelp/devhelp.xsl
@ -0,0 +1,473 @@
+<?xml version="1.0"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
+		xmlns="http://www.devhelp.net/book"
+		xmlns:exsl="http://exslt.org/common"
+		xmlns:str="http://exslt.org/strings"
+		extension-element-prefixes="exsl str"
+		exclude-result-prefixes="exsl str">
+  <xsl:output method="xml" encoding="UTF-8" indent="yes"/>
+
+  <!-- Build keys for all symbols -->
+  <xsl:key name="symbols" match="/api/symbols/*" use="@name"/>
+
+  <!-- This is convoluted but needed to force the current document to
+       be the API one and not the result tree from the tokenize() result,
+       because the keys are only defined on the main document -->
+  <xsl:template mode="dumptoken" match='*' xmlns="">
+    <xsl:param name="token"/>
+    <xsl:variable name="ref" select="key('symbols', $token)"/>
+    <xsl:choose>
+      <xsl:when test="$ref">
+        <a href="libxml-{$ref/@file}.html#{$ref/@name}"><xsl:value-of select="$token"/></a>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:value-of select="$token"/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
+  <!-- dumps a string, making cross-reference links -->
+  <xsl:template name="dumptext" xmlns="">
+    <xsl:param name="text"/>
+    <xsl:variable name="ctxt" select='.'/>
+    <!-- <xsl:value-of select="$text"/> -->
+    <xsl:for-each select="str:tokenize($text, ' &#9;')">
+      <xsl:apply-templates select="$ctxt" mode='dumptoken'>
+        <xsl:with-param name="token" select="string(.)"/>
+      </xsl:apply-templates>
+      <xsl:if test="position() != last()">
+        <xsl:text> </xsl:text>
+      </xsl:if>
+    </xsl:for-each>
+  </xsl:template>
+
+  <xsl:template match="/api">
+    <book title="{@name} Reference Manual" link="index.html" author="" name="{@name}">
+      <xsl:apply-templates select="files"/>
+      <xsl:apply-templates select="symbols"/>
+    </book>
+  </xsl:template>
+  <xsl:template match="/api/files">
+    <chapters>
+      <sub name="API" link="general.html">
+        <xsl:apply-templates select="file"/>
+      </sub>
+    </chapters>
+  </xsl:template>
+  <xsl:template match="/api/files/file">
+    <xsl:variable name="module" select="@name"/>
+    <sub name="{@name}" link="libxml2-{@name}.html"/>
+    <xsl:document xmlns="" href="libxml2-{@name}.html" method="xml" indent="yes" encoding="UTF-8">
+      <html>
+        <head>
+	  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+	  <title><xsl:value-of select="concat(@name, ': ', summary)"/></title>
+	  <meta name="generator" content="Libxml2 devhelp stylesheet"/>
+	  <link rel="start" href="index.html" title="libxml2 Reference Manual"/>
+	  <link rel="up" href="general.html" title="API"/>
+	  <link rel="stylesheet" href="style.css" type="text/css"/>
+	  <link rel="chapter" href="general.html" title="API"/>
+        </head>
+	<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+
+          <table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
+	    <tr valign="middle">
+              <td><a accesskey="p" href="ORBit2-orbit2-allocators.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"/></a></td>
+              <td><a accesskey="u" href="general.html"><img src="up.png" width="24" height="24" border="0" alt="Up"/></a></td>
+              <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"/></a></td>
+              <th width="100%" align="center">libxml2 Reference Manual</th>
+            </tr>
+	  </table>
+	  <h2><span class="refentrytitle"><xsl:value-of select="@name"/></span></h2>
+	  <p><xsl:value-of select="@name"/> - <xsl:value-of select="summary"/></p>
+	  <p><xsl:value-of select="description"/></p>
+	  <xsl:if test="deprecated">
+	    <p> WARNING: this module is deprecated !</p>
+	  </xsl:if>
+	  <p>Author(s): <xsl:value-of select="author"/></p>
+	  <div class="refsynopsisdiv">
+	  <h2>Synopsis</h2>
+	  <pre class="synopsis">
+	    <xsl:apply-templates mode="synopsis" select="exports"/>
+	  </pre>
+	  </div>
+	  <div class="refsect1" lang="en">
+	  <h2>Description</h2>
+	  </div>
+	  <div class="refsect1" lang="en">
+	  <h2>Details</h2>
+	  <div class="refsect2" lang="en">
+	    <xsl:apply-templates mode="details" select="/api/symbols/macro[@file=$module]"/>
+	    <xsl:apply-templates mode="details" select="/api/symbols/typedef[@file=$module] | /api/symbols/struct[@file=$module]"/>
+	    <xsl:apply-templates mode="details" select="/api/symbols/function[@module=$module]"/>
+	  </div>
+	  </div>
+	</body>
+      </html>
+    </xsl:document>
+  </xsl:template>
+  <xsl:template match="/api/symbols">
+    <functions>
+      <xsl:apply-templates select="function"/>
+    </functions>
+  </xsl:template>
+  <xsl:template match="/api/symbols/function">
+    <function name="{@name} ()" link="libxml2-{@module}.html#{@name}"/>
+  </xsl:template>
+
+<!--
+
+             The following builds the Synopsis section
+
+-->
+  <xsl:template mode="synopsis" match="function" xmlns="">
+    <xsl:variable name="name" select="string(@name)"/>
+    <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>
+    <xsl:text>&#9;</xsl:text>
+    <a href="#{@name}"><xsl:value-of select="@name"/></a>
+    <xsl:if test="$blen - 40 &lt; -8">
+      <xsl:text>&#9;</xsl:text>
+    </xsl:if>
+    <xsl:if test="$blen - 40 &lt; 0">
+      <xsl:text>&#9;</xsl:text>
+    </xsl:if>
+    <xsl:text>&#9;(</xsl:text>
+    <xsl:if test="not(arg)">
+      <xsl:text>void</xsl:text>
+    </xsl:if>
+    <xsl:for-each select="arg">
+      <xsl:call-template name="dumptext">
+        <xsl:with-param name="text" select="@type"/>
+      </xsl:call-template>
+      <xsl:text> </xsl:text>
+      <xsl:value-of select="@name"/>
+      <xsl:if test="position() != last()">
+        <xsl:text>, </xsl:text><br/>
+	<xsl:if test="$blen - 40 &gt; 8">
+	  <xsl:text>&#9;</xsl:text>
+	</xsl:if>
+	<xsl:if test="$blen - 40 &gt; 0">
+	  <xsl:text>&#9;</xsl:text>
+	</xsl:if>
+	<xsl:text>&#9;&#9;&#9;&#9;&#9; </xsl:text>
+      </xsl:if>
+    </xsl:for-each>
+    <xsl:text>);</xsl:text>
+    <xsl:text>
+</xsl:text>
+  </xsl:template>
+
+  <xsl:template mode="synopsis" match="functype" xmlns="">
+    <xsl:variable name="name" select="string(@name)"/>
+    <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>
+    <xsl:call-template name="dumptext">
+      <xsl:with-param name="text" select="return/@type"/>
+    </xsl:call-template>
+    <xsl:text> </xsl:text>
+    <a href="#{@name}"><xsl:value-of select="@name"/></a>
+    <xsl:if test="$blen - 40 &lt; -8">
+      <xsl:text>&#9;</xsl:text>
+    </xsl:if>
+    <xsl:if test="$blen - 40 &lt; 0">
+      <xsl:text>&#9;</xsl:text>
+    </xsl:if>
+    <xsl:text>&#9;(</xsl:text>
+    <xsl:if test="not(arg)">
+      <xsl:text>void</xsl:text>
+    </xsl:if>
+    <xsl:for-each select="arg">
+      <xsl:call-template name="dumptext">
+        <xsl:with-param name="text" select="@type"/>
+      </xsl:call-template>
+      <xsl:text> </xsl:text>
+      <xsl:value-of select="@name"/>
+      <xsl:if test="position() != last()">
+        <xsl:text>, </xsl:text><br/>
+	<xsl:if test="$blen - 40 &gt; 8">
+	  <xsl:text>&#9;</xsl:text>
+	</xsl:if>
+	<xsl:if test="$blen - 40 &gt; 0">
+	  <xsl:text>&#9;</xsl:text>
+	</xsl:if>
+	<xsl:text>&#9;&#9;&#9;&#9;&#9; </xsl:text>
+      </xsl:if>
+    </xsl:for-each>
+    <xsl:text>);</xsl:text>
+    <xsl:text>
+</xsl:text>
+  </xsl:template>
+
+  <xsl:template mode="synopsis" match="exports[@type='function']" xmlns="">
+    <xsl:variable name="def" select="key('symbols',@symbol)"/>
+    <xsl:apply-templates mode="synopsis" select="$def"/>
+  </xsl:template>
+
+  <xsl:template mode="synopsis" match="exports[@type='typedef']" xmlns="">
+    <xsl:text>typedef </xsl:text>
+    <xsl:call-template name="dumptext">
+      <xsl:with-param name="text" select="string(key('symbols',@symbol)/@type)"/>
+    </xsl:call-template>
+    <xsl:text> </xsl:text>
+    <a href="#{@symbol}"><xsl:value-of select="@symbol"/></a>
+    <xsl:text>;
+</xsl:text>
+  </xsl:template>
+
+  <xsl:template mode="synopsis" match="exports[@type='macro']" xmlns="">
+    <xsl:variable name="def" select="key('symbols',@symbol)"/>
+    <xsl:text>#define </xsl:text>
+    <a href="#{@symbol}"><xsl:value-of select="@symbol"/></a>
+    <xsl:if test="$def/arg">
+      <xsl:text>(</xsl:text>
+      <xsl:for-each select="$def/arg">
+        <xsl:value-of select="@name"/>
+	<xsl:if test="position() != last()">
+	  <xsl:text>, </xsl:text>
+	</xsl:if>
+      </xsl:for-each>
+      <xsl:text>)</xsl:text>
+    </xsl:if>
+    <xsl:text>;
+</xsl:text>
+  </xsl:template>
+  <xsl:template mode="synopsis" match="exports[@type='enum']" xmlns="">
+  </xsl:template>
+  <xsl:template mode="synopsis" match="exports[@type='struct']" xmlns="">
+  </xsl:template>
+
+<!--
+
+             The following builds the Details section
+
+-->
+  <xsl:template mode="details" match="struct" xmlns="">
+    <xsl:variable name="name" select="string(@name)"/>
+    <div class="refsect2" lang="en">
+    <h3><a name="{$name}">Structure </a><xsl:value-of select="$name"/></h3>
+    <pre class="programlisting">
+    <xsl:value-of select="@type"/><xsl:text> {
+</xsl:text>
+    <xsl:if test="not(field)">
+      <xsl:text>The content of this structure is not made public by the API.
+</xsl:text>
+    </xsl:if>
+    <xsl:for-each select="field">
+        <xsl:text>    </xsl:text>
+	<xsl:call-template name="dumptext">
+	  <xsl:with-param name="text" select="@type"/>
+	</xsl:call-template>
+	<xsl:text>&#9;</xsl:text>
+	<xsl:value-of select="@name"/>
+	<xsl:if test="@info != ''">
+	  <xsl:text>&#9;: </xsl:text>
+	  <xsl:call-template name="dumptext">
+	    <xsl:with-param name="text" select="substring(@info, 1, 40)"/>
+	  </xsl:call-template>
+	</xsl:if>
+	<xsl:text>
+</xsl:text>
+    </xsl:for-each>
+    <xsl:text>} </xsl:text>
+    <xsl:value-of select="$name"/>
+    <xsl:text>;
+</xsl:text>
+    </pre>
+    <p>
+    <xsl:call-template name="dumptext">
+      <xsl:with-param name="text" select="info"/>
+    </xsl:call-template>
+    </p><xsl:text>
+</xsl:text>
+    </div><hr/>
+  </xsl:template>
+
+  <xsl:template mode="details" match="typedef[@type != 'enum']" xmlns="">
+    <xsl:variable name="name" select="string(@name)"/>
+    <div class="refsect2" lang="en">
+    <h3><a name="{$name}">Typedef </a><xsl:value-of select="$name"/></h3>
+    <pre class="programlisting">
+    <xsl:call-template name="dumptext">
+      <xsl:with-param name="text" select="string(@type)"/>
+    </xsl:call-template>
+    <xsl:text> </xsl:text>
+    <xsl:value-of select="$name"/>
+    <xsl:text>;
+</xsl:text>
+    </pre>
+    <p>
+    <xsl:call-template name="dumptext">
+      <xsl:with-param name="text" select="info"/>
+    </xsl:call-template>
+    </p><xsl:text>
+</xsl:text>
+    </div><hr/>
+  </xsl:template>
+
+  <xsl:template mode="details" match="typedef[@type = 'enum']" xmlns="">
+    <xsl:variable name="name" select="string(@name)"/>
+    <div class="refsect2" lang="en">
+    <h3><a name="{$name}">Enum </a><xsl:value-of select="$name"/></h3>
+    <pre class="programlisting">
+    <xsl:text>enum </xsl:text>
+    <a href="#{$name}"><xsl:value-of select="$name"/></a>
+    <xsl:text> {
+</xsl:text>
+    <xsl:for-each select="/api/symbols/enum[@type=$name]">
+      <xsl:sort select="@value" data-type="number" order="ascending"/>
+      <xsl:text>    </xsl:text>
+      <a name="{@name}"><xsl:value-of select="@name"/></a>
+      <xsl:if test="@value">
+        <xsl:text> = </xsl:text>
+	<xsl:value-of select="@value"/>
+      </xsl:if>
+      <xsl:if test="@info">
+        <xsl:text> /* </xsl:text>
+	<xsl:value-of select="@info"/>
+        <xsl:text> */</xsl:text>
+      </xsl:if>
+      <xsl:text>
+</xsl:text>
+    </xsl:for-each>
+    <xsl:text>};
+</xsl:text>
+    </pre>
+    <p>
+    <xsl:call-template name="dumptext">
+      <xsl:with-param name="text" select="info"/>
+    </xsl:call-template>
+    </p><xsl:text>
+</xsl:text>
+    </div><hr/>
+  </xsl:template>
+
+  <xsl:template mode="details" match="macro" xmlns="">
+    <xsl:variable name="name" select="string(@name)"/>
+    <div class="refsect2" lang="en">
+    <h3><a name="{$name}">Macro </a><xsl:value-of select="$name"/></h3>
+    <pre class="programlisting">
+    <xsl:text>#define </xsl:text>
+    <a href="#{$name}"><xsl:value-of select="$name"/></a>
+    <xsl:if test="arg">
+      <xsl:text>(</xsl:text>
+      <xsl:for-each select="arg">
+        <xsl:value-of select="@name"/>
+	<xsl:if test="position() != last()">
+	  <xsl:text>, </xsl:text>
+	</xsl:if>
+      </xsl:for-each>
+      <xsl:text>)</xsl:text>
+    </xsl:if>
+    <xsl:text>;
+</xsl:text>
+    </pre>
+    <p>
+    <xsl:call-template name="dumptext">
+      <xsl:with-param name="text" select="info"/>
+    </xsl:call-template>
+    </p>
+    <xsl:if test="arg">
+      <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>
+      </tbody></table></div>
+    </xsl:if>
+    <xsl:text>
+</xsl:text>
+    </div><hr/>
+  </xsl:template>
+
+  <xsl:template mode="details" match="function" xmlns="">
+    <xsl:variable name="name" select="string(@name)"/>
+    <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))"/>
+    <div class="refsect2" lang="en">
+    <h3><a name="{$name}"></a><xsl:value-of select="$name"/> ()</h3>
+    <pre class="programlisting">
+    <xsl:call-template name="dumptext">
+      <xsl:with-param name="text" select="return/@type"/>
+    </xsl:call-template>
+    <xsl:text>&#9;</xsl:text>
+    <xsl:value-of select="@name"/>
+    <xsl:if test="$blen - 40 &lt; -8">
+      <xsl:text>&#9;</xsl:text>
+    </xsl:if>
+    <xsl:if test="$blen - 40 &lt; 0">
+      <xsl:text>&#9;</xsl:text>
+    </xsl:if>
+    <xsl:text>&#9;(</xsl:text>
+    <xsl:if test="not(arg)">
+      <xsl:text>void</xsl:text>
+    </xsl:if>
+    <xsl:for-each select="arg">
+      <xsl:call-template name="dumptext">
+        <xsl:with-param name="text" select="@type"/>
+      </xsl:call-template>
+      <xsl:text> </xsl:text>
+      <xsl:value-of select="@name"/>
+      <xsl:if test="position() != last()">
+        <xsl:text>, </xsl:text><br/>
+	<xsl:if test="$blen - 40 &gt; 8">
+	  <xsl:text>&#9;</xsl:text>
+	</xsl:if>
+	<xsl:if test="$blen - 40 &gt; 0">
+	  <xsl:text>&#9;</xsl:text>
+	</xsl:if>
+	<xsl:text>&#9;&#9;&#9;&#9;&#9; </xsl:text>
+      </xsl:if>
+    </xsl:for-each>
+    <xsl:text>)</xsl:text><br/>
+    <xsl:text>
+</xsl:text>
+    </pre>
+    <p>
+    <xsl:call-template name="dumptext">
+      <xsl:with-param name="text" select="info"/>
+    </xsl:call-template>
+    </p><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>
+	    <xsl:call-template name="dumptext">
+	      <xsl:with-param name="text" select="return/@info"/>
+	    </xsl:call-template>
+	  </td>
+        </tr>
+      </xsl:if>
+      </tbody></table></div>
+    </xsl:if>
+    </div><hr/>
+  </xsl:template>
+</xsl:stylesheet>
+
+
--- a/doc/devhelp/home.png
+++ b/doc/devhelp/home.png
--- a/doc/devhelp/left.png
+++ b/doc/devhelp/left.png
--- a/doc/devhelp/right.png
+++ b/doc/devhelp/right.png
--- a/doc/devhelp/up.png
+++ b/doc/devhelp/up.png
--- a/doc/libxml2-api.xml
+++ b/doc/libxml2-api.xml
@ -5767,9 +5767,13 @@ if necessary or NULL'/>
    <typedef name='xmlAttributeTablePtr' file='valid' type='xmlAttributeTable *'/>
    <typedef name='xmlAttributeType' file='tree' type='enum'/>
    <struct name='xmlAutomata' file='xmlautomata' type='struct _xmlAutomata'/>
-    <typedef name='xmlAutomataPtr' file='xmlautomata' type='xmlAutomata *'/>
+    <typedef name='xmlAutomataPtr' file='xmlautomata' type='xmlAutomata *'>
+      <info>A libxml automata description, It can be compiled into a regexp</info>
+    </typedef>
    <struct name='xmlAutomataState' file='xmlautomata' type='struct _xmlAutomataState'/>
-    <typedef name='xmlAutomataStatePtr' file='xmlautomata' type='xmlAutomataState *'/>
+    <typedef name='xmlAutomataStatePtr' file='xmlautomata' type='xmlAutomataState *'>
+      <info>A state int the automata description,</info>
+    </typedef>
    <struct name='xmlBuffer' file='tree' type='struct _xmlBuffer'>
      <field name='content' type='xmlChar *' info=' The buffer content UTF8'/>
      <field name='use' type='unsigned int' info=' The buffer size used'/>
@ -5799,7 +5803,9 @@ if necessary or NULL'/>
      <field name='high' type='unsigned short' info=''/>
    </struct>
    <typedef name='xmlChSRangePtr' file='chvalid' type='xmlChSRange *'/>
-    <typedef name='xmlChar' file='xmlstring' type='unsigned char'/>
+    <typedef name='xmlChar' file='xmlstring' type='unsigned char'>
+      <info>This is a basic byte in an UTF-8 encoded string. It&apos;s unsigned allowing to pinpoint case where char * are assigned to xmlChar * (possibly making serialization back impossible).</info>
+    </typedef>
    <typedef name='xmlCharEncoding' file='encoding' type='enum'/>
    <struct name='xmlCharEncodingHandler' file='encoding' type='struct _xmlCharEncodingHandler'>
      <field name='name' type='char *' info=''/>
@ -6007,7 +6013,9 @@ actually an xmlCharEncoding'/>
    <typedef name='xmlLocationSetPtr' file='xpointer' type='xmlLocationSet *'/>
    <struct name='xmlModule' file='xmlmodule' type='struct _xmlModule'/>
    <typedef name='xmlModuleOption' file='xmlmodule' type='enum'/>
-    <typedef name='xmlModulePtr' file='xmlmodule' type='xmlModule *'/>
+    <typedef name='xmlModulePtr' file='xmlmodule' type='xmlModule *'>
+      <info>A handle to a dynamically loaded module</info>
+    </typedef>
    <struct name='xmlMutex' file='threads' type='struct _xmlMutex'/>
    <typedef name='xmlMutexPtr' file='threads' type='xmlMutex *'/>
    <struct name='xmlNode' file='tree' type='struct _xmlNode'>
@ -6222,9 +6230,13 @@ actually an xmlCharEncoding'/>
    <struct name='xmlRefTable' file='valid' type='struct _xmlHashTable'/>
    <typedef name='xmlRefTablePtr' file='valid' type='xmlRefTable *'/>
    <struct name='xmlRegExecCtxt' file='xmlregexp' type='struct _xmlRegExecCtxt'/>
-    <typedef name='xmlRegExecCtxtPtr' file='xmlregexp' type='xmlRegExecCtxt *'/>
+    <typedef name='xmlRegExecCtxtPtr' file='xmlregexp' type='xmlRegExecCtxt *'>
+      <info>A libxml progressive regular expression evaluation context</info>
+    </typedef>
    <struct name='xmlRegexp' file='xmlregexp' type='struct _xmlRegexp'/>
-    <typedef name='xmlRegexpPtr' file='xmlregexp' type='xmlRegexp *'/>
+    <typedef name='xmlRegexpPtr' file='xmlregexp' type='xmlRegexp *'>
+      <info>A libxml regular expression, they can actually be far more complex thank the POSIX regex expressions.</info>
+    </typedef>
    <struct name='xmlRelaxNG' file='relaxng' type='struct _xmlRelaxNG'/>
    <struct name='xmlRelaxNGParserCtxt' file='relaxng' type='struct _xmlRelaxNGParserCtxt'/>
    <typedef name='xmlRelaxNGParserCtxtPtr' file='relaxng' type='xmlRelaxNGParserCtxt *'/>
@ -6529,7 +6541,9 @@ actually an xmlCharEncoding'/>
    <struct name='xmlTextReader' file='xmlreader' type='struct _xmlTextReader'/>
    <typedef name='xmlTextReaderLocatorPtr' file='xmlreader' type='void *'/>
    <typedef name='xmlTextReaderMode' file='xmlreader' type='enum'/>
-    <typedef name='xmlTextReaderPtr' file='xmlreader' type='xmlTextReader *'/>
+    <typedef name='xmlTextReaderPtr' file='xmlreader' type='xmlTextReader *'>
+      <info>Pointer to an xmlReader context.</info>
+    </typedef>
    <struct name='xmlTextWriter' file='xmlwriter' type='struct _xmlTextWriter'/>
    <typedef name='xmlTextWriterPtr' file='xmlwriter' type='xmlTextWriter *'/>
    <struct name='xmlURI' file='uri' type='struct _xmlURI'>
--- a/include/libxml/xmlstring.h
+++ b/include/libxml/xmlstring.h
@ -25,7 +25,6 @@ extern "C" {
 * It's unsigned allowing to pinpoint case where char * are assigned
 * to xmlChar * (possibly making serialization back impossible).
 */
-
 typedef unsigned char xmlChar;

 /**