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.

Source/CMakeLists.txt

@@ -449,6 +449,8 @@ SET(CPACK_SRCS
   CPack/cmCPackTarBZip2Generator.cxx
   CPack/cmCPackTarCompressGenerator.cxx
   CPack/cmCPackZIPGenerator.cxx
+  CPack/cmCPackDocumentVariables.cxx
+  CPack/cmCPackDocumentMacros.cxx
   )
 
 IF(CYGWIN)

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);
+}

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

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");
+}

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

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() ||
+  cmDocumentation doc;
-    !helpHTML.empty() || helpVersion )
+  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();

Source/CursesDialog/ccmake.cxx

@@ -102,6 +102,7 @@ int main(int argc, char** argv)
 {
   cmSystemTools::FindExecutableDirectory(argv[0]);
   cmDocumentation doc;
+  doc.addCMakeStandardDocSections();
   if(doc.CheckOptions(argc, argv))
     {
     cmake hcm;

Source/QtDialog/CMakeSetup.cxx

@@ -64,6 +64,7 @@ int main(int argc, char** argv)
   // check docs first so that X is not need to get docs
   // do docs, if args were given
   cmDocumentation doc;
+  doc.addCMakeStandardDocSections();
   if(argc >1 && doc.CheckOptions(argc, argv))
     {
     // Construct and print requested documentation.

Source/cmDocumentation.cxx

@@ -220,55 +220,7 @@ cmDocumentation::cmDocumentation()
 :CurrentFormatter(0)
 {
   this->SetForm(TextForm);
-
+  this->addCommonStandardDocSections();
-  cmDocumentationSection *sec;
-
-  sec = new cmDocumentationSection("Author","AUTHOR");
-  sec->Append(cmDocumentationEntry
-              (0,
-               "This manual page was generated by the \"--help-man\" option.",
-               0));
-  this->AllSections["Author"] = sec;
-
-  sec = new cmDocumentationSection("Copyright","COPYRIGHT");
-  sec->Append(cmDocumentationCopyright);
-  this->AllSections["Copyright"] = sec;
-
-  sec = new cmDocumentationSection("See Also","SEE ALSO");
-  sec->Append(cmDocumentationStandardSeeAlso);
-  this->AllSections["Standard See Also"] = sec;
-
-  sec = new cmDocumentationSection("Options","OPTIONS");
-  sec->Append(cmDocumentationStandardOptions);
-  this->AllSections["Options"] = sec;
-
-  sec = new cmDocumentationSection("Properties","PROPERTIES");
-  sec->Append(cmPropertiesDocumentationDescription);
-  this->AllSections["Properties Description"] = sec;
-
-  sec = new cmDocumentationSection("Generators","GENERATORS");
-  sec->Append(cmDocumentationGeneratorsHeader);
-  this->AllSections["Generators"] = sec;
-
-  sec = new cmDocumentationSection("Compatibility Commands",
-                                   "COMPATIBILITY COMMANDS");
-  sec->Append(cmCompatCommandsDocumentationDescription);
-  this->AllSections["Compatibility Commands"] = sec;
-
-
-  this->PropertySections.push_back("Properties of Global Scope");
-  this->PropertySections.push_back("Properties on Directories");
-  this->PropertySections.push_back("Properties on Targets");
-  this->PropertySections.push_back("Properties on Tests");
-  this->PropertySections.push_back("Properties on Source Files");
-  this->PropertySections.push_back("Properties on Cache Entries");
-
-  this->VariableSections.push_back("Variables that Provide Information");
-  this->VariableSections.push_back("Variables That Change Behavior");
-  this->VariableSections.push_back("Variables That Describe the System");
-  this->VariableSections.push_back("Variables that Control the Build");
-  this->VariableSections.push_back("Variables for Languages");
-
   this->ShowGenerators = true;
 }
 
@@ -709,6 +661,88 @@ cmDocumentation::Form cmDocumentation::GetFormFromFilename(
   return cmDocumentation::TextForm;
 }
 
+//----------------------------------------------------------------------------
+void cmDocumentation::addCommonStandardDocSections()
+{
+    cmDocumentationSection *sec;
+
+    sec = new cmDocumentationSection("Author","AUTHOR");
+    sec->Append(cmDocumentationEntry
+               (0,
+                "This manual page was generated by the \"--help-man\" option.",
+                0));
+    this->AllSections["Author"] = sec;
+
+    sec = new cmDocumentationSection("Copyright","COPYRIGHT");
+    sec->Append(cmDocumentationCopyright);
+    this->AllSections["Copyright"] = sec;
+
+    sec = new cmDocumentationSection("See Also","SEE ALSO");
+    sec->Append(cmDocumentationStandardSeeAlso);
+    this->AllSections["Standard See Also"] = sec;
+
+    sec = new cmDocumentationSection("Options","OPTIONS");
+    sec->Append(cmDocumentationStandardOptions);
+    this->AllSections["Options"] = sec;
+
+    sec = new cmDocumentationSection("Compatibility Commands",
+                                     "COMPATIBILITY COMMANDS");
+    sec->Append(cmCompatCommandsDocumentationDescription);
+    this->AllSections["Compatibility Commands"] = sec;
+}
+
+//----------------------------------------------------------------------------
+void cmDocumentation::addCMakeStandardDocSections()
+{
+    cmDocumentationSection *sec;
+
+    sec = new cmDocumentationSection("Properties","PROPERTIES");
+    sec->Append(cmPropertiesDocumentationDescription);
+    this->AllSections["Properties Description"] = sec;
+
+    sec = new cmDocumentationSection("Generators","GENERATORS");
+    sec->Append(cmDocumentationGeneratorsHeader);
+    this->AllSections["Generators"] = sec;
+
+    this->PropertySections.push_back("Properties of Global Scope");
+    this->PropertySections.push_back("Properties on Directories");
+    this->PropertySections.push_back("Properties on Targets");
+    this->PropertySections.push_back("Properties on Tests");
+    this->PropertySections.push_back("Properties on Source Files");
+    this->PropertySections.push_back("Properties on Cache Entries");
+
+    this->VariableSections.push_back("Variables that Provide Information");
+    this->VariableSections.push_back("Variables That Change Behavior");
+    this->VariableSections.push_back("Variables That Describe the System");
+    this->VariableSections.push_back("Variables that Control the Build");
+    this->VariableSections.push_back("Variables for Languages");
+
+}
+
+//----------------------------------------------------------------------------
+void cmDocumentation::addCTestStandardDocSections()
+{
+    cmDocumentationSection *sec;
+    // This is currently done for backward compatibility reason
+    // We may suppress some of these.
+    addCMakeStandardDocSections();
+}
+
+//----------------------------------------------------------------------------
+void cmDocumentation::addCPackStandardDocSections()
+{
+    cmDocumentationSection *sec;
+
+    sec = new cmDocumentationSection("Generators","GENERATORS");
+    sec->Append(cmDocumentationGeneratorsHeader);
+    this->AllSections["Generators"] = sec;
+
+    this->VariableSections.push_back(
+            "Variables common to all CPack generators");
+    this->VariableSections.push_back(
+            "Variables specific to a CPack generator");
+}
+
 //----------------------------------------------------------------------------
 bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
                                    const char* exitOpt)

Source/cmDocumentation.h

@@ -119,6 +119,18 @@ public:
   
   static Form GetFormFromFilename(const std::string& filename);
 
+  /** Add common (to all tools) documentation section(s) */
+  void addCommonStandardDocSections();
+
+  /** Add the CMake standard documentation section(s) */
+  void addCMakeStandardDocSections();
+
+  /** Add the CTest standard documentation section(s) */
+  void addCTestStandardDocSections();
+
+  /** Add the CPack standard documentation section(s) */
+  void addCPackStandardDocSections();
+
 private:
   void SetForm(Form f);
   void SetDocName(const char* docname);

Source/cmakemain.cxx

@@ -355,6 +355,7 @@ int do_cmake(int ac, char** av)
 
 #ifdef CMAKE_BUILD_WITH_CMAKE
   cmDocumentation doc;
+  doc.addCMakeStandardDocSections();
   if(doc.CheckOptions(ac, av, "-E") || nocwd)
     { 
     // Construct and print requested documentation.

Source/ctest.cxx

@@ -291,6 +291,7 @@ int main (int argc, char *argv[])
         << "*********************************" << std::endl);
       }
     cmDocumentation doc;
+    doc.addCTestStandardDocSections();
     if(doc.CheckOptions(argc, argv) || nocwd)
       {
       // Construct and print requested documentation.