ENH: put compatibility commands in extra section and prepare for creating

separate man pages for properties, modules, commands and compatibility
commands

Alex

Source/cmDocumentation.cxx

@@ -43,6 +43,48 @@ static const cmDocumentationEntry cmDocumentationStandardOptions[] =
   {0,0,0}
 };
 
+//----------------------------------------------------------------------------
+static const cmDocumentationEntry cmModulesDocumentationDescription[] =
+{
+  {0,
+  "  CMake Modules - Modules coming with CMake, the Cross-Platform Makefile Generator.", 0},
+//  CMAKE_DOCUMENTATION_OVERVIEW,
+  {0,
+  "This is the documentation for the modules and scripts coming with CMake. "
+  "Using these modules you can check the computer system for "
+  "installed software packages, features of the compiler and the "
+  "existance of headers to name just a few.", 0},
+  {0,0,0}
+};
+
+//----------------------------------------------------------------------------
+static const cmDocumentationEntry cmPropertiesDocumentationDescription[] =
+{
+  {0,
+   "  CMake Properties - Properties supported by CMake, the Cross-Platform Makefile Generator.", 0},
+//  CMAKE_DOCUMENTATION_OVERVIEW,
+  {0,
+   "This is the documentation for the properties supported by CMake. "
+  "Properties can have different scopes. They can either be assigned to a source file, "
+  "a directory, a target or globally to CMake. "
+  "By modifying the values of properties the behaviour of the buildsystem can be "
+  "customized.", 0},
+  {0,0,0}
+};
+
+//----------------------------------------------------------------------------
+static const cmDocumentationEntry cmCompatCommandsDocumentationDescription[] =
+{
+  {0,
+   "  CMake Compatibility Listfile Commands - Obsolete commands supported by CMake for compatibility.", 0},
+//  CMAKE_DOCUMENTATION_OVERVIEW,
+  {0,
+  "This is the documentation for now obsolete listfile commands from "
+  "previous CMake versions, which are still supported for compatibility reasons. "
+  "You should instead use the newer, faster and shinier new commands. ;-)", 0},
+  {0,0,0}
+};
+
 //----------------------------------------------------------------------------
 static const cmDocumentationEntry cmDocumentationCommandsHeader[] =
 {
@@ -229,10 +271,10 @@ void cmDocumentation::AddSection(const char* name,
 void cmDocumentation::AddSection(const cmSection& section)
 {
   if (!section.IsEmpty())
-  {
-     this->Names.push_back(section.GetName(this->CurrentForm));
-     this->Sections.push_back(section.GetEntries());
-  }
+    {
+    this->Names.push_back(section.GetName(this->CurrentForm));
+    this->Sections.push_back(section.GetEntries());
+    }
 }
 
 //----------------------------------------------------------------------------
@@ -636,6 +678,13 @@ void cmDocumentation::SetCommandsSection(const cmDocumentationEntry* section)
   this->CommandsSection.Set(cmDocumentationCommandsHeader, section, 0);
 }
 
+//----------------------------------------------------------------------------
+void cmDocumentation::SetCompatCommandsSection(const cmDocumentationEntry* 
+                                               section)
+{
+  this->CompatCommandsSection.Set(cmDocumentationCommandsHeader, section, 0);
+}
+
 //----------------------------------------------------------------------------
 void cmDocumentation
 ::SetPropertiesSection(const cmDocumentationEntry* section)
@@ -1171,6 +1220,16 @@ bool cmDocumentation::PrintDocumentationSingle(std::ostream& os)
       return true;
       }
     }
+  for(cmDocumentationEntry* entry = this->CompatCommandsSection.GetEntries();
+      entry->brief; ++entry)
+    {
+    if(entry->name && this->SingleCommand == entry->name)
+      {
+      this->PrintDocumentationCommand(os, entry);
+      return true;
+      }
+    }
+
   // Argument was not a command.  Complain.
   os << "Argument \"" << this->SingleCommand.c_str()
      << "\" to --help-command is not a CMake command.  "
@@ -1380,6 +1439,7 @@ void cmDocumentation::CreateFullDocumentation()
   this->AddSection(this->OptionsSection);
   this->AddSection(this->GeneratorsSection);
   this->AddSection(this->CommandsSection);
+  this->AddSection(this->CompatCommandsSection);
   this->AddSection(this->ModulesSection);
   this->AddSection(this->PropertiesSection);
   this->AddSection(this->CopyrightSection.GetName(this->CurrentForm),
@@ -1398,6 +1458,44 @@ void cmDocumentation::CreateFullDocumentation()
     }
 }
 
+void cmDocumentation::CreateCurrentCommandDocumentation()
+{
+  this->ClearSections();
+  this->AddSection(this->DescriptionSection.GetName(CurrentForm), cmCompatCommandsDocumentationDescription);
+  this->AddSection(this->CompatCommandsSection);
+  this->AddSection(this->CopyrightSection.GetName(CurrentForm), cmDocumentationCopyright);
+  this->AddSection(this->SeeAlsoSection.GetName(CurrentForm), cmDocumentationStandardSeeAlso);
+}
+
+void cmDocumentation::CreateCompatCommandDocumentation()
+{
+  this->ClearSections();
+  this->AddSection(this->DescriptionSection.GetName(CurrentForm), cmCompatCommandsDocumentationDescription);
+  this->AddSection(this->CompatCommandsSection);
+  this->AddSection(this->CopyrightSection.GetName(CurrentForm), cmDocumentationCopyright);
+  this->AddSection(this->SeeAlsoSection.GetName(CurrentForm), cmDocumentationStandardSeeAlso);
+}
+
+//----------------------------------------------------------------------------
+void cmDocumentation::CreateModulesDocumentation()
+ {
+   this->ClearSections();
+  this->AddSection(this->DescriptionSection.GetName(CurrentForm), cmModulesDocumentationDescription);
+  this->AddSection(this->ModulesSection);
+  this->AddSection(this->CopyrightSection.GetName(CurrentForm), cmDocumentationCopyright);
+  this->AddSection(this->SeeAlsoSection.GetName(CurrentForm), cmDocumentationStandardSeeAlso);
+}
+
+//----------------------------------------------------------------------------
+void cmDocumentation::CreatePropertiesDocumentation()
+{
+  this->ClearSections();
+  this->AddSection(this->DescriptionSection.GetName(CurrentForm), cmPropertiesDocumentationDescription);
+  this->AddSection(this->PropertiesSection);
+  this->AddSection(this->CopyrightSection.GetName(CurrentForm), cmDocumentationCopyright);
+  this->AddSection(this->SeeAlsoSection.GetName(CurrentForm), cmDocumentationStandardSeeAlso);
+}
+
 //----------------------------------------------------------------------------
 void cmDocumentation::cmSection::Set(const cmDocumentationEntry* header,
                                      const cmDocumentationEntry* section,

Source/cmDocumentation.h

@@ -71,6 +71,9 @@ public:
   /** Set the listfile commands for standard document generation.  */
   void SetCommandsSection(const cmDocumentationEntry*);
   
+  /** Set the listfile compat. commands for standard document generation.  */
+  void SetCompatCommandsSection(const cmDocumentationEntry*);
+  
   /** Set the properties for standard document generation.  */
   void SetPropertiesSection(const cmDocumentationEntry*);
 
@@ -206,6 +209,10 @@ private:
   
   void CreateUsageDocumentation();
   void CreateFullDocumentation();
+  void CreateCurrentCommandDocumentation();
+  void CreateCompatCommandDocumentation();
+  void CreateModulesDocumentation();
+  void CreatePropertiesDocumentation();
 
   void SetSection(const cmDocumentationEntry* header,
                   const cmDocumentationEntry* section,

Source/cmake.cxx

@@ -2135,12 +2135,19 @@ void cmake::UpdateProgress(const char *msg, float prog)
     }
 }
 
-void cmake::GetCommandDocumentation(
-  std::vector<cmDocumentationEntry>& v) const
+void cmake::GetCommandDocumentation(std::vector<cmDocumentationEntry>& v, 
+                                    bool withCurrentCommands, 
+                                    bool withCompatCommands) const
 {
   for(RegisteredCommandsMap::const_iterator j = this->Commands.begin();
       j != this->Commands.end(); ++j)
     {
+      if (((  withCompatCommands == false) && ( (*j).second->IsDiscouraged()))
+        || ((withCurrentCommands == false) && (!(*j).second->IsDiscouraged())))
+        {
+        continue;
+        }
+
     cmDocumentationEntry e =
       {
         (*j).second->GetName(),

Source/cmake.h

@@ -239,7 +239,16 @@ class cmake
   ///! Get the variable watch object
   cmVariableWatch* GetVariableWatch() { return this->VariableWatch; }
 
-  void GetCommandDocumentation(std::vector<cmDocumentationEntry>&) const;
+  /** Get the documentation entries for the supported commands.
+   *  If withCurrentCommands is true, the documentation for the 
+   *  recommended set of commands is included.
+   *  If withCompatCommands is true, the documentation for discouraged
+   *  (compatibility) commands is included.
+   *  You probably don't want to set both to false.
+   */
+  void GetCommandDocumentation(std::vector<cmDocumentationEntry>& entries, 
+                               bool withCurrentCommands = true, 
+                               bool withCompatCommands = true) const;
   void GetPropertiesDocumentation(std::vector<cmDocumentationEntry>&);
   void GetGeneratorDocumentation(std::vector<cmDocumentationEntry>&);