From cecfaa2e2679b340ba45af9ad25ac1d4e87f91af Mon Sep 17 00:00:00 2001 From: Steven Knight Date: Mon, 5 Apr 2010 05:06:48 +0000 Subject: Fix XML in documentation, and in the bin/scons-doc.py script that generates the User's Guide XML from the .in files' SGML. --- bin/scons-doc.py | 26 +++++++++++----------- doc/design/engine.xml | 12 +++++------ doc/design/goals.xml | 2 +- doc/design/native.xml | 6 +++--- doc/design/overview.xml | 2 +- doc/developer/preface.xml | 2 +- doc/python10/abstract.xml | 2 +- doc/python10/design.xml | 50 +++++++++++++++++++++---------------------- doc/python10/main.xml | 2 +- doc/python10/process.xml | 2 +- doc/user/actions.in | 4 ++-- doc/user/actions.xml | 4 ++-- doc/user/builders-writing.in | 30 +++++++++++++------------- doc/user/builders-writing.xml | 12 +++++------ doc/user/command-line.in | 4 ++-- doc/user/command-line.xml | 4 ++-- doc/user/environments.in | 2 +- doc/user/environments.xml | 2 +- doc/user/parseflags.xml | 2 +- doc/user/troubleshoot.xml | 2 +- src/CHANGES.txt | 7 ++++++ 21 files changed, 94 insertions(+), 85 deletions(-) diff --git a/bin/scons-doc.py b/bin/scons-doc.py index 03c66fa..f7a3a23 100644 --- a/bin/scons-doc.py +++ b/bin/scons-doc.py @@ -204,7 +204,7 @@ Sep = { orig = SCons.Node.FS.EntryProxy class MyEntryProxy(orig): def __str__(self): - return string.replace(str(self._Proxy__subject), os.sep, Sep) + return str(self._Proxy__subject).replace(os.sep, Sep) SCons.Node.FS.EntryProxy = MyEntryProxy # Slip our own RDirs() method into the Node.FS.File class so that the @@ -213,8 +213,7 @@ SCons.Node.FS.EntryProxy = MyEntryProxy # running on to what's appropriate for the example system. orig_RDirs = SCons.Node.FS.File.RDirs def my_RDirs(self, pathlist, orig_RDirs=orig_RDirs): - return map(lambda x: string.replace(str(x), os.sep, Sep), - orig_RDirs(self, pathlist)) + return [str(x).replace(os.sep, Sep) for x in orig_RDirs(self, pathlist)] SCons.Node.FS.File.RDirs = my_RDirs class Curry: @@ -235,8 +234,8 @@ class Curry: def Str(target, source, env, cmd=""): result = [] for cmd in env.subst_list(cmd, target=target, source=source): - result.append(string.join(map(str, cmd))) - return string.join(result, '\\n') + result.append(' '.join(map(str, cmd))) + return '\\n'.join(result) class ToolSurrogate: def __init__(self, tool, variable, func, varlist): @@ -379,7 +378,7 @@ ToolList = { } toollist = ToolList[platform] -filter_tools = string.split('%(tools)s') +filter_tools = '%(tools)s'.split() if filter_tools: toollist = [x for x in toollist if x[0] in filter_tools] @@ -564,6 +563,12 @@ class MySGML(sgmllib.SGMLParser): # Here is where the heavy lifting begins. The following methods # handle the begin-end tags of our SCons examples. + def for_display(self, contents): + contents = contents.replace('__ROOT__', '') + contents = contents.replace('<', '<') + contents = contents.replace('>', '>') + return contents + def start_scons_example(self, attrs): t = [t for t in attrs if t[0] == 'name'] if t: @@ -589,9 +594,7 @@ class MySGML(sgmllib.SGMLParser): i = len(f.data) - 1 while f.data[i] == ' ': i = i - 1 - output = f.data[:i+1].replace('__ROOT__', '') - output = output.replace('<', '<') - output = output.replace('>', '>') + output = self.for_display(f.data[:i+1]) self.outfp.write(output) if e.data and e.data[0] == '\n': e.data = e.data[1:] @@ -773,8 +776,7 @@ class MySGML(sgmllib.SGMLParser): content = engine_re.sub(r' File "bootstrap/src/engine/SCons/', content) content = file_re.sub(r'\1 ', content) content = nodelist_re.sub(r"\1 'NodeList' object \2", content) - content = content.replace('<', '<') - content = content.replace('>', '>') + content = self.for_display(content) self.outfp.write(p + content + '\n') if o.data[0] == '\n': @@ -811,7 +813,7 @@ class MySGML(sgmllib.SGMLParser): def end_sconstruct(self): f = self.f self.outfp.write('') - output = f.data.replace('__ROOT__', '') + output = self.for_display(f.data) self.outfp.write(output + '') delattr(self, 'f') self.afunclist = self.afunclist[:-1] diff --git a/doc/design/engine.xml b/doc/design/engine.xml index 1a1e335..afe9877 100644 --- a/doc/design/engine.xml +++ b/doc/design/engine.xml @@ -85,7 +85,7 @@
- &ConsEnvs + &ConsEnvs; @@ -129,7 +129,7 @@ It would be nice if we could avoid re-inventing the wheel here by - using some other Python-based tool &Autoconf replacement--like what + using some other Python-based tool &Autoconf; replacement--like what was supposed to come out of the Software Carpentry configuration tool contest. It will probably be most efficient to roll our own logic initially and convert if something better does come along. @@ -283,7 +283,7 @@ MyBuilder = Builder(command = "$XX $XXFLAGS -c $_INPUTS -o $target") env.Command(targets = 'bar.out', sources = 'bar.in', - command = "sed '1d' < $source > $target") + command = "sed '1d' < $source > $target") @@ -317,7 +317,7 @@ env = Environment(FUNC = myfunc) env.Command(target = 'foo.out', source = 'foo.in', - command = "${FUNC($<)}") + command = "${FUNC($<)}") @@ -1678,8 +1678,8 @@ I dunno, maybe this is fine as it is... target (that is, one passed to the &Build; or &Clean; method). Objects which a top-level target is directly dependent upon have a - level of <1>, their direct dependencies have a - level of <2>, etc. Typically used to indent + level of <1>, their direct dependencies have a + level of <2>, etc. Typically used to indent output to reflect the recursive levels. diff --git a/doc/design/goals.xml b/doc/design/goals.xml index 2a7b69b..f2e6b7c 100644 --- a/doc/design/goals.xml +++ b/doc/design/goals.xml @@ -26,7 +26,7 @@ As a next-generation build tool, - &SCons should fundamentally + &SCons; should fundamentally improve on its predecessors. Rather than simply being driven by trying to not be like previous tools, diff --git a/doc/design/native.xml b/doc/design/native.xml index 8cdd867..c665e0c 100644 --- a/doc/design/native.xml +++ b/doc/design/native.xml @@ -52,7 +52,7 @@ By default, the &SCons; utility searches for a file named - &SConstruct;, &Sconstruct; or &sconstruct (in that order) in the + &SConstruct;, &Sconstruct; or &sconstruct; (in that order) in the current directory, and reads its configuration from the first file found. A command-line option exists to read a different file name. @@ -175,7 +175,7 @@ Any variables (not just &SCons; objects) that are to be shared between configuration files must be explicitly passed in the &SConscript; call - using the &Export method: + using the &Export; method: @@ -261,7 +261,7 @@ Equivalent to the above example: - &SCons; will allow users to share &consenvs, as well as other &SCons; + &SCons; will allow users to share &consenvs;, as well as other &SCons; objects and Python variables, by importing them from a central, shared repository using normal Python syntax: diff --git a/doc/design/overview.xml b/doc/design/overview.xml index 38e4258..266c9e8 100644 --- a/doc/design/overview.xml +++ b/doc/design/overview.xml @@ -409,7 +409,7 @@ This is where it will go, anyway... An alternate &SCons; interface would provide backwards - compatibility with the classic &Make utility. + compatibility with the classic &Make; utility. This would be done by embedding the &SCons; Build Engine in a Python script that can translate existing &Makefile;s into the underlying calls to the diff --git a/doc/developer/preface.xml b/doc/developer/preface.xml index 5784cee..39ef93a 100644 --- a/doc/developer/preface.xml +++ b/doc/developer/preface.xml @@ -36,7 +36,7 @@ There are a few overriding principles - we try to live up to in designing and implementing &SCons: + we try to live up to in designing and implementing &SCons;: diff --git a/doc/python10/abstract.xml b/doc/python10/abstract.xml index 294180b..45b4918 100644 --- a/doc/python10/abstract.xml +++ b/doc/python10/abstract.xml @@ -3,7 +3,7 @@ &SCons; is a software construction tool (build tool, or make tool) implemented in Python, which uses Python scripts as "configuration files" for software builds. Based on the design which won the - Software Carpentry build tool competition, &SCons solves a number of + Software Carpentry build tool competition, &SCons; solves a number of problems associated with other build tools, especially including the classic and ubiquitous &Make; itself. diff --git a/doc/python10/design.xml b/doc/python10/design.xml index cb58af9..0dd5faa 100644 --- a/doc/python10/design.xml +++ b/doc/python10/design.xml @@ -6,14 +6,14 @@ - + - + @@ -166,14 +166,14 @@ - + - + @@ -230,14 +230,14 @@ - + - + @@ -264,7 +264,7 @@ signature information for &Node; objects. The signature subsystem in &SCons; supports multiple ways to - determine whether a &Node is up-to-date + determine whether a &Node; is up-to-date by using an abstract &Sig; class as a strategy wrapper: @@ -272,14 +272,14 @@ - + - + @@ -328,14 +328,14 @@ - + - + @@ -391,14 +391,14 @@ - + - + @@ -435,7 +435,7 @@ - The &Taskmaster uses the node subsystem's + The &Taskmaster; uses the node subsystem's &Walker; class to walk the dependency tree, and the &Sig; class to use the appropriate method @@ -629,8 +629,8 @@ &Builder; objects are associated with a &consenv; through a - &consvar; named &BUILDERS;, a list of the &Builder objects that - will be available for execution through the &consenv: + &consvar; named &BUILDERS;, a list of the &Builder; objects that + will be available for execution through the &consenv;: @@ -679,7 +679,7 @@ &Scanner; objects are associated with a &consenv; through a &consvar; named &SCANNERS;, a list of the &Scanner; objects that - will be available through the &consenv: + will be available through the &consenv;: @@ -818,10 +818,10 @@ The most noticeable difference between &scons; and &Make;, or most other build tools, is that the configuration files are actually Python scripts, generically called "SConscripts" (although the - top-level "Makefile" is named &SConstruct). Users do not have to + top-level "Makefile" is named &SConstruct;). Users do not have to learn a new language syntax, but instead configure dependency information by making direct calls to the Python API of the - &SCons; Build Engine. Here is an example &SConstruct file which + &SCons; Build Engine. Here is an example &SConstruct; file which builds a program in side-by-side normal and debug versions: diff --git a/doc/python10/main.xml b/doc/python10/main.xml index 42bc4af..e061b90 100644 --- a/doc/python10/main.xml +++ b/doc/python10/main.xml @@ -182,7 +182,7 @@ O'Reilly & Associates, Inc. - O'Reilly & Associates, Inc. + O'Reilly & Associates, Inc. Managing Projects with Make, 2nd Ed. diff --git a/doc/python10/process.xml b/doc/python10/process.xml index f1b2479..6b049be 100644 --- a/doc/python10/process.xml +++ b/doc/python10/process.xml @@ -181,7 +181,7 @@ - In practice, these restrictions can be overridden as necessary­for + In practice, these restrictions can be overridden as necessary--for example, when changing comments or documentation. diff --git a/doc/user/actions.in b/doc/user/actions.in index c1e5616..d2a3dad 100644 --- a/doc/user/actions.in +++ b/doc/user/actions.in @@ -245,7 +245,7 @@ solutions to the above limitations. - b = Builder(action = 'build < $SOURCE > $TARGET') + b = Builder(action = 'build < $SOURCE > $TARGET') @@ -255,7 +255,7 @@ solutions to the above limitations. - b = Builder(action = Action('build < $SOURCE > $TARGET')) + b = Builder(action = Action('build < $SOURCE > $TARGET')) diff --git a/doc/user/actions.xml b/doc/user/actions.xml index 04178b0..ea76eb9 100644 --- a/doc/user/actions.xml +++ b/doc/user/actions.xml @@ -245,7 +245,7 @@ solutions to the above limitations. - b = Builder(action = 'build < $SOURCE > $TARGET') + b = Builder(action = 'build < $SOURCE > $TARGET') @@ -255,7 +255,7 @@ solutions to the above limitations. - b = Builder(action = Action('build < $SOURCE > $TARGET')) + b = Builder(action = Action('build < $SOURCE > $TARGET')) diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in index 2c5cce2..2410831 100644 --- a/doc/user/builders-writing.in +++ b/doc/user/builders-writing.in @@ -129,7 +129,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') @@ -165,7 +165,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) import os env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() @@ -180,7 +180,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) @@ -276,7 +276,7 @@ This functionality could be invoked as in the following example: env = Environment() import os env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env.Append(BUILDERS = {'Foo' : bld}) env.Foo('file.foo', 'file.input') env.Program('hello.c') @@ -294,7 +294,7 @@ This functionality could be invoked as in the following example: env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env.Append(BUILDERS = {'Foo' : bld}) env.Foo('file.foo', 'file.input') env.Program('hello.c') @@ -309,7 +309,7 @@ This functionality could be invoked as in the following example: env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env['BUILDERS']['Foo'] = bld env.Foo('file.foo', 'file.input') env.Program('hello.c') @@ -352,7 +352,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + bld = Builder(action = 'foobuild < $SOURCE > $TARGET', suffix = '.foo', src_suffix = '.input') env = Environment(BUILDERS = {'Foo' : bld}) @@ -373,7 +373,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + bld = Builder(action = 'foobuild < $SOURCE > $TARGET', suffix = '.foo', src_suffix = '.input') env = Environment(BUILDERS = {'Foo' : bld}) @@ -544,7 +544,7 @@ This functionality could be invoked as in the following example: def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (target[0], source[0]) + return 'foobuild < %s > %s' % (target[0], source[0]) @@ -647,7 +647,7 @@ This functionality could be invoked as in the following example: def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (source[0], target[0]) + return 'foobuild < %s > %s' % (source[0], target[0]) bld = Builder(generator = generate_actions, suffix = '.foo', src_suffix = '.input') @@ -666,7 +666,7 @@ This functionality could be invoked as in the following example: def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (source[0], target[0]) + return 'foobuild < %s > %s' % (source[0], target[0]) bld = Builder(generator = generate_actions, suffix = '.foo', src_suffix = '.input') @@ -790,7 +790,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'my_command $SOURCES > $TARGET', + bld = Builder(action = 'my_command $SOURCES > $TARGET', suffix = '.foo', src_suffix = '.input', emitter = '$MY_EMITTER') @@ -828,7 +828,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'my_command $SOURCES > $TARGET', + bld = Builder(action = 'my_command $SOURCES > $TARGET', suffix = '.foo', src_suffix = '.input', emitter = '$MY_EMITTER') @@ -934,8 +934,8 @@ This functionality could be invoked as in the following example: def TOOL_ADD_HEADER(env): """A Tool to add a header from $HEADER to the source file""" - add_header = Builder(action=['echo "$HEADER" > $TARGET', - 'cat $SOURCE >> $TARGET']) + add_header = Builder(action=['echo "$HEADER" > $TARGET', + 'cat $SOURCE >> $TARGET']) env.Append(BUILDERS = {'AddHeader' : add_header}) env['HEADER'] = '' # set default value diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index 3932181..99dfc94 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -166,7 +166,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env = Environment(BUILDERS = {'Foo' : bld}) @@ -251,7 +251,7 @@ This functionality could be invoked as in the following example: env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env.Append(BUILDERS = {'Foo' : bld}) env.Foo('file.foo', 'file.input') env.Program('hello.c') @@ -266,7 +266,7 @@ This functionality could be invoked as in the following example: env = Environment() - bld = Builder(action = 'foobuild < $SOURCE > $TARGET') + bld = Builder(action = 'foobuild < $SOURCE > $TARGET') env['BUILDERS']['Foo'] = bld env.Foo('file.foo', 'file.input') env.Program('hello.c') @@ -313,7 +313,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'foobuild < $SOURCE > $TARGET', + bld = Builder(action = 'foobuild < $SOURCE > $TARGET', suffix = '.foo', src_suffix = '.input') env = Environment(BUILDERS = {'Foo' : bld}) @@ -586,7 +586,7 @@ This functionality could be invoked as in the following example: def generate_actions(source, target, env, for_signature): - return 'foobuild < %s > %s' % (source[0], target[0]) + return 'foobuild < %s > %s' % (source[0], target[0]) bld = Builder(generator = generate_actions, suffix = '.foo', src_suffix = '.input') @@ -708,7 +708,7 @@ This functionality could be invoked as in the following example: - bld = Builder(action = 'my_command $SOURCES > $TARGET', + bld = Builder(action = 'my_command $SOURCES > $TARGET', suffix = '.foo', src_suffix = '.input', emitter = '$MY_EMITTER') diff --git a/doc/user/command-line.in b/doc/user/command-line.in index 6834d2a..f26f2c7 100644 --- a/doc/user/command-line.in +++ b/doc/user/command-line.in @@ -1237,7 +1237,7 @@ choices to a specific set of allowed colors. This can be set up quite easily using the &EnumVariable;, - which takes a list of &allowed_values + which takes a list of &allowed_values; in addition to the variable name, default value, and help text arguments: @@ -2154,7 +2154,7 @@ &SCons; supports a &DEFAULT_TARGETS; variable that lets you get at the current list of default targets. - The &DEFAULT_TARGETS variable has + The &DEFAULT_TARGETS; variable has two important differences from the &COMMAND_LINE_TARGETS; variable. First, the &DEFAULT_TARGETS; variable is a list of internal &SCons; nodes, diff --git a/doc/user/command-line.xml b/doc/user/command-line.xml index 148922e..f5e70ad 100644 --- a/doc/user/command-line.xml +++ b/doc/user/command-line.xml @@ -1208,7 +1208,7 @@ choices to a specific set of allowed colors. This can be set up quite easily using the &EnumVariable;, - which takes a list of &allowed_values + which takes a list of &allowed_values; in addition to the variable name, default value, and help text arguments: @@ -2064,7 +2064,7 @@ &SCons; supports a &DEFAULT_TARGETS; variable that lets you get at the current list of default targets. - The &DEFAULT_TARGETS variable has + The &DEFAULT_TARGETS; variable has two important differences from the &COMMAND_LINE_TARGETS; variable. First, the &DEFAULT_TARGETS; variable is a list of internal &SCons; nodes, diff --git a/doc/user/environments.in b/doc/user/environments.in index afd1463..7bb9d01 100644 --- a/doc/user/environments.in +++ b/doc/user/environments.in @@ -1553,7 +1553,7 @@ environment, of directory names, suffixes, etc. #!/usr/bin/env python import os import sys - if len(sys.argv) > 1: + if len(sys.argv) > 1: keys = sys.argv[1:] else: keys = sorted(os.environ.keys()) diff --git a/doc/user/environments.xml b/doc/user/environments.xml index 563d635..8f62b3b 100644 --- a/doc/user/environments.xml +++ b/doc/user/environments.xml @@ -1540,7 +1540,7 @@ environment, of directory names, suffixes, etc. #!/usr/bin/env python import os import sys - if len(sys.argv) > 1: + if len(sys.argv) > 1: keys = sys.argv[1:] else: keys = sorted(os.environ.keys()) diff --git a/doc/user/parseflags.xml b/doc/user/parseflags.xml index 09533d2..e5aadec 100644 --- a/doc/user/parseflags.xml +++ b/doc/user/parseflags.xml @@ -155,7 +155,7 @@ env = Environment() d = env.ParseFlags(["!echo -I/opt/include", "!echo -L/opt/lib", "-lfoo"]) - for k,v in l: + for k,v in sorted(d.items()): if v: print k, v env.MergeFlags(d) diff --git a/doc/user/troubleshoot.xml b/doc/user/troubleshoot.xml index a3339e0..ffc37fc 100644 --- a/doc/user/troubleshoot.xml +++ b/doc/user/troubleshoot.xml @@ -1118,7 +1118,7 @@ % scons -Q --debug=stacktrace scons: *** [prog.o] Source `prog.c' not found, needed by target `prog.o'. scons: internal stack trace: - File "bootstrap/src/engine/SCons/Job.py", line 197, in start + File "bootstrap/src/engine/SCons/Job.py", line 199, in start task.prepare() File "bootstrap/src/engine/SCons/Script/Main.py", line 167, in prepare return SCons.Taskmaster.OutOfDateTask.prepare(self) diff --git a/src/CHANGES.txt b/src/CHANGES.txt index 9749e43..e1c1f0a 100644 --- a/src/CHANGES.txt +++ b/src/CHANGES.txt @@ -7,6 +7,13 @@ Change Log +RELEASE X.X.X - + + From Dirk Baechle: + + - Fix XML in documentation. + + RELEASE 1.3.0 - Tue, 23 Mar 2010 21:44:19 -0400 From Steven Knight: -- cgit v0.12