Commits

Anonymous committed 71a7a08

Add the generated function documentation to the User's Guide as an appendix.
Fixes and refactoring in the bin/scons-proc.py script to support this.
Fixes to various parts of the XML input.

Comments (0)

Files changed (10)

bin/scons-proc.py

 import getopt
 import os
 import re
+import string
 import sys
 import xml.sax
 try:
         for v in self.values:
             f.write('\n<varlistentry id="%s%s">\n' %
                         (v.prefix, v.idfunc()))
-            for term in v.termfunc():
-                f.write('<term><%s>%s</%s></term>\n' %
-                        (v.tag, term, v.tag))
+            f.write('%s\n' % v.xml_term())
             f.write('<listitem>\n')
             for chunk in v.summary.body:
                 f.write(str(chunk))
         f = self.fopen(filename)
         chunks = []
         for v in self.values:
-            chunks.extend(v.mansep())
-            chunks.extend(v.initial_chunks())
+            chunks.extend(v.man_separator())
+            chunks.extend(v.initial_man_chunks())
             chunks.extend(list(map(str, v.summary.body)))
 
         body = ''.join(chunks)
             return cmp(self.__subject, other)
         return cmp(self.__dict__, other.__dict__)
 
-class Builder(Proxy):
+class SConsThing(Proxy):
+    def idfunc(self):
+        return self.name
+    def xml_term(self):
+        return '<term>%s</term>' % self.name
+
+class Builder(SConsThing):
     description = 'builder'
     prefix = 'b-'
     tag = 'function'
-    def idfunc(self):
-        return self.name
-    def termfunc(self):
-        return ['%s()' % self.name, 'env.%s()' % self.name]
+    def xml_term(self):
+        return ('<term><%s>%s()</%s></term>\n<term><%s>env.%s()</%s></term>' %
+                (self.tag, self.name, self.tag, self.tag, self.name, self.tag))
     def entityfunc(self):
         return self.name
-    def mansep(self):
+    def man_separator(self):
         return ['\n', "'\\" + '"'*69 + '\n']
-    def initial_chunks(self):
-        return [ '.IP %s\n' % t for t in self.termfunc() ]
+    def initial_man_chunks(self):
+        return [ '.IP %s()\n.IP env.%s()\n' % (self.name, self.name) ]
 
-class Function(Proxy):
+class Function(SConsThing):
     description = 'function'
     prefix = 'f-'
     tag = 'function'
-    def idfunc(self):
-        return self.name
-    def termfunc(self):
-        return ['%s()' % self.name, 'env.%s()' % self.name]
+    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 = []
+        for arg in arguments:
+            try:
+                signature = arg.signature
+            except AttributeError:
+                signature = "both"
+            s = self.args_to_xml(arg)
+            if signature in ('both', 'global'):
+                result.append('<term>%s%s</term>\n' % (self.name, s)) #<br>
+            if signature in ('both', 'env'):
+                result.append('<term><varname>env</varname>.%s%s</term>\n' % (self.name, s))
+        return ''.join(result)
     def entityfunc(self):
         return self.name
-    def mansep(self):
+    def man_separator(self):
         return ['\n', "'\\" + '"'*69 + '\n']
     def args_to_man(self, arg):
         """Converts the contents of an <arguments> tag, which
                     m = '"%s"' % m
                 result.append(m)
         return ' '.join(result)
-    def initial_chunks(self):
+    def initial_man_chunks(self):
         try:
             arguments = self.arguments
         except AttributeError:
                 result.append('.TP\n.IR env .%s%s\n' % (self.name, s))
         return result
 
-class Tool(Proxy):
+class Tool(SConsThing):
     description = 'tool'
     prefix = 't-'
     tag = 'literal'
     def idfunc(self):
         return self.name.replace('+', 'X')
-    def termfunc(self):
-        return [self.name]
     def entityfunc(self):
         return self.name
-    def mansep(self):
+    def man_separator(self):
         return ['\n']
-    def initial_chunks(self):
+    def initial_man_chunks(self):
         return ['.IP %s\n' % self.name]
 
-class Variable(Proxy):
+class Variable(SConsThing):
     description = 'construction variable'
     prefix = 'cv-'
     tag = 'envar'
-    def idfunc(self):
-        return self.name
-    def termfunc(self):
-        return [self.name]
     def entityfunc(self):
         return '$' + self.name
-    def mansep(self):
+    def man_separator(self):
         return ['\n']
-    def initial_chunks(self):
+    def initial_man_chunks(self):
         return ['.IP %s\n' % self.name]
 
 if output_type == '--man':
 
     builders_gen = os.path.join(build, 'user', 'builders.gen')
     builders_mod = os.path.join(build, 'user', 'builders.mod')
+    functions_gen = os.path.join(build, 'user', 'functions.gen')
+    functions_mod = os.path.join(build, 'user', 'functions.mod')
     tools_gen = os.path.join(build, 'user', 'tools.gen')
     tools_mod = os.path.join(build, 'user', 'tools.mod')
     variables_gen = os.path.join(build, 'user', 'variables.gen')
     # vs. the other.  The *.gen and *.mod targets will still be dependent
     # on the list of the files themselves.
     doc_output_files = [builders_gen, builders_mod,
+                        functions_gen, functions_mod,
                         tools_gen, tools_mod,
                         variables_gen, variables_mod]
     b = env.Command(doc_output_files,
                     scons_doc_files,
-                    "$PYTHON $SCONS_PROC_PY --xml -b ${TARGETS[0]},${TARGETS[1]} -t ${TARGETS[2]},${TARGETS[3]} -v ${TARGETS[4]},${TARGETS[5]} $( $SOURCES $)")
+                    "$PYTHON $SCONS_PROC_PY --xml -b ${TARGETS[0]},${TARGETS[1]} -f ${TARGETS[2]},${TARGETS[3]} -t ${TARGETS[4]},${TARGETS[5]} -v ${TARGETS[6]},${TARGETS[7]} $( $SOURCES $)")
     env.Depends(b, "$SCONS_PROC_PY")
 
     env.Local(b)

doc/user/MANIFEST

 example.xml
 factories.xml
 file-removal.xml
+functions.xml
 hierarchy.xml
 install.xml
 java.xml

doc/user/functions.in

+<!--
+
+  __COPYRIGHT__
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+<para>
+
+This appendix contains descriptions of all of the
+function and construction environment methods
+in this version of &SCons;
+
+</para>
+
+<variablelist>
+
+&functions-gen;
+
+</variablelist>

doc/user/functions.xml

+<!--
+
+  __COPYRIGHT__
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+  KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+
+<para>
+
+This appendix contains descriptions of all of the
+function and construction environment methods
+in this version of &SCons;
+
+</para>
+
+<variablelist>
+
+&functions-gen;
+
+</variablelist>
     <!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 example SYSTEM "example.xml">
     <!ENTITY factories SYSTEM "factories.xml">
     <!ENTITY file-removal SYSTEM "file-removal.xml">
+    <!ENTITY functions SYSTEM "functions.xml">
     <!ENTITY hierarchy SYSTEM "hierarchy.xml">
     <!ENTITY java SYSTEM "java.xml">
     <!ENTITY install SYSTEM "install.xml">
     <!ENTITY variants SYSTEM "variants.xml">
 
     <!ENTITY builders-gen SYSTEM "builders.gen">
+    <!ENTITY functions-gen SYSTEM "functions.gen">
     <!ENTITY tools-gen SYSTEM "tools.gen">
     <!ENTITY variables-gen SYSTEM "variables.gen">
 
     &tools;
   </appendix>
 
+  <appendix id="app-functions">
+    <title>Functions and Environment Methods</title>
+    &functions;
+  </appendix>
+
   <appendix id="app-tasks">
     <title>Handling Common Tasks</title>
     &tasks;

doc/user/main.xml

     <!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 example SYSTEM "example.xml">
     <!ENTITY factories SYSTEM "factories.xml">
     <!ENTITY file-removal SYSTEM "file-removal.xml">
+    <!ENTITY functions SYSTEM "functions.xml">
     <!ENTITY hierarchy SYSTEM "hierarchy.xml">
     <!ENTITY java SYSTEM "java.xml">
     <!ENTITY install SYSTEM "install.xml">
     <!ENTITY variants SYSTEM "variants.xml">
 
     <!ENTITY builders-gen SYSTEM "builders.gen">
+    <!ENTITY functions-gen SYSTEM "functions.gen">
     <!ENTITY tools-gen SYSTEM "tools.gen">
     <!ENTITY variables-gen SYSTEM "variables.gen">
 
     &tools;
   </appendix>
 
+  <appendix id="app-functions">
+    <title>Functions and Environment Methods</title>
+    &functions;
+  </appendix>
+
   <appendix id="app-tasks">
     <title>Handling Common Tasks</title>
     &tasks;

src/engine/SCons/Environment.xml

 <variablelist>
 <varlistentry>
 <term>timestamp-newer</term>
-<listitem>
+<listitem><para>
 Specifies that a target shall be considered out of date and rebuilt
 if the dependency's timestamp is newer than the target file's timestamp.
 This is the behavior of the classic Make utility,
 <literal>make</literal>
 can be used a synonym for
 <literal>timestamp-newer</literal>.
-</listitem>
+</para></listitem>
 </varlistentry>
-
 <varlistentry>
 <term>timestamp-match</term>
-<listitem>
+<listitem><para>
 Specifies that a target shall be considered out of date and rebuilt
 if the dependency's timestamp is different than the
 timestamp recorded the last time the target was built.
 dependency file has been restored to a version with an
 <emphasis>earlier</emphasis>
 timestamp, such as can happen when restoring files from backup archives.
-</listitem>
+</para></listitem>
 </varlistentry>
-
 <varlistentry>
 <term>MD5</term>
-<listitem>
+<listitem><para>
 Specifies that a target shall be considered out of date and rebuilt
 if the dependency's content has changed sine the last time
 the target was built,
 <literal>content</literal>
 can be used as a synonym for
 <literal>MD5</literal>.
-</listitem>
+</para></listitem>
 </varlistentry>
-
 <varlistentry>
 <term>MD5-timestamp</term>
-<listitem>
+<listitem><para>
 Specifies that a target shall be considered out of date and rebuilt
 if the dependency's content has changed sine the last time
 the target was built,
 updates a file,
 and runs the build again,
 all within a single second.
-</listitem>
+</para></listitem>
 </varlistentry>
 </variablelist>
 
 <variablelist>
 <varlistentry>
 <term><parameter>dependency</parameter></term>
-<listitem>
+<listitem><para>
 The Node (file) which
 should cause the
 <varname>target</varname>
 if it has "changed" since the last tme
 <varname>target</varname>
 was built.
-</listitem>
+</para></listitem>
 </varlistentry>
-
 <varlistentry>
 <term><parameter>target</parameter></term>
-<listitem>
+<listitem><para>
 The Node (file) being built.
 In the normal case,
 this is what should get rebuilt
 if the
 <varname>dependency</varname>
 has "changed."
-</listitem>
+</para></listitem>
 </varlistentry>
-
 <varlistentry>
 <term><parameter>prev_ni</parameter></term>
-<listitem>
+<listitem><para>
 Stored information about the state of the
 <varname>dependency</varname>
 the last time the
 file characteristics
 such as the timestamp,
 size, or content signature.
-</listitem>
+</para></listitem>
 </varlistentry>
 </variablelist>
 
 must be set to lists of
 target and source nodes, respectively,
 if you want the
-&TARGET;,
-&TARGETS;,
-&SOURCE;
+&cv-TARGET;,
+&cv-TARGETS;,
+&cv-SOURCE;
 and
-&SOURCES;
+&cv-SOURCES;
 to be available for expansion.
 This is usually necessary if you are
 calling

src/engine/SCons/Script/Main.xml

 <variablelist>
 <varlistentry>
 <term><literal>cache_debug</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --cache-debug;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>cache_disable</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --cache-disable;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>cache_force</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --cache-force;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>cache_show</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --cache-show;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>clean</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -c, --clean and --remove;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>config</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --config;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>directory</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -C and --directory;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>diskcheck</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --diskcheck
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>duplicate</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --duplicate;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>file</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -f, --file, --makefile and --sconstruct;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>help</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -h and --help;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>ignore_errors</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --ignore-errors;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>implicit_cache</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --implicit-cache;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>implicit_deps_changed</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --implicit-deps-changed;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>implicit_deps_unchanged</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --implicit-deps-unchanged;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>interactive</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --interact and --interactive;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>keep_going</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -k and --keep-going;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>max_drift</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --max-drift;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>no_exec</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>no_site_dir</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --no-site-dir;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>num_jobs</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -j and --jobs;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>profile_file</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --profile;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>question</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -q and --question;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>random</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --random;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>repository</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -Y, --repository and --srcdir;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>silent</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -s, --silent and --quiet;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>site_dir</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --site-dir;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>stack_size</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --stack-size;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>taskmastertrace_file</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --taskmastertrace; and
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>warn</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --warn and --warning.
-</listitem>
+</para></listitem>
 </varlistentry>
 </variablelist>
 
 <variablelist>
 <varlistentry>
 <term><literal>clean</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -c, --clean and --remove;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>duplicate</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --duplicate;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>help</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -h and --help;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>implicit_cache</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --implicit-cache;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>max_drift</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --max-drift;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>no_exec</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -n, --no-exec, --just-print, --dry-run and --recon;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>num_jobs</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to -j and --jobs;
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>random</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --random; and
-</listitem>
+</para></listitem>
 </varlistentry>
 <varlistentry>
 <term><literal>stack_size</literal></term>
-<listitem>
+<listitem><para>
 which corresponds to --stack-size.
-</listitem>
+</para></listitem>
 </varlistentry>
 </variablelist>
 

src/engine/SCons/Tool/packaging/__init__.xml

 <summary>
 Annotates file or directory Nodes with
 information about how the
-&f-link-Package;
+&b-link-Package;
 Builder should package those files or directories.
 All tags are optional.