Help: Explain interaction of cpack(1) and CPack.

In particular, make clear that package/installer generators
are not the makefile generators of the cmake command.

Also insert sections in CPack doc, and capitalize section titles.

Help/manual/cpack.1.rst

@@ -13,12 +13,29 @@ Synopsis
 Description
 ===========
 
-The ``cpack`` executable is the CMake packaging program.
-CMake projects use :command:`install` commands to define the contents of
-packages which can be generated in various formats by this tool.
-The :module:`CPack` module greatly simplifies the creation of the input file
-used by ``cpack``, allowing most aspects of the packaging configuration to be
-controlled directly from the CMake project's own ``CMakeLists.txt`` files.
+The ``cpack`` executable is the CMake packaging program.  It generates
+installers and source packages in a variety of formats.
+
+For each installer or package format, ``cpack`` has a specific backend,
+called "generator". A generator is responsible for generating the required
+inputs and invoking the specific package creation tools. These installer
+or package generators are not to be confused with the makefile generators
+of the :manual:`cmake <cmake(1)>` command.
+
+All supported generators are specified in the :manual:`cpack-generators
+<cpack-generators(7)>` manual.  The command ``cpack --help`` prints a
+list of generators supported for the target platform.  Which of them are
+to be used can be selected through the :variable:`CPACK_GENERATOR` variable
+or through the command-line option ``-G``.
+
+The ``cpack`` program is steered by a configuration file written in the
+:manual:`CMake language <cmake-language(7)>`. Unless chosen differently
+through the command-line option ``--config``, the file ``CPackConfig.cmake``
+in the current directory is used.
+
+In the standard CMake workflow, the file ``CPackConfig.cmake`` is generated
+by the :manual:`cmake <cmake(1)>` executable, provided the :module:`CPack`
+module is included by the project's ``CMakeLists.txt`` file.
 
 Options
 =======
@@ -27,14 +44,9 @@ Options
   ``<generators>`` is a :ref:`semicolon-separated list <CMake Language Lists>`
   of generator names.  ``cpack`` will iterate through this list and produce
   package(s) in that generator's format according to the details provided in
-  the ``CPackConfig.cmake`` configuration file.  A generator is responsible for
-  generating the required inputs for a particular package system and invoking
-  that system's package creation tools.  All supported generators are specified
-  in the :manual:`Generators <cpack-generators(7)>` section of the manual and
-  the ``--help`` option lists the generators supported for the target platform.
-
-  If this option is not given, the :variable:`CPACK_GENERATOR` variable
-  determines the default set of generators that will be used.
+  the ``CPackConfig.cmake`` configuration file.  If this option is not given,
+  the :variable:`CPACK_GENERATOR` variable determines the default set of
+  generators that will be used.
 
 ``-C <Configuration>``
   Specify the project configuration to be packaged (e.g. ``Debug``,

Modules/CPack.cmake

@@ -10,20 +10,23 @@ Build binary and source package installers.
 Introduction
 ^^^^^^^^^^^^
 
-The CPack module generates binary and source installers in a variety of
-formats using the cpack program.  Inclusion of the CPack module adds
-two new build targets, ``package`` and ``package_source``, which build
-the binary and source installers respectively.  The generated binary
-installers contain everything installed via CMake's :command:`install`
-command (and the deprecated :command:`install_files`,
-:command:`install_programs` and :command:`install_targets` commands).
+The CPack module generates a file ``CPackConfig.cmake`` intended for
+use in a subsequent run of  the :manual:`cpack <cpack(1)>` program
+where it steers the generation of installers or/and source packages.
+
+Inclusion of the CPack module adds two new build targets, ``package``
+and ``package_source``, which build the binary and source installers
+respectively.  The generated binary installers contain everything
+installed via CMake's :command:`install` command (and the deprecated
+commands :command:`install_files`, :command:`install_programs`, and
+:command:`install_targets`).
 
 For certain kinds of binary installers (including the graphical
 installers on macOS and Windows), CPack generates installers that
 allow users to select individual application components to install.
 See :module:`CPackComponent` module for further details.
 
-CPack generators
+CPack Generators
 ^^^^^^^^^^^^^^^^
 
 The :variable:`CPACK_GENERATOR` variable has different meanings in different
@@ -60,7 +63,7 @@ This is the key: For each generator listed in :variable:`CPACK_GENERATOR` in
 internally to *the one currently being used* and then include the
 :variable:`CPACK_PROJECT_CONFIG_FILE`.
 
-Variables common to all CPack generators
+Variables common to all CPack Generators
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Before including this CPack module in your ``CMakeLists.txt`` file, there
@@ -250,6 +253,9 @@ installers.  The most commonly-used variables are:
   received by the cpack program.  Defaults to ``FALSE`` for backwards
   compatibility.
 
+Variables for Source Package Generators
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 The following CPack variables are specific to source packages, and
 will not affect binary packages:
 
@@ -284,6 +290,9 @@ will not affect binary packages:
   must be properly escaped), e.g.,
   ``/CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*``
 
+Variables for Advanced Use
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 The following variables are for advanced uses of CPack:
 
 .. variable:: CPACK_CMAKE_GENERATOR