Merge topic 'doc-cpack-revise'

bfb91ff7f2 CPack: Add more markup to module documentation
5fc59ea7c8 CPack: Document `CPACK_PACKAGE_DESCRIPTION` variable
3f354d65b4 CPack: Move CPACK_BINARY_<GENNAME> with rest of docs
53ec402069 CPack: Convert documentation to long-bracket comment syntax

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2051

1 files changed, 339 insertions, 330 deletions

diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake
index f6d74c5..05fb78a 100644
--- a/Modules/CPack.cmake
+++ b/Modules/CPack.cmake
@@ -1,326 +1,342 @@
 # Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
 # file Copyright.txt or https://cmake.org/licensing for details.
 
-#.rst:
-# CPack
-# -----
-#
-# Build binary and source package installers.
-#
-# Variables common to all CPack generators
-# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-#
-# 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 targets to the resulting makefiles, package and
-# package_source, which build the binary and source installers,
-# respectively.  The generated binary installers contain everything
-# installed via CMake's INSTALL command (and the deprecated
-# INSTALL_FILES, INSTALL_PROGRAMS, and INSTALL_TARGETS commands).
-#
-# For certain kinds of binary installers (including the graphical
-# installers on Mac OS X and Windows), CPack generates installers that
-# allow users to select individual application components to install.
-# See CPackComponent module for that.
-#
-# The CPACK_GENERATOR variable has different meanings in different
-# contexts.  In your CMakeLists.txt file, CPACK_GENERATOR is a *list of
-# generators*: when run with no other arguments, CPack will iterate over
-# that list and produce one package for each generator.  In a
-# CPACK_PROJECT_CONFIG_FILE, though, CPACK_GENERATOR is a *string naming
-# a single generator*.  If you need per-cpack- generator logic to
-# control *other* cpack settings, then you need a
-# CPACK_PROJECT_CONFIG_FILE.
-#
-# The CMake source tree itself contains a CPACK_PROJECT_CONFIG_FILE.
-# See the top level file CMakeCPackOptions.cmake.in for an example.
-#
-# If set, the CPACK_PROJECT_CONFIG_FILE is included automatically on a
-# per-generator basis.  It only need contain overrides.
-#
-# Here's how it works:
-#
-# * cpack runs
-# * it includes CPackConfig.cmake
-# * it iterates over the generators given by the ``-G`` command line option,
-#   or if no such option was specified, over the list of generators given by
-#   the CPACK_GENERATOR variable set in the CPackConfig.cmake input file.
-# * foreach generator, it then
-#
-#   - sets CPACK_GENERATOR to the one currently being iterated
-#   - includes the CPACK_PROJECT_CONFIG_FILE
-#   - produces the package for that generator
-#
-# This is the key: For each generator listed in CPACK_GENERATOR in
-# CPackConfig.cmake, cpack will *reset* CPACK_GENERATOR internally to
-# *the one currently being used* and then include the
-# CPACK_PROJECT_CONFIG_FILE.
-#
-# Before including this CPack module in your CMakeLists.txt file, there
-# are a variety of variables that can be set to customize the resulting
-# installers.  The most commonly-used variables are:
-#
-# .. variable:: CPACK_PACKAGE_NAME
-#
-#  The name of the package (or application). If not specified, defaults to
-#  the project name.
-#
-# .. variable:: CPACK_PACKAGE_VENDOR
-#
-#  The name of the package vendor. (e.g., "Kitware"). Default is "Humanity".
-#
-# .. variable:: CPACK_PACKAGE_DIRECTORY
-#
-#  The directory in which CPack is doing its packaging. If it is not set
-#  then this will default (internally) to the build dir. This variable may
-#  be defined in CPack config file or from the cpack command line option
-#  "-B". If set the command line option override the value found in the
-#  config file.
-#
-# .. variable:: CPACK_PACKAGE_VERSION_MAJOR
-#
-#  Package major version.  This variable will always be set, but its default
-#  value depends on whether or not version details were given to the
-#  :command:`project` command in the top level CMakeLists.txt file.  If version
-#  details were given, the default value will be
-#  :variable:`CMAKE_PROJECT_VERSION_MAJOR`.  If no version details were given,
-#  a default version of 0.1.1 will be assumed, leading to
-#  ``CPACK_PACKAGE_VERSION_MAJOR`` having a default value of 0.
-#
-# .. variable:: CPACK_PACKAGE_VERSION_MINOR
-#
-#  Package minor version.  The default value is determined based on whether or
-#  not version details were given to the :command:`project` command in the top
-#  level CMakeLists.txt file.  If version details were given, the default
-#  value will be :variable:`CMAKE_PROJECT_VERSION_MINOR`, but if no minor
-#  version component was specified then ``CPACK_PACKAGE_VERSION_MINOR`` will be
-#  left unset.  If no project version was given at all, a default version of
-#  0.1.1 will be assumed, leading to ``CPACK_PACKAGE_VERSION_MINOR`` having a
-#  default value of 1.
-#
-# .. variable:: CPACK_PACKAGE_VERSION_PATCH
-#
-#  Package patch version.  The default value is determined based on whether or
-#  not version details were given to the :command:`project` command in the top
-#  level CMakeLists.txt file.  If version details were given, the default
-#  value will be :variable:`CMAKE_PROJECT_VERSION_PATCH`, but if no patch
-#  version component was specified then ``CPACK_PACKAGE_VERSION_PATCH`` will be
-#  left unset.  If no project version was given at all, a default version of
-#  0.1.1 will be assumed, leading to ``CPACK_PACKAGE_VERSION_PATCH`` having a
-#  default value of 1.
-#
-# .. variable:: CPACK_PACKAGE_DESCRIPTION_FILE
-#
-#  A text file used to describe the project. Used, for example, the
-#  introduction screen of a CPack-generated Windows installer to describe
-#  the project.
-#
-# .. variable:: CPACK_PACKAGE_DESCRIPTION_SUMMARY
-#
-#  Short description of the project (only a few words). Default value is::
-#
-#    ${CMAKE_PROJECT_DESCRIPTION}
-#
-#  if DESCRIPTION has given to the project() call or
-#  CMake generated string with PROJECT_NAME otherwise.
-#
-# .. variable:: CPACK_PACKAGE_HOMEPAGE_URL
-#
-#  Project homepage URL. Default value is::
-#
-#    ${CMAKE_PROJECT_HOMEPAGE_URL}
-#
-#  if HOMEPAGE_URL has given to the project().
-#
-# .. variable:: CPACK_PACKAGE_FILE_NAME
-#
-#  The name of the package file to generate, not including the
-#  extension. For example, cmake-2.6.1-Linux-i686.  The default value is::
-#
-#   ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}.
-#
-# .. variable:: CPACK_PACKAGE_INSTALL_DIRECTORY
-#
-#  Installation directory on the target system. This may be used by some
-#  CPack generators like NSIS to create an installation directory e.g.,
-#  "CMake 2.5" below the installation prefix. All installed element will be
-#  put inside this directory.
-#
-# .. variable:: CPACK_PACKAGE_ICON
-#
-#  A branding image that will be displayed inside the installer (used by GUI
-#  installers).
-#
-# .. variable:: CPACK_PACKAGE_CHECKSUM
-#
-#  An algorithm that will be used to generate additional file with checksum
-#  of the package. Output file name will be::
-#
-#     ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}
-#
-#  Supported algorithms are those listed by the
-#  :ref:`string(\<HASH\>) <Supported Hash Algorithms>`
-#  command.
-#
-# .. variable:: CPACK_PROJECT_CONFIG_FILE
-#
-#  CPack-time project CPack configuration file. This file included at cpack
-#  time, once per generator after CPack has set CPACK_GENERATOR to the
-#  actual generator being used. It allows per-generator setting of CPACK_*
-#  variables at cpack time.
-#
-# .. variable:: CPACK_RESOURCE_FILE_LICENSE
-#
-#  License to be embedded in the installer. It will typically be displayed
-#  to the user by the produced installer (often with an explicit "Accept"
-#  button, for graphical installers) prior to installation. This license
-#  file is NOT added to installed file but is used by some CPack generators
-#  like NSIS. If you want to install a license file (may be the same as this
-#  one) along with your project you must add an appropriate CMake INSTALL
-#  command in your CMakeLists.txt.
-#
-# .. variable:: CPACK_RESOURCE_FILE_README
-#
-#  ReadMe file to be embedded in the installer. It typically describes in
-#  some detail the purpose of the project during the installation. Not all
-#  CPack generators uses this file.
-#
-# .. variable:: CPACK_RESOURCE_FILE_WELCOME
-#
-#  Welcome file to be embedded in the installer. It welcomes users to this
-#  installer.  Typically used in the graphical installers on Windows and Mac
-#  OS X.
-#
-# .. variable:: CPACK_MONOLITHIC_INSTALL
-#
-#  Disables the component-based installation mechanism. When set the
-#  component specification is ignored and all installed items are put in a
-#  single "MONOLITHIC" package.  Some CPack generators do monolithic
-#  packaging by default and may be asked to do component packaging by
-#  setting CPACK_<GENNAME>_COMPONENT_INSTALL to 1/TRUE.
-#
-# .. variable:: CPACK_GENERATOR
-#
-#  List of CPack generators to use.  If not specified, CPack will create a
-#  set of options CPACK_BINARY_<GENNAME> (e.g., CPACK_BINARY_NSIS) allowing
-#  the user to enable/disable individual generators.  If the ``-G`` option
-#  is given on the :manual:`cpack <cpack(1)>` command line, it will override
-#  this variable and any CPACK_BINARY_<GENNAME> options.
-#
-# .. variable:: CPACK_OUTPUT_CONFIG_FILE
-#
-#  The name of the CPack binary configuration file. This file is the CPack
-#  configuration generated by the CPack module for binary
-#  installers. Defaults to CPackConfig.cmake.
-#
-# .. variable:: CPACK_PACKAGE_EXECUTABLES
-#
-#  Lists each of the executables and associated text label to be used to
-#  create Start Menu shortcuts. For example, setting this to the list
-#  ccmake;CMake will create a shortcut named "CMake" that will execute the
-#  installed executable ccmake. Not all CPack generators use it (at least
-#  NSIS, WIX and OSXX11 do).
-#
-# .. variable:: CPACK_STRIP_FILES
-#
-#  List of files to be stripped. Starting with CMake 2.6.0 CPACK_STRIP_FILES
-#  will be a boolean variable which enables stripping of all files (a list
-#  of files evaluates to TRUE in CMake, so this change is compatible).
-#
-# .. variable:: CPACK_VERBATIM_VARIABLES
-#
-#  If set to TRUE, values of variables prefixed with CPACK_ will be escaped
-#  before being written to the configuration files, so that the cpack program
-#  receives them exactly as they were specified. If not, characters like quotes
-#  and backslashes can cause parsing errors or alter the value received by the
-#  cpack program. Defaults to FALSE for backwards compatibility.
-#
-#  * Mandatory : NO
-#  * Default   : FALSE
-#
-# The following CPack variables are specific to source packages, and
-# will not affect binary packages:
-#
-# .. variable:: CPACK_SOURCE_PACKAGE_FILE_NAME
-#
-#  The name of the source package. For example cmake-2.6.1.
-#
-# .. variable:: CPACK_SOURCE_STRIP_FILES
-#
-#  List of files in the source tree that will be stripped. Starting with
-#  CMake 2.6.0 CPACK_SOURCE_STRIP_FILES will be a boolean variable which
-#  enables stripping of all files (a list of files evaluates to TRUE in
-#  CMake, so this change is compatible).
-#
-# .. variable:: CPACK_SOURCE_GENERATOR
-#
-#  List of generators used for the source packages. As with CPACK_GENERATOR,
-#  if this is not specified then CPack will create a set of options (e.g.,
-#  CPACK_SOURCE_ZIP) allowing users to select which packages will be
-#  generated.
-#
-# .. variable:: CPACK_SOURCE_OUTPUT_CONFIG_FILE
-#
-#  The name of the CPack source configuration file. This file is the CPack
-#  configuration generated by the CPack module for source
-#  installers. Defaults to CPackSourceConfig.cmake.
-#
-# .. variable:: CPACK_SOURCE_IGNORE_FILES
-#
-#  Pattern of files in the source tree that won't be packaged when building
-#  a source package. This is a list of regular expression patterns (that
-#  must be properly escaped), e.g.,
-#  /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
-#
-# The following variables are for advanced uses of CPack:
-#
-# .. variable:: CPACK_CMAKE_GENERATOR
-#
-#  What CMake generator should be used if the project is CMake
-#  project. Defaults to the value of CMAKE_GENERATOR few users will want to
-#  change this setting.
-#
-# .. variable:: CPACK_INSTALL_CMAKE_PROJECTS
-#
-#  List of four values that specify what project to install. The four values
-#  are: Build directory, Project Name, Project Component, Directory. If
-#  omitted, CPack will build an installer that installs everything.
-#
-# .. variable:: CPACK_SYSTEM_NAME
-#
-#  System name, defaults to the value of ${CMAKE_SYSTEM_NAME}, except on
-#  Windows where it will be "win32" or "win64".
-#
-# .. variable:: CPACK_PACKAGE_VERSION
-#
-#  Package full version, used internally. By default, this is built from
-#  CPACK_PACKAGE_VERSION_MAJOR, CPACK_PACKAGE_VERSION_MINOR, and
-#  CPACK_PACKAGE_VERSION_PATCH.
-#
-# .. variable:: CPACK_TOPLEVEL_TAG
-#
-#  Directory for the installed files.
-#
-# .. variable:: CPACK_INSTALL_COMMANDS
-#
-#  Extra commands to install components.
-#
-# .. variable:: CPACK_INSTALLED_DIRECTORIES
-#
-#  Extra directories to install.
-#
-# .. variable:: CPACK_PACKAGE_INSTALL_REGISTRY_KEY
-#
-#  Registry key used when installing this project. This is only used by
-#  installer for Windows.  The default value is based on the installation
-#  directory.
-#
-# .. variable:: CPACK_CREATE_DESKTOP_LINKS
-#
-#  List of desktop links to create.
-#  Each desktop link requires a corresponding start menu shortcut
-#  as created by :variable:`CPACK_PACKAGE_EXECUTABLES`.
+#[=======================================================================[.rst:
+CPack
+-----
+
+Build binary and source package installers.
+
+Variables common to all CPack generators
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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).
+
+For certain kinds of binary installers (including the graphical
+installers on Mac OS X and Windows), CPack generates installers that
+allow users to select individual application components to install.
+See :module:`CPackComponent` module for further details.
+
+The :variable:`CPACK_GENERATOR` variable has different meanings in different
+contexts.  In a ``CMakeLists.txt`` file, :variable:`CPACK_GENERATOR` is a
+*list of generators*: and when :manual:`cpack <cpack(1)>` is run with no other
+arguments, it will iterate over that list and produce one package for each
+generator.  In a :variable:`CPACK_PROJECT_CONFIG_FILE`,
+:variable:`CPACK_GENERATOR` is a *string naming a single generator*.  If you
+need per-cpack-generator logic to control *other* cpack settings, then you
+need a :variable:`CPACK_PROJECT_CONFIG_FILE`.
+
+The CMake source tree itself contains a :variable:`CPACK_PROJECT_CONFIG_FILE`.
+See the top level file ``CMakeCPackOptions.cmake.in`` for an example.
+
+If set, the :variable:`CPACK_PROJECT_CONFIG_FILE` is included automatically
+on a per-generator basis.  It only need contain overrides.
+
+Here's how it works:
+
+* :manual:`cpack <cpack(1)>` runs
+* it includes ``CPackConfig.cmake``
+* it iterates over the generators given by the ``-G`` command line option,
+  or if no such option was specified, over the list of generators given by
+  the :variable:`CPACK_GENERATOR` variable set in the ``CPackConfig.cmake``
+  input file.
+* foreach generator, it then
+
+  - sets :variable:`CPACK_GENERATOR` to the one currently being iterated
+  - includes the :variable:`CPACK_PROJECT_CONFIG_FILE`
+  - produces the package for that generator
+
+This is the key: For each generator listed in :variable:`CPACK_GENERATOR` in
+``CPackConfig.cmake``, cpack will *reset* :variable:`CPACK_GENERATOR`
+internally to *the one currently being used* and then include the
+:variable:`CPACK_PROJECT_CONFIG_FILE`.
+
+Before including this CPack module in your ``CMakeLists.txt`` file, there
+are a variety of variables that can be set to customize the resulting
+installers.  The most commonly-used variables are:
+
+.. variable:: CPACK_PACKAGE_NAME
+
+  The name of the package (or application).  If not specified, it defaults to
+  the project name.
+
+.. variable:: CPACK_PACKAGE_VENDOR
+
+  The name of the package vendor. (e.g., "Kitware").  The default is "Humanity".
+
+.. variable:: CPACK_PACKAGE_DIRECTORY
+
+  The directory in which CPack is doing its packaging.  If it is not set
+  then this will default (internally) to the build dir.  This variable may
+  be defined in a CPack config file or from the :manual:`cpack <cpack(1)>`
+  command line option ``-B``.  If set, the command line option overrides the
+  value found in the config file.
+
+.. variable:: CPACK_PACKAGE_VERSION_MAJOR
+
+  Package major version.  This variable will always be set, but its default
+  value depends on whether or not version details were given to the
+  :command:`project` command in the top level CMakeLists.txt file.  If version
+  details were given, the default value will be
+  :variable:`CMAKE_PROJECT_VERSION_MAJOR`.  If no version details were given,
+  a default version of 0.1.1 will be assumed, leading to
+  ``CPACK_PACKAGE_VERSION_MAJOR`` having a default value of 0.
+
+.. variable:: CPACK_PACKAGE_VERSION_MINOR
+
+  Package minor version.  The default value is determined based on whether or
+  not version details were given to the :command:`project` command in the top
+  level CMakeLists.txt file.  If version details were given, the default
+  value will be :variable:`CMAKE_PROJECT_VERSION_MINOR`, but if no minor
+  version component was specified then ``CPACK_PACKAGE_VERSION_MINOR`` will be
+  left unset.  If no project version was given at all, a default version of
+  0.1.1 will be assumed, leading to ``CPACK_PACKAGE_VERSION_MINOR`` having a
+  default value of 1.
+
+.. variable:: CPACK_PACKAGE_VERSION_PATCH
+
+  Package patch version.  The default value is determined based on whether or
+  not version details were given to the :command:`project` command in the top
+  level CMakeLists.txt file.  If version details were given, the default
+  value will be :variable:`CMAKE_PROJECT_VERSION_PATCH`, but if no patch
+  version component was specified then ``CPACK_PACKAGE_VERSION_PATCH`` will be
+  left unset.  If no project version was given at all, a default version of
+  0.1.1 will be assumed, leading to ``CPACK_PACKAGE_VERSION_PATCH`` having a
+  default value of 1.
+
+.. variable:: CPACK_PACKAGE_DESCRIPTION
+
+  A description of the project, used in places such as the introduction
+  screen of CPack-generated Windows installers.  If not set, the value of
+  this variable is populated from the file named by
+  :variable:`CPACK_PACKAGE_DESCRIPTION_FILE`.
+
+.. variable:: CPACK_PACKAGE_DESCRIPTION_FILE
+
+  A text file used to describe the project when
+  :variable:`CPACK_PACKAGE_DESCRIPTION` is not explicitly set.  The default
+  value for ``CPACK_PACKAGE_DESCRIPTION_FILE`` points to a built-in template
+  file ``Templates/CPack.GenericDescription.txt``.
+
+.. variable:: CPACK_PACKAGE_DESCRIPTION_SUMMARY
+
+  Short description of the project (only a few words).  If the
+  :variable:`CMAKE_PROJECT_DESCRIPTION` variable is set, it is used as the
+  default value, otherwise the default will be a string generated by CMake
+  based on :variable:`CMAKE_PROJECT_NAME`.
+
+.. variable:: CPACK_PACKAGE_HOMEPAGE_URL
+
+  Project homepage URL.  The default value is taken from the
+  :variable:`CMAKE_PROJECT_HOMEPAGE_URL` variable, which is set by the top
+  level :command:`project` command, or else the default will be empty if no
+  URL was provided to :command:`project`.
+
+.. variable:: CPACK_PACKAGE_FILE_NAME
+
+  The name of the package file to generate, not including the
+  extension.  For example, ``cmake-2.6.1-Linux-i686``.  The default value
+  is::
+
+    ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}
+
+.. variable:: CPACK_PACKAGE_INSTALL_DIRECTORY
+
+  Installation directory on the target system. This may be used by some
+  CPack generators like NSIS to create an installation directory e.g.,
+  "CMake 2.5" below the installation prefix.  All installed elements will be
+  put inside this directory.
+
+.. variable:: CPACK_PACKAGE_ICON
+
+  A branding image that will be displayed inside the installer (used by GUI
+  installers).
+
+.. variable:: CPACK_PACKAGE_CHECKSUM
+
+  An algorithm that will be used to generate an additional file with the
+  checksum of the package.  The output file name will be::
+
+    ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}
+
+  Supported algorithms are those listed by the
+  :ref:`string(\<HASH\>) <Supported Hash Algorithms>` command.
+
+.. variable:: CPACK_PROJECT_CONFIG_FILE
+
+  CPack-time project CPack configuration file.  This file is included at cpack
+  time, once per generator after CPack has set :variable:`CPACK_GENERATOR`
+  to the actual generator being used.  It allows per-generator setting of
+  ``CPACK_*`` variables at cpack time.
+
+.. variable:: CPACK_RESOURCE_FILE_LICENSE
+
+  License to be embedded in the installer.  It will typically be displayed
+  to the user by the produced installer (often with an explicit "Accept"
+  button, for graphical installers) prior to installation.  This license
+  file is NOT added to the installed files but is used by some CPack generators
+  like NSIS.  If you want to install a license file (may be the same as this
+  one) along with your project, you must add an appropriate CMake
+  :command:`install` command in your ``CMakeLists.txt``.
+
+.. variable:: CPACK_RESOURCE_FILE_README
+
+  ReadMe file to be embedded in the installer.  It typically describes in
+  some detail the purpose of the project during the installation.  Not all
+  CPack generators use this file.
+
+.. variable:: CPACK_RESOURCE_FILE_WELCOME
+
+  Welcome file to be embedded in the installer.  It welcomes users to this
+  installer.  Typically used in the graphical installers on Windows and Mac
+  OS X.
+
+.. variable:: CPACK_MONOLITHIC_INSTALL
+
+  Disables the component-based installation mechanism.  When set, the
+  component specification is ignored and all installed items are put in a
+  single "MONOLITHIC" package.  Some CPack generators do monolithic
+  packaging by default and may be asked to do component packaging by
+  setting ``CPACK_<GENNAME>_COMPONENT_INSTALL`` to ``TRUE``.
+
+.. variable:: CPACK_GENERATOR
+
+  List of CPack generators to use.  If not specified, CPack will create a
+  set of options following the naming pattern
+  :variable:`CPACK_BINARY_<GENNAME>` (e.g. ``CPACK_BINARY_NSIS``) allowing
+  the user to enable/disable individual generators.  If the ``-G`` option is
+  given on the :manual:`cpack <cpack(1)>` command line, it will override this
+  variable and any ``CPACK_BINARY_<GENNAME>`` options.
+
+.. variable:: CPACK_OUTPUT_CONFIG_FILE
+
+  The name of the CPack binary configuration file.  This file is the CPack
+  configuration generated by the CPack module for binary installers.
+  Defaults to ``CPackConfig.cmake``.
+
+.. variable:: CPACK_PACKAGE_EXECUTABLES
+
+  Lists each of the executables and associated text label to be used to
+  create Start Menu shortcuts.  For example, setting this to the list
+  ``ccmake;CMake`` will create a shortcut named "CMake" that will execute the
+  installed executable ``ccmake``.  Not all CPack generators use it (at least
+  NSIS, WIX and OSXX11 do).
+
+.. variable:: CPACK_STRIP_FILES
+
+  List of files to be stripped.  Starting with CMake 2.6.0,
+  ``CPACK_STRIP_FILES`` will be a boolean variable which enables
+  stripping of all files (a list of files evaluates to ``TRUE`` in CMake,
+  so this change is compatible).
+
+.. variable:: CPACK_VERBATIM_VARIABLES
+
+  If set to ``TRUE``, values of variables prefixed with ``CPACK_`` will be
+  escaped before being written to the configuration files, so that the cpack
+  program receives them exactly as they were specified.  If not, characters
+  like quotes and backslashes can cause parsing errors or alter the value
+  received by the cpack program.  Defaults to ``FALSE`` for backwards
+  compatibility.
+
+The following CPack variables are specific to source packages, and
+will not affect binary packages:
+
+.. variable:: CPACK_SOURCE_PACKAGE_FILE_NAME
+
+  The name of the source package.  For example ``cmake-2.6.1``.
+
+.. variable:: CPACK_SOURCE_STRIP_FILES
+
+  List of files in the source tree that will be stripped.  Starting with
+  CMake 2.6.0, ``CPACK_SOURCE_STRIP_FILES`` will be a boolean
+  variable which enables stripping of all files (a list of files evaluates
+  to ``TRUE`` in CMake, so this change is compatible).
+
+.. variable:: CPACK_SOURCE_GENERATOR
+
+  List of generators used for the source packages.  As with
+  :variable:`CPACK_GENERATOR`, if this is not specified then CPack will
+  create a set of options (e.g. ``CPACK_SOURCE_ZIP``) allowing
+  users to select which packages will be generated.
+
+.. variable:: CPACK_SOURCE_OUTPUT_CONFIG_FILE
+
+  The name of the CPack source configuration file.  This file is the CPack
+  configuration generated by the CPack module for source installers.
+  Defaults to ``CPackSourceConfig.cmake``.
+
+.. variable:: CPACK_SOURCE_IGNORE_FILES
+
+  Pattern of files in the source tree that won't be packaged when building
+  a source package.  This is a list of regular expression patterns (that
+  must be properly escaped), e.g.,
+  ``/CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*``
+
+The following variables are for advanced uses of CPack:
+
+.. variable:: CPACK_CMAKE_GENERATOR
+
+  What CMake generator should be used if the project is a CMake
+  project.  Defaults to the value of :variable:`CMAKE_GENERATOR`.  Few users
+  will want to change this setting.
+
+.. variable:: CPACK_INSTALL_CMAKE_PROJECTS
+
+  List of four values that specify what project to install.  The four values
+  are: Build directory, Project Name, Project Component, Directory.  If
+  omitted, CPack will build an installer that installs everything.
+
+.. variable:: CPACK_SYSTEM_NAME
+
+  System name, defaults to the value of :variable:`CMAKE_SYSTEM_NAME`,
+  except on Windows where it will be ``win32`` or ``win64``.
+
+.. variable:: CPACK_PACKAGE_VERSION
+
+  Package full version, used internally.  By default, this is built from
+  :variable:`CPACK_PACKAGE_VERSION_MAJOR`,
+  :variable:`CPACK_PACKAGE_VERSION_MINOR`, and
+  :variable:`CPACK_PACKAGE_VERSION_PATCH`.
+
+.. variable:: CPACK_TOPLEVEL_TAG
+
+  Directory for the installed files.
+
+.. variable:: CPACK_INSTALL_COMMANDS
+
+  Extra commands to install components.
+
+.. variable:: CPACK_INSTALLED_DIRECTORIES
+
+  Extra directories to install.
+
+.. variable:: CPACK_PACKAGE_INSTALL_REGISTRY_KEY
+
+  Registry key used when installing this project.  This is only used by
+  installers for Windows.  The default value is based on the installation
+  directory.
+
+.. variable:: CPACK_CREATE_DESKTOP_LINKS
+
+  List of desktop links to create.  Each desktop link requires a
+  corresponding start menu shortcut as created by
+  :variable:`CPACK_PACKAGE_EXECUTABLES`.
+
+.. variable:: CPACK_BINARY_<GENNAME>
+
+  CPack generated options for binary generators.  The ``CPack.cmake`` module
+  generates (when :variable:`CPACK_GENERATOR` is not set) a set of CMake
+  options (see CMake :command:`option` command) which may then be used to
+  select the CPack generator(s) to be used when building the ``package``
+  target or when running :manual:`cpack <cpack(1)>` without the ``-G`` option.
+
+#]=======================================================================]
 
 # Define this var in order to avoid (or warn) concerning multiple inclusion
 if(CPack_CMake_INCLUDED)
@@ -501,16 +517,9 @@ macro(cpack_optional_append _list _cond _item)
   endif()
 endmacro()
 
-#.rst:
-# .. variable:: CPACK_BINARY_<GENNAME>
-#
-#  CPack generated options for binary generators. The CPack.cmake module
-#  generates (when CPACK_GENERATOR is not set) a set of CMake options (see
-#  CMake option command) which may then be used to select the CPack
-#  generator(s) to be used when launching the package target.
-#
-#  Provide options to choose generators we might check here if the required
-#  tools for the generates exist and set the defaults according to the results
+# Provide options to choose generators we might check here if the required
+# tools for the generators exist and set the defaults according to the
+# results.
 if(NOT CPACK_GENERATOR)
   if(UNIX)
     if(CYGWIN)