- added Docbook Tool to the sources

- added SConstruct for the MAN pages

2 files changed, 135 insertions, 105 deletions

diff --git a/bin/SConsDoc.py b/bin/SConsDoc.py
index e5d28cd4..c6d4785f 100644
--- a/bin/SConsDoc.py
+++ b/bin/SConsDoc.py
@@ -126,43 +126,69 @@ try:
 except:
     has_lxml = False
 
+try:
+  from lxml import etree
+except ImportError:
+  try:
+    # Python 2.5
+    import xml.etree.cElementTree as etree
+  except ImportError:
+    try:
+      # Python 2.5
+      import xml.etree.ElementTree as etree
+    except ImportError:
+      try:
+        # normal cElementTree install
+        import cElementTree as etree
+      except ImportError:
+        try:
+          # normal ElementTree install
+          import elementtree.ElementTree as etree
+        except ImportError:
+          print("Failed to import ElementTree from any known place")
+          sys.exit(1)
 
 re_entity = re.compile("\&([^;]+);")
-
-entity_header = """<!DOCTYPE sconsdoc [
-<!ENTITY % scons SYSTEM 'scons.mod'>
-%scons;
-<!ENTITY % builders-mod SYSTEM 'builders.mod'>
-%builders-mod;
-<!ENTITY % functions-mod SYSTEM 'functions.mod'>
-%functions-mod;
-<!ENTITY % tools-mod SYSTEM 'tools.mod'>
-%tools-mod;
-<!ENTITY % variables-mod SYSTEM 'variables.mod'>
-%variables-mod;
-]>"""
+re_entity_header = re.compile("<!DOCTYPE\s+sconsdoc\s+[^\]]+\]>")
 
 # Namespace for the SCons Docbook XSD
 dbxsd="http://www.scons.org/dbxsd/v1.0"
+# Namespace for schema instances
+xsi = "http://www.w3.org/2001/XMLSchema-instance"
 
-xml_header = """<?xml version="1.0" encoding="UTF-8"?>
-<!--
+# Header comment with copyright
+copyright_comment = """
 __COPYRIGHT__
 
 This file is processed by the bin/SConsDoc.py module.
 See its __doc__ string for a discussion of the format.
--->
+"""
+# Header comment for automatically generated files
+generated_comment = """
+    THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
+  """
+
+def xml_tree(root, comment=generated_comment):
+    """ Return a XML file tree with the correct namespaces set,
+        the element root as top entry and the given header comment.
+    """
+    NSMAP = {None: dbxsd,
+             'xsi' : xsi}
+
+    t = etree.Element(root,
+                      nsmap = NSMAP,
+                      attrib = {"{"+xsi+"}schemaLocation" : "%s scons.xsd" % dbxsd})
 
-%s
+    c = etree.Comment(comment)
+    t.append(c)
 
-<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
-          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-          xsi:schemaLocation="%s scons.xsd">
-""" % (entity_header, dbxsd)
+    # print etree.tostring(t, xml_declaration=True, encoding="UTF-8", pretty_print=True)
+
+    return t
 
 def remove_entities(content):
     # Cut out entity inclusions
-    content = content.replace(entity_header, "")
+    content = re_entity_header.sub("", content, re.M)
     # Cut out entities themselves
     content = re_entity.sub(lambda match: match.group(1), content)
     
@@ -176,7 +202,6 @@ def validate_xml(fpath, xmlschema_context):
         # to conflicts when installed together with libxml2.
         if has_lxml:
             # Use lxml
-            from lxml import etree
             xmlschema = etree.XMLSchema(xmlschema_context)
             doc = etree.parse(fpath)
             try:
@@ -219,7 +244,6 @@ def prettyprint_xml(fpath):
         # to conflicts when installed together with libxml2.
         if has_lxml:
             # Use lxml
-            from lxml import etree
             fin = open(fpath,'r')
             tree = etree.parse(fin)
             pretty_content = etree.tostring(tree, pretty_print=True)
@@ -255,7 +279,6 @@ def validate_all_xml(dpath='src', xsdfile=default_xsd):
         # to conflicts when installed together with libxml2.
         if has_lxml:
             # Use lxml
-            from lxml import etree
             xmlschema_context = etree.parse(xsdfile)
     else:
         # Use libxml2 and prepare the schema validation context
@@ -291,28 +314,6 @@ def validate_all_xml(dpath='src', xsdfile=default_xsd):
     
     return True
 
-try:
-  from lxml import etree
-except ImportError:
-  try:
-    # Python 2.5
-    import xml.etree.cElementTree as etree
-  except ImportError:
-    try:
-      # Python 2.5
-      import xml.etree.ElementTree as etree
-    except ImportError:
-      try:
-        # normal cElementTree install
-        import cElementTree as etree
-      except ImportError:
-        try:
-          # normal ElementTree install
-          import elementtree.ElementTree as etree
-        except ImportError:
-          print("Failed to import ElementTree from any known place")
-          sys.exit(1)
-
 class Item(object):
     def __init__(self, name):
         self.name = name
@@ -335,7 +336,6 @@ class Builder(Item):
 class Function(Item):
     def __init__(self, name):
         super(Function, self).__init__(name)
-        self.arguments = ['()']
 
 class Tool(Item):
     def __init__(self, name):
@@ -417,8 +417,17 @@ class SConsDocHandler(object):
         uses, sets = self.parseUsesSets(domelem)
         instance.uses.extend(uses)
         instance.sets.extend(sets)
-        # Parse summary and function blobs
-        
+        # Parse summary and function arguments
+        for s in domelem.iterchildren(tag="{%s}summary" % dbxsd):
+            if not hasattr(instance, 'summary'):
+                instance.summary = []
+            for c in s:
+                instance.summary.append(c)
+        for a in domelem.iterchildren(tag="{%s}arguments" % dbxsd):
+            if not hasattr(instance, 'arguments'):
+                instance.arguments = []
+            instance.arguments.append(a)
+
     def parseDomtree(self, root):    
         # Process Builders
         for b in root.iterchildren(tag="{%s}builder" % dbxsd):
diff --git a/bin/scons-proc.py b/bin/scons-proc.py
index 3d460ab2..e17a3393 100644
--- a/bin/scons-proc.py
+++ b/bin/scons-proc.py
@@ -14,6 +14,7 @@ import os
 import re
 import string
 import sys
+import copy
 try:
     from io import StringIO     # usable as of 2.6; takes unicode only
 except ImportError:
@@ -22,6 +23,28 @@ except ImportError:
 
 import SConsDoc
 
+try:
+  from lxml import etree
+except ImportError:
+  try:
+    # Python 2.5
+    import xml.etree.cElementTree as etree
+  except ImportError:
+    try:
+      # Python 2.5
+      import xml.etree.ElementTree as etree
+    except ImportError:
+      try:
+        # normal cElementTree install
+        import cElementTree as etree
+      except ImportError:
+        try:
+          # normal ElementTree install
+          import elementtree.ElementTree as etree
+        except ImportError:
+          print("Failed to import ElementTree from any known place")
+          sys.exit(1)
+
 base_sys_path = [os.getcwd() + '/build/test-tar-gz/lib/scons'] + sys.path
 
 helpstr = """\
@@ -125,42 +148,35 @@ class SCons_XML(object):
         if filename.count(','):
             fl = filename.split(',')
             filename = fl[0]
-        f = self.fopen(filename)
-        
-        # Write XML header
-        f.write("""<?xml version='1.0'?>
-<variablelist xmlns="%s"
-              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="%s scons.xsd">
-
-""" % (SConsDoc.dbxsd, SConsDoc.dbxsd))
-        f.write(Warning)
+            
+        # Start new XML file
+        root = SConsDoc.xml_tree("variablelist")
         
         for v in self.values:
-            f.write('\n<varlistentry id="%s%s">\n' %
-                        (v.prefix, v.idfunc()))
-            f.write('%s\n' % v.xml_term())
-            f.write('<listitem>\n')
-            # TODO: write summary
-            f.write('<para>\n')
+            ve = etree.Element("varlistentry",
+                               attrib = {'id' : '%s%s' % (v.prefix, v.idfunc())})
+            ve.append(v.xml_term())
+            vl = etree.Element("listitem")
             if v.summary:
-                pass
-            f.write('</para>\n')
+                for s in v.summary:
+                    vl.append(copy.deepcopy(s))
+            
             if v.sets:
+                vp = etree.Element("para")
                 s = ['&cv-link-%s;' % x for x in v.sets]
-                f.write('<para>\n')
-                f.write('Sets:  ' + ', '.join(s) + '.\n')
-                f.write('</para>\n')
+                vp.text = 'Sets:  ' + ', '.join(s) + '.'
+                vl.append(vp)
             if v.uses:
+                vp = etree.Element("para")
                 u = ['&cv-link-%s;' % x for x in v.uses]
-                f.write('<para>\n')
-                f.write('Uses:  ' + ', '.join(u) + '.\n')
-                f.write('</para>\n')
-            f.write('</listitem>\n')
-            f.write('</varlistentry>\n')
+                vp.text = 'Uses:  ' + ', '.join(u) + '.'
+                vl.append(vp)
+            ve.append(vl)
+            root.append(ve)
             
-        # Write end tag
-        f.write('\n</variablelist>\n')
+        # Write file        
+        f = self.fopen(filename)
+        f.write(etree.tostring(root, xml_declaration=True, encoding="UTF-8", pretty_print=True))
             
     def write_mod(self, filename):
         try:
@@ -232,7 +248,9 @@ class SConsThing(Proxy):
         return self.name
     
     def xml_term(self):
-        return '<term>%s</term>' % self.name
+        e = etree.Element("term")
+        e.text = self.name
+        return e
 
 class Builder(SConsThing):
     description = 'builder'
@@ -240,9 +258,19 @@ class Builder(SConsThing):
     tag = 'function'
     
     def xml_term(self):
-        return ('<term><synopsis><%s>%s()</%s></synopsis>\n<synopsis><%s>env.%s()</%s></synopsis></term>' %
-                (self.tag, self.name, self.tag, self.tag, self.name, self.tag))
-        
+        t = etree.Element("term")
+        s = etree.Element("synopsis")
+        b = etree.Element(self.tag)
+        b.text = self.name+'()'
+        s.append(b)
+        t.append(s)
+        s = etree.Element("synopsis")
+        b = etree.Element(self.tag)
+        b.text = 'env.'+self.name+'()'
+        s.append(b)
+        t.append(s)
+        return t
+            
     def entityfunc(self):
         return self.name
 
@@ -251,37 +279,30 @@ class Function(SConsThing):
     prefix = 'f-'
     tag = 'function'
     
-    def args_to_xml(self, arg):
-        s = ''.join(arg.body).strip()
-        result = []
-        for m in re.findall('([a-zA-Z/_]+=?|[^a-zA-Z/_]+)', s):
-            if m[0] in string.letters:
-                if m[-1] == '=':
-                    result.append('<literal>%s</literal>=' % m[:-1])
-                else:
-                    result.append('<varname>%s</varname>' % m)
-            else:
-                result.append(m)
-        return ''.join(result)
-    
     def xml_term(self):
         try:
             arguments = self.arguments
         except AttributeError:
-            arguments = ['()']
-        result = ['<term>']
+            a = etree.Element("arguments")
+            a.text = '()'
+            arguments = [a]
+        t = etree.Element("term")
         for arg in arguments:
-            try:
-                signature = arg.signature
-            except AttributeError:
+            if 'signature' in arg.attrib:
+                signature = arg.attrib['signature']
+            else:
                 signature = "both"
-            s = arg # TODO: self.args_to_xml(arg)
+            s = arg.text.strip()
             if signature in ('both', 'global'):
-                result.append('<synopsis>%s%s</synopsis>\n' % (self.name, s)) #<br>
+                syn = etree.Element("synopsis")
+                syn.text = '%s%s' % (self.name, s)
+                t.append(syn)
             if signature in ('both', 'env'):
-                result.append('<synopsis><varname>env</varname>.%s%s</synopsis>' % (self.name, s))
-        result.append('</term>')
-        return ''.join(result)
+                syn = etree.Element("synopsis")
+                syn.text = 'env.%s%s' % (self.name, s)
+                t.append(syn)
+
+        return t
     
     def entityfunc(self):
         return self.name