CPack Documentation extraction from CMake script begins to work

 - Enhance extract doc parser. Seems robust now. The legacy
   module documentation parser works as before ignoring
   the new markup.

 - Proof of concept for CPack (generic), CPack RPM and CPack Deb
   generator for macro and variables.
   Try cpack --help-command and cpack --help-variables

3 files changed, 161 insertions, 35 deletions

diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake
index ce59693680..1718008ae9 100644
--- a/Modules/CPack.cmake
+++ b/Modules/CPack.cmake
@@ -1,5 +1,4 @@
-# - Build binary and source package installers
-#
+# - Build binary and source package installers.
 # 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
@@ -55,7 +54,7 @@
 ##end
 #
 ##variable
-#   CPACK_PACKAGE_VENDOR - The name of the package vendor (e.g.,
+#   CPACK_PACKAGE_VENDOR - The name of the package vendor. (e.g.,
 #   "Kitware").
 ##end
 #
@@ -77,78 +76,112 @@
 #   CPack-generated Windows installer to describe the project.
 ##end
 #
+##variable
 #   CPACK_PACKAGE_DESCRIPTION_SUMMARY - Short description of the
 #   project (only a few words).
+##end
 #
+##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.
+##end
 #
+##variable
 #   CPACK_PACKAGE_INSTALL_DIRECTORY - Installation directory on the
 #   target system, e.g., "CMake 2.5".
+##end
 #
+##variable
 #   CPACK_PROJECT_CONFIG_FILE - File included at cpack time, once per
 #   generator after setting CPACK_GENERATOR to the actual generator
 #   being used. Allows per-generator setting of CPACK_* variables at
 #   cpack time.
+##end
 #
+##variable
 #   CPACK_RESOURCE_FILE_LICENSE - License file for the project, which
 #   will typically be displayed to the user (often with an explicit
 #   "Accept" button, for graphical installers) prior to installation.
+##end
 #
+##variable
 #   CPACK_RESOURCE_FILE_README - ReadMe file for the project, which
 #   typically describes in some detail
+##end
 #
+##variable
 #   CPACK_RESOURCE_FILE_WELCOME - Welcome file for the project, which
 #   welcomes users to this installer. Typically used in the graphical
 #   installers on Windows and Mac OS X.
+##end
 #
+##variable
 #   CPACK_MONOLITHIC_INSTALL - Disables the component-based 
 #   installation mechanism, so that all components are always installed.
+##end
 #
+##variable
 #   CPACK_GENERATOR - List of CPack generators to use. If not
 #   specified, CPack will create a set of options (e.g.,
 #   CPACK_BINARY_NSIS) allowing the user to enable/disable individual
 #   generators.
+##end
 #
+##variable
 #   CPACK_OUTPUT_CONFIG_FILE - The name of the CPack configuration file
 #   for binary installers that will be generated by the CPack
 #   module. Defaults to CPackConfig.cmake.
+##end
 #
+##variable
 #   CPACK_PACKAGE_EXECUTABLES - Lists each of the executables along
 #   with a text label, to be used to create Start Menu shortcuts on
 #   Windows. For example, setting this to the list ccmake;CMake will
 #   create a shortcut named "CMake" that will execute the installed
 #   executable ccmake.
+##end
 #
+##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).
+##end
 #
 # 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,
 #   e.g., cmake-2.6.1
+##end
 #
+##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).
+##end
 #
+##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.
+##end
 #
+##variable
 #   CPACK_SOURCE_OUTPUT_CONFIG_FILE - The name of the CPack
 #   configuration file for source installers that will be generated by
 #   the CPack module. Defaults to CPackSourceConfig.cmake.
+##end
 #
+##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 patterns, e.g., /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
+##end
 #
 # The following variables are specific to the DragNDrop installers
 # built on Mac OS X:
@@ -207,27 +240,41 @@
 #
 # 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.
+##end
 #
+##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 installers everything.
+##end
 #
+##variable
 #   CPACK_SYSTEM_NAME - System name, defaults to the value of
 #   ${CMAKE_SYSTEM_NAME}.
+##end
 #
+##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.
+##end
 #
+##variable
 #   CPACK_TOPLEVEL_TAG - Directory for the installed files.
+##end
 #
+##variable
 #   CPACK_INSTALL_COMMANDS - Extra commands to install components.
+##end
 #
+##variable
 #   CPACK_INSTALLED_DIRECTORIES - Extra directories to install.
+##end
 #
 
 #=============================================================================
@@ -271,7 +318,7 @@ MACRO(cpack_set_if_not_set name value)
   ENDIF(NOT DEFINED "${name}")
 ENDMACRO(cpack_set_if_not_set)
 
-# Macro to encode variables for the configuration file
+# cpack_encode_variables - Macro to encode variables for the configuration file
 # find any variable that starts with CPACK and create a variable
 # _CPACK_OTHER_VARIABLES_ that contains SET commands for
 # each cpack variable.  _CPACK_OTHER_VARIABLES_ is then
diff --git a/Modules/CPackDeb.cmake b/Modules/CPackDeb.cmake
index 26433bb978..fc7f992c73 100644
--- a/Modules/CPackDeb.cmake
+++ b/Modules/CPackDeb.cmake
@@ -12,42 +12,61 @@
 #  http://www.cmake.org/Wiki/CMake:CPackPackageGenerators#DEB_.28UNIX_only.29
 # However as a handy reminder here comes the list of specific variables:
 #
+##variable
 # CPACK_DEBIAN_PACKAGE_NAME
 #     Mandatory : YES
 #     Default   : CPACK_PACKAGE_NAME (lower case)
 #     The debian package summary
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_VERSION
 #     Mandatory : YES
 #     Default   : CPACK_PACKAGE_VERSION
 #     The debian package version
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_ARCHITECTURE
 #     Mandatory : YES
 #     Default   : Output of dpkg --print-architecture (or i386 if dpkg is not found)
 #     The debian package architecture
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_DEPENDS
 #     Mandatory : NO
 #     Default   : -
 #     May be used to set deb dependencies.
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_MAINTAINER
 #     Mandatory : YES
 #     Default   : CPACK_PACKAGE_CONTACT
 #     The debian package maintainer
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_DESCRIPTION
 #     Mandatory : YES
 #     Default   : CPACK_PACKAGE_DESCRIPTION_SUMMARY
 #     The debian package description
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_SECTION
 #     Mandatory : YES
 #     Default   : 'devel'
 #     The debian package section
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_PRIORITY
 #     Mandatory : YES
 #     Default   : 'optional'
 #     The debian package priority
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_HOMEPAGE
 #     Mandatory : NO
 #     Default   : -
 #     The URL of the web site for this package
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_SHLIBDEPS
 #     Mandatory : NO
 #     Default   : OFF
@@ -57,11 +76,15 @@
 #     if you use this feature, because if you don't dpkg-shlibdeps
 #     may fail to find your own shared libs.
 #     See http://www.cmake.org/Wiki/CMake_RPATH_handling.
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_DEBUG
 #     Mandatory : NO
 #     Default   : -
 #     May be set when invoking cpack in order to trace debug information
 #     during CPackDeb run.
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_PREDEPENDS
 #     Mandatory : NO
 #     Default   : -
@@ -69,12 +92,16 @@
 #     This field is like Depends, except that it also forces dpkg to complete installation of
 #     the packages named before even starting the installation of the package which declares
 #     the pre-dependency.
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_ENHANCES
 #     Mandatory : NO
 #     Default   : -
 #     see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 #     This field is similar to Suggests but works in the opposite direction.
 #     It is used to declare that a package can enhance the functionality of another package.
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_BREAKS
 #     Mandatory : NO
 #     Default   : -
@@ -82,23 +109,30 @@
 #     When one binary package declares that it breaks another, dpkg will refuse to allow the
 #     package which declares Breaks be installed unless the broken package is deconfigured first,
 #     and it will refuse to allow the broken package to be reconfigured.
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_CONFLICTS
 #     Mandatory : NO
 #     Default   : -
 #     see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 #     When one binary package declares a conflict with another using a Conflicts field,
 #     dpkg will refuse to allow them to be installed on the system at the same time.
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_PROVIDES
 #     Mandatory : NO
 #     Default   : -
 #     see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 #     A virtual package is one which appears in the Provides control field of another package.
+##end
+##variable
 # CPACK_DEBIAN_PACKAGE_REPLACES
 #     Mandatory : NO
 #     Default   : -
 #     see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
 #     Packages can declare in their control file that they should overwrite
 #     files in certain other packages, or completely replace other packages.
+##end
 
 #=============================================================================
 # Copyright 2007-2009 Kitware, Inc.
diff --git a/Modules/CPackRPM.cmake b/Modules/CPackRPM.cmake
index e1e76edcdb..de06feff21 100644
--- a/Modules/CPackRPM.cmake
+++ b/Modules/CPackRPM.cmake
@@ -1,4 +1,5 @@
 # - The builtin (binary) CPack RPM generator (Unix only)
+##module
 # 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
@@ -15,52 +16,67 @@
 # You'll find a detailed usage of CPackRPM on the wiki:
 #  http://www.cmake.org/Wiki/CMake:CPackPackageGenerators#RPM_.28Unix_Only.29
 # However as a handy reminder here comes the list of specific variables:
+##end
 #
-#  CPACK_RPM_PACKAGE_SUMMARY
+##variable
+#  CPACK_RPM_PACKAGE_SUMMARY - The RPM package summary.
 #     Mandatory : YES
 #     Default   : CPACK_PACKAGE_DESCRIPTION_SUMMARY
-#     The RPM package summary
-#  CPACK_RPM_PACKAGE_NAME
+##end
+##variable
+#  CPACK_RPM_PACKAGE_NAME - The RPM package name.
 #     Mandatory : YES
 #     Default   : CPACK_PACKAGE_NAME
-#     The RPM package name
-#  CPACK_RPM_PACKAGE_VERSION
+##end
+##variable
+#  CPACK_RPM_PACKAGE_VERSION - The RPM package version.
 #     Mandatory : YES
 #     Default   : CPACK_PACKAGE_VERSION
-#     The RPM package version
-#  CPACK_RPM_PACKAGE_ARCHITECTURE
+##end
+##variable
+#  CPACK_RPM_PACKAGE_ARCHITECTURE - The RPM package architecture.
 #     Mandatory : NO
 #     Default   : -
-#     The RPM package architecture. This may be set to "noarch" if you
+#     This may be set to "noarch" if you
 #     know you are building a noarch package.
-#  CPACK_RPM_PACKAGE_RELEASE
+##end
+##variable
+#  CPACK_RPM_PACKAGE_RELEASE - The RPM package release.
 #     Mandatory : YES
 #     Default   : 1
-#     The RPM package release. This is the numbering of the RPM package
+#     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
+##end
+##variable
+#  CPACK_RPM_PACKAGE_LICENSE - The RPM package license policy.
 #     Mandatory : YES
 #     Default   : "unknown"
-#     The RPM package license policy.
-#  CPACK_RPM_PACKAGE_GROUP
+##end
+##variable
+#  CPACK_RPM_PACKAGE_GROUP - The RPM package group.
 #     Mandatory : YES
 #     Default   : "unknown"
-#     The RPM package group.
-#  CPACK_RPM_PACKAGE_VENDOR
+##end
+##variable
+#  CPACK_RPM_PACKAGE_VENDOR - The RPM package vendor.
 #     Mandatory : YES
 #     Default   : CPACK_PACKAGE_VENDOR if set or "unknown"
-#     The RPM package vendor.
-#  CPACK_RPM_PACKAGE_URL
+##end
+##variable
+#  CPACK_RPM_PACKAGE_URL - The projects URL.
 #     Mandatory : NO
 #     Default   : -
-#     The projects URL.
-#  CPACK_RPM_PACKAGE_DESCRIPTION
+##end
+##variable
+#  CPACK_RPM_PACKAGE_DESCRIPTION - RPM package description.
 #     Mandatory : YES
 #     Default   : CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available"
-#  CPACK_RPM_COMPRESSION_TYPE
+##end
+##variable
+#  CPACK_RPM_COMPRESSION_TYPE - RPM compression type.
 #     Mandatory : NO
 #     Default   : -
 #     May be used to override RPM compression type to be used
@@ -68,7 +84,9 @@
 #     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.
-#  CPACK_RPM_PACKAGE_REQUIRES
+##end
+##variable
+#  CPACK_RPM_PACKAGE_REQUIRES - RPM spec requires field.
 #     Mandatory : NO
 #     Default   : -
 #     May be used to set RPM dependencies (requires).
@@ -77,22 +95,30 @@
 #     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
-#  CPACK_RPM_PACKAGE_SUGGESTS
+##end
+##variable
+#  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.
-#  CPACK_RPM_PACKAGE_PROVIDES
+##end
+##variable
+#  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
-#  CPACK_RPM_PACKAGE_OBSOLETES
+##end
+##variable
+#  CPACK_RPM_PACKAGE_OBSOLETES - RPM spec obsoletes field.
 #     Mandatory : NO
 #     Default   : -
 #     May be used to set RPM packages that are obsoleted by this one.
-#  CPACK_RPM_PACKAGE_RELOCATABLE
+##end
+##variable
+#  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
@@ -103,7 +129,9 @@
 #     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_SPEC_INSTALL_POST [deprecated]
+##end
+##variable
+#  CPACK_RPM_SPEC_INSTALL_POST - [deprecated].
 #     Mandatory : NO
 #     Default   : -
 #     This way of specifying post-install script is deprecated use
@@ -111,23 +139,31 @@
 #     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_SPEC_MORE_DEFINE
+##end
+##variable
+#  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.
-#  CPACK_RPM_PACKAGE_DEBUG
+##end
+##variable
+#  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
-#  CPACK_RPM_USER_BINARY_SPECFILE
+##end
+##variable
+#  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).
-#  CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE
+##end
+##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
@@ -135,6 +171,8 @@
 #     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.
+##end
+##variable
 #  CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
 #  CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
 #     Mandatory : NO
@@ -148,6 +186,8 @@
 #     CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE
 #     One may verify which scriptlet has been included with
 #      rpm -qp --scripts  package.rpm
+##end
+##variable
 #  CPACK_RPM_POST_INSTALL_SCRIPT_FILE
 #  CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
 #     Mandatory : NO
@@ -161,6 +201,8 @@
 #     CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE
 #     One may verify which scriptlet has been included with
 #      rpm -qp --scripts  package.rpm
+##end
+##variable
 #  CPACK_RPM_USER_FILELIST
 #  CPACK_RPM_<COMPONENT>_USER_FILELIST
 #     Mandatory : NO
@@ -170,12 +212,15 @@
 #     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.
-#  CPACK_RPM_CHANGELOG_FILE
+##end
+##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.
+##end
 
 #=============================================================================
 # Copyright 2007-2009 Kitware, Inc.