Rename some doc files; Packaging doc fixups [skip appveyor]

Renamed those documentation files named __init__.xml to the name of the
component directory.

Merged SCons/Tool/packaging.xml (which had no unique content) into
the renamed SCons/Tool/packaging/packaging.xml

Considerable rework was needed to the packaging content to
fill in some gaps:
* properly named the commandline option
* add the option to the manpage (with a note it's not always avail)
* only list the packagers once
* add example of selecting packaging tool, and of specifying multiple packagers
* more description of source, target and metadata for Packaging
* mention use of PACKAGEROOT
* redo tag description
* add a bit of explanation to the complete packaging example

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

7 files changed, 106 insertions, 108 deletions

diff --git a/SCons/Platform/__init__.xml b/SCons/Platform/Platform.xml
index 6582590..6582590 100644
--- a/SCons/Platform/__init__.xml
+++ b/SCons/Platform/Platform.xml
diff --git a/SCons/Scanner/__init__.xml b/SCons/Scanner/Scanner.xml
index 4f96d39..4f96d39 100644
--- a/SCons/Scanner/__init__.xml
+++ b/SCons/Scanner/Scanner.xml
diff --git a/SCons/Tool/__init__.xml b/SCons/Tool/Tool.xml
index b9aeb0d..b9aeb0d 100644
--- a/SCons/Tool/__init__.xml
+++ b/SCons/Tool/Tool.xml
diff --git a/SCons/Tool/docbook/__init__.xml b/SCons/Tool/docbook/docbook.xml
index 4c079b7..4c079b7 100644
--- a/SCons/Tool/docbook/__init__.xml
+++ b/SCons/Tool/docbook/docbook.xml
diff --git a/SCons/Tool/packaging.xml b/SCons/Tool/packaging.xml
deleted file mode 100644
index c2b7087..0000000
--- a/SCons/Tool/packaging.xml
+++ /dev/null
@@ -1,46 +0,0 @@
-<?xml version="1.0"?>
-<!--
-__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 http://www.scons.org/dbxsd/v1.0/scons.xsd">
-
-<tool name="packaging">
-<summary>
-<para>
-A framework for building binary and source packages.
-</para>
-</summary>
-</tool>
-
-<builder name="Package">
-<summary>
-<para>
-Builds a Binary Package of the given source files.
-</para>
-
-<example_commands>
-env.Package(source = FindInstalledFiles())
-</example_commands>
-</summary>
-</builder>
-
-</sconsdoc>
diff --git a/SCons/Tool/packaging/__init__.xml b/SCons/Tool/packaging/packaging.xml
index 03fd3e9..cb796b1 100644
--- a/SCons/Tool/packaging/__init__.xml
+++ b/SCons/Tool/packaging/packaging.xml
@@ -23,10 +23,12 @@ See its __doc__ string for a discussion of the format.
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
 
-<tool name="Packaging">
+<tool name="packaging">
 <summary>
 <para>
 Sets construction variables for the &b-Package; Builder.
+If this tool is enabled, the <option>--package-type</option>
+command-line option is also enabled.
 </para>
 </summary>
 <sets>
@@ -39,50 +41,78 @@ Sets construction variables for the &b-Package; Builder.
 <summary>
 <para>
 Builds software distribution packages.
-Packages consist of files to install and packaging information.
-The former may be specified with the &source; parameter and may be left out,
-in which case the &FindInstalledFiles; function will collect
-all files that have an &b-Install; or &b-InstallAs; Builder attached.
-If the &target; is not specified
-it will be deduced from additional information given to this Builder.
+A <firstterm>Package</firstterm> is a container format which
+includes files to install along with metadata.
+Packaging is optional, and must be enabled by specifying
+the &t-link-packaging; tool. For example:
 </para>
 
+<example_commands>
+env = Environment(tools=['default', 'packaging'])
+</example_commands>
+
+<para>
+&SCons; can build packages in a number of well known packaging formats.
+The target package type may be selected with the
+the &cv-link-PACKAGETYPE; construction variable
+or the <option>--package-type</option> command line option.
+The package type may be a list, in which case &SCons; will attempt
+to build packages for each type in the list. Example:
+</para>
+
+<example_commands>
+env.Package(PACKAGETYPE=['src_zip', 'src_targz'], <replaceable>...other args...</replaceable>)
+</example_commands>
+
+<para>
+The currently supported packagers are:
+</para>
+
+<informaltable frame="all">
+<tr><td><literal>msi</literal></td><td>Microsoft Installer package</td></tr>
+<tr><td><literal>rpm</literal></td><td>RPM Package Manger package</td></tr>
+<tr><td><literal>ipkg</literal></td><td>Itsy Package Management package</td></tr>
+<tr><td><literal>tarbz2</literal></td><td>bzip2-compressed tar file</td></tr>
+<tr><td><literal>targz</literal></td><td>gzip-compressed tar file</td></tr>
+<tr><td><literal>tarxz</literal></td><td>xz-compressed tar file</td></tr>
+<tr><td><literal>zip</literal></td><td>zip file</td></tr>
+<tr><td><literal>src_tarbz2</literal></td><td>bzip2-compressed tar file suitable as source to another packager</td></tr>
+<tr><td><literal>src_targz</literal></td><td>gzip-compressed tar file suitable as source to another packager</td></tr>
+<tr><td><literal>src_tarxz</literal></td><td>xz-compressed tar file suitable as source to another packager</td></tr>
+<tr><td><literal>src_zip</literal></td><td>zip file suitable as source to another packager</td></tr>
+</informaltable>
+
 <para>
-The packaging information is specified
-with the help of construction variables documented below.
-This information is called a tag to stress that
-some of them can also be attached to files with the &Tag; function.
-The mandatory ones will complain if they were not specified.
-They vary depending on chosen target packager.
+The file list to include in the package may be specified with
+the &source; keyword argument. If omitted,
+the &f-link-FindInstalledFiles; function is called to select
+all files that have an &b-link-Install;, &b-link-InstallAs;
+or &b-link-InstallVersionedLib; Builder attached.
+If the &target; keyword argument is omitted, the target name(s)
+will be deduced from the package type(s).
 </para>
 
 <para>
-The target packager may be selected with the "PACKAGETYPE" command line
-option or with the &cv-PACKAGETYPE; construction variable. Currently
-the following packagers available:
+The metadata comes partly from attributes of the files to be packaged,
+and partly from packaging <firstterm>tags</firstterm>.
+Tags can be passed as keyword arguments
+to the &b-Package; builder call,
+and may also be attached to files
+(or more accurately, Nodes representing files)
+with the &f-link-Tag; function.
+Some package-level tags are mandatory, and will lead to errors if omitted.
+The mandatory tags vary depending on the package type.
+<!-- TODO: should document which tags are mandatory for which packager -->
 </para>
 
-<blockquote>
-<simplelist type='vert' columns='1'>
-<member><literal>msi</literal> - Microsoft Installer</member>
-<member><literal>rpm</literal> - RPM Package Manger</member>
-<member><literal>ipkg</literal> - Itsy Package Management System</member>
-<member><literal>tarbz2</literal> - bzip2 compressed tar</member>
-<member><literal>targz</literal> - gzip compressed tar</member>
-<member><literal>tarxz</literal> - xz compressed tar</member>
-<member><literal>zip</literal> - zip file</member>
-<member><literal>src_tarbz2</literal> - bzip2 compressed tar source</member>
-<member><literal>src_targz</literal> - gzip compressed tar source</member>
-<member><literal>src_tarxz</literal> - xz compressed tar source</member>
-<member><literal>src_zip</literal> - zip file source</member>
-</simplelist>
-</blockquote>
+<para>
+While packaging, the builder uses a temporary location named
+by the value of the &cv-link-PACKAGEROOT; variable,
+so the package sources are copied there before packaging.
+</para>
 
 <para>
-An updated list is always available under the
-<replaceable>package_type</replaceable> option when
-running <command>scons --help</command>
-on a project that has packaging activated.
+Packaging example:
 </para>
 
 <example_commands>
@@ -100,6 +130,21 @@ env.Package(
     SOURCE_URL="http://foo.org/foo-1.2.3.tar.gz",
 )
 </example_commands>
+
+<para>
+In this example, the target <filename>/bin/my_program</filename>
+created by the &b-Install; call would not be built by default
+since it is not under the project top directory.
+However, since no <parameter>source</parameter>
+is specified to the &b-Package; builder,
+it is selected for packaging by the call to &f-FindInstalledFiles;.
+Since packaging is done using &cv-PACKAGEROOT;, no write is
+actually done to the system's <filename>/bin</filename> directory,
+and the target <emphasis>will</emphasis> be selected since
+after rebasing to underneath &cv-PACKAGEROOT; it is now under
+the top directory of the project.
+</para>
+
 </summary>
 </builder>
 
@@ -201,27 +246,13 @@ placed if applicable.  The default value is "$NAME-$VERSION".
 <cvar name="PACKAGETYPE">
 <summary>
 <para>
-Selects the package type to build.  Currently these are available:
+Selects the package type to build when using the &b-link-Package;
+builder. May be a string or list of strings. See the docuentation
+for the builder for the currently supported types.
 </para>
 
-<blockquote>
-<simplelist type='vert' columns='1'>
-<member><literal>msi</literal> - Microsoft Installer</member>
-<member><literal>rpm</literal> - RPM Package Manger</member>
-<member><literal>ipkg</literal> - Itsy Package Management System</member>
-<member><literal>tarbz2</literal> - bzip2 compressed tar</member>
-<member><literal>targz</literal> - gzip compressed tar</member>
-<member><literal>tarxz</literal> - xz compressed tar</member>
-<member><literal>zip</literal> - zip file</member>
-<member><literal>src_tarbz2</literal> - bzip2 compressed tar source</member>
-<member><literal>src_targz</literal> - gzip compressed tar source</member>
-<member><literal>src_tarxz</literal> - xz compressed tar source</member>
-<member><literal>src_zip</literal> - zip file source</member>
-</simplelist>
-</blockquote>
-
 <para>
-This may be overridden with the <option>package_type</option>
+&cv-PACKAGETYPE; may be overridden with the <option>--package-type</option>
 command line option.
 </para>
 </summary>
@@ -854,7 +885,7 @@ Annotates file or directory Nodes with
 information about how the
 &b-link-Package;
 Builder should package those files or directories.
-All tags are optional.
+All Node-level tags are optional.
 </para>
 
 <para>
@@ -862,12 +893,11 @@ Examples:
 </para>
 
 <example_commands>
-# makes sure the built library will be installed with 0o644 file
-# access mode
-Tag( Library( 'lib.c' ), UNIX_ATTR="0o644" )
+# makes sure the built library will be installed with 644 file access mode
+Tag(Library('lib.c'), UNIX_ATTR="0o644")
 
 # marks file2.txt to be a documentation file
-Tag( 'file2.txt', DOC )
+Tag('file2.txt', DOC)
 </example_commands>
 </summary>
 </scons_function>
diff --git a/doc/man/scons.xml b/doc/man/scons.xml
index b33c035..c4a0db6 100644
--- a/doc/man/scons.xml
+++ b/doc/man/scons.xml
@@ -1162,12 +1162,15 @@ This implies
   </varlistentry>
 
   <varlistentry>
-  <term><option>--install-sandbox=<replaceable>path</replaceable></option></term>
+  <term><option>--install-sandbox=<replaceable>INSTALL_SANDBOX</replaceable></option></term>
   <listitem>
 <para>
-When using the &Install; functions, prepend <replaceable>path</replaceable>
+When using the &Install; builders, prepend
+<replaceable>INSTALL_SANDBOX</replaceable>
 to the installation paths such that all installed files will be placed
-underneath <replaceable>path</replaceable>.
+under that directory path. This option is unavailable if
+one of &b-link-Install;, &b-link-InstallAs; or
+&b-link-InstallVersionedLib; is not used in the SConscript files.
 </para>
   </listitem>
   </varlistentry>
@@ -1493,6 +1496,17 @@ dirs to the toolpath.</para>
 <!--  .EE -->
 
   <varlistentry>
+  <term><option>--package-type=<replaceable>PACKAGE_TYPE</replaceable></option></term>
+  <listitem>
+<para>The type
+of package to create when using the &b-link-Package; builder.
+Note this option is only available if the &t-link-packaging; tool
+has been enabled.
+</para>
+  </listitem>
+  </varlistentry>
+
+  <varlistentry>
   <term><option>--profile=<replaceable>file</replaceable></option></term>
   <listitem>
 <para>Run SCons under the Python profiler
@@ -5540,7 +5554,7 @@ a = Action(build_it)
 </itemizedlist>
 
 <para>As usual the environment method form &f-link-env-Action;
-will expand &consvars; in any argument strings, 
+will expand &consvars; in any argument strings,
 including the action argument, at the time it is called,
 using the construction variables in the &consenv; through which
 it was called. The global function form &f-link-Action;