added autogeneration of a web page for the examples updated the
* doc/site.xsl doc/examples/Makefile.am doc/examples/index.html:
added autogeneration of a web page for the examples
* doc/examples/example1.c doc/examples/.cvsignore
doc/examples/examples.xml doc/examples/index.py: updated the
informations extracted, improved the format and indexing.
Daniel
diff --git a/doc/examples/.cvsignore b/doc/examples/.cvsignore
index 15eb3ab..4c50877 100644
--- a/doc/examples/.cvsignore
+++ b/doc/examples/.cvsignore
@@ -1,3 +1,4 @@
+.memdump
Makefile.in
Makefile
example1
diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am
index 8690a2f..6615fe8 100644
--- a/doc/examples/Makefile.am
+++ b/doc/examples/Makefile.am
@@ -11,7 +11,10 @@
example1_DEPENDENCIES = $(DEPS)
example1_LDADD= @RDL_LIBS@ $(LDADDS)
-all: examples.xml
+all: examples.xml index.html
examples.xml: index.py *.c
-@($(srcdir)/index.py)
+
+index.html: examples.xml examples.xsl
+ -@(xsltproc examples.xsl examples.xml && echo "Rebuilt web page" && xmllint --valid --noout index.html)
diff --git a/doc/examples/example1.c b/doc/examples/example1.c
index f36b4ba..42b2b4a 100644
--- a/doc/examples/example1.c
+++ b/doc/examples/example1.c
@@ -1,8 +1,9 @@
/**
+ * section: Parsing
* purpose: Demonstrate the use of xmlReadFile() to read an XML file
* into a tree and and xmlFreeDoc() to free the resulting tree
* usage: example1 test1.xml
- * author: [email protected]
+ * author: Daniel veillard
* copy: see Copyright for the status of this software.
*/
diff --git a/doc/examples/examples.xml b/doc/examples/examples.xml
index 7831021..d81f93c 100644
--- a/doc/examples/examples.xml
+++ b/doc/examples/examples.xml
@@ -2,16 +2,19 @@
<example filename='example1.c'>
<purpose>Demonstrate the use of xmlReadFile() to read an XML file into a tree and and xmlFreeDoc() to free the resulting tree</purpose>
<usage>example1 test1.xml</usage>
- <author>[email protected]</author>
+ <author>Daniel veillard</author>
<copy>see Copyright for the status of this software. </copy>
- <uses>
+ <section>Parsing</section>
+ <includes>
<include><libxml/tree.h></include>
<include><libxml/parser.h></include>
- <function line='47' file='parser'>xmlCleanupParser</function>
- <macro line='42' file='xmlversion'>LIBXML_TEST_VERSION</macro>
- <function line='28' file='tree'>xmlFreeDoc</function>
- <function line='23' file='parser'>xmlReadFile</function>
- <typedef line='21' file='tree'>xmlDocPtr</typedef>
+ </includes>
+ <uses>
+ <function line='48' file='parser' name='xmlCleanupParser'/>
+ <macro line='43' file='xmlversion' name='LIBXML_TEST_VERSION'/>
+ <function line='29' file='tree' name='xmlFreeDoc'/>
+ <function line='24' file='parser' name='xmlReadFile'/>
+ <typedef line='22' file='tree' name='xmlDocPtr'/>
</uses>
</example>
<symbols>
@@ -31,4 +34,9 @@
<ref filename='example1.c'/>
</symbol>
</symbols>
+ <sections>
+ <section name='Parsing'>
+ <example filename='example1.c'/>
+ </section>
+ </sections>
</examples>
diff --git a/doc/examples/examples.xsl b/doc/examples/examples.xsl
new file mode 100644
index 0000000..8b2453d
--- /dev/null
+++ b/doc/examples/examples.xsl
@@ -0,0 +1,153 @@
+<?xml version="1.0"?>
+<xsl:stylesheet version="1.0"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:exsl="http://exslt.org/common"
+ extension-element-prefixes="exsl"
+ exclude-result-prefixes="exsl">
+
+ <xsl:import href="../site.xsl"/>
+
+ <xsl:variable name="href_base">../</xsl:variable>
+
+ <xsl:variable name="toc">
+ <form action="../search.php"
+ enctype="application/x-www-form-urlencoded" method="get">
+ <input name="query" type="text" size="20" value=""/>
+ <input name="submit" type="submit" value="Search ..."/>
+ </form>
+ <ul><!-- style="margin-left: -1em" -->
+ <li><a href="{$href_base}index.html">Home</a></li>
+ <li><a style="font-weight:bold"
+ href="{$href_base}docs.html">Developer Menu</a></li>
+ <li><a href="{$href_base}guidelines.html">XML Guidelines</a></li>
+ </ul>
+ </xsl:variable>
+
+ <xsl:template match="include">
+ <!-- TODO improve with a link -->
+ <li><xsl:value-of select="."/></li>
+ </xsl:template>
+
+ <xsl:template match="typedef">
+ <xsl:variable name="name" select="@name"/>
+ <xsl:variable name="header" select="concat(@file, '.h')"/>
+ <xsl:variable name="doc" select="concat('../html/libxml-', @file, '.html#', $name)"/>
+ <li> line <xsl:value-of select="@line"/>: Type <a href="{$doc}"><xsl:value-of select="$name"/></a> from <xsl:value-of select="$header"/></li>
+ </xsl:template>
+
+ <xsl:template match="function">
+ <xsl:variable name="name" select="@name"/>
+ <xsl:variable name="header" select="concat(@file, '.h')"/>
+ <xsl:variable name="doc" select="concat('../html/libxml-', @file, '.html#', $name)"/>
+ <li> line <xsl:value-of select="@line"/>: Function <a href="{$doc}"><xsl:value-of select="$name"/></a> from <xsl:value-of select="$header"/></li>
+ </xsl:template>
+
+ <xsl:template match="macro">
+ <xsl:variable name="name" select="@name"/>
+ <xsl:variable name="header" select="concat(@file, '.h')"/>
+ <xsl:variable name="doc" select="concat('../html/libxml-', @file, '.html#', $name)"/>
+ <li> line <xsl:value-of select="@line"/>: Macro <a href="{$doc}"><xsl:value-of select="$name"/></a> from <xsl:value-of select="$header"/></li>
+ </xsl:template>
+
+ <xsl:template match="example">
+ <xsl:variable name="filename" select="string(@filename)"/>
+ <h3><a name="{$filename}" href="{$filename}"><xsl:value-of select="$filename"/></a></h3>
+ <p><xsl:value-of select="purpose"/></p>
+ <p>Includes:</p>
+ <ul>
+ <xsl:for-each select="includes/include">
+ <xsl:apply-templates select='.'/>
+ </xsl:for-each>
+ </ul>
+ <p>Uses:</p>
+ <ul>
+ <xsl:for-each select="uses/*">
+ <xsl:sort select="@line" data-type="number"/>
+ <xsl:apply-templates select='.'/>
+ </xsl:for-each>
+ </ul>
+ <p>Usage:</p>
+ <p><xsl:value-of select="usage"/></p>
+ <p>Author: <xsl:value-of select="author"/></p>
+ </xsl:template>
+
+ <xsl:template match="section">
+ <li><p> <xsl:value-of select="@name"/> :</p>
+ <ul>
+ <xsl:for-each select="example">
+ <xsl:sort select='.'/>
+ <li> <a href="#{@filename}"><xsl:value-of select="@filename"/></a></li>
+ </xsl:for-each>
+ </ul>
+ </li>
+ </xsl:template>
+
+ <xsl:template match="sections">
+ <p> The examples are stored per section depending on the main focus
+ of the example:</p>
+ <ul>
+ <xsl:for-each select="section">
+ <xsl:sort select='.'/>
+ <xsl:apply-templates select='.'/>
+ </xsl:for-each>
+ </ul>
+ </xsl:template>
+
+ <xsl:template match="examples">
+ <xsl:variable name="title">Libxml2 set of examples</xsl:variable>
+ <xsl:document href="index.html" method="xml" encoding="ISO-8859-1"
+ doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"
+ doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+ <html>
+ <head>
+ <xsl:call-template name="style"/>
+ <xsl:element name="title">
+ <xsl:value-of select="$title"/>
+ </xsl:element>
+ </head>
+ <body bgcolor="#8b7765" text="#000000" link="#000000" vlink="#000000">
+ <xsl:call-template name="titlebox">
+ <xsl:with-param name="title" select="$title"/>
+ </xsl:call-template>
+ <table border="0" cellpadding="4" cellspacing="0" width="100%" align="center">
+ <tr>
+ <td bgcolor="#8b7765">
+ <table border="0" cellspacing="0" cellpadding="2" width="100%">
+ <tr>
+ <td valign="top" width="200" bgcolor="#8b7765">
+ <xsl:call-template name="toc"/>
+ </td>
+ <td valign="top" bgcolor="#8b7765">
+ <table border="0" cellspacing="0" cellpadding="1" width="100%">
+ <tr>
+ <td>
+ <table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000">
+ <tr>
+ <td>
+ <table border="0" cellpadding="3" cellspacing="1" width="100%">
+ <tr>
+ <td bgcolor="#fffacd">
+ <xsl:apply-templates select="sections"/>
+ <xsl:apply-templates select="example"/>
+ <p><a href="../bugs.html">Daniel Veillard</a></p>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ </table>
+ </body>
+ </html>
+ </xsl:document>
+ </xsl:template>
+
+</xsl:stylesheet>
diff --git a/doc/examples/index.html b/doc/examples/index.html
new file mode 100644
index 0000000..0673611
--- /dev/null
+++ b/doc/examples/index.html
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><link rel="SHORTCUT ICON" href="/favicon.ico" /><style type="text/css">
+TD {font-family: Verdana,Arial,Helvetica}
+BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
+H1 {font-family: Verdana,Arial,Helvetica}
+H2 {font-family: Verdana,Arial,Helvetica}
+H3 {font-family: Verdana,Arial,Helvetica}
+A:link, A:visited, A:active { text-decoration: underline }
+</style><title>Libxml2 set of examples</title></head><body bgcolor="#8b7765" text="#000000" link="#000000" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="../epatents.png" alt="Action against software patents" /></a></td><td width="180"><a href="http://www.gnome.org/"><img src="../gnome2.png" alt="Gnome2 Logo" /></a><a href="http://www.w3.org/Status"><img src="../w3c.png" alt="W3C Logo" /></a><a href="http://www.redhat.com/"><img src="../redhat.gif" alt="Red Hat Logo" /></a><div align="left"><a href="http://xmlsoft.org/"><img src="../Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo" /></a></div></td><td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center"><h1></h1><h2>Libxml2 set of examples</h2></td></tr></table></td></tr></table></td></tr></table><table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="../search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="../index.html">Home</a></li><li><a style="font-weight:bold" href="../docs.html">Developer Menu</a></li><li><a href="../guidelines.html">XML Guidelines</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://garypennington.net/libxml2/">Solaris binaries</a></li><li><a href="http://www.zveno.com/open_source/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd"><p> The examples are stored per section depending on the main focus
+ of the example:</p><ul><li><p>Parsing :</p><ul><li><a href="#example1.c">example1.c</a></li></ul></li></ul><h3><a name="example1.c" href="example1.c" id="example1.c">example1.c</a></h3><p>Demonstrate the use of xmlReadFile() to read an XML file into a tree and and xmlFreeDoc() to free the resulting tree</p><p>Includes:</p><ul><li><libxml/tree.h></li><li><libxml/parser.h></li></ul><p>Uses:</p><ul><li> line 22: Type <a href="../html/libxml-tree.html#xmlDocPtr">xmlDocPtr</a> from tree.h</li><li> line 24: Function <a href="../html/libxml-parser.html#xmlReadFile">xmlReadFile</a> from parser.h</li><li> line 29: Function <a href="../html/libxml-tree.html#xmlFreeDoc">xmlFreeDoc</a> from tree.h</li><li> line 43: Macro <a href="../html/libxml-xmlversion.html#LIBXML_TEST_VERSION">LIBXML_TEST_VERSION</a> from xmlversion.h</li><li> line 48: Function <a href="../html/libxml-parser.html#xmlCleanupParser">xmlCleanupParser</a> from parser.h</li></ul><p>Usage:</p><p>example1 test1.xml</p><p>Author: Daniel veillard</p><p><a href="../bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>
diff --git a/doc/examples/index.py b/doc/examples/index.py
index fe14bee..ad88276 100755
--- a/doc/examples/index.py
+++ b/doc/examples/index.py
@@ -1,8 +1,9 @@
#!/usr/bin/python -u
#
-# Indexes the examples and build doc and web pages.
+# Indexes the examples and build an XML description
#
import string
+import glob
import sys
try:
import libxml2
@@ -11,6 +12,7 @@
sys.path.append("..")
from apibuild import CParser, escape
+sections = {}
symbols = {}
api_dict = None
api_doc = None
@@ -86,6 +88,7 @@
def parse(filename, output):
global symbols
+ global sections
parser = CParser(filename)
parser.collect_references()
@@ -112,16 +115,26 @@
output.write(" <copy>%s</copy>\n" % copy);
except:
print "Example %s lacks a copyright description" % (filename)
+ try:
+ section = info['section']
+ output.write(" <section>%s</section>\n" % section);
+ if sections.has_key(section):
+ sections[section].append(filename)
+ else:
+ sections[section] = [filename]
+ except:
+ print "Example %s lacks a section description" % (filename)
for topic in info.keys():
if topic != "purpose" and topic != "usage" and \
- topic != "author" and topic != "copy":
+ topic != "author" and topic != "copy" and topic != "section":
str = info[topic]
output.write(" <extra topic='%s'>%s</extra>\n" % str)
-# print idx.functions
- output.write(" <uses>\n")
+ output.write(" <includes>\n")
for include in idx.includes.keys():
if include.find("libxml") != -1:
output.write(" <include>%s</include>\n" % (escape(include)))
+ output.write(" </includes>\n")
+ output.write(" <uses>\n")
for ref in idx.references.keys():
id = idx.references[ref]
name = id.get_name()
@@ -140,12 +153,12 @@
if info != None:
type = info[0]
file = info[1]
- output.write(" <%s line='%d' file='%s'>%s</%s>\n" % (type,
- line, file, name, type))
+ output.write(" <%s line='%d' file='%s' name='%s'/>\n" % (type,
+ line, file, name))
else:
type = id.get_type()
- output.write(" <%s line='%d'>%s</%s>\n" % (type,
- line, name, type))
+ output.write(" <%s line='%d' name='%s'/>\n" % (type,
+ line, name))
output.write(" </uses>\n")
output.write(" </example>\n")
@@ -168,14 +181,32 @@
output.write(" </symbol>\n")
output.write(" </symbols>\n")
+def dump_sections(output):
+ global sections
+
+ output.write(" <sections>\n")
+ keys = sections.keys()
+ keys.sort()
+ for section in keys:
+ output.write(" <section name='%s'>\n" % (section))
+ info = sections[section]
+ i = 0
+ while i < len(info):
+ output.write(" <example filename='%s'/>\n" % (info[i]))
+ i = i + 1
+ output.write(" </section>\n")
+ output.write(" </sections>\n")
+
if __name__ == "__main__":
load_api()
output = open("examples.xml", "w")
output.write("<examples>\n")
- parse("example1.c", output)
+ for file in glob.glob('*.c'):
+ parse(file, output)
dump_symbols(output)
+ dump_sections(output)
output.write("</examples>\n")
output.close()
