Merge topic 'ImproveCPackDoc-reloaded'

d4b77eb Avoid discovering system infos for documentation. Adding some path is enough.
9002f73 Fix non existent std::string::clear on VS6
02ccb32 Create getDocumentedModulesListInDir which may be used in other context.
24fbc28 Add missing section markup for CPackComponent
bafd8a9 Example of builtin variable documentation (i.e. only used in C++ source code).
543f1ad Make the load of script documentation more efficient and dynamic.
cdbd1a9 Fix another compiler warning due to a typo
52c53de Really avoid compiler warning about unused vars
37f90ed Calm down compiler warning about unused var
7c82b7f Fix potential bad memory access, thanks to Eike
62b589b Suppress unused var, beautify code, avoid 1 extra newline.
751713f Update bash completion file in order to handle new CPack doc options.
1629615 CPack Documentation extraction from CMake script begins to work
83e34dd Implement simple CMake script comment markup language.
c6a0169 CPack begin the implementation of --help-command* and --help-variables*

5 files changed, 179 insertions, 6 deletions

diff --git a/Source/CPack/cmCPackDocumentMacros.cxx b/Source/CPack/cmCPackDocumentMacros.cxx
new file mode 100644
index 0000000..ddc75a4
--- /dev/null
+++ b/Source/CPack/cmCPackDocumentMacros.cxx
@@ -0,0 +1,16 @@
+#include "cmCPackDocumentMacros.h"
+
+void cmCPackDocumentMacros::GetMacrosDocumentation(
+        std::vector<cmDocumentationEntry>& )
+{
+   // Commented-out example of use
+   //
+   //    cmDocumentationEntry e("cpack_<macro>",
+   //            "Brief Description"
+   //            "which may be on several lines.",
+   //            "Long description in pre-formatted format"
+   //            "                          blah\n"
+   //            "                          blah\n"
+   //);
+   //v.push_back(e);
+}
diff --git a/Source/CPack/cmCPackDocumentMacros.h b/Source/CPack/cmCPackDocumentMacros.h
new file mode 100644
index 0000000..544f74f
--- /dev/null
+++ b/Source/CPack/cmCPackDocumentMacros.h
@@ -0,0 +1,21 @@
+/*============================================================================
+  CMake - Cross Platform Makefile Generator
+  Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
+
+  Distributed under the OSI-approved BSD License (the "License");
+  see accompanying file Copyright.txt for details.
+
+  This software is distributed WITHOUT ANY WARRANTY; without even the
+  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the License for more information.
+============================================================================*/
+#ifndef cmCPackDocumentMacros_h
+#define cmCPackDocumentMacros_h
+#include "cmStandardIncludes.h"
+class cmCPackDocumentMacros
+{
+public:
+  static void GetMacrosDocumentation(std::vector<cmDocumentationEntry>& v);
+};
+
+#endif
diff --git a/Source/CPack/cmCPackDocumentVariables.cxx b/Source/CPack/cmCPackDocumentVariables.cxx
new file mode 100644
index 0000000..68cde78
--- /dev/null
+++ b/Source/CPack/cmCPackDocumentVariables.cxx
@@ -0,0 +1,32 @@
+#include "cmCPackDocumentVariables.h"
+#include "cmake.h"
+
+void cmCPackDocumentVariables::DefineVariables(cmake* cm)
+{
+  // Subsection: variables defined/used by cpack,
+  // which are common to all CPack generators
+
+  cm->DefineProperty
+      ("CPACK_PACKAGING_INSTALL_PREFIX", cmProperty::VARIABLE,
+       "The prefix used in the built package.",
+       "Each CPack generator has a default value (like /usr)."
+       " This default value may"
+       " be overwritten from the CMakeLists.txt or the cpack command line"
+       " by setting an alternative value.\n"
+       "e.g. "
+       " set(CPACK_PACKAGING_INSTALL_PREFIX \"/opt\")\n"
+       "This is not the same purpose as CMAKE_INSTALL_PREFIX which"
+       " is used when installing from the build tree without building"
+       " a package."
+       "", false,
+       "Variables common to all CPack generators");
+
+  // Subsection: variables defined/used by cpack,
+  // which are specific to one CPack generator
+//  cm->DefineProperty
+//      ("CPACK_RPM_PACKAGE_NAME", cmProperty::VARIABLE,
+//       "RPM specific package name.",
+//       "If not specified, defaults to CPACK_PACKAGE_NAME."
+//       "", false,
+//       "Variables specific to a CPack generator");
+}
diff --git a/Source/CPack/cmCPackDocumentVariables.h b/Source/CPack/cmCPackDocumentVariables.h
new file mode 100644
index 0000000..e7971be
--- /dev/null
+++ b/Source/CPack/cmCPackDocumentVariables.h
@@ -0,0 +1,21 @@
+/*============================================================================
+  CMake - Cross Platform Makefile Generator
+  Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
+
+  Distributed under the OSI-approved BSD License (the "License");
+  see accompanying file Copyright.txt for details.
+
+  This software is distributed WITHOUT ANY WARRANTY; without even the
+  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+  See the License for more information.
+============================================================================*/
+#ifndef cmCPackDocumentVariables_h
+#define cmCPackDocumentVariables_h
+class cmake;
+class cmCPackDocumentVariables
+{
+public:
+  static void DefineVariables(cmake* cm);
+};
+
+#endif
diff --git a/Source/CPack/cpack.cxx b/Source/CPack/cpack.cxx
index 163f744..c541610 100644
--- a/Source/CPack/cpack.cxx
+++ b/Source/CPack/cpack.cxx
@@ -14,6 +14,8 @@
 // Need these for documentation support.
 #include "cmake.h"
 #include "cmDocumentation.h"
+#include "cmCPackDocumentVariables.h"
+#include "cmCPackDocumentMacros.h"
 #include "cmCPackGeneratorFactory.h"
 #include "cmCPackGenerator.h"
 #include "cmake.h"
@@ -24,6 +26,7 @@
 #include "cmCPackLog.h"
 
 #include <cmsys/CommandLineArguments.hxx>
+#include <cmsys/SystemTools.hxx>
 #include <memory> // auto_ptr
 
 //----------------------------------------------------------------------------
@@ -90,6 +93,40 @@ static const char * cmDocumentationOptions[][3] =
      "If vendor is not specified on cpack command line "
      "(or inside CMakeLists.txt) then"
      "CPack.cmake defines it with a default value"},
+    {"--help-command cmd [file]", "Print help for a single command and exit.",
+    "Full documentation specific to the given command is displayed. "
+    "If a file is specified, the documentation is written into and the output "
+    "format is determined depending on the filename suffix. Supported are man "
+    "page, HTML, DocBook and plain text."},
+    {"--help-command-list [file]", "List available commands and exit.",
+     "The list contains all commands for which help may be obtained by using "
+     "the --help-command argument followed by a command name. "
+    "If a file is specified, the documentation is written into and the output "
+    "format is determined depending on the filename suffix. Supported are man "
+    "page, HTML, DocBook and plain text."},
+    {"--help-commands [file]", "Print help for all commands and exit.",
+     "Full documentation specific for all current command is displayed."
+    "If a file is specified, the documentation is written into and the output "
+    "format is determined depending on the filename suffix. Supported are man "
+    "page, HTML, DocBook and plain text."},
+    {"--help-variable var [file]",
+     "Print help for a single variable and exit.",
+     "Full documentation specific to the given variable is displayed."
+    "If a file is specified, the documentation is written into and the output "
+    "format is determined depending on the filename suffix. Supported are man "
+    "page, HTML, DocBook and plain text."},
+    {"--help-variable-list [file]", "List documented variables and exit.",
+     "The list contains all variables for which help may be obtained by using "
+     "the --help-variable argument followed by a variable name.  If a file is "
+     "specified, the help is written into it."
+    "If a file is specified, the documentation is written into and the output "
+    "format is determined depending on the filename suffix. Supported are man "
+     "page, HTML, DocBook and plain text."},
+    {"--help-variables [file]", "Print help for all variables and exit.",
+     "Full documentation for all variables is displayed."
+    "If a file is specified, the documentation is written into and the output "
+    "format is determined depending on the filename suffix. Supported are man "
+    "page, HTML, DocBook and plain text."},
     {0,0,0}
 };
 
@@ -137,12 +174,15 @@ int cpackDefinitionArgument(const char* argument, const char* cValue,
   return 1;
 }
 
+
 //----------------------------------------------------------------------------
 // this is CPack.
 int main (int argc, char *argv[])
 {
   cmSystemTools::FindExecutableDirectory(argv[0]);
   cmCPackLog log;
+  int nocwd = 0;
+
   log.SetErrorPrefix("CPack Error: ");
   log.SetWarningPrefix("CPack Warning: ");
   log.SetOutputPrefix("CPack: ");
@@ -154,6 +194,7 @@ int main (int argc, char *argv[])
     {
     cmCPack_Log(&log, cmCPackLog::LOG_ERROR,
       "Current working directory cannot be established." << std::endl);
+    nocwd = 1;
     }
 
   std::string generator;
@@ -179,7 +220,6 @@ int main (int argc, char *argv[])
 
   cpackConfigFile = "";
 
-  cmDocumentation doc;
   cmsys::CommandLineArguments arg;
   arg.Initialize(argc, argv);
   typedef cmsys::CommandLineArguments argT;
@@ -252,17 +292,25 @@ int main (int argc, char *argv[])
   generators.SetLogger(&log);
   cmCPackGenerator* cpackGenerator = 0;
 
-  if ( !helpFull.empty() || !helpMAN.empty() ||
-    !helpHTML.empty() || helpVersion )
+  cmDocumentation doc;
+  doc.addCPackStandardDocSections();
+  /* Were we invoked to display doc or to do some work ? */
+  if(doc.CheckOptions(argc, argv,"-G") || nocwd)
     {
-    help = true;
+      help = true;
     }
+  else
+    {
+      help = false;
+    }
+
+  // This part is used for cpack documentation lookup as well.
+  cminst.AddCMakePaths();
 
   if ( parsed && !help )
     {
     // find out which system cpack is running on, so it can setup the search
     // paths, so FIND_XXX() commands can be used in scripts
-    cminst.AddCMakePaths();
     std::string systemFile =
       globalMF->GetModulesFile("CMakeDetermineSystem.cmake");
     if (!globalMF->ReadListFile(0, systemFile.c_str()))
@@ -465,14 +513,49 @@ int main (int argc, char *argv[])
    */
   if ( help )
     {
-    doc.CheckOptions(argc, argv);
     // Construct and print requested documentation.
+    std::vector<cmDocumentationEntry> variables;
+
     doc.SetName("cpack");
     doc.SetSection("Name",cmDocumentationName);
     doc.SetSection("Usage",cmDocumentationUsage);
     doc.SetSection("Description",cmDocumentationDescription);
     doc.PrependSection("Options",cmDocumentationOptions);
 
+    // statically (in C++ code) defined variables
+    cmCPackDocumentVariables::DefineVariables(&cminst);
+
+    std::vector<cmDocumentationEntry> commands;
+
+    std::string                              docedFile;
+    std::string                              docPath;
+    cmDocumentation::documentedModulesList_t docedModList;
+
+    docedFile = globalMF->GetModulesFile("CPack.cmake");
+    if (docedFile.length()!=0)
+      {
+      docPath = cmSystemTools::GetFilenamePath(docedFile.c_str());
+      doc.getDocumentedModulesListInDir(docPath,"CPack*.cmake",docedModList);
+      }
+
+    // parse the files for documentation.
+    cmDocumentation::documentedModulesList_t::iterator docedIt;
+    for (docedIt = docedModList.begin();
+         docedIt!= docedModList.end(); ++docedIt)
+      {
+          doc.GetStructuredDocFromFile(
+              (docedIt->first).c_str(),
+              commands,&cminst,(docedIt->second).c_str());
+      }
+
+    std::map<std::string,cmDocumentationSection *> propDocs;
+    cminst.GetPropertiesDocumentation(propDocs);
+    doc.SetSections(propDocs);
+    cminst.GetCommandDocumentation(commands,true,false);
+    // statically (in C++ code) defined macros/commands
+    cmCPackDocumentMacros::GetMacrosDocumentation(commands);
+    doc.SetSection("Commands",commands);
+
     std::vector<cmDocumentationEntry> v;
     cmCPackGeneratorFactory::DescriptionsMap::const_iterator generatorIt;
     for( generatorIt = generators.GetGeneratorsList().begin();