ENH: generate separate documentation for the commands, compatiblity

commands, modules and properties as html, text and man pages.
The names of the man pages are cmcommands, cmcompat, cmprops and cmmodules,
so they are easy to type.

Alex

Source/cmDocumentation.cxx

@@ -305,14 +305,28 @@ bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os)
       return this->PrintDocumentationSingleModule(os);
     case cmDocumentation::SingleProperty:
       return this->PrintDocumentationSingleProperty(os);
-    case cmDocumentation::List:      return this->PrintDocumentationList(os);
-    case cmDocumentation::ModuleList: return this->PrintModuleList(os);
-    case cmDocumentation::PropertyList: return this->PrintPropertyList(os);
-
-    case cmDocumentation::Full: return this->PrintDocumentationFull(os);
-
-    case cmDocumentation::Copyright: return this->PrintCopyright(os);
-    case cmDocumentation::Version:   return true;
+    case cmDocumentation::List:      
+      return this->PrintDocumentationList(os);
+    case cmDocumentation::ModuleList: 
+      return this->PrintModuleList(os);
+    case cmDocumentation::PropertyList: 
+      return this->PrintPropertyList(os);
+
+    case cmDocumentation::Full: 
+      return this->PrintDocumentationFull(os);
+    case cmDocumentation::Modules: 
+      return this->PrintDocumentationModules(os);
+    case cmDocumentation::Properties: 
+      return this->PrintDocumentationProperties(os);
+    case cmDocumentation::Commands: 
+      return this->PrintDocumentationCurrentCommands(os);
+    case cmDocumentation::CompatCommands: 
+      return this->PrintDocumentationCompatCommands(os);
+
+    case cmDocumentation::Copyright: 
+      return this->PrintCopyright(os);
+    case cmDocumentation::Version:   
+      return true;
     default: return false;
     }
 }
@@ -549,6 +563,30 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv)
         help.Type = cmDocumentation::Single;
         }
       }
+    else if(strcmp(argv[i], "--help-properties") == 0)
+      {
+      help.Type = cmDocumentation::Properties;
+      GET_OPT_FILENAME(help.Filename);
+      help.Form = this->GetFormFromFilename(help.Filename);
+      }
+    else if(strcmp(argv[i], "--help-modules") == 0)
+      {
+      help.Type = cmDocumentation::Modules;
+      GET_OPT_FILENAME(help.Filename);
+      help.Form = this->GetFormFromFilename(help.Filename);
+      }
+    else if(strcmp(argv[i], "--help-commands") == 0)
+      {
+      help.Type = cmDocumentation::Commands;
+      GET_OPT_FILENAME(help.Filename);
+      help.Form = this->GetFormFromFilename(help.Filename);
+      }
+    else if(strcmp(argv[i], "--help-compatcommands") == 0)
+      {
+      help.Type = cmDocumentation::CompatCommands;
+      GET_OPT_FILENAME(help.Filename);
+      help.Form = this->GetFormFromFilename(help.Filename);
+      }
     else if(strcmp(argv[i], "--help-full") == 0)
       {
       help.Type = cmDocumentation::Full;
@@ -1387,6 +1425,46 @@ bool cmDocumentation::PrintDocumentationFull(std::ostream& os)
   return true;
 }
 
+//----------------------------------------------------------------------------
+bool cmDocumentation::PrintDocumentationModules(std::ostream& os)
+{
+  this->CreateModulesDocumentation();
+  this->PrintHeader(GetNameString(), os);
+  this->Print(os);
+  this->PrintFooter(os);
+  return true;
+}
+
+//----------------------------------------------------------------------------
+bool cmDocumentation::PrintDocumentationProperties(std::ostream& os)
+{
+  this->CreatePropertiesDocumentation();
+  this->PrintHeader(GetNameString(), os);
+  this->Print(os);
+  this->PrintFooter(os);
+  return true;
+}
+
+//----------------------------------------------------------------------------
+bool cmDocumentation::PrintDocumentationCurrentCommands(std::ostream& os)
+{
+  this->CreateCurrentCommandsDocumentation();
+  this->PrintHeader(GetNameString(), os);
+  this->Print(os);
+  this->PrintFooter(os);
+  return true;
+}
+
+//----------------------------------------------------------------------------
+bool cmDocumentation::PrintDocumentationCompatCommands(std::ostream& os)
+{
+  this->CreateCompatCommandsDocumentation();
+  this->PrintHeader(GetNameString(), os);
+  this->Print(os);
+  this->PrintFooter(os);
+  return true;
+}
+
 //----------------------------------------------------------------------------
 void cmDocumentation::PrintHeader(const char* name, std::ostream& os)
 {
@@ -1476,19 +1554,17 @@ void cmDocumentation::CreateFullDocumentation()
     }
 }
 
-void cmDocumentation::CreateCurrentCommandDocumentation()
+void cmDocumentation::CreateCurrentCommandsDocumentation()
 {
   this->ClearSections();
-  this->AddSection(this->DescriptionSection.GetName(CurrentForm), 
-                   cmCompatCommandsDocumentationDescription);
-  this->AddSection(this->CompatCommandsSection);
+  this->AddSection(this->CommandsSection);
   this->AddSection(this->CopyrightSection.GetName(CurrentForm), 
                    cmDocumentationCopyright);
   this->AddSection(this->SeeAlsoSection.GetName(CurrentForm), 
                    cmDocumentationStandardSeeAlso);
 }
 
-void cmDocumentation::CreateCompatCommandDocumentation()
+void cmDocumentation::CreateCompatCommandsDocumentation()
 {
   this->ClearSections();
   this->AddSection(this->DescriptionSection.GetName(CurrentForm), 
@@ -1502,8 +1578,9 @@ void cmDocumentation::CreateCompatCommandDocumentation()
 
 //----------------------------------------------------------------------------
 void cmDocumentation::CreateModulesDocumentation()
- {
-   this->ClearSections();
+{
+  this->ClearSections();
+  this->CreateModulesSection();
   this->AddSection(this->DescriptionSection.GetName(CurrentForm), 
                    cmModulesDocumentationDescription);
   this->AddSection(this->ModulesSection);

Source/cmDocumentation.h

@@ -31,7 +31,8 @@ public:
   /** Types of help provided.  */
   enum Type { None, Usage, Single, SingleModule, SingleProperty,
               List, ModuleList, PropertyList,
-              Full, Copyright, Version };
+              Full, Properties, Modules, Commands, CompatCommands,
+              Copyright, Version };
   
   /**
    * Check command line arguments for documentation options.  Returns
@@ -205,13 +206,17 @@ private:
   bool PrintDocumentationSingleProperty(std::ostream& os);
   bool PrintDocumentationUsage(std::ostream& os);
   bool PrintDocumentationFull(std::ostream& os);
+  bool PrintDocumentationModules(std::ostream& os);
+  bool PrintDocumentationProperties(std::ostream& os);
+  bool PrintDocumentationCurrentCommands(std::ostream& os);
+  bool PrintDocumentationCompatCommands(std::ostream& os);
   void PrintDocumentationCommand(std::ostream& os,
                                  const cmDocumentationEntry* entry);
   
   void CreateUsageDocumentation();
   void CreateFullDocumentation();
-  void CreateCurrentCommandDocumentation();
-  void CreateCompatCommandDocumentation();
+  void CreateCurrentCommandsDocumentation();
+  void CreateCompatCommandsDocumentation();
   void CreateModulesDocumentation();
   void CreatePropertiesDocumentation();
 

Source/cmakemain.cxx

@@ -100,12 +100,18 @@ static const cmDocumentationEntry cmDocumentationOptions[] =
    "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 help is written into it."},
+  {"--help-commands [file]", "Print help for all commands and exit.",
+   "Full documentation specific for all current command is displayed."},
+  {"--help-compatcommands [file]", "Print help for compatibility commands. ",
+   "Full documentation specific for all compatibility commands is displayed."},
   {"--help-module module [file]", "Print help for a single module and exit.",
    "Full documentation specific to the given module is displayed."},
   {"--help-module-list [file]", "List available modules and exit.",
    "The list contains all modules for which help may be obtained by using "
    "the --help-module argument followed by a module name.  If a file is "
    "specified, the help is written into it."},
+  {"--help-modules [file]", "Print help for all modules and exit.",
+   "Full documentation for all modules is displayed."},
   {"--help-property prop [file]", 
    "Print help for a single property and exit.",
    "Full documentation specific to the given module is displayed."},
@@ -113,6 +119,8 @@ static const cmDocumentationEntry cmDocumentationOptions[] =
    "The list contains all properties for which help may be obtained by using "
    "the --help-property argument followed by a property name.  If a file is "
    "specified, the help is written into it."},
+  {"--help-properties [file]", "Print help for all properties and exit.",
+   "Full documentation for all properties is displayed."},
   {0,0,0}
 };
 

Utilities/CMakeLists.txt

@@ -29,22 +29,56 @@ MACRO(ADD_DOCS target dependency)
 ENDMACRO(ADD_DOCS target dependency)
 
 # add the docs for the executables
-ADD_DOCS(cmake      ${CMake_SOURCE_DIR}/Utilities/Doxygen/authors.txt)
 ADD_DOCS(ctest      ${CMake_SOURCE_DIR}/Utilities/Doxygen/authors.txt)
 ADD_DOCS(cpack      ${CMake_SOURCE_DIR}/Utilities/Doxygen/authors.txt)
 ADD_DOCS(ccmake     ${CMake_SOURCE_DIR}/Utilities/Doxygen/authors.txt)
 ADD_DOCS(CMakeSetup ${CMake_SOURCE_DIR}/Utilities/Doxygen/doxyfile.in)
 
-# add the Copyright file
+# add the documentation for cmake itself
+SET(CMAKE_DOC_FILES 
+    ${CMake_BINARY_DIR}/Docs/cmake.txt
+    ${CMake_BINARY_DIR}/Docs/cmake.html
+    ${CMake_BINARY_DIR}/Docs/cmake-properties.txt
+    ${CMake_BINARY_DIR}/Docs/cmake-properties.html
+    ${CMake_BINARY_DIR}/Docs/cmake-modules.txt
+    ${CMake_BINARY_DIR}/Docs/cmake-modules.html
+    ${CMake_BINARY_DIR}/Docs/cmake-commands.txt
+    ${CMake_BINARY_DIR}/Docs/cmake-commands.html
+    ${CMake_BINARY_DIR}/Docs/cmake-compatcommands.txt
+    ${CMake_BINARY_DIR}/Docs/cmake-compatcommands.html )
+
+
 GET_TARGET_PROPERTY(CMD cmake LOCATION)
 ADD_CUSTOM_COMMAND(
-  OUTPUT ${CMake_BINARY_DIR}/Docs/Copyright.txt
+  OUTPUT ${CMAKE_DOC_FILES}
   COMMAND ${CMD} --copyright ${CMake_BINARY_DIR}/Docs/Copyright.txt
+       --help-full ${CMake_BINARY_DIR}/Docs/cmake.txt
+       --help-full ${CMake_BINARY_DIR}/Docs/cmake.html
+       --help-full ${CMake_BINARY_DIR}/Docs/cmake.1
+       --help-properties ${CMake_BINARY_DIR}/Docs/cmake-properties.txt
+       --help-properties ${CMake_BINARY_DIR}/Docs/cmake-properties.html
+       --help-properties ${CMake_BINARY_DIR}/Docs/cmprops.1
+       --help-modules ${CMake_BINARY_DIR}/Docs/cmake-modules.txt
+       --help-modules ${CMake_BINARY_DIR}/Docs/cmake-modules.html
+       --help-modules ${CMake_BINARY_DIR}/Docs/cmmodules.1
+       --help-commands ${CMake_BINARY_DIR}/Docs/cmake-commands.txt
+       --help-commands ${CMake_BINARY_DIR}/Docs/cmake-commands.html
+       --help-commands ${CMake_BINARY_DIR}/Docs/cmcommands.1
+       --help-compatcommands ${CMake_BINARY_DIR}/Docs/cmake-compatcommands.txt
+       --help-compatcommands ${CMake_BINARY_DIR}/Docs/cmake-compatcommands.html
+       --help-compatcommands ${CMake_BINARY_DIR}/Docs/cmcompat.1
   DEPENDS ${target}
   MAIN_DEPENDENCY ${CMake_SOURCE_DIR}/Utilities/Doxygen/authors.txt
   )
-INSTALL_FILES(${CMAKE_DOC_DIR} FILES ${CMake_BINARY_DIR}/Docs/Copyright.txt )
-SET(DOC_FILES ${DOC_FILES} ${CMake_BINARY_DIR}/Docs/Copyright.txt)
+
+INSTALL_FILES(${CMAKE_MAN_DIR}/man1 FILES
+              ${CMake_BINARY_DIR}/Docs/cmake.1
+              ${CMake_BINARY_DIR}/Docs/cmcommands.1
+              ${CMake_BINARY_DIR}/Docs/cmcompat.1
+              ${CMake_BINARY_DIR}/Docs/cmprops.1
+              ${CMake_BINARY_DIR}/Docs/cmmodules.1)
+
+INSTALL_FILES(${CMAKE_DOC_DIR} FILES ${CMAKE_DOC_FILES} )
 
 # Drive documentation generation.
-ADD_CUSTOM_TARGET(documentation ALL DEPENDS ${DOC_FILES} )
+ADD_CUSTOM_TARGET(documentation ALL DEPENDS ${DOC_FILES} ${CMAKE_DOC_FILES} )