Clean up some manpage duplication, File, Dir

Removed some dupes in the Construction Variables section -
the JAR entries plus File, Dir.

Tweaked the File and Dir function entries, and the
File and Directory Nodes section.

The end-to-end tests for File and Dir didn't test the case of
supplying a list-of-strings (thus returning a list-of-nodes)
to those two functions, added a primitive one.

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

5 files changed, 107 insertions, 182 deletions

diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index bd8d5f0..289d840 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -4383,20 +4383,17 @@ vars.AddVariables(
 
 </refsect2>
 
-<refsect2 id='file_and_directory_nodes'><title>File and Directory Nodes</title>
+<refsect2 id='file_and_directory_nodes'>
+<title>File and Directory Nodes</title>
 
-<para>The
-<emphasis>File</emphasis>()
-and
-<emphasis>Dir</emphasis>()
-functions return
-<emphasis>File</emphasis>
-and
-<emphasis>Dir</emphasis>
-Nodes, respectively.
-Python objects, respectively.
-Those objects have several user-visible attributes
-and methods that are often useful:</para>
+<para>
+The &f-link-File; and &f-link-Dir;
+functions/methods return
+File and Directory Nodes, respectively.
+Such nodes are Python objects with
+several user-visible attributes
+and methods that are often useful to access
+in SConscript files:</para>
 
 <variablelist>
   <varlistentry>
@@ -4412,33 +4409,31 @@ file is found).
 The build path is the same as the source path if
 <emphasis>variant_dir</emphasis>
 is not being used.</para>
-
   </listitem>
   </varlistentry>
+
   <varlistentry>
   <term>abspath</term>
   <listitem>
 <para>The absolute build path of the given file or directory.</para>
-
   </listitem>
   </varlistentry>
+
   <varlistentry>
   <term>srcnode()</term>
   <listitem>
 <para>The
 <emphasis>srcnode</emphasis>()
 method
-returns another
-<emphasis>File</emphasis>
-or
-<emphasis>Dir</emphasis>
-object representing the
-<emphasis>source</emphasis>
-path of the given
-<emphasis>File</emphasis>
-or
-<emphasis>Dir</emphasis>.
-The</para>
+returns another File or Directory Node
+representing the source path of the given
+File or Directory Node.
+</para>
+  </listitem>
+  </varlistentry>
+</variablelist>
+
+<para>For example:</para>
 
 <literallayout class="monospaced">
 # Get the current build dir's path, relative to top.
@@ -4451,98 +4446,90 @@ File('foo.c').srcnode().path   # source path of the given source file.
 
 # Builders also return File objects:
 foo = env.Program('foo.c')
-print("foo will be built in %s"%foo.path)
+print("foo will be built in", foo.path)
 </literallayout>
 
-<para>A
-<emphasis>Dir</emphasis>
-Node or
-<emphasis>File</emphasis>
-Node can also be used to create
-file and subdirectory Nodes relative to the generating Node.
-A
-<emphasis>Dir</emphasis>
-Node will place the new Nodes within the directory it represents.
-A
-<emphasis>File</emphasis>
-node will place the new Nodes within its parent directory
-(that is, "beside" the file in question).
-If
-<emphasis>d</emphasis>
-is a
-<emphasis>Dir</emphasis>
-(directory) Node and
-<emphasis>f</emphasis>
-is a
-<emphasis>File</emphasis>
-(file) Node,
-then these methods are available:</para>
+<para>
+Node objects have methods to create
+File and Directory Nodes relative to the orignal Node.
+</para>
+
+<para>
+If the object is a Directory Node,
+these methods will place the the new Node within the directory
+the Node represents:
+</para>
 
-  </listitem>
-  </varlistentry>
-</variablelist>
 <variablelist>
   <varlistentry>
-  <term><emphasis>d</emphasis>.Dir(<emphasis>name</emphasis>)</term>
+  <term><replaceable>d</replaceable>.Dir(<replaceable>name</replaceable>)</term>
   <listitem>
 <para>Returns a directory Node for a subdirectory of
-<emphasis>d</emphasis>
+<replaceable>d</replaceable>
 named
-<emphasis>name</emphasis>.</para>
-
+<replaceable>name</replaceable>.</para>
   </listitem>
   </varlistentry>
+
   <varlistentry>
-  <term><emphasis>d</emphasis>.File(<emphasis>name</emphasis>)</term>
+  <term><replaceable>d</replaceable>.File(<replaceable>name</replaceable>)</term>
   <listitem>
 <para>Returns a file Node for a file within
-<emphasis>d</emphasis>
+<replaceable>d</replaceable>
 named
-<emphasis>name</emphasis>.</para>
-
+<replaceable>name</replaceable>.</para>
   </listitem>
   </varlistentry>
+
   <varlistentry>
-  <term><emphasis>d</emphasis>.Entry(<emphasis>name</emphasis>)</term>
+  <term><replaceable>d</replaceable>.Entry(<replaceable>name</replaceable>)</term>
   <listitem>
 <para>Returns an unresolved Node within
-<emphasis>d</emphasis>
+<replaceable>d</replaceable>
 named
-<emphasis>name</emphasis>.</para>
-
+<replaceable>name</replaceable>.</para>
   </listitem>
   </varlistentry>
+</variablelist>
+
+<para>
+If the object is a File Node,
+these methods will place the the new Node in the same
+directory as the one the Node represents:
+</para>
+
+<variablelist>
   <varlistentry>
-  <term><emphasis>f</emphasis>.Dir(<emphasis>name</emphasis>)</term>
+  <term><replaceable>d</replaceable>.Dir(<replaceable>name</replaceable>)</term>
   <listitem>
 <para>Returns a directory named
-<emphasis>name</emphasis>
+<replaceable>name</replaceable>
 within the parent directory of
-<emphasis>f</emphasis>.</para>
-
+<replaceable>f</replaceable>.</para>
   </listitem>
   </varlistentry>
+
   <varlistentry>
-  <term><emphasis>f</emphasis>.File(<emphasis>name</emphasis>)</term>
+  <term><replaceable>d</replaceable>.File(<replaceable>name</replaceable>)</term>
   <listitem>
 <para>Returns a file named
-<emphasis>name</emphasis>
+<replaceable>name</replaceable>
 within the parent directory of
-<emphasis>f</emphasis>.</para>
-
+<replaceable>f</replaceable>.</para>
   </listitem>
   </varlistentry>
+
   <varlistentry>
-  <term><emphasis>f</emphasis>.Entry(<emphasis>name</emphasis>)</term>
+  <term><replaceable>d</replaceable>.Entry(<replaceable>name</replaceable>)</term>
   <listitem>
 <para>Returns an unresolved Node named
-<emphasis>name</emphasis>
+<replaceable>name</replaceable>
 within the parent directory of
-<emphasis>f</emphasis>.</para>
-
+<replaceable>f</replaceable>.</para>
   </listitem>
   </varlistentry>
 </variablelist>
+
 <para>For example:</para>
 
 <literallayout class="monospaced">
@@ -5923,7 +5910,7 @@ action='$CC -c -o $TARGET $SOURCES'
 cc -c -o foo foo.c bar.c
 </literallayout>
 
-<para>Variable names may be surrounded by curly braces 
+<para>Variable names may be surrounded by curly braces
 <emphasis role="bold">{ }</emphasis>
 to separate the name from surrounding characters which
 are not part of the name.
@@ -7200,7 +7187,7 @@ in addition to those passed on the command line.</para>
     <listitem>
 <para>(Windows only). If set, save the shell environment variables
 generated when setting up the Microsoft Visual C++ compiler
-(and/or Build Tools) to a file to give these settings, 
+(and/or Build Tools) to a file to give these settings,
 which are expensive to generate, persistence
 across &scons; invocations.
 Use of this option is primarily intended to aid performance
diff --git a/src/engine/SCons/Environment.xml b/src/engine/SCons/Environment.xml
index 35e4bd8..286e882 100644
--- a/src/engine/SCons/Environment.xml
+++ b/src/engine/SCons/Environment.xml
@@ -65,15 +65,6 @@ env['BUILDERS']['NewBuilder'] = foo
 </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>
@@ -130,15 +121,6 @@ env = Environment(ENV = {'PATH' : os.environ['PATH']})
 </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>
@@ -1351,11 +1333,10 @@ cc_values = env.Dictionary('CC', 'CCFLAGS', 'CCCOM')
 </arguments>
 <summary>
 <para>
-This returns a Directory Node,
-an object that represents the specified directory
-<varname>name</varname>.
+Returns Directory Node(s).
+A Directory Node is an object that represents a directory.
 <varname>name</varname>
-can be a relative or absolute path.
+can be a relative or absolute path or a list of such paths.
 <varname>directory</varname>
 is an optional directory that will be used as the parent directory.
 If no
@@ -1366,7 +1347,10 @@ is specified, the current script's directory is used as the parent.
 <para>
 If
 <varname>name</varname>
-is a list, SCons returns a list of Dir nodes.
+is a single pathname, the corresponding node is returned.
+If
+<varname>name</varname>
+is a list, SCons returns a list of nodes.
 Construction variables are expanded in
 <varname>name</varname>.
 </para>
@@ -1511,20 +1495,24 @@ if Execute("mkdir sub/dir/ectory"):
 </arguments>
 <summary>
 <para>
-This returns a
-File Node,
-an object that represents the specified file
-<varname>name</varname>.
+Returns File Node(s).
+A File Node is an object that represents a file.
 <varname>name</varname>
-can be a relative or absolute path.
+can be a relative or absolute path or a list of such paths.
 <varname>directory</varname>
 is an optional directory that will be used as the parent directory.
+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 File nodes.
+is a single pathname, the corresponding node is returned.
+If
+<varname>name</varname>
+is a list, SCons returns a list of nodes.
 Construction variables are expanded in
 <varname>name</varname>.
 </para>
diff --git a/src/engine/SCons/Tool/packaging.xml b/src/engine/SCons/Tool/packaging.xml
index 8ab4912..55fecec 100644
--- a/src/engine/SCons/Tool/packaging.xml
+++ b/src/engine/SCons/Tool/packaging.xml
@@ -34,7 +34,7 @@ A framework for building binary and source packages.
 <builder name="Package">
 <summary>
 <para>
-Builds a Binary Package of the given source files. 
+Builds a Binary Package of the given source files.
 </para>
 
 <example_commands>
@@ -43,68 +43,4 @@ env.Package(source = FindInstalledFiles())
 </summary>
 </builder>
 
-<cvar name="JAR">
-<summary>
-<para>
-The Java archive tool.
-</para>
-</summary>
-</cvar>
-
-<cvar name="JARCHDIR">
-<summary>
-<para>
-The directory to which the Java archive tool should change
-(using the
-<option>-C</option>
-option).
-</para>
-</summary>
-</cvar>
-
-<cvar name="JARCOM">
-<summary>
-<para>
-The command line used to call the Java archive tool.
-</para>
-</summary>
-</cvar>
-
-<cvar name="JARCOMSTR">
-<summary>
-<para>
-The string displayed when the Java archive tool
-is called
-If this is not set, then &cv-JARCOM; (the command line) is displayed.
-</para>
-
-<example_commands>
-env = Environment(JARCOMSTR = "JARchiving $SOURCES into $TARGET")
-</example_commands>
-</summary>
-</cvar>
-
-<cvar name="JARFLAGS">
-<summary>
-<para>
-General options passed to the Java archive tool.
-By default this is set to
-<option>cf</option>
-to create the necessary
-<command>jar</command>
-file.
-</para>
-</summary>
-</cvar>
-
-<cvar name="JARSUFFIX">
-<summary>
-<para>
-The suffix for Java archives:
-<filename>.jar</filename>
-by default.
-</para>
-</summary>
-</cvar>
-
 </sconsdoc>
diff --git a/test/Dir/Dir.py b/test/Dir/Dir.py
index e726b94..42a48f3 100644
--- a/test/Dir/Dir.py
+++ b/test/Dir/Dir.py
@@ -36,28 +36,34 @@ test = TestSCons.TestSCons()
 
 test.write('SConstruct', """
 DefaultEnvironment(tools=[])
-env = Environment(tools=[], FOO = 'fff', BAR = 'bbb')
+env = Environment(tools=[], FOO='fff', BAR='bbb')
 print(Dir('ddd'))
 print(Dir('$FOO'))
 print(Dir('${BAR}_$BAR'))
+rv = Dir(['mmm', 'nnn'])
+rv_msg = [node.path for node in rv]
+print(rv_msg)
 print(env.Dir('eee'))
 print(env.Dir('$FOO'))
 print(env.Dir('${BAR}_$BAR'))
+rv = env.Dir(['ooo', 'ppp'])
+rv_msg = [node.path for node in rv]
+print(rv_msg)
 """)
 
-test.run(stdout = test.wrap_stdout(read_str = """\
+test.run(stdout=test.wrap_stdout(read_str="""\
 ddd
 $FOO
 ${BAR}_$BAR
+['mmm', 'nnn']
 eee
 fff
 bbb_bbb
-""", build_str = """\
+['ooo', 'ppp']
+""", build_str="""\
 scons: `.' is up to date.
 """))
 
-
-
 test.write('SConstruct', """\
 DefaultEnvironment(tools=[])
 import os
@@ -66,7 +72,7 @@ def my_mkdir(target=None, source=None, env=None):
 
 MDBuilder = Builder(action=my_mkdir, target_factory=Dir)
 env = Environment(tools=[])
-env.Append(BUILDERS = {'MD':MDBuilder})
+env.Append(BUILDERS={'MD': MDBuilder})
 env.MD(target='sub1', source=['SConstruct'])
 env.MD(target='sub2', source=['SConstruct'], OVERRIDE='foo')
 """)
diff --git a/test/File.py b/test/File.py
index ec148b2..bde4449 100644
--- a/test/File.py
+++ b/test/File.py
@@ -37,13 +37,19 @@ import TestSCons
 test = TestSCons.TestSCons()
 
 test.write('SConstruct', """
-env = Environment(FOO = 'fff', BAR = 'bbb')
+env = Environment(FOO='fff', BAR='bbb')
 print(File('ddd'))
 print(File('$FOO'))
 print(File('${BAR}_$BAR'))
+rv = File(['mmm', 'nnn'])
+rv_msg = [node.path for node in rv]
+print(rv_msg)
 print(env.File('eee'))
 print(env.File('$FOO'))
 print(env.File('${BAR}_$BAR'))
+rv = env.File(['ooo', 'ppp'])
+rv_msg = [node.path for node in rv]
+print(rv_msg)
 f1 = env.File('f1')
 print(f1)
 f2 = f1.File('f2')
@@ -54,16 +60,18 @@ expect = test.wrap_stdout(read_str = """\
 ddd
 $FOO
 ${BAR}_$BAR
+['mmm', 'nnn']
 eee
 fff
 bbb_bbb
+['ooo', 'ppp']
 f1
 f2
-""", build_str = """\
+""", build_str="""\
 scons: `.' is up to date.
 """)
 
-test.run(stdout = expect)
+test.run(stdout=expect)
 
 test.pass_test()