ENH: Added SEE ALSO section to generated man page. Minor formatting improvements for generated text-only documentation.

Source/cmDocumentation.cxx

@@ -341,6 +341,22 @@ void cmDocumentation::SetGeneratorsSection(const cmDocumentationEntry* section)
                    this->GeneratorsSection);
 }
 
+//----------------------------------------------------------------------------
+void cmDocumentation::SetSeeAlsoList(const cmDocumentationEntry* also)
+{
+  this->SeeAlsoString = ".B ";
+  for(const cmDocumentationEntry* i = also; i->brief; ++i)
+    {
+    this->SeeAlsoString += i->brief;
+    this->SeeAlsoString += (i+1)->brief? "(1), ":"(1)";    
+    }
+  cmDocumentationEntry e = {0, 0, 0};
+  e.brief = this->SeeAlsoString.c_str();
+  this->SeeAlsoSection.push_back(e);
+  e.brief = 0;
+  this->SeeAlsoSection.push_back(e);  
+}
+
 //----------------------------------------------------------------------------
 void cmDocumentation::PrintSection(std::ostream& os,
                                    const cmDocumentationEntry* section,
@@ -362,6 +378,9 @@ void cmDocumentation::PrintSectionText(std::ostream& os,
 {
   if(name)
     {
+    os <<
+      "---------------------------------------"
+      "---------------------------------------\n";
     os << name << "\n\n";
     }
   if(!section) { return; }
@@ -772,10 +791,6 @@ void cmDocumentation::PrintDocumentationMan(std::ostream& os)
 void cmDocumentation::CreateUsageDocumentation()
 {
   this->ClearSections();
-  if(!this->NameSection.empty())
-    {
-    this->AddSection("Name", &this->NameSection[0]);
-    }
   if(!this->UsageSection.empty())
     {
     this->AddSection("Usage", &this->UsageSection[0]);
@@ -784,6 +799,10 @@ void cmDocumentation::CreateUsageDocumentation()
     {
     this->AddSection("Command-Line Options", &this->OptionsSection[0]);
     }
+  if(!this->GeneratorsSection.empty())
+    {
+    this->AddSection("Generators", &this->GeneratorsSection[0]);
+    }
 }
 
 //----------------------------------------------------------------------------
@@ -802,14 +821,14 @@ void cmDocumentation::CreateFullDocumentation()
     {
     this->AddSection(0, &this->DescriptionSection[0]);
     }
-  if(!this->GeneratorsSection.empty())
-    {
-    this->AddSection("Generators", &this->GeneratorsSection[0]);
-    }
   if(!this->OptionsSection.empty())
     {
     this->AddSection("Command-Line Options", &this->OptionsSection[0]);
     }
+  if(!this->GeneratorsSection.empty())
+    {
+    this->AddSection("Generators", &this->GeneratorsSection[0]);
+    }
   if(!this->CommandsSection.empty())
     {
     this->AddSection("Listfile Commands", &this->CommandsSection[0]);
@@ -834,20 +853,24 @@ void cmDocumentation::CreateManDocumentation()
     {
     this->AddSection("DESCRIPTION", &this->DescriptionSection[0]);
     }
-  if(!this->GeneratorsSection.empty())
-    {
-    this->AddSection("GENERATORS", &this->GeneratorsSection[0]);
-    }
   if(!this->OptionsSection.empty())
     {
     this->AddSection("OPTIONS", &this->OptionsSection[0]);
     }
+  if(!this->GeneratorsSection.empty())
+    {
+    this->AddSection("GENERATORS", &this->GeneratorsSection[0]);
+    }
   if(!this->CommandsSection.empty())
     {
     this->AddSection("COMMANDS", &this->CommandsSection[0]);
     }
   this->AddSection("COPYRIGHT", cmDocumentationCopyright);
   this->AddSection("MAILING LIST", cmDocumentationMailingList);  
+  if(!this->SeeAlsoSection.empty())
+    {
+    this->AddSection("SEE ALSO", &this->SeeAlsoSection[0]);
+    }
   this->AddSection("AUTHOR", cmDocumentationAuthor);
 }
 

Source/cmDocumentation.h

@@ -67,6 +67,9 @@ public:
   /** Set the generator descriptions for standard document generation.  */
   void SetGeneratorsSection(const cmDocumentationEntry*);
   
+  /** Set the see-also list of references to the other tools.  */
+  void SetSeeAlsoList(const cmDocumentationEntry*);
+  
   // Low-level interface for custom documents:
   
   /** Forms of documentation output.  */
@@ -136,6 +139,8 @@ private:
   std::vector<cmDocumentationEntry> OptionsSection;
   std::vector<cmDocumentationEntry> CommandsSection;
   std::vector<cmDocumentationEntry> GeneratorsSection;
+  std::vector<cmDocumentationEntry> SeeAlsoSection;
+  std::string SeeAlsoString;
   
   std::vector< const char* > Names;
   std::vector< const cmDocumentationEntry* > Sections;

Source/cmakemain.cxx

@@ -41,7 +41,11 @@ static const cmDocumentationEntry cmDocumentationUsage[] =
 static const cmDocumentationEntry cmDocumentationDescription[] =
 {
   {0,
-   "CMake reads ... ", 0},
+   "The \"cmake\" executable is the CMake command-line interface.  It may "
+   "be used to configure projects in scripts.  Project configuration settings "
+   "may be specified on the command line with the -D option.  The -i option "
+   "will cause cmake to interactively prompt for such settings.", 0},
+  CMAKE_STANDARD_INTRODUCTION,
   {0,0,0}
 };
 
@@ -66,6 +70,14 @@ static const cmDocumentationEntry cmDocumentationOptions[] =
   {0,0,0}
 };
 
+//----------------------------------------------------------------------------
+static const cmDocumentationEntry cmDocumentationSeeAlso[] =
+{
+  {0, "ccmake", 0},
+  {0, "ctest", 0},
+  {0, 0, 0}
+};
+
 //----------------------------------------------------------------------------
 static const cmDocumentationEntry cmDocumentationNOTE[] =
 {
@@ -107,6 +119,7 @@ int do_cmake(int ac, char** av)
     doc.SetGeneratorsSection(&generators[0]);
     doc.SetOptionsSection(cmDocumentationOptions);
     doc.SetCommandsSection(&commands[0]);
+    doc.SetSeeAlsoList(cmDocumentationSeeAlso);
     int result = doc.PrintRequestedDocumentation(std::cout)? 0:1;
     
     // If we were run with no arguments, but a CMakeLists.txt file