dirkbaechle avatar dirkbaechle committed 3cb0a7b

- rewrote all tool/builder docs to new SCons XSD

Comments (0)

Files changed (108)

src/engine/SCons/Action.xml

+<?xml version="1.0" encoding="UTF-8"?>
 <!--
 __COPYRIGHT__
 
 This file is processed by the bin/SConsDoc.py module.
 See its __doc__ string for a discussion of the format.
 -->
+
+<!DOCTYPE sconsdoc [
+<!ENTITY % scons SYSTEM '../../../doc/scons.mod'>
+%scons;
+<!ENTITY % builders-mod SYSTEM '../../../doc/generated/builders.mod'>
+%builders-mod;
+<!ENTITY % functions-mod SYSTEM '../../../doc/generated/functions.mod'>
+%functions-mod;
+<!ENTITY % tools-mod SYSTEM '../../../doc/generated/tools.mod'>
+%tools-mod;
+<!ENTITY % variables-mod SYSTEM '../../../doc/generated/variables.mod'>
+%variables-mod;
+]>
+
+<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 scons.xsd">
+
 <cvar name="IMPLICIT_COMMAND_DEPENDENCIES">
 <summary>
+<para>
 Controls whether or not SCons will
 add implicit dependencies for the commands
 executed to build targets.
+</para>
 
+<para>
 By default, SCons will add
 to each target
 an implicit dependency on the command
 variable in the
 <varname>ENV</varname>
 environment used to execute the command.
+</para>
 
+<para>
 If the construction variable
 &cv-IMPLICIT_COMMAND_DEPENDENCIES;
 is set to a false value
 then the implicit dependency will
 not be added to the targets
 built with that construction environment.
+</para>
 
-<example>
+<example_commands>
 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
-</example>
+</example_commands>
 </summary>
 </cvar>
 
 <cvar name="PRINT_CMD_LINE_FUNC">
 <summary>
+<para>
 A Python function used to print the command lines as they are executed
 (assuming command printing is not disabled by the
 <option>-q</option>
 the source(s) used (file node, list, or string name(s)), and
 <varname>env</varname>,
 the environment being used.
+</para>
 
+<para>
 The function must do the printing itself.  The default implementation,
 used if this variable is not set or is None, is:
-<example>
+</para>
+<example_commands>
 def print_cmd_line(s, target, source, env):
   sys.stdout.write(s + "\n")
-</example>
+</example_commands>
 
+<para>
 Here's an example of a more interesting function:
+</para>
 
-<example>
+<example_commands>
 def print_cmd_line(s, target, source, env):
    sys.stdout.write("Building %s -> %s...\n" %
     (' and '.join([str(x) for x in source]),
      ' and '.join([str(x) for x in target])))
 env=Environment(PRINT_CMD_LINE_FUNC=print_cmd_line)
 env.Program('foo', 'foo.c')
-</example>
+</example_commands>
 
+<para>
 This just prints "Building <varname>targetname</varname> from <varname>sourcename</varname>..." instead
 of the actual commands.
 Such a function could also log the actual commands to a log file,
 for example.
+</para>
 </summary>
 </cvar>
 
 <cvar name="SPAWN">
 <summary>
+<para>
 A command interpreter function that will be called to execute command line
 strings. The function must expect the following arguments:
+</para>
 
-<example>
+<example_commands>
 def spawn(shell, escape, cmd, args, env):
-</example>
+</example_commands>
 
+<para>
 <varname>sh</varname>
 is a string naming the shell program to use.
 <varname>escape</varname>
 <varname>env</varname>
 is a dictionary of the environment variables
 in which the command should be executed.
+</para>
 </summary>
 </cvar>
+
+</sconsdoc>

src/engine/SCons/Defaults.xml

+<?xml version="1.0" encoding="UTF-8"?>
 <!--
 __COPYRIGHT__
 
 This file is processed by the bin/SConsDoc.py module.
 See its __doc__ string for a discussion of the format.
 -->
+
+<!DOCTYPE sconsdoc [
+<!ENTITY % scons SYSTEM '../../../doc/scons.mod'>
+%scons;
+<!ENTITY % builders-mod SYSTEM '../../../doc/generated/builders.mod'>
+%builders-mod;
+<!ENTITY % functions-mod SYSTEM '../../../doc/generated/functions.mod'>
+%functions-mod;
+<!ENTITY % tools-mod SYSTEM '../../../doc/generated/tools.mod'>
+%tools-mod;
+<!ENTITY % variables-mod SYSTEM '../../../doc/generated/variables.mod'>
+%variables-mod;
+]>
+
+<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 scons.xsd">
+
 <cvar name ="_concat">
 <summary>
+<para>
 A function used to produce variables like &cv-_CPPINCFLAGS;. It takes
 four or five
 arguments: a prefix to concatenate onto each element, a list of
 elements, a suffix to concatenate onto each element, an environment
 for variable interpolation, and an optional function that will be
 called to transform the list before concatenation.
+</para>
 
-<example>
+<example_commands>
 env['_CPPINCFLAGS'] = '$( ${_concat(INCPREFIX, CPPPATH, INCSUFFIX, __env__, RDirs)} $)',
-</example>
+</example_commands>
 </summary>
 </cvar>
 
 <cvar name="CONFIGUREDIR">
 <summary>
+<para>
 The name of the directory in which
 Configure context test files are written.
 The default is
 containing the
 <filename>SConstruct</filename>
 file.
+</para>
 </summary>
 </cvar>
 
 <cvar name="CONFIGURELOG">
 <summary>
+<para>
 The name of the Configure context log file.
 The default is
 <filename>config.log</filename>
 containing the
 <filename>SConstruct</filename>
 file.
+</para>
 </summary>
 </cvar>
 
 <cvar name="_CPPDEFFLAGS">
 <summary>
+<para>
 An automatically-generated construction variable
 containing the C preprocessor command-line options
 to define values.
 by appending &cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX;
 to the beginning and end
 of each definition in &cv-CPPDEFINES;.
+</para>
 </summary>
 </cvar>
 
 <cvar name="CPPDEFINES">
 <summary>
+<para>
 A platform independent specification of C preprocessor definitions.
 The definitions will be added to command lines
 through the automatically-generated
 &cv-_CPPDEFFLAGS; construction variable (see above),
 which is constructed according to
 the type of value of &cv-CPPDEFINES;:
+</para>
 
+<para>
 If &cv-CPPDEFINES; is a string,
 the values of the
 &cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX;
 construction variables
 will be added to the beginning and end.
+</para>
 
-<example>
+<example_commands>
 # Will add -Dxyz to POSIX compiler command lines,
 # and /Dxyz to Microsoft Visual C++ command lines.
 env = Environment(CPPDEFINES='xyz')
-</example>
+</example_commands>
 
+<para>
 If &cv-CPPDEFINES; is a list,
 the values of the
 &cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX;
 If any element is a list or tuple,
 then the first item is the name being
 defined and the second item is its value:
+</para>
 
-<example>
+<example_commands>
 # Will add -DB=2 -DA to POSIX compiler command lines,
 # and /DB=2 /DA to Microsoft Visual C++ command lines.
 env = Environment(CPPDEFINES=[('B', 2), 'A'])
-</example>
+</example_commands>
 
+<para>
 If &cv-CPPDEFINES; is a dictionary,
 the values of the
 &cv-CPPDEFPREFIX; and &cv-CPPDEFSUFFIX;
 command line is consistent each time
 &scons;
 is run.
+</para>
 
-<example>
+<example_commands>
 # Will add -DA -DB=2 to POSIX compiler command lines,
 # and /DA /DB=2 to Microsoft Visual C++ command lines.
 env = Environment(CPPDEFINES={'B':2, 'A':None})
-</example>
+</example_commands>
 </summary>
 </cvar>
 
 <cvar name="CPPDEFPREFIX">
 <summary>
+<para>
 The prefix used to specify preprocessor definitions
 on the C compiler command line.
 This will be appended to the beginning of each definition
 in the &cv-CPPDEFINES; construction variable
 when the &cv-_CPPDEFFLAGS; variable is automatically generated.
+</para>
 </summary>
 </cvar>
 
 <cvar name="CPPDEFSUFFIX">
 <summary>
+<para>
 The suffix used to specify preprocessor definitions
 on the C compiler command line.
 This will be appended to the end of each definition
 in the &cv-CPPDEFINES; construction variable
 when the &cv-_CPPDEFFLAGS; variable is automatically generated.
+</para>
 </summary>
 </cvar>
 
 <cvar name="_CPPINCFLAGS">
 <summary>
+<para>
 An automatically-generated construction variable
 containing the C preprocessor command-line options
 for specifying directories to be searched for include files.
 by appending &cv-INCPREFIX; and &cv-INCSUFFIX;
 to the beginning and end
 of each directory in &cv-CPPPATH;.
+</para>
 </summary>
 </cvar>
 
 <cvar name="CPPPATH">
 <summary>
+<para>
 The list of directories that the C preprocessor will search for include
 directories. The C/C++ implicit dependency scanner will search these
 directories for include files. Don't explicitly put include directory
 directory when they are used in a command. To force
 &scons;
 to look-up a directory relative to the root of the source tree use #:
+</para>
 
-<example>
+<example_commands>
 env = Environment(CPPPATH='#/include')
-</example>
+</example_commands>
 
+<para>
 The directory look-up can also be forced using the
 &Dir;()
 function:
+</para>
 
-<example>
+<example_commands>
 include = Dir('include')
 env = Environment(CPPPATH=include)
-</example>
+</example_commands>
 
+<para>
 The directory list will be added to command lines
 through the automatically-generated
 &cv-_CPPINCFLAGS;
 Any command lines you define that need
 the CPPPATH directory list should
 include &cv-_CPPINCFLAGS;:
+</para>
 
-<example>
+<example_commands>
 env = Environment(CCCOM="my_compiler $_CPPINCFLAGS -c -o $TARGET $SOURCE")
-</example>
+</example_commands>
 </summary>
 </cvar>
 
 <cvar name="Dir">
 <summary>
+<para>
 A function that converts a string
 into a Dir instance relative to the target being built.
+</para>
 </summary>
 </cvar>
 
 <cvar name="Dirs">
 <summary>
+<para>
 A function that converts a list of strings
 into a list of Dir instances relative to the target being built.
+</para>
 </summary>
 </cvar>
 
 <cvar name="DSUFFIXES">
 <summary>
+<para>
 The list of suffixes of files that will be scanned
 for imported D package files.
 The default list is:
+</para>
 
-<example>
+<example_commands>
 ['.d']
-</example>
+</example_commands>
 </summary>
 </cvar>
 
 <cvar name="File">
 <summary>
+<para>
 A function that converts a string into a File instance relative to the
 target being built.
+</para>
 </summary>
 </cvar>
 
 <cvar name="IDLSUFFIXES">
 <summary>
+<para>
 The list of suffixes of files that will be scanned
 for IDL implicit dependencies
 (#include or import lines).
 The default list is:
+</para>
 
-<example>
+<example_commands>
 [".idl", ".IDL"]
-</example>
+</example_commands>
 </summary>
 </cvar>
 
 <cvar name="INCPREFIX">
 <summary>
+<para>
 The prefix used to specify an include directory on the C compiler command
 line.
 This will be appended to the beginning of each directory
 in the &cv-CPPPATH; and &cv-FORTRANPATH; construction variables
 when the &cv-_CPPINCFLAGS; and &cv-_FORTRANINCFLAGS;
 variables are automatically generated.
+</para>
 </summary>
 </cvar>
 
 <cvar name="INCSUFFIX">
 <summary>
+<para>
 The suffix used to specify an include directory on the C compiler command
 line.
 This will be appended to the end of each directory
 in the &cv-CPPPATH; and &cv-FORTRANPATH; construction variables
 when the &cv-_CPPINCFLAGS; and &cv-_FORTRANINCFLAGS;
 variables are automatically generated.
+</para>
 </summary>
 </cvar>
 
 <cvar name="INSTALL">
 <summary>
+<para>
 A function to be called to install a file into a
 destination file name.
 The default function copies the file into the destination
 (and sets the destination file's mode and permission bits
 to match the source file's).
 The function takes the following arguments:
+</para>
 
-<example>
+<example_commands>
 def install(dest, source, env):
-</example>
+</example_commands>
 
+<para>
 <varname>dest</varname>
 is the path name of the destination file.
 <varname>source</varname>
 is the construction environment
 (a dictionary of construction values)
 in force for this file installation.
+</para>
 </summary>
 </cvar>
 
 <cvar name="INSTALLSTR">
 <summary>
+<para>
 The string displayed when a file is
 installed into a destination file name.
 The default is:
-<example>
+</para>
+<example_commands>
 Install file: "$SOURCE" as "$TARGET"
-</example>
+</example_commands>
 </summary>
 </cvar>
 
 <cvar name="LATEXSUFFIXES">
 <summary>
+<para>
 The list of suffixes of files that will be scanned
 for LaTeX implicit dependencies
 (<literal>\include</literal> or <literal>\import</literal> files).
 The default list is:
+</para>
 
-<example>
+<example_commands>
 [".tex", ".ltx", ".latex"]
-</example>
+</example_commands>
 </summary>
 </cvar>
 
 <cvar name="_LIBDIRFLAGS">
 <summary>
+<para>
 An automatically-generated construction variable
 containing the linker command-line options
 for specifying directories to be searched for library.
 by appending &cv-LIBDIRPREFIX; and &cv-LIBDIRSUFFIX;
 to the beginning and end
 of each directory in &cv-LIBPATH;.
+</para>
 </summary>
 </cvar>
 
 <cvar name="LIBDIRPREFIX">
 <summary>
+<para>
 The prefix used to specify a library directory on the linker command line.
 This will be appended to the beginning of each directory
 in the &cv-LIBPATH; construction variable
 when the &cv-_LIBDIRFLAGS; variable is automatically generated.
+</para>
 </summary>
 </cvar>
 
 <cvar name="LIBDIRSUFFIX">
 <summary>
+<para>
 The suffix used to specify a library directory on the linker command line.
 This will be appended to the end of each directory
 in the &cv-LIBPATH; construction variable
 when the &cv-_LIBDIRFLAGS; variable is automatically generated.
+</para>
 </summary>
 </cvar>
 
 <cvar name="_LIBFLAGS">
 <summary>
+<para>
 An automatically-generated construction variable
 containing the linker command-line options
 for specifying libraries to be linked with the resulting target.
 by appending &cv-LIBLINKPREFIX; and &cv-LIBLINKSUFFIX;
 to the beginning and end
 of each filename in &cv-LIBS;.
+</para>
 </summary>
 </cvar>
 
 <cvar name="LIBLINKPREFIX">
 <summary>
+<para>
 The prefix used to specify a library to link on the linker command line.
 This will be appended to the beginning of each library
 in the &cv-LIBS; construction variable
 when the &cv-_LIBFLAGS; variable is automatically generated.
+</para>
 </summary>
 </cvar>
 
 <cvar name="LIBLINKSUFFIX">
 <summary>
+<para>
 The suffix used to specify a library to link on the linker command line.
 This will be appended to the end of each library
 in the &cv-LIBS; construction variable
 when the &cv-_LIBFLAGS; variable is automatically generated.
+</para>
 </summary>
 </cvar>
 
 <cvar name="LIBPATH">
 <summary>
+<para>
 The list of directories that will be searched for libraries.
 The implicit dependency scanner will search these
 directories for include files. Don't explicitly put include directory
 directory when they are used in a command. To force
 &scons;
 to look-up a directory relative to the root of the source tree use #:
+</para>
 
-<example>
+<example_commands>
 env = Environment(LIBPATH='#/libs')
-</example>
+</example_commands>
 
+<para>
 The directory look-up can also be forced using the
 &Dir;()
 function:
+</para>
 
-<example>
+<example_commands>
 libs = Dir('libs')
 env = Environment(LIBPATH=libs)
-</example>
+</example_commands>
 
+<para>
 The directory list will be added to command lines
 through the automatically-generated
 &cv-_LIBDIRFLAGS;
 Any command lines you define that need
 the LIBPATH directory list should
 include &cv-_LIBDIRFLAGS;:
+</para>
 
-<example>
+<example_commands>
 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
-</example>
+</example_commands>
 </summary>
 </cvar>
 
 <cvar name="LIBS">
 <summary>
+<para>
 A list of one or more libraries
 that will be linked with
 any executable programs
 created by this environment.
+</para>
 
+<para>
 The library list will be added to command lines
 through the automatically-generated
 &cv-_LIBFLAGS;
 Any command lines you define that need
 the LIBS library list should
 include &cv-_LIBFLAGS;:
+</para>
 
-<example>
+<example_commands>
 env = Environment(LINKCOM="my_linker $_LIBDIRFLAGS $_LIBFLAGS -o $TARGET $SOURCE")
-</example>
+</example_commands>
 
+<para>
 If you add a
 File
 object to the
 or
 &cv-LIBLINKSUFFIX;.
 For example:
+</para>
 
-<example>
+<example_commands>
 env.Append(LIBS=File('/tmp/mylib.so'))
-</example>
+</example_commands>
 
+<para>
 In all cases, scons will add dependencies from the executable program to
 all the libraries in this list.
+</para>
 </summary>
 </cvar>
 
 <cvar name="RDirs">
 <summary>
+<para>
 A function that converts a string into a list of Dir instances by
 searching the repositories.
+</para>
 </summary>
 </cvar>
 
 ([args])
 </arguments>
 <summary>
+<para>
 Creates and returns a default construction environment object.
 This construction environment is used internally by SCons
 in order to execute many of the global functions in this list,
 and to fetch source files transparently
 from source code management systems.
+</para>
 </summary>
 </scons_function>
+
+</sconsdoc>

src/engine/SCons/Environment.xml

+<?xml version="1.0" encoding="UTF-8"?>
 <!--
 __COPYRIGHT__
 
 See its __doc__ string for a discussion of the format.
 -->
 
+<!DOCTYPE sconsdoc [
+<!ENTITY % scons SYSTEM '../../../doc/scons.mod'>
+%scons;
+<!ENTITY % builders-mod SYSTEM '../../../doc/generated/builders.mod'>
+%builders-mod;
+<!ENTITY % functions-mod SYSTEM '../../../doc/generated/functions.mod'>
+%functions-mod;
+<!ENTITY % tools-mod SYSTEM '../../../doc/generated/tools.mod'>
+%tools-mod;
+<!ENTITY % variables-mod SYSTEM '../../../doc/generated/variables.mod'>
+%variables-mod;
+]>
+
+<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 scons.xsd">
+
+
 <!-- Construction variables -->
 
 <cvar name="BUILDERS">
 <summary>
+<para>
 A dictionary mapping the names of the builders
 available through this environment
 to underlying Builder objects.
 are available by default.
 If you initialize this variable when an
 Environment is created:
-
-<example>
+</para>
+
+<example_commands>
 env = Environment(BUILDERS = {'NewBuilder' : foo})
-</example>
-
+</example_commands>
+
+<para>
 the default Builders will no longer be available.
 To use a new Builder object in addition to the default Builders,
 add your new Builder object like this:
-
-<example>
+</para>
+
+<example_commands>
 env = Environment()
 env.Append(BUILDERS = {'NewBuilder' : foo})
-</example>
-
+</example_commands>
+
+<para>
 or this:
-
-<example>
+</para>
+
+<example_commands>
 env = Environment()
 env['BUILDERS]['NewBuilder'] = foo
-</example>
+</example_commands>
 </summary>
 </cvar>
 
 <cvar name="Dir">
 <summary>
+<para>
 A function that converts a string
 into a Dir instance relative to the target being built.
+</para>
 </summary>
 </cvar>
 
 <cvar name="ENV">
 <summary>
+<para>
 A dictionary of environment variables
 to use when invoking commands. When
 &cv-ENV; is used in a command all list
 variables set at the time
 &scons;
 is invoked.
-
+</para>
+
+<para>
 If you want to propagate your
 environment variables
 to the commands executed
 to build target files,
 you must do so explicitly:
-
-<example>
+</para>
+
+<example_commands>
 import os
 env = Environment(ENV = os.environ)
-</example>
-
+</example_commands>
+
+<para>
 Note that you can choose only to propagate
 certain environment variables.
 A common example is
 &scons;
 uses the same utilities
 as the invoking shell (or other process):
-
-<example>
+</para>
+
+<example_commands>
 import os
 env = Environment(ENV = {'PATH' : os.environ['PATH']})
-</example>
+</example_commands>
 </summary>
 </cvar>
 
 <cvar name="File">
 <summary>
+<para>
 A function that converts a string into a File instance relative to the
 target being built.
+</para>
 </summary>
 </cvar>
 
 <cvar name="SCANNERS">
 <summary>
+<para>
 A list of the available implicit dependency scanners.
 New file scanners may be added by
 appending to this list,
 See the sections "Builder Objects"
 and "Scanner Objects,"
 below, for more information.
+</para>
 </summary>
 </cvar>
 
 <cvar name="CHANGED_SOURCES">
 <summary>
+<para>
 A reserved variable name
 that may not be set or used in a construction environment.
 (See "Variable Substitution," below.)
+</para>
 </summary>
 </cvar>
 
 <cvar name="CHANGED_TARGETS">
 <summary>
+<para>
 A reserved variable name
 that may not be set or used in a construction environment.
 (See "Variable Substitution," below.)
+</para>
 </summary>
 </cvar>
 
 <cvar name="SOURCE">
 <summary>
+<para>
 A reserved variable name
 that may not be set or used in a construction environment.
 (See "Variable Substitution," below.)
+</para>
 </summary>
 </cvar>
 
 <cvar name="SOURCES">
 <summary>
+<para>
 A reserved variable name
 that may not be set or used in a construction environment.
 (See "Variable Substitution," below.)
+</para>
 </summary>
 </cvar>
 
 <cvar name="TARGET">
 <summary>
+<para>
 A reserved variable name
 that may not be set or used in a construction environment.
 (See "Variable Substitution," below.)
+</para>
 </summary>
 </cvar>
 
 <cvar name="TARGETS">
 <summary>
+<para>
 A reserved variable name
 that may not be set or used in a construction environment.
 (See "Variable Substitution," below.)
+</para>
 </summary>
 </cvar>
 
 <cvar name="UNCHANGED_SOURCES">
 <summary>
+<para>
 A reserved variable name
 that may not be set or used in a construction environment.
 (See "Variable Substitution," below.)
+</para>
 </summary>
 </cvar>
 
 <cvar name="UNCHANGED_TARGETS">
 <summary>
+<para>
 A reserved variable name
 that may not be set or used in a construction environment.
 (See "Variable Substitution," below.)
+</para>
 </summary>
 </cvar>
 
 <cvar name="TOOLS">
 <summary>
+<para>
 A list of the names of the Tool specifications
 that are part of this construction environment.
+</para>
 </summary>
 </cvar>
 
 (action, [cmd/str/fun, [var, ...]] [option=value, ...])
 </arguments>
 <summary>
+<para>
 Creates an Action object for
 the specified
 <varname>action</varname>.
 See the section "Action Objects,"
 below, for a complete explanation of the arguments and behavior.
-
+</para>
+
+<para>
 Note that the
 <function>env.Action</function>()
 form of the invocation will expand
 <function>Action</function>()
 form delays all variable expansion
 until the Action object is actually used.
+</para>
 </summary>
 </scons_function>
 
 (function, [name])
 </arguments>
 <summary>
+<para>
 When called with the
 <function>AddMethod</function>()
 form,
 specified
 <varname>function</varname>
 itself is used for the method name.
-
+</para>
+
+<para>
 Examples:
-
-<example>
+</para>
+
+<example_commands>
 # Note that the first argument to the function to
 # be attached as a method must be the object through
 # which the method will be called; the Python
 env = Environment()
 env.AddMethod(my_method, 'other_method_name')
 env.other_method_name('another arg')
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 (target, action)
 </arguments>
 <summary>
+<para>
 Arranges for the specified
 <varname>action</varname>
 to be performed
 an Action object, or anything that
 can be converted into an Action object
 (see below).
-
+</para>
+
+<para>
 When multiple targets are supplied,
 the action may be called multiple times,
 once after each action that generates
 one or more targets in the list.
+</para>
 </summary>
 </scons_function>
 
 (target, action)
 </arguments>
 <summary>
+<para>
 Arranges for the specified
 <varname>action</varname>
 to be performed
 an Action object, or anything that
 can be converted into an Action object
 (see below).
-
+</para>
+
+<para>
 When multiple targets are specified,
 the action(s) may be called multiple times,
 once before each action that generates
 one or more targets in the list.
-
+</para>
+
+<para>
 Note that if any of the targets are built in multiple steps,
 the action will be invoked just
 before the "final" action that specifically
 from a specified source
 <filename>.c</filename>
 file via an intermediate object file:
-
-<example>
+</para>
+
+<example_commands>
 foo = Program('foo.c')
 AddPreAction(foo, 'pre_action')
-</example>
-
+</example_commands>
+
+<para>
 The specified
 <literal>pre_action</literal>
 would be executed before
 not before compiling the
 <filename>foo.c</filename>
 file into an object file.
+</para>
 </summary>
 </scons_function>
 
 (alias, [targets, [action]])
 </arguments>
 <summary>
+<para>
 Creates one or more phony targets that
 expand to one or more other targets.
 An optional
 can be called multiple times for the same
 alias to add additional targets to the alias,
 or additional actions to the list for this alias.
-
+</para>
+
+<para>
 Examples:
-
-<example>
+</para>
+
+<example_commands>
 Alias('install')
 Alias('install', '/usr/bin')
 Alias(['install', 'install-lib'], '/usr/local/lib')
 env.Alias('install', ['/usr/local/man'])
 
 env.Alias('update', ['file1', 'file2'], "update_database $SOURCES")
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 (target, ...)
 </arguments>
 <summary>
+<para>
 Marks each given
 <varname>target</varname>
 so that it is always assumed to be out of date,
 be built if so specified.
 Multiple targets can be passed in to a single call to
 &f-AlwaysBuild;.
+</para>
 </summary>
 </scons_function>
 
 (key=val, [...])
 </arguments>
 <summary>
+<para>
 Appends the specified keyword arguments
 to the end of construction variables in the environment.
 If the Environment does not have
 are both coerced to lists,
 and the lists are added together.
 (See also the Prepend method, below.)
-
+</para>
+
+<para>
 Example:
-
-<example>
+</para>
+
+<example_commands>
 env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy'])
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 (name, newpath, [envname, sep, delete_existing])
 </arguments>
 <summary>
+<para>
 This appends new path elements to the given path in the
 specified external environment
 (<literal>ENV</literal>
 This can also handle the
 case where the given old path variable is a list instead of a
 string, in which case a list will be returned instead of a string.
-
+</para>
+
+<para>
 If 
 <varname>delete_existing</varname>
 is 0, then adding a path that already exists
 will not move it to the end; it will stay where it is in the list.
-
+</para>
+
+<para>
 Example:
-
-<example>
+</para>
+
+<example_commands>
 print 'before:',env['ENV']['INCLUDE']
 include_path = '/foo/bar:/foo'
 env.AppendENVPath('INCLUDE', include_path)
 yields:
 before: /foo:/biz
 after: /biz:/foo/bar:/foo
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 (key=val, [...], delete_existing=0)
 </arguments>
 <summary>
+<para>
 Appends the specified keyword arguments
 to the end of construction variables in the environment.
 If the Environment does not have
 However, if delete_existing is 1, 
 existing matching values are removed first, so
 existing values in the arg list move to the end of the list.
-
+</para>
+
+<para>
 Example:
-
-<example>
+</para>
+
+<example_commands>
 env.AppendUnique(CCFLAGS = '-g', FOO = ['foo.yyy'])
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 (build_dir, src_dir, [duplicate])
 </arguments>
 <summary>
+<para>
 Deprecated synonyms for
 &f-VariantDir;
 and
 &f-VariantDir;
 or
 <function>env.VariantDir</function>().
+</para>
 </summary>
 </scons_function>
 
 (action, [arguments])
 </arguments>
 <summary>
+<para>
 Creates a Builder object for
 the specified
 <varname>action</varname>.
 See the section "Builder Objects,"
 below, for a complete explanation of the arguments and behavior.
-
+</para>
+
+<para>
 Note that the
 <function>env.Builder</function>()
 form of the invocation will expand
 &f-Builder;
 form delays all variable expansion
 until after the Builder object is actually called.
+</para>
 </summary>
 </scons_function>
 
 (cache_dir)
 </arguments>
 <summary>
+<para>
 Specifies that
 &scons;
 will maintain a cache of derived files in
 of
 <literal>None</literal>
 disables derived file caching.
-
+</para>
+
+<para>
 Calling
 <function>env.CacheDir</function>()
 will only affect targets built
 have an
 <function>env.CacheDir</function>()
 specified.
-
+</para>
+
+<para>
 When a
 <function>CacheDir</function>()
 is being used and
 so that it may be retrieved by other
 builds that need to build the same derived file
 from identical inputs.
-
+</para>
+
+<para>
 Use of a specified
 &f-CacheDir;
 may be disabled for any invocation
 by using the
 <option>--cache-disable</option>
 option.
-
+</para>
+
+<para>
 If the
 <option>--cache-force</option>
 option is used,
 or after using the
 <option>--cache-disable</option>
 option.
-
+</para>
+
+<para>
 When using
 &f-CacheDir;,
 &scons;
 that are equivalent regardless of whether
 a given derived file has been built in-place
 or retrieved from the cache.
-
+</para>
+
+<para>
 The
 &f-link-NoCache;
 method can be used to disable caching of specific files.  This can be
 useful if inputs and/or outputs of some tool are impossible to
 predict or prohibitively large.
+</para>
 </summary>
 </scons_function>
 
 (targets, files_or_dirs)
 </arguments>
 <summary>
+<para>
 This specifies a list of files or directories which should be removed
 whenever the targets are specified with the
 <option>-c</option>
 are legal,
 and create new targets or add files and directories to the
 clean list for the specified targets.
-
+</para>
+
+<para>
 Multiple files or directories should be specified
 either as separate arguments to the
 &f-Clean;
 will also accept the return value of any of the construction environment
 Builder methods.
 Examples:
-
+</para>
+
+<para>
 The related
 &f-link-NoClean;
 function overrides calling
 be removed by the
 <option>-c</option>
 option.
-
+</para>
+
+<para>
 Examples:
-
-<example>
+</para>
+
+<example_commands>
 Clean('foo', ['bar', 'baz'])
 Clean('dist', env.Program('hello', 'hello.c'))
 Clean(['foo', 'bar'], 'something_else_to_clean')
-</example>
-
+</example_commands>
+
+<para>
 In this example,
 installing the project creates a subdirectory for the documentation.
 This statement causes the subdirectory to be removed
 if the project is deinstalled.
-<example>
+</para>
+<example_commands>
 Clean(docdir, os.path.join(docdir, projectname))
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 ([key=val, ...])
 </arguments>
 <summary>
+<para>
 Returns a separate copy of a construction environment.
 If there are any keyword arguments specified,
 they are added to the returned copy,
 overwriting any existing values
 for the keywords.
-
+</para>
+
+<para>
 Example:
-
-<example>
+</para>
+
+<example_commands>
 env2 = env.Clone()
 env3 = env.Clone(CCFLAGS = '-g')
-</example>
-
+</example_commands>
+
+<para>
 Additionally, a list of tools and a toolpath may be specified, as in
 the Environment constructor:
-
-<example>
+</para>
+
+<example_commands>
 def MyTool(env): env['FOO'] = 'bar'
 env4 = env.Clone(tools = ['msvc', MyTool])
-</example>
-
+</example_commands>
+
+<para>
 The
 <varname>parse_flags</varname>
 keyword argument is also recognized:
-
-<example>
+</para>
+
+<example_commands>
 # create an environment for compiling programs that use wxWidgets
 wx_env = env.Clone(parse_flags = '!wx-config --cflags --cxxflags')
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 <builder name="Command">
 <summary>
+<para>
 The &b-Command; "Builder" is actually implemented
 as a function that looks like a Builder,
 but actually takes an additional argument of the action
 from which the Builder should be made.
 See the &f-link-Command; function description
 for the calling syntax and details.
+</para>
 </summary>
 </builder>
 
 (target, source, action, [key=val, ...])
 </arguments>
 <summary>
+<para>
 Executes a specific action
 (or list of actions)
 to build a target file or files.
 This is more convenient
 than defining a separate Builder object
 for a single special-case build.
-
+</para>
+
+<para>
 As a special case, the
 <varname>source_scanner</varname>
 keyword argument can
 that must be scanned on-disk for
 changes to files that aren't
 already specified in other Builder of function calls.)
-
+</para>
+
+<para>
 Any other keyword arguments specified override any
 same-named existing construction variables.
-
+</para>
+
+<para>
 An action can be an external command,
 specified as a string,
 or a callable Python object;
 <literal>-</literal>
 (hyphen)
 to ignore the exit status of the external command.
-
+</para>
+
+<para>
 Examples:
-
-<example>
+</para>
+
+<example_commands>
 env.Command('foo.out', 'foo.in',
             "$FOO_BUILD &lt; $SOURCES &gt; $TARGET")
 
 env.Command('baz.out', 'baz.in',
             ["$BAZ_BUILD &lt; $SOURCES &gt; .tmp",
 	     rename ])
-</example>
-
+</example_commands>
+
+<para>
 Note that the
 &f-Command;
 function will usually assume, by default,
 or
 <function>env.Dir</function>()
 functions.
-
+</para>
+
+<para>
 Examples:
-
-<example>
+</para>
+
+<example_commands>
 env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
 
 env['DISTDIR'] = 'destination/directory'
 env.Command(env.Dir('$DISTDIR')), None, make_distdir)
-</example>
-
+</example_commands>
+
+<para>
 (Also note that SCons will usually
 automatically create any directory necessary to hold a target file,
 so you normally don't need to create directories by hand.)
+</para>
 </summary>
 </scons_function>
 
 ([custom_tests, conf_dir, log_file, config_h])
 </arguments>
 <summary>
+<para>
 Creates a Configure object for integrated
 functionality similar to GNU autoconf.
 See the section "Configure Contexts,"
 below, for a complete explanation of the arguments and behavior.
+</para>
 </summary>
 </scons_function>
 
 ([key=val, ...])
 </arguments>
 <summary>
+<para>
 A now-deprecated synonym for
 <function>env.Clone</function>().
+</para>
 </summary>
 </scons_function>
 
 (function)
 </arguments>
 <summary>
+<para>
 Specifies that all up-to-date decisions for
 targets built through this construction environment
 will be handled by the specified
 can be one of the following strings
 that specify the type of decision function
 to be performed:
-
+</para>
+
+<para>
 <variablelist>
 <varlistentry>
 <term><literal>timestamp-newer</literal></term>
 </listitem>
 </varlistentry>
 </variablelist>
-
+</para>
+
+<para>
 Examples:
-
-<example>
+</para>
+
+<example_commands>
 # Use exact timestamp matches by default.
 Decider('timestamp-match')
 
 # Use MD5 content signatures for any targets built
 # with the attached construction environment.
 env.Decider('content')
-</example>
-
+</example_commands>
+
+<para>
 In addition to the above already-available functions,
 the
 <varname>function</varname>
 argument may be an actual Python function
 that takes the following three arguments:
-
+</para>
+
+<para>
 <variablelist>
 <varlistentry>
 <term><parameter>dependency</parameter></term>
 </listitem>
 </varlistentry>
 </variablelist>
-
+</para>
+
+<para>
 The
 <varname>function</varname>
 should return a
 using whatever criteria are appopriate.
 Ignoring some or all of the function arguments
 is perfectly normal.
-
+</para>
+
+<para>
 Example:
-
-<example>
+</para>
+
+<example_commands>
 def my_decider(dependency, target, prev_ni):
     return not os.path.exists(str(target))
 
 env.Decider(my_decider)
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 (target, dependency)
 </arguments>
 <summary>
+<para>
 Specifies an explicit dependency;
 the
 <varname>target</varname>
 for cases where the dependency
 is not caught by a Scanner
 for the file.
-
+</para>
+
+<para>
 Example:
-
-<example>
+</para>
+
+<example_commands>
 env.Depends('foo', 'other-input-file-for-foo')
 
 mylib = env.Library('mylib.c')
 # and $LIBPATH variables, not using an env.Depends() call.)
 
 env.Depends(bar, installed_lib)
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 ([vars])
 </arguments>
 <summary>
+<para>
 Returns a dictionary object
 containing copies of all of the
 construction variables in the environment.
 If there are any variable names specified,
 only the specified construction
 variables are returned in the dictionary.
-
+</para>
+
+<para>
 Example:
-
-<example>
+</para>
+
+<example_commands>
 dict = env.Dictionary()
 cc_dict = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 (name, [directory])
 </arguments>
 <summary>
+<para>
 This returns a Directory Node,
 an object that represents the specified directory
 <varname>name</varname>.
 If no
 <varname>directory</varname>
 is specified, the current script's directory is used as the parent.
-
+</para>
+
+<para>
 If
 <varname>name</varname>
 is a list, SCons returns a list of Dir nodes.
 Construction variables are expanded in
 <varname>name</varname>.
-
+</para>
+
+<para>
 Directory Nodes can be used anywhere you
 would supply a string as a directory name
 to a Builder method or function.
 Directory Nodes have attributes and methods
 that are useful in many situations;
 see "File and Directory Nodes," below.
+</para>
 </summary>
 </scons_function>
 
 ([key])
 </arguments>
 <summary>
+<para>
 Returns a pretty printable representation of the environment.
 <varname>key</varname>,
 if not
 <literal>None</literal>,
 should be a string containing the name of the variable of interest.
-
+</para>
+
+<para>
 This SConstruct:
-
-<example>
+</para>
+
+<example_commands>
 env=Environment()
 print env.Dump('CCCOM')
-</example>
-
+</example_commands>
+
+<para>
 will print:
-
-<example>
+</para>
+
+<example_commands>
 '$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES'
-</example>
-
+</example_commands>
+
+<para>
 While this SConstruct:
-
-<example>
+</para>
+
+<example_commands>
 env=Environment()
 print env.Dump()
-</example>
-
+</example_commands>
+
+<para>
 will print:
-<example>
+</para>
+<example_commands>
 { 'AR': 'ar',
   'ARCOM': '$AR $ARFLAGS $TARGET $SOURCES\n$RANLIB $RANLIBFLAGS $TARGET',
   'ARFLAGS': ['r'],
   'ASCOM': '$AS $ASFLAGS -o $TARGET $SOURCES',
   'ASFLAGS': [],
   ...
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 ([key=value, ...])
 </arguments>
 <summary>
+<para>
 Return a new construction environment
 initialized with the specified
 <varname>key</varname><literal>=</literal><varname>value</varname>
 pairs.
+</para>
 </summary>
 </scons_function>
 
 (action, [strfunction, varlist])
 </arguments>
 <summary>
+<para>
 Executes an Action object.
 The specified
 <varname>action</varname>
 The exit value of the command
 or return value of the Python function
 will be returned.
-
+</para>
+
+<para>
 Note that
 &scons;
 will print an error message if the executed
 &f-Execute;
 call,
 you must explicitly check for a non-zero return value:
-
-<example>
+</para>
+
+<example_commands>
 Execute(Copy('file.out', 'file.in'))
 
 if Execute("mkdir sub/dir/ectory"):
     # The mkdir failed, don't try to build.
     Exit(1)
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 (name, [directory])
 </arguments>
 <summary>
+<para>
 This returns a
 File Node,
 an object that represents the specified file
 can be a relative or absolute path.
 <varname>directory</varname>
 is an optional directory that will be used as the parent directory.
-
+</para>
+
+<para>
 If
 <varname>name</varname>
 is a list, SCons returns a list of File nodes.
 Construction variables are expanded in
 <varname>name</varname>.
-
+</para>
+
+<para>
 File Nodes can be used anywhere you
 would supply a string as a file name
 to a Builder method or function.
 File Nodes have attributes and methods
 that are useful in many situations;
 see "File and Directory Nodes," below.
+</para>
 </summary>
 </scons_function>
 
 (file, dirs)
 </arguments>
 <summary>
+<para>
 Search for
 <varname>file</varname>
 in the path specified by
 In addition to searching for files that exist in the filesystem,
 this function also searches for derived files
 that have not yet been built.
-
+</para>
+
+<para>
 Example:
-
-<example>
+</para>
+
+<example_commands>
 foo = env.FindFile('foo', ['dir1', 'dir2'])
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 ()
 </arguments>
 <summary>
+<para>
 Returns the list of targets set up by the
 &b-link-Install;
 or
 &b-link-InstallAs;
 builders.
-
+</para>
+
+<para>
 This function serves as a convenient method to select the contents of
 a binary package.
-
+</para>
+
+<para>
 Example:
-
-<example>
+</para>
+
+<example_commands>
 Install( '/bin', [ 'executable_a', 'executable_b' ] )
 
 # will return the file node list
 # will return the file node list
 # [ '/bin/executable_a', '/bin/executable_b', '/lib/some_library' ]
 FindInstalledFiles()
-</example>
+</example_commands>
 </summary>
 </scons_function>
 
 (node='"."')
 </arguments>
 <summary>
+<para>
 Returns the list of nodes which serve as the source of the built files.
 It does so by inspecting the dependency tree starting at the optional
 argument
 which defaults to the '"."'-node. It will then return all leaves of
 <varname>node</varname>.
 These are all children which have no further children.
-
+</para>
+
+<para>
 This function is a convenient method to select the contents of a Source
 Package.