CPack begin the implementation of --help-command* and --help-variables*

This modifications set tries to keep the unified doc for cmake/ctest/cpack
while introducing tool specific documentation separated.
Some documentation sections for CMake do not fit well to CPack.

5 files changed, 211 insertions, 5 deletions

diff --git a/Source/CPack/cmCPackDocumentMacros.cxx b/Source/CPack/cmCPackDocumentMacros.cxx
new file mode 100644
index 0000000..0dd51a9
--- /dev/null
+++ b/Source/CPack/cmCPackDocumentMacros.cxx
@@ -0,0 +1,78 @@
+#include "cmCPackDocumentMacros.h"
+
+void cmCPackDocumentMacros::GetMacrosDocumentation(
+        std::vector<cmDocumentationEntry>& v)
+{
+    cmDocumentationEntry e("cpack_add_component",
+            "Describes a CPack installation component "
+            "named by the COMPONENT argument to a CMake INSTALL command.",
+            "       cpack_add_component(compname\n"
+            "                          [DISPLAY_NAME name]\n"
+            "                          [DESCRIPTION description]\n"
+            "                          [HIDDEN | REQUIRED | DISABLED ]\n"
+            "                          [GROUP group]\n"
+            "                          [DEPENDS comp1 comp2 ... ]\n"
+            "                          [INSTALL_TYPES type1 type2 ... ]\n"
+            "                          [DOWNLOADED]\n"
+            "                          [ARCHIVE_FILE filename])\n"
+            "\n"
+            "The cmake_add_component command describes an installation"
+            "component, which the user can opt to install or remove as part of"
+            " the graphical installation process. compname is the name of the "
+            "component, as provided to the COMPONENT argument of one or more "
+            "CMake INSTALL commands."
+            "\n"
+          "DISPLAY_NAME is the displayed name of the component, used in "
+          "graphical installers to display the component name. This value "
+          "can be any string."
+          "\n"
+          "DESCRIPTION is an extended description of the component, used in "
+          "graphical installers to give the user additional information about "
+          "the component. Descriptions can span multiple lines using \"\\n\" "
+          " as the line separator. Typically, these descriptions should be no "
+          "more than a few lines long."
+          "\n"
+          "HIDDEN indicates that this component will be hidden in the "
+          "graphical installer, so that the user cannot directly change "
+          "whether it is installed or not."
+          "\n"
+          "REQUIRED indicates that this component is required, and therefore "
+          "will always be installed. It will be visible in the graphical "
+          "installer, but it cannot be unselected. (Typically, required "
+          "components are shown greyed out)."
+          "\n"
+          "DISABLED indicates that this component should be disabled "
+          "(unselected) by default. The user is free to select this component "
+          "for installation, unless it is also HIDDEN."
+          "\n"
+          "DEPENDS lists the components on which this component depends. If "
+          "this component is selected, then each of the components listed "
+          "must also be selected. The dependency information is encoded "
+          "within the installer itself, so that users cannot install "
+          "inconsistent sets of components."
+          "\n"
+          "GROUP names the component group of which this component is a "
+          "part. If not provided, the component will be a standalone "
+          "component, not part of any component group. Component groups are "
+          "described with the cpack_add_component_group command, detailed"
+          "below."
+          "\n"
+          "INSTALL_TYPES lists the installation types of which this component "
+          "is a part. When one of these installations types is selected, this "
+          "component will automatically be selected. Installation types are"
+          "described with the cpack_add_install_type command, detailed below."
+          "\n"
+          "DOWNLOADED indicates that this component should be downloaded "
+          "on-the-fly by the installer, rather than packaged in with the "
+          "installer itself. For more information, see the "
+          "cpack_configure_downloads command."
+          "\n"
+          "ARCHIVE_FILE provides a name for the archive file created by CPack "
+          "to be used for downloaded components. If not supplied, CPack will "
+          "create a file with some name based on CPACK_PACKAGE_FILE_NAME and "
+          "the name of the component. See cpack_configure_downloads for more "
+          "information."
+);
+
+    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..1c98e7c
--- /dev/null
+++ b/Source/CPack/cmCPackDocumentVariables.cxx
@@ -0,0 +1,30 @@
+#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_PACKAGE_NAME", cmProperty::VARIABLE,
+     "The name of the package (or application).",
+     "If not specified, defaults to the project name."
+     "", false,
+     "Variables common to all CPack generators");
+
+  cm->DefineProperty
+      ("CPACK_PACKAGE_VENDOR", cmProperty::VARIABLE,
+       "The name of the package vendor.",
+       "If not specified, defaults to \"Humanity\"."
+       "", 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..2cfbf12 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"
@@ -90,6 +92,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 +173,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 +193,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 +219,6 @@ int main (int argc, char *argv[])
 
   cpackConfigFile = "";
 
-  cmDocumentation doc;
   cmsys::CommandLineArguments arg;
   arg.Initialize(argc, argv);
   typedef cmsys::CommandLineArguments argT;
@@ -252,10 +291,16 @@ 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;
     }
 
   if ( parsed && !help )
@@ -465,14 +510,25 @@ 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);
 
+    cmCPackDocumentVariables::DefineVariables(&cminst);
+    std::map<std::string,cmDocumentationSection *> propDocs;
+    cminst.GetPropertiesDocumentation(propDocs);
+    doc.SetSections(propDocs);
+
+    std::vector<cmDocumentationEntry> commands;
+    cminst.GetCommandDocumentation(commands);
+    cmCPackDocumentMacros::GetMacrosDocumentation(commands);
+    doc.SetSection("Commands",commands);
+
     std::vector<cmDocumentationEntry> v;
     cmCPackGeneratorFactory::DescriptionsMap::const_iterator generatorIt;
     for( generatorIt = generators.GetGeneratorsList().begin();