Update generation of scons-xml entities [ci skip]

PR #3602 introduced a new problem - the documents that include
the generated functions and builders files now don't validate.
The global function/environment method name was bolded by
using <emphasis>, but Docbook doesn't allow that inside a
<literal> element (it actually works fine with the processing
tools we use, but does fail validation).

Rework the idea: use <function> and <methodname> for the markup,
and change the way those are rendered in html (man/html.xsl and
user/html.xsl) - the PDF already rendered these in bold so no
change needed there.  Also don't wrap the whole contents of the
<term> element in <literal>, which would have left the argument
list in regular font which the function name and instance
name in monospace - an odd look.  So the argument list was
wrapped in <parameter>, since that's what they are.  Don't
bother to try to parse it down into individual args, just do
the whole chunk, less the parentheses.

Signed-off-by: Mats Wichmann <mats@linux.com>

1 files changed, 35 insertions, 16 deletions

diff --git a/bin/scons-proc.py b/bin/scons-proc.py
index ac52894d3..d6e503087 100644
--- a/bin/scons-proc.py
+++ b/bin/scons-proc.py
@@ -254,6 +254,7 @@ class Proxy(object):
     ##     return self.__dict__ < other.__dict__
 
 class SConsThing(Proxy):
+    """Base class for the SConsDoc special elements"""
     def idfunc(self):
         return self.name
     
@@ -263,6 +264,7 @@ class SConsThing(Proxy):
         return [e]
 
 class Builder(SConsThing):
+    """Generate the descriptions and entities for <builder> elements"""
     description = 'builder'
     prefix = 'b-'
     tag = 'function'
@@ -272,20 +274,20 @@ class Builder(SConsThing):
 
         builders don't show a full signature, just func()
         """
+        # build term for global function
         gterm = stf.newNode("term")
-        sig = stf.newSubNode(gterm, "literal")
-        func = stf.newSubNode(sig, "emphasis", role="bold")
+        func = stf.newSubNode(gterm, "function")
         stf.setText(func, self.name)
         stf.setTail(func, '()')
 
+        # build term for env. method
         mterm = stf.newNode("term")
-        sig = stf.newSubNode(mterm, "literal")
-        inst = stf.newSubNode(sig, "replaceable")
+        inst = stf.newSubNode(mterm, "parameter")
         stf.setText(inst, "env")
         stf.setTail(inst, ".")
-        func = stf.newSubNode(sig, "emphasis", role="bold")
-        stf.setText(func, self.name)
-        stf.setTail(func, '()')
+        meth = stf.newSubNode(mterm, "methodname")
+        stf.setText(meth, self.name)
+        stf.setTail(meth, '()')
 
         return [gterm, mterm]
             
@@ -293,6 +295,7 @@ class Builder(SConsThing):
         return self.name
 
 class Function(SConsThing):
+    """Generate the descriptions and entities for <scons_function> elements"""
     description = 'function'
     prefix = 'f-'
     tag = 'function'
@@ -314,23 +317,37 @@ class Function(SConsThing):
             signature = 'both'
             if stf.hasAttribute(arg, 'signature'):
                 signature = stf.getAttribute(arg, 'signature')
-            s = stf.getText(arg).strip()
+            sig = stf.getText(arg).strip()[1:-1]  # strip (), temporarily
             if signature in ('both', 'global'):
+                # build term for global function
                 gterm = stf.newNode("term")
-                sig = stf.newSubNode(gterm, "literal")
-                func = stf.newSubNode(sig, "emphasis", role="bold")
+                func = stf.newSubNode(gterm, "function")
                 stf.setText(func, self.name)
-                stf.setTail(func, s)
+                if sig:
+                    # if there are parameters, use that entity
+                    stf.setTail(func, "(")
+                    s = stf.newSubNode(gterm, "parameter")
+                    stf.setText(s, sig)
+                    stf.setTail(s, ")")
+                else:
+                    stf.setTail(func, "()")
                 tlist.append(gterm)
             if signature in ('both', 'env'):
+                # build term for env. method
                 mterm = stf.newNode("term")
-                sig = stf.newSubNode(mterm, "literal")
-                inst = stf.newSubNode(sig, "replaceable")
+                inst = stf.newSubNode(mterm, "replaceable")
                 stf.setText(inst, "env")
                 stf.setTail(inst, ".")
-                func = stf.newSubNode(sig, "emphasis", role="bold")
-                stf.setText(func, self.name)
-                stf.setTail(func, s)
+                meth = stf.newSubNode(mterm, "methodname")
+                stf.setText(meth, self.name)
+                if sig:
+                    # if there are parameters, use that entity
+                    stf.setTail(meth, "(")
+                    s = stf.newSubNode(mterm, "parameter")
+                    stf.setText(s, sig)
+                    stf.setTail(s, ")")
+                else:
+                    stf.setTail(meth, "()")
                 tlist.append(mterm)
 
         if not tlist:
@@ -341,6 +358,7 @@ class Function(SConsThing):
         return self.name
 
 class Tool(SConsThing):
+    """Generate the descriptions and entities for <tool> elements"""
     description = 'tool'
     prefix = 't-'
     tag = 'literal'
@@ -352,6 +370,7 @@ class Tool(SConsThing):
         return self.name
 
 class Variable(SConsThing):
+    """Generate the descriptions and entities for <cvar> elements"""
     description = 'construction variable'
     prefix = 'cv-'
     tag = 'envar'