From 9c08098a9522379f50983e9f54eda769db351513 Mon Sep 17 00:00:00 2001 From: stevenknight Date: Mon, 5 Apr 2010 05:06:48 +0000 Subject: [PATCH] Fix XML in documentation, and in the bin/scons-doc.py script that generates the User's Guide XML from the .in files' SGML. git-svn-id: http://scons.tigris.org/svn/scons/trunk@4767 fdb21ef1-2011-0410-befe-b5e4ea1792b1 --- 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 03c66fa5..f7a3a232 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 1a1e3354..afe98771 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 2a7b69b5..f2e6b7c7 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 8cdd867d..c665e0c1 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 38e42585..266c9e81 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 5784cee3..39ef93a0 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 294180ba..45b49181 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 cb58af97..0dd5faaf 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 42bc4af2..e061b90a 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 f1b24798..6b049be7 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 c1e56166..d2a3dad8 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 04178b0d..ea76eb9d 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 2c5cce24..2410831e 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 3932181b..99dfc94e 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 6834d2a8..f26f2c7d 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 148922eb..f5e70ad7 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 afd1463c..7bb9d01e 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 563d6353..8f62b3bf 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 09533d24..e5aadec2 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 a3339e03..ffc37fcf 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 9749e432..e1c1f0a2 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: -- 2.26.2