CPack: Add more markup to module documentation

Also indent variable docs consistently.

1 files changed, 174 insertions, 174 deletions

diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake
index a0f95f3..05fb78a 100644
--- a/Modules/CPack.cmake
+++ b/Modules/CPack.cmake
@@ -10,332 +10,332 @@ Build binary and source package installers.
 Variables common to all CPack generators
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The
-CPack module generates binary and source installers in a variety of
+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).
+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 CPackComponent module for that.
+See :module:`CPackComponent` module for further details.
 
-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 :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 CPACK_PROJECT_CONFIG_FILE.
-See the top level file CMakeCPackOptions.cmake.in for an example.
+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 CPACK_PROJECT_CONFIG_FILE is included automatically on a
-per-generator basis.  It only need contain overrides.
+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:
 
-* cpack runs
-* it includes CPackConfig.cmake
+* :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 CPACK_GENERATOR variable set in the CPackConfig.cmake input file.
+  the :variable:`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
+  - 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 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.
+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
+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.
+  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"). Default is "Humanity".
+  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 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.
+  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.
+  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.
+  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.
+  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
-  ``CPACK_PACKAGE_DESCRIPTION_FILE``.
+  :variable:`CPACK_PACKAGE_DESCRIPTION_FILE`.
 
 .. variable:: CPACK_PACKAGE_DESCRIPTION_FILE
 
   A text file used to describe the project when
-  ``CPACK_PACKAGE_DESCRIPTION`` is not explicitly set.  The default
+  :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). Default value is::
-
-   ${CMAKE_PROJECT_DESCRIPTION}
-
- if DESCRIPTION has given to the project() call or
- CMake generated string with PROJECT_NAME otherwise.
+  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. Default value is::
-
-   ${CMAKE_PROJECT_HOMEPAGE_URL}
-
- if HOMEPAGE_URL has given to the project().
+  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::
+  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}.
+    ${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.
+  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).
+  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::
+  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.
+  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.
+  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 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.
+  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 uses this file.
+  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.
+  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.
+  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 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.
+  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.
+  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).
+  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).
+  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
+  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.
+  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).
+  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.
+  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.
+  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.*
+  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.
+  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.
+  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".
+  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
- CPACK_PACKAGE_VERSION_MAJOR, CPACK_PACKAGE_VERSION_MINOR, and
- CPACK_PACKAGE_VERSION_PATCH.
+  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.
+  Directory for the installed files.
 
 .. variable:: CPACK_INSTALL_COMMANDS
 
- Extra commands to install components.
+  Extra commands to install components.
 
 .. variable:: CPACK_INSTALLED_DIRECTORIES
 
- Extra directories to install.
+  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.
+  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`.
+  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 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.
+  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