Improve configuration-related documentation

- Separate configuration selection and description merging into separate
  documents and formalize "appendix" as the preferred term for
  supplemental, non-configuration-specific files. (This has been in use
  in other contexts, including CMake's implementation, but previously
  the specification itself did not provide a specific term for these.)
  This should also help the description merging documentation to be more
  discoverable, since, while configuration-specific files are one of the
  things that need merging, merging is not a sub-topic of configuration
  selection.

- Clarify what contents are allowed in an appendix. (This information
  was previously missing.) Clarify meaning of `default_license` when
  used in an appendix.

- Specify that configurations shall be treated as case insensitive.

- Improve explanation of configurations and add much more extensive
  recommendations on how configurations should be used.

- Fix minor error in multi-axis configuration example.

Author: mwoehlke

configurations.rst

@@ -1,22 +1,42 @@
 Package Configurations
 ======================
 
-Configurations provide a mechanism
-for a package to provide multiple configurations
-from a single distribution.
-Such configurations might include
-separate debug and release libraries,
-builds with and without thread safety,
-and so forth.
+Configurations allow packages to provide
+multiple "flavors" of binary objects
+in a single distribution,
+which have been compiled using different options
+to facilitate different use cases.
+Nominally, such objects must be *type-homogeneous*,
+meaning all configurations of a component
+must be of the same `type`_.
+(See `Multi-Axis Configurations`_
+for a way to work around this restriction;
+however, be aware of the caveats described therein.)
+
+Typical configuration axes include
+presence or omission of instrumentation code,
+optimization level,
+and selection of interchangeable implementations.
 The possible configurations
 are determined by each individual package,
 and it is left to the consumer and build system
 to decide when and how to select a non-default configuration.
+Refer to `Configuration Use Cases`_ for guidance
+on what should or should not be expressed as a configuration.
+
+Like appendices, configurations support partial installation.
+This allows a package to be built in several configurations,
+while permitting users to install only one desired configuration.
+Refer to `Description Merging`_ for additional information.
+
+Configuration Selection
+'''''''''''''''''''''''
 
 When a consumer consumes a component,
 the build system must determine the attribute values for that component
 by selecting which configuration of the component to use
 (if the component has multiple configurations).
+Selection shall treat configuration names as case insensitive.
 It is recommended that build systems select a configuration as follows:
 
 - For each package, the consumer shall have a mechanism
@@ -60,68 +80,6 @@ otherwise, a value of :keyword:`null`
 shall be treated as the attribute being unset
 (and shall suppress falling back to the non-configuration-specific value).
 
-Configuration Merging
-'''''''''''''''''''''
-
-Some build systems may desire to output
-separate specifications per configuration,
-and/or to output separate CPS files per component.
-This is especially useful to permit piecemeal installation
-of individual components and/or configurations
-(for example, a "base" package
-with release libraries and common components,
-an optional package with debug libraries,
-and another optional package with optional components).
-
-When a tool locates a CPS file, :var:`name`\ :path:`.cps`,
-the tool shall look in the same directory for any files
-which match any of the patterns
-(the asterisk (``*``) represents file globbing):
-
-  - :var:`name`\ :path:`:`\ :glob:`*`\ :path:`.cps`
-
-  - :var:`name`\ :path:`-`\ :glob:`*`\ :path:`.cps`
-
-  - :var:`name`\ :path:`@`\ :glob:`*`\ :path:`.cps`
-
-  - :var:`name`\ :path:`:`\ :glob:`*`\ :path:`@`\ :glob:`*`\ :path:`.cps`
-
-  - :var:`name`\ :path:`-`\ :glob:`*`\ :path:`@`\ :glob:`*`\ :path:`.cps`
-
-Patterns containing colon (``:``) shall be skipped
-on platforms for which that character
-is not permitted in file names (e.g. Windows).
-
-If any such package specifications are found,
-they shall be loaded at the same time,
-and their contents appended to the information loaded from the base CPS.
-(Note, however, that tools are permitted
-to ignore the information in any such supplemental CPS file
-as they may determine is not relevant to the user's needs.
-In particular, see `Transitive Dependencies`_.)
-
-A ``.cps`` file whose name contains ``@``
-is a configuration-specific CPS.
-The structure of a configuration-specific CPS
-is the same as a common CPS, with three exceptions:
-
-- The only defined :object:`package` keys are
-  `name`_, `configuration`_, and `components <components\ (package)>`_.
-  The first two are required.
-  Use of other attributes specified in the schema is ill-formed.
-
-- The per-configuration specification may not specify
-  any :object:`component` attributes (e.g. :attribute:`type`).
-  Only :object:`configuration` attributes are allowed.
-
-- An attribute on a :object:`component`
-  is considered to belong instead
-  to the component-configuration
-  identified by the configuration-specific CPS.
-
-The order in which the data from multiple CPS files is appended
-is implementation-defined.
-
 .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... .. ... ..
 
 .. kate: hl reStructuredText

index.rst

@@ -57,6 +57,7 @@ Core Specification
    components
    configurations
    searching
+   merging
 
 Appendices
 ''''''''''

merging.rst

@@ -0,0 +1,88 @@
+Description Merging
+===================
+
+Some build systems may desire to output
+separate specifications per configuration,
+and/or to break a package's components into multiple output files,
+often according to functional groups.
+This is especially useful to permit piecemeal installation
+of components and/or configurations
+(for example, a "base" package
+with release libraries and common components,
+an optional package with debug libraries,
+and another optional package with optional components).
+This also allows build tools to import only those components
+which are actually required by a consumer.
+
+When a tool locates a CPS file, :var:`name`\ :path:`.cps`,
+the tool shall look in the same directory for any files
+which match any of the patterns
+(the asterisk (``*``) represents file globbing):
+
+  - :var:`name`\ :path:`:`\ :glob:`*`\ :path:`.cps`
+
+  - :var:`name`\ :path:`-`\ :glob:`*`\ :path:`.cps`
+
+  - :var:`name`\ :path:`@`\ :glob:`*`\ :path:`.cps`
+
+  - :var:`name`\ :path:`:`\ :glob:`*`\ :path:`@`\ :glob:`*`\ :path:`.cps`
+
+  - :var:`name`\ :path:`-`\ :glob:`*`\ :path:`@`\ :glob:`*`\ :path:`.cps`
+
+.. note::
+
+    Patterns containing colon (``:``) shall be skipped
+    on platforms for which that character
+    is not permitted in file names (e.g. Windows).
+
+If any such package specifications are found,
+they shall be loaded at the same time,
+and their contents appended to the information loaded from the base CPS.
+However, tools are permitted and encouraged
+to ignore the information in any such supplemental CPS files
+as they may determine is not relevant to the user's needs.
+In particular, see `Transitive Dependencies`_.)
+
+A ``.cps`` file whose name contains ``@``
+is a configuration-specific CPS.
+The structure of a configuration-specific CPS
+is the same as a base CPS, with three exceptions:
+
+- The only defined :object:`package` keys are
+  `name`_, `cps_version`_, `configuration`_,
+  and `components <components\ (package)>`_.
+  The first three are required.
+  Use of other attributes specified in the schema is ill-formed.
+
+- The per-configuration specification may not specify
+  any :object:`component` attributes (e.g. :attribute:`type`).
+  Only :object:`configuration` attributes are allowed.
+
+- An attribute on a :object:`component`
+  is considered to belong instead
+  to the component-configuration
+  identified by the configuration-specific CPS.
+
+A ``.cps`` file which supplements the components
+of the package's base CPS
+is known as an "appendix".
+The structure of a CPS appendix
+is the same as a base CPS, with two exceptions:
+
+- The only defined :object:`package` keys are
+  `name`_, `requires <requires\ (package)>`_, `default_license`_
+  and `components <components\ (package)>`_.
+  The first is required.
+  Use of other attributes specified in the schema is ill-formed.
+
+- An appendix may not specify components
+  which are described in the base CPS
+  or in any other appendix.
+
+The order in which the data from multiple CPS files is collated
+is implementation-defined.
+Behavior when a supplemental CPS file's `cps_version`_
+differs from the base CPS's version
+is implementation-defined.
+(However, for obvious reasons,
+this is strongly discouraged.)

overview.rst

@@ -75,7 +75,7 @@ Advantages of CPS
 
   CPS allows a package to provide targets in multiple configurations,
   with no restriction on the naming of configurations.
-  Use of interface targets (see `Configurations as Flags`_)
+  Use of interface targets (see `Multi-Axis Configurations`_)
   allows consumers to select the appropriate configuration
   by specifying target points along multiple axes.
   This especially facilitates creation and use of packages