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.

2 files changed, 65 insertions, 15 deletions

diff --git a/Source/CPack/cpack.cxx b/Source/CPack/cpack.cxx
index 4117971..25a72fa 100644
--- a/Source/CPack/cpack.cxx
+++ b/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
-    // 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);
-    docPair.first  = "CPackRPM.cmake";
-    docPair.second = "Variables specific to a CPack generator";
-    docedModList.push_back(docPair);
-    docPair.first  = "CPackDeb.cmake";
-    docedModList.push_back(docPair);
+    cmsys::Glob gl;
+    std::string findExpr;
+    std::vector<std::string> files;
+    std::string line;
+    docedFile = globalMF->GetModulesFile("CPack.cmake");
+    if (docedFile.length()!=0)
+      {
+      findExpr += cmSystemTools::GetFilenamePath(docedFile.c_str());
+      findExpr += "/CPack*.cmake";
+      if (gl.FindFiles(findExpr))
+        {
+        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();
diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx
index 80f74a6..ed1e5e1 100644
--- a/Source/cmDocumentation.cxx
+++ b/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;