CPack: Replace #<type> markup with reStructuredText equivalent

Drop #end and #module.  Convert #section to a subsection header.
Convert #variable to the cmake domain "variable" directive.
Convert #macro to the cmake domain "command" directive.
Perform minor formatting fixes in text near these changes.

1 files changed, 222 insertions, 228 deletions

diff --git a/Modules/CPackRPM.cmake b/Modules/CPackRPM.cmake
index f8303ab..a13a46f 100644
--- a/Modules/CPackRPM.cmake
+++ b/Modules/CPackRPM.cmake
@@ -4,7 +4,9 @@
 #
 # The builtin (binary) CPack RPM generator (Unix only)
 #
-# #section Variables specific to CPack RPM generator #end #module
+# Variables specific to CPack RPM generator
+# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#
 # CPackRPM may be used to create RPM package using CPack.  CPackRPM is a
 # CPack generator thus it uses the CPACK_XXX variables used by CPack :
 # http://www.cmake.org/Wiki/CMake:CPackConfiguration
@@ -25,313 +27,305 @@
 #   http://www.cmake.org/Wiki/CMake:CPackPackageGenerators#RPM_.28Unix_Only.29
 #
 # However as a handy reminder here comes the list of specific variables:
-# #end
 #
-# #variable
+# .. variable:: CPACK_RPM_PACKAGE_SUMMARY
 #
-# ::
+#  The RPM package summary.
 #
-#   CPACK_RPM_PACKAGE_SUMMARY - The RPM package summary.
-#      Mandatory : YES
-#      Default   : CPACK_PACKAGE_DESCRIPTION_SUMMARY
+#  * Mandatory : YES
+#  * Default   : CPACK_PACKAGE_DESCRIPTION_SUMMARY
 #
-# #end #variable
+# .. variable:: CPACK_RPM_PACKAGE_NAME
 #
-# ::
+#  The RPM package name.
 #
-#   CPACK_RPM_PACKAGE_NAME - The RPM package name.
-#      Mandatory : YES
-#      Default   : CPACK_PACKAGE_NAME
+#  * Mandatory : YES
+#  * Default   : CPACK_PACKAGE_NAME
 #
-# #end #variable
+# .. variable:: CPACK_RPM_PACKAGE_VERSION
 #
-# ::
+#  The RPM package version.
 #
-#   CPACK_RPM_PACKAGE_VERSION - The RPM package version.
-#      Mandatory : YES
-#      Default   : CPACK_PACKAGE_VERSION
+#  * Mandatory : YES
+#  * Default   : CPACK_PACKAGE_VERSION
 #
-# #end #variable
+# .. variable:: CPACK_RPM_PACKAGE_ARCHITECTURE
 #
-# ::
+#  The RPM package architecture.
 #
-#   CPACK_RPM_PACKAGE_ARCHITECTURE - The RPM package architecture.
-#      Mandatory : NO
-#      Default   : -
-#      This may be set to "noarch" if you
-#      know you are building a noarch package.
+#  * Mandatory : NO
+#  * Default   : -
 #
-# #end #variable
+#  This may be set to "noarch" if you know you are building a noarch package.
 #
-# ::
+# .. variable:: CPACK_RPM_PACKAGE_RELEASE
 #
-#   CPACK_RPM_PACKAGE_RELEASE - The RPM package release.
-#      Mandatory : YES
-#      Default   : 1
-#      This is the numbering of the RPM package
-#      itself, i.e. the version of the packaging and not the version of the
-#      content (see CPACK_RPM_PACKAGE_VERSION). One may change the default
-#      value if the previous packaging was buggy and/or you want to put here
-#      a fancy Linux distro specific numbering.
+#  The RPM package release.
 #
-# #end #variable
+#  * Mandatory : YES
+#  * Default   : 1
 #
-# ::
+#  This is the numbering of the RPM package itself, i.e. the version of the
+#  packaging and not the version of the content (see
+#  CPACK_RPM_PACKAGE_VERSION). One may change the default value if the
+#  previous packaging was buggy and/or you want to put here a fancy Linux
+#  distro specific numbering.
 #
-#   CPACK_RPM_PACKAGE_LICENSE - The RPM package license policy.
-#      Mandatory : YES
-#      Default   : "unknown"
+# .. variable:: CPACK_RPM_PACKAGE_LICENSE
 #
-# #end #variable
+#  The RPM package license policy.
 #
-# ::
+#  * Mandatory : YES
+#  * Default   : "unknown"
 #
-#   CPACK_RPM_PACKAGE_GROUP - The RPM package group.
-#      Mandatory : YES
-#      Default   : "unknown"
+# .. variable:: CPACK_RPM_PACKAGE_GROUP
 #
-# #end #variable
+#  The RPM package group.
 #
-# ::
+#  * Mandatory : YES
+#  * Default   : "unknown"
 #
-#   CPACK_RPM_PACKAGE_VENDOR - The RPM package vendor.
-#      Mandatory : YES
-#      Default   : CPACK_PACKAGE_VENDOR if set or "unknown"
+# .. variable:: CPACK_RPM_PACKAGE_VENDOR
 #
-# #end #variable
+#  The RPM package vendor.
 #
-# ::
+#  * Mandatory : YES
+#  * Default   : CPACK_PACKAGE_VENDOR if set or "unknown"
 #
-#   CPACK_RPM_PACKAGE_URL - The projects URL.
-#      Mandatory : NO
-#      Default   : -
+# .. variable:: CPACK_RPM_PACKAGE_URL
 #
-# #end #variable
+#  The projects URL.
 #
-# ::
+#  * Mandatory : NO
+#  * Default   : -
 #
-#   CPACK_RPM_PACKAGE_DESCRIPTION - RPM package description.
-#      Mandatory : YES
-#      Default   : CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available"
+# .. variable:: CPACK_RPM_PACKAGE_DESCRIPTION
 #
-# #end #variable
+#  RPM package description.
 #
-# ::
+#  * Mandatory : YES
+#  * Default : CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package
+#    description available"
 #
-#   CPACK_RPM_COMPRESSION_TYPE - RPM compression type.
-#      Mandatory : NO
-#      Default   : -
-#      May be used to override RPM compression type to be used
-#      to build the RPM. For example some Linux distribution now default
-#      to lzma or xz compression whereas older cannot use such RPM.
-#      Using this one can enforce compression type to be used.
-#      Possible value are: lzma, xz, bzip2 and gzip.
+# .. variable:: CPACK_RPM_COMPRESSION_TYPE
 #
-# #end #variable
+#  RPM compression type.
 #
-# ::
+#  * Mandatory : NO
+#  * Default   : -
 #
-#   CPACK_RPM_PACKAGE_REQUIRES - RPM spec requires field.
-#      Mandatory : NO
-#      Default   : -
-#      May be used to set RPM dependencies (requires).
-#      Note that you must enclose the complete requires string between quotes,
-#      for example:
-#      set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")
-#      The required package list of an RPM file could be printed with
-#      rpm -qp --requires file.rpm
+#  May be used to override RPM compression type to be used to build the
+#  RPM. For example some Linux distribution now default to lzma or xz
+#  compression whereas older cannot use such RPM.  Using this one can enforce
+#  compression type to be used.  Possible value are: lzma, xz, bzip2 and gzip.
 #
-# #end #variable
+# .. variable:: CPACK_RPM_PACKAGE_REQUIRES
 #
-# ::
+#  RPM spec requires field.
 #
-#   CPACK_RPM_PACKAGE_SUGGESTS - RPM spec suggest field.
-#      Mandatory : NO
-#      Default   : -
-#      May be used to set weak RPM dependencies (suggests).
-#      Note that you must enclose the complete requires string between quotes.
+#  * Mandatory : NO
+#  * Default   : -
 #
-# #end #variable
+#  May be used to set RPM dependencies (requires).  Note that you must enclose
+#  the complete requires string between quotes, for example::
 #
-# ::
+#   set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")
 #
-#   CPACK_RPM_PACKAGE_PROVIDES - RPM spec provides field.
-#      Mandatory : NO
-#      Default   : -
-#      May be used to set RPM dependencies (provides).
-#      The provided package list of an RPM file could be printed with
-#      rpm -qp --provides file.rpm
+#  The required package list of an RPM file could be printed with::
 #
-# #end #variable
+#   rpm -qp --requires file.rpm
 #
-# ::
+# .. variable:: CPACK_RPM_PACKAGE_SUGGESTS
 #
-#   CPACK_RPM_PACKAGE_OBSOLETES - RPM spec obsoletes field.
-#      Mandatory : NO
-#      Default   : -
-#      May be used to set RPM packages that are obsoleted by this one.
+#  RPM spec suggest field.
 #
-# #end #variable
+#  * Mandatory : NO
+#  * Default   : -
 #
-# ::
+#  May be used to set weak RPM dependencies (suggests).  Note that you must
+#  enclose the complete requires string between quotes.
 #
-#   CPACK_RPM_PACKAGE_RELOCATABLE - build a relocatable RPM.
-#      Mandatory : NO
-#      Default   : CPACK_PACKAGE_RELOCATABLE
-#      If this variable is set to TRUE or ON CPackRPM will try
-#      to build a relocatable RPM package. A relocatable RPM may
-#      be installed using rpm --prefix or --relocate in order to
-#      install it at an alternate place see rpm(8).
-#      Note that currently this may fail if CPACK_SET_DESTDIR is set to ON.
-#      If CPACK_SET_DESTDIR is set then you will get a warning message
-#      but if there is file installed with absolute path you'll get
-#      unexpected behavior.
+# .. variable:: CPACK_RPM_PACKAGE_PROVIDES
 #
-# #end #variable
+#  RPM spec provides field.
 #
-# ::
+#  * Mandatory : NO
+#  * Default   : -
 #
-#   CPACK_RPM_SPEC_INSTALL_POST - [deprecated].
-#      Mandatory : NO
-#      Default   : -
-#      This way of specifying post-install script is deprecated use
-#      CPACK_RPM_POST_INSTALL_SCRIPT_FILE
-#      May be used to set an RPM post-install command inside the spec file.
-#      For example setting it to "/bin/true" may be used to prevent
-#      rpmbuild to strip binaries.
+#  May be used to set RPM dependencies (provides).  The provided package list
+#  of an RPM file could be printed with::
 #
-# #end #variable
+#   rpm -qp --provides file.rpm
 #
-# ::
+# .. variable:: CPACK_RPM_PACKAGE_OBSOLETES
 #
-#   CPACK_RPM_SPEC_MORE_DEFINE - RPM extended spec definitions lines.
-#      Mandatory : NO
-#      Default   : -
-#      May be used to add any %define lines to the generated spec file.
+#  RPM spec obsoletes field.
 #
-# #end #variable
+#  * Mandatory : NO
+#  * Default   : -
 #
-# ::
+#  May be used to set RPM packages that are obsoleted by this one.
 #
-#   CPACK_RPM_PACKAGE_DEBUG - Toggle CPackRPM debug output.
-#      Mandatory : NO
-#      Default   : -
-#      May be set when invoking cpack in order to trace debug information
-#      during CPack RPM run. For example you may launch CPack like this
-#      cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM
+# .. variable:: CPACK_RPM_PACKAGE_RELOCATABLE
 #
-# #end #variable
+#  build a relocatable RPM.
 #
-# ::
+#  * Mandatory : NO
+#  * Default   : CPACK_PACKAGE_RELOCATABLE
 #
-#   CPACK_RPM_USER_BINARY_SPECFILE - A user provided spec file.
-#      Mandatory : NO
-#      Default   : -
-#      May be set by the user in order to specify a USER binary spec file
-#      to be used by CPackRPM instead of generating the file.
-#      The specified file will be processed by configure_file( @ONLY).
-#      One can provide a component specific file by setting
-#      CPACK_RPM_<componentName>_USER_BINARY_SPECFILE.
+#  If this variable is set to TRUE or ON CPackRPM will try
+#  to build a relocatable RPM package. A relocatable RPM may
+#  be installed using::
 #
-# #end #variable
+#   rpm --prefix or --relocate
 #
-# ::
+#  in order to install it at an alternate place see rpm(8).  Note that
+#  currently this may fail if CPACK_SET_DESTDIR is set to ON.  If
+#  CPACK_SET_DESTDIR is set then you will get a warning message but if there
+#  is file installed with absolute path you'll get unexpected behavior.
 #
-#   CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE - Spec file template.
-#      Mandatory : NO
-#      Default   : -
-#      If set CPack will generate a template for USER specified binary
-#      spec file and stop with an error. For example launch CPack like this
-#      cpack -D CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE=1 -G RPM
-#      The user may then use this file in order to hand-craft is own
-#      binary spec file which may be used with CPACK_RPM_USER_BINARY_SPECFILE.
+# .. variable:: CPACK_RPM_SPEC_INSTALL_POST
 #
-# #end #variable
+#  * Mandatory : NO
+#  * Default   : -
+#  * Deprecated: YES
 #
-# ::
+#  This way of specifying post-install script is deprecated, use
+#  CPACK_RPM_POST_INSTALL_SCRIPT_FILE.
+#  May be used to set an RPM post-install command inside the spec file.
+#  For example setting it to "/bin/true" may be used to prevent
+#  rpmbuild to strip binaries.
 #
-#   CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
-#   CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
-#      Mandatory : NO
-#      Default   : -
-#      May be used to embed a pre (un)installation script in the spec file.
-#      The refered script file(s) will be read and directly
-#      put after the %pre or %preun section
-#      If CPACK_RPM_COMPONENT_INSTALL is set to ON the (un)install script for
-#      each component can be overridden with
-#      CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE and
-#      CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE
-#      One may verify which scriptlet has been included with
-#       rpm -qp --scripts  package.rpm
-#
-# #end #variable
+# .. variable:: CPACK_RPM_SPEC_MORE_DEFINE
 #
-# ::
+#  RPM extended spec definitions lines.
 #
-#   CPACK_RPM_POST_INSTALL_SCRIPT_FILE
-#   CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
-#      Mandatory : NO
-#      Default   : -
-#      May be used to embed a post (un)installation script in the spec file.
-#      The refered script file(s) will be read and directly
-#      put after the %post or %postun section
-#      If CPACK_RPM_COMPONENT_INSTALL is set to ON the (un)install script for
-#      each component can be overridden with
-#      CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE and
-#      CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE
-#      One may verify which scriptlet has been included with
-#       rpm -qp --scripts  package.rpm
-#
-# #end #variable
+#  * Mandatory : NO
+#  * Default   : -
 #
-# ::
+#  May be used to add any %define lines to the generated spec file.
 #
-#   CPACK_RPM_USER_FILELIST
-#   CPACK_RPM_<COMPONENT>_USER_FILELIST
-#      Mandatory : NO
-#      Default   : -
-#      May be used to explicitly specify %(<directive>) file line
-#      in the spec file. Like %config(noreplace) or any other directive
-#      that be found in the %files section. Since CPackRPM is generating
-#      the list of files (and directories) the user specified files of
-#      the CPACK_RPM_<COMPONENT>_USER_FILELIST list will be removed from the generated list.
+# .. variable:: CPACK_RPM_PACKAGE_DEBUG
 #
-# #end #variable
+#  Toggle CPackRPM debug output.
 #
-# ::
+#  * Mandatory : NO
+#  * Default   : -
 #
-#   CPACK_RPM_CHANGELOG_FILE - RPM changelog file.
-#      Mandatory : NO
-#      Default   : -
-#      May be used to embed a changelog in the spec file.
-#      The refered file will be read and directly put after the %changelog
-#      section.
+#  May be set when invoking cpack in order to trace debug information
+#  during CPack RPM run. For example you may launch CPack like this::
 #
-# #end #variable
+#   cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM
 #
-# ::
+# .. variable:: CPACK_RPM_USER_BINARY_SPECFILE
 #
-#   CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST - list of path to be excluded.
-#      Mandatory : NO
-#      Default   : /etc /etc/init.d /usr /usr/share /usr/share/doc /usr/bin /usr/lib /usr/lib64 /usr/include
-#      May be used to exclude path (directories or files) from the auto-generated
-#      list of paths discovered by CPack RPM. The defaut value contains a reasonable
-#      set of values if the variable is not defined by the user. If the variable
-#      is defined by the user then CPackRPM will NOT any of the default path.
-#      If you want to add some path to the default list then you can use
-#      CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION variable.
+#  A user provided spec file.
 #
-# #end #variable
+#  * Mandatory : NO
+#  * Default   : -
 #
-# ::
+#  May be set by the user in order to specify a USER binary spec file
+#  to be used by CPackRPM instead of generating the file.
+#  The specified file will be processed by configure_file( @ONLY).
+#  One can provide a component specific file by setting
+#  CPACK_RPM_<componentName>_USER_BINARY_SPECFILE.
+#
+# .. variable:: CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE
+#
+#  Spec file template.
+#
+#  * Mandatory : NO
+#  * Default   : -
+#
+#  If set CPack will generate a template for USER specified binary
+#  spec file and stop with an error. For example launch CPack like this::
+#
+#   cpack -D CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE=1 -G RPM
+#
+#  The user may then use this file in order to hand-craft is own
+#  binary spec file which may be used with CPACK_RPM_USER_BINARY_SPECFILE.
+#
+# .. variable:: CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
+#               CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
+#
+#  * Mandatory : NO
+#  * Default   : -
+#
+#  May be used to embed a pre (un)installation script in the spec file.
+#  The refered script file(s) will be read and directly
+#  put after the %pre or %preun section
+#  If CPACK_RPM_COMPONENT_INSTALL is set to ON the (un)install script for
+#  each component can be overridden with
+#  CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE and
+#  CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE.
+#  One may verify which scriptlet has been included with::
+#
+#   rpm -qp --scripts  package.rpm
+#
+# .. variable:: CPACK_RPM_POST_INSTALL_SCRIPT_FILE
+#               CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
+#
+#  * Mandatory : NO
+#  * Default   : -
+#
+#  May be used to embed a post (un)installation script in the spec file.
+#  The refered script file(s) will be read and directly
+#  put after the %post or %postun section.
+#  If CPACK_RPM_COMPONENT_INSTALL is set to ON the (un)install script for
+#  each component can be overridden with
+#  CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE and
+#  CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE.
+#  One may verify which scriptlet has been included with::
+#
+#   rpm -qp --scripts  package.rpm
+#
+# .. variable:: CPACK_RPM_USER_FILELIST
+#               CPACK_RPM_<COMPONENT>_USER_FILELIST
+#
+#  * Mandatory : NO
+#  * Default   : -
+#
+#  May be used to explicitly specify %(<directive>) file line
+#  in the spec file. Like %config(noreplace) or any other directive
+#  that be found in the %files section. Since CPackRPM is generating
+#  the list of files (and directories) the user specified files of
+#  the CPACK_RPM_<COMPONENT>_USER_FILELIST list will be removed from
+#  the generated list.
+#
+# .. variable:: CPACK_RPM_CHANGELOG_FILE
+#
+#  RPM changelog file.
+#
+#  * Mandatory : NO
+#  * Default   : -
+#
+#  May be used to embed a changelog in the spec file.
+#  The refered file will be read and directly put after the %changelog
+#  section.
+#
+# .. variable:: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST
+#
+#  list of path to be excluded.
+#
+#  * Mandatory : NO
+#  * Default   : /etc /etc/init.d /usr /usr/share /usr/share/doc /usr/bin /usr/lib /usr/lib64 /usr/include
+#
+#  May be used to exclude path (directories or files) from the auto-generated
+#  list of paths discovered by CPack RPM. The defaut value contains a
+#  reasonable set of values if the variable is not defined by the user. If the
+#  variable is defined by the user then CPackRPM will NOT any of the default
+#  path.  If you want to add some path to the default list then you can use
+#  CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION variable.
+#
+# .. variable:: CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION
+#
+#  additional list of path to be excluded.
 #
-#   CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION - additional list of path to be excluded.
-#      Mandatory : NO
-#      Default   : -
-#      May be used to add more exclude path (directories or files) from the initial
-#      default list of excluded paths. See CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST.
+#  * Mandatory : NO
+#  * Default   : -
 #
-# #end
+#  May be used to add more exclude path (directories or files) from the initial
+#  default list of excluded paths. See CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST.
 
 #=============================================================================
 # Copyright 2007-2009 Kitware, Inc.