Make the load of script documentation more efficient and dynamic.

CPack help will be searched in any CPack*.cmake file located
near to CPack.cmake file. The script files is parsed iff
the first line begin with ##section. Moreover the documentation
section name is specified on the remaining part of the line
minus the space immediately following ##section.

Modules/CPack.cmake

@@ -1,3 +1,6 @@
+##section Variables common to all CPack generators
+##end
+##module
 # - 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
@@ -28,16 +31,16 @@
 # on a per-generator basis. It only need contain overrides.
 #
 # Here's how it works:
-# - cpack runs
+#  - cpack runs
-# - it includes CPackConfig.cmake
+#  - it includes CPackConfig.cmake
-# - it iterates over the generators listed in that file's
+#  - it iterates over the generators listed in that file's
-#     CPACK_GENERATOR list variable (unless told to use just a
+#    CPACK_GENERATOR list variable (unless told to use just a
-#     specific one via -G on the command line...)
+#    specific one via -G on the command line...)
 #
-# - foreach generator, it then
+#  - foreach generator, it then
-#   - sets CPACK_GENERATOR to the one currently being iterated
+#    - sets CPACK_GENERATOR to the one currently being iterated
-#   - includes the CPACK_PROJECT_CONFIG_FILE
+#    - includes the CPACK_PROJECT_CONFIG_FILE
-#   - produces the package for that generator
+#    - 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
@@ -47,6 +50,7 @@
 # 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:
+##end
 #
 ##variable
 #   CPACK_PACKAGE_NAME - The name of the package (or application). If

Modules/CPackDeb.cmake

@@ -1,3 +1,6 @@
+##section Variables specific to a CPack generator
+##end
+##module
 # - The builtin (binary) CPack Deb generator (Unix only)
 # CPackDeb may be used to create Deb package using CPack.
 # CPackDeb is a CPack generator thus it uses the CPACK_XXX variables
@@ -11,6 +14,7 @@
 # the wiki:
 #  http://www.cmake.org/Wiki/CMake:CPackPackageGenerators#DEB_.28UNIX_only.29
 # However as a handy reminder here comes the list of specific variables:
+##end
 #
 ##variable
 # CPACK_DEBIAN_PACKAGE_NAME

Modules/CPackRPM.cmake

@@ -1,5 +1,7 @@
-# - The builtin (binary) CPack RPM generator (Unix only)
+##section Variables specific to a CPack generator
+##end
 ##module
+# - The builtin (binary) CPack RPM generator (Unix only)
 # 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

Source/CPack/cpack.cxx

@@ -26,6 +26,8 @@
 #include "cmCPackLog.h"
 
 #include <cmsys/CommandLineArguments.hxx>
+#include <cmsys/Glob.hxx>
+#include <cmsys/SystemTools.hxx>
 #include <memory> // auto_ptr
 
 //----------------------------------------------------------------------------
@@ -527,22 +529,54 @@ int main (int argc, char *argv[])
 
     typedef std::pair<std::string,std::string> docModuleSectionPair_t;
     typedef std::list<docModuleSectionPair_t>  docedModulesList_t;
-    docedModulesList_t docedModList;
+    docedModulesList_t     docedModList;
     docModuleSectionPair_t docPair;
     std::string            docedFile;
 
-    // build the list of files to be parsed for documentation
+    cmsys::Glob gl;
-    // extraction
+    std::string findExpr;
-    docPair.first  = "CPack.cmake";
+    std::vector<std::string> files;
-    docPair.second = "Variables common to all CPack generators";
+    std::string line;
-    docedModList.push_back(docPair);
+    docedFile = globalMF->GetModulesFile("CPack.cmake");
-    docPair.first  = "CPackComponent.cmake";
+    if (docedFile.length()!=0)
-    docedModList.push_back(docPair);
+      {
-    docPair.first  = "CPackRPM.cmake";
+      findExpr += cmSystemTools::GetFilenamePath(docedFile.c_str());
-    docPair.second = "Variables specific to a CPack generator";
+      findExpr += "/CPack*.cmake";
-    docedModList.push_back(docPair);
+      if (gl.FindFiles(findExpr))
-    docPair.first  = "CPackDeb.cmake";
+        {
-    docedModList.push_back(docPair);
+        files = gl.GetFiles();
+        for (std::vector<std::string>::iterator itf=files.begin();
+             itf!=files.end();++itf)
+          {
+          std::ifstream fin((*itf).c_str());
+          if (!fin) continue;
+          if (cmSystemTools::GetLineFromStream(fin, line))
+            {
+            if (line.find("##section")!=std::string::npos)
+              {
+              docPair.first = cmSystemTools::GetFilenameName(*itf);
+              // 10 is the size of '##section' + 1
+              docPair.second = line.substr(10,std::string::npos);
+              docedModList.push_back(docPair);
+              }
+            }
+          else
+            {
+            line.clear();
+            }
+          }
+        }
+      else
+        {
+        // build the list of files to be parsed for documentation
+        // extraction
+        docPair.first  = "CPack.cmake";
+        docPair.second = "Variables common to all CPack generators";
+        docedModList.push_back(docPair);
+        docPair.first  = "CPackComponent.cmake";
+        docedModList.push_back(docPair);
+        }
+      }
 
     // parse the files for documentation.
     for (docedModulesList_t::iterator it = docedModList.begin();

Source/cmDocumentation.cxx

@@ -768,6 +768,7 @@ int cmDocumentation::GetStructuredDocFromFile(
 {
     typedef enum sdoce {
         SDOC_NONE, SDOC_MODULE, SDOC_MACRO, SDOC_FUNCTION, SDOC_VARIABLE,
+        SDOC_SECTION,
         SDOC_UNKNOWN} sdoc_t;
     int nbDocItemFound = 0;
     int docCtxIdx      = 0;
@@ -795,9 +796,13 @@ int cmDocumentation::GetStructuredDocFromFile(
       if(line.size() && line[0] == '#')
         {
         /* handle structured doc context */
-        if (line[1]=='#')
+        if ((line.size()>=2) && line[1]=='#')
         {
-            std::string mkword = line.substr(2,std::string::npos);
+            /* markup word is following '##' stopping at first space
+             * Some markup word like 'section' may have more characters
+             * following but we don't handle those here.
+             */
+            std::string mkword = line.substr(2,line.find(' ',2)-2);
             if (mkword=="macro")
             {
                docCtxIdx++;
@@ -822,6 +827,14 @@ int cmDocumentation::GetStructuredDocFromFile(
                docContextStack[docCtxIdx]=SDOC_MODULE;
                newCtx = true;
             }
+            else if (mkword=="section")
+            {
+               docCtxIdx++;
+               docContextStack[docCtxIdx]=SDOC_SECTION;
+               /* drop the rest of the line */
+               line.clear();
+               newCtx = true;
+            }
             else if (mkword.substr(0,3)=="end")
             {
                switch (docContextStack[docCtxIdx]) {
@@ -841,6 +854,9 @@ int cmDocumentation::GetStructuredDocFromFile(
                case SDOC_MODULE:
                    /*  not implemented */
                    break;
+               case SDOC_SECTION:
+                   /*  not implemented */
+                   break;
                default:
                    /* ignore other cases */
                    break;