ENH: some more cleanup, fixes, and patch for HTML output

Source/MFCDialog/CMakeSetup.cpp

@@ -115,19 +115,22 @@ BOOL CMakeSetup::InitInstance()
     doc.SetCMakeRoot(hcm.GetCacheDefinition("CMAKE_ROOT"));
     std::vector<cmDocumentationEntry> commands;
     std::vector<cmDocumentationEntry> compatCommands;
+    std::map<std::string,cmDocumentationSection *> propDocs;
 
     std::vector<cmDocumentationEntry> generators;
     hcm.GetCommandDocumentation(commands, true, false);
     hcm.GetCommandDocumentation(compatCommands, false, true);
     hcm.GetGeneratorDocumentation(generators);
+    hcm.GetPropertiesDocumentation(propDocs);
     doc.SetName("cmake");
     doc.SetSection("Name",cmDocumentationName);
     doc.SetSection("Usage",cmDocumentationUsage);
     doc.SetSection("Description",cmDocumentationDescription);
-    doc.SetSection("Generators",generators);
+    doc.AppendSection("Generators",generators);
-    doc.SetSection("Options",cmDocumentationOptions);
+    doc.PrependSection("Options",cmDocumentationOptions);
     doc.SetSection("Commands",commands);
     doc.SetSection("Compatilbility Commands", compatCommands);
+    doc.SetSections(propDocs);
 
     return (doc.PrintRequestedDocumentation(std::cout)? 0:1);
     }

Source/cmDocumentation.cxx

@@ -240,6 +240,19 @@ cmDocumentation::cmDocumentation()
                                    "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->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");
 }
 
 //----------------------------------------------------------------------------
@@ -325,6 +338,8 @@ bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os)
       return this->PrintDocumentationSingleModule(os);
     case cmDocumentation::SingleProperty:
       return this->PrintDocumentationSingleProperty(os);
+    case cmDocumentation::SingleVariable:
+      return this->PrintDocumentationSingleVariable(os);
     case cmDocumentation::List:
       this->PrintDocumentationList(os,"Commands");
       this->PrintDocumentationList(os,"Compatibility Commands");
@@ -334,11 +349,20 @@ bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os)
       return true;
     case cmDocumentation::PropertyList: 
       this->PrintDocumentationList(os,"Properties Description");
-      this->PrintDocumentationList(os,"Properties of Global Scope");
+      for (std::vector<std::string>::iterator i = 
-      this->PrintDocumentationList(os,"Properties on Directories");
+             this->PropertySections.begin();
-      this->PrintDocumentationList(os,"Properties on Targets");
+           i != this->PropertySections.end(); ++i)
-      this->PrintDocumentationList(os,"Properties on Tests");
+        {
-      this->PrintDocumentationList(os,"Properties on Source Files");
+        this->PrintDocumentationList(os,i->c_str());
+        }
+      return true;
+    case cmDocumentation::VariableList: 
+      for (std::vector<std::string>::iterator i = 
+             this->VariableSections.begin();
+           i != this->VariableSections.end(); ++i)
+        {
+        this->PrintDocumentationList(os,i->c_str());
+        }
       return true;
     case cmDocumentation::Full: 
       return this->PrintDocumentationFull(os);
@@ -348,6 +372,8 @@ bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os)
       return this->PrintDocumentationCustomModules(os);
     case cmDocumentation::Properties: 
       return this->PrintDocumentationProperties(os);
+    case cmDocumentation::Variables: 
+      return this->PrintDocumentationVariables(os);
     case cmDocumentation::Commands: 
       return this->PrintDocumentationCurrentCommands(os);
     case cmDocumentation::CompatCommands: 
@@ -641,6 +667,12 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv)
       GET_OPT_ARGUMENT(help.Filename);
       help.HelpForm = this->GetFormFromFilename(help.Filename);
       }
+    else if(strcmp(argv[i], "--help-variables") == 0)
+      {
+      help.HelpType = cmDocumentation::Variables;
+      GET_OPT_ARGUMENT(help.Filename);
+      help.HelpForm = this->GetFormFromFilename(help.Filename);
+      }
     else if(strcmp(argv[i], "--help-modules") == 0)
       {
       help.HelpType = cmDocumentation::Modules;
@@ -705,6 +737,13 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv)
       GET_OPT_ARGUMENT(help.Filename);
       help.HelpForm = this->GetFormFromFilename(help.Filename);
       }
+    else if(strcmp(argv[i], "--help-variable") == 0)
+      {
+      help.HelpType = cmDocumentation::SingleVariable;
+      GET_OPT_ARGUMENT(help.Argument);
+      GET_OPT_ARGUMENT(help.Filename);
+      help.HelpForm = this->GetFormFromFilename(help.Filename);
+      }
     else if(strcmp(argv[i], "--help-command-list") == 0)
       {
       help.HelpType = cmDocumentation::List;
@@ -723,6 +762,12 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv)
       GET_OPT_ARGUMENT(help.Filename);
       help.HelpForm = cmDocumentation::TextForm;
       }
+    else if(strcmp(argv[i], "--help-variable-list") == 0)
+      {
+      help.HelpType = cmDocumentation::VariableList;
+      GET_OPT_ARGUMENT(help.Filename);
+      help.HelpForm = cmDocumentation::TextForm;
+      }
     else if(strcmp(argv[i], "--copyright") == 0)
       {
       help.HelpType = cmDocumentation::Copyright;
@@ -834,6 +879,24 @@ void cmDocumentation::PrependSection(const char *name,
   sec->Prepend(docs);
 }
 
+//----------------------------------------------------------------------------
+void cmDocumentation::PrependSection(const char *name, 
+                                     std::vector<cmDocumentationEntry> &docs)
+{
+  cmDocumentationSection *sec = 0;
+  if (this->AllSections.find(name) == this->AllSections.end())
+    {
+    sec = new cmDocumentationSection
+      (name, cmSystemTools::UpperCase(name).c_str());
+    this->SetSection(name,sec);
+    }
+  else
+    {
+    sec = this->AllSections[name];
+    }
+  sec->Prepend(docs);
+}
+
 //----------------------------------------------------------------------------
 void cmDocumentation::AppendSection(const char *name, 
                                     const char *docs[][3])
@@ -870,6 +933,26 @@ void cmDocumentation::AppendSection(const char *name,
   sec->Append(docs);
 }
 
+//----------------------------------------------------------------------------
+void cmDocumentation::AppendSection(const char *name, 
+                                    cmDocumentationEntry &docs)
+{
+
+  std::vector<cmDocumentationEntry> docsVec;
+  docsVec.push_back(docs);
+  this->AppendSection(name,docsVec);
+}
+
+//----------------------------------------------------------------------------
+void cmDocumentation::PrependSection(const char *name, 
+                                     cmDocumentationEntry &docs)
+{
+
+  std::vector<cmDocumentationEntry> docsVec;
+  docsVec.push_back(docs);
+  this->PrependSection(name,docsVec);
+}
+
 //----------------------------------------------------------------------------
 void cmDocumentation::SetSeeAlsoList(const char *data[][3])
 {
@@ -996,23 +1079,15 @@ bool cmDocumentation::PrintDocumentationSingleModule(std::ostream& os)
 //----------------------------------------------------------------------------
 bool cmDocumentation::PrintDocumentationSingleProperty(std::ostream& os)
 {
-  if (this->PrintDocumentationGeneric(os,"Properties of Global Scope"))
+  bool done = false;
+  for (std::vector<std::string>::iterator i = 
+         this->PropertySections.begin();
+       !done && i != this->PropertySections.end(); ++i)
     {
-    return true;
+    done = this->PrintDocumentationGeneric(os,i->c_str());
     }
-  if (this->PrintDocumentationGeneric(os,"Properties on Directories"))
+
-    {
+  if (done)
-    return true;
-    }
-  if (this->PrintDocumentationGeneric(os,"Properties on Targets"))
-    {
-    return true;
-    }
-  if (this->PrintDocumentationGeneric(os,"Properties on Tests"))
-    {
-    return true;
-    }
-  if (this->PrintDocumentationGeneric(os,"Properties on Source Files"))
     {
     return true;
     }
@@ -1024,6 +1099,29 @@ bool cmDocumentation::PrintDocumentationSingleProperty(std::ostream& os)
   return false;
 }
 
+//----------------------------------------------------------------------------
+bool cmDocumentation::PrintDocumentationSingleVariable(std::ostream& os)
+{
+  bool done = false;
+  for (std::vector<std::string>::iterator i = 
+         this->VariableSections.begin();
+       !done && i != this->VariableSections.end(); ++i)
+    {
+    done = this->PrintDocumentationGeneric(os,i->c_str());
+    }
+
+  if (done)
+    {
+    return true;
+    }
+
+  // Argument was not a command.  Complain.
+  os << "Argument \"" << this->CurrentArgument.c_str()
+     << "\" to --help-variable is not a defined variable.  "
+     << "Use --help-variable-list to see all defined variables.\n";
+  return false;
+}
+
 //----------------------------------------------------------------------------
 bool cmDocumentation::PrintDocumentationList(std::ostream& os,
                                              const char *section)
@@ -1105,11 +1203,30 @@ bool cmDocumentation::PrintDocumentationProperties(std::ostream& os)
 {
   this->ClearSections();
   this->AddSectionToPrint("Properties Description");
-  this->AddSectionToPrint("Properties of Global Scope");
+  for (std::vector<std::string>::iterator i = 
-  this->AddSectionToPrint("Properties on Directories");
+         this->PropertySections.begin();
-  this->AddSectionToPrint("Properties on Targets");
+       i != this->PropertySections.end(); ++i)
-  this->AddSectionToPrint("Properties on Tests");
+    {
-  this->AddSectionToPrint("Properties on Source Files");
+    this->AddSectionToPrint(i->c_str());
+    }
+  this->AddSectionToPrint("Copyright");
+  this->AddSectionToPrint("Standard See Also");
+  this->CurrentFormatter->PrintHeader(this->GetNameString(), os);
+  this->Print(os);
+  this->CurrentFormatter->PrintFooter(os);
+  return true;
+}
+
+//----------------------------------------------------------------------------
+bool cmDocumentation::PrintDocumentationVariables(std::ostream& os)
+{
+  this->ClearSections();
+  for (std::vector<std::string>::iterator i = 
+         this->VariableSections.begin();
+       i != this->VariableSections.end(); ++i)
+    {
+    this->AddSectionToPrint(i->c_str());
+    }
   this->AddSectionToPrint("Copyright");
   this->AddSectionToPrint("Standard See Also");
   this->CurrentFormatter->PrintHeader(this->GetNameString(), os);
@@ -1181,18 +1298,16 @@ void cmDocumentation::CreateFullDocumentation()
   this->AddSectionToPrint("Commands");
   emitted.insert("Commands");
 
+  
   this->AddSectionToPrint("Properties Description");
   emitted.insert("Properties Description");
-  this->AddSectionToPrint("Properties of Global Scope");
+  for (std::vector<std::string>::iterator i = 
-  emitted.insert("Properties of Global Scope");
+         this->PropertySections.begin();
-  this->AddSectionToPrint("Properties on Directories");
+       i != this->PropertySections.end(); ++i)
-  emitted.insert("Properties on Directories");
+    {
-  this->AddSectionToPrint("Properties on Targets");
+    this->AddSectionToPrint(i->c_str());
-  emitted.insert("Properties on Targets");
+    emitted.insert(i->c_str());
-  this->AddSectionToPrint("Properties on Tests");
+    }
-  emitted.insert("Properties on Tests");
-  this->AddSectionToPrint("Properties on Source Files");
-  emitted.insert("Properties on Source Files");
 
   emitted.insert("Copyright");
   emitted.insert("See Also");

Source/cmDocumentation.h

@@ -76,10 +76,16 @@ public:
   /** Add the documentation to the beginning/end of the section */
   void PrependSection(const char *sectionName,
                       const char *docs[][3]);
+  void PrependSection(const char *sectionName,
+                      std::vector<cmDocumentationEntry> &docs);
+  void PrependSection(const char *sectionName,
+                      cmDocumentationEntry &docs);
   void AppendSection(const char *sectionName,
                      const char *docs[][3]);
   void AppendSection(const char *sectionName,
                      std::vector<cmDocumentationEntry> &docs);
+  void AppendSection(const char *sectionName,
+                     cmDocumentationEntry &docs);
 
   /**
    * Print documentation in the given form.  All previously added
@@ -131,11 +137,13 @@ private:
   bool PrintDocumentationSingle(std::ostream& os);
   bool PrintDocumentationSingleModule(std::ostream& os);
   bool PrintDocumentationSingleProperty(std::ostream& os);
+  bool PrintDocumentationSingleVariable(std::ostream& os);
   bool PrintDocumentationUsage(std::ostream& os);
   bool PrintDocumentationFull(std::ostream& os);
   bool PrintDocumentationModules(std::ostream& os);
   bool PrintDocumentationCustomModules(std::ostream& os);
   bool PrintDocumentationProperties(std::ostream& os);
+  bool PrintDocumentationVariables(std::ostream& os);
   bool PrintDocumentationCurrentCommands(std::ostream& os);
   bool PrintDocumentationCompatCommands(std::ostream& os);
   void PrintDocumentationCommand(std::ostream& os,
@@ -171,7 +179,9 @@ private:
   cmDocumentationFormatterMan ManFormatter;
   cmDocumentationFormatterText TextFormatter;
   cmDocumentationFormatterUsage UsageFormatter;
-  
+
+  std::vector<std::string> PropertySections;
+  std::vector<std::string> VariableSections;
 };
 
 #endif

Source/cmDocumentationFormatter.h

@@ -30,10 +30,10 @@ class cmDocumentationEnums
 public:
   /** Types of help provided.  */
   enum Type 
-     { None, Usage, Single, SingleModule, SingleProperty,
+  { None, Usage, Single, SingleModule, SingleProperty, SingleVariable,
-       List, ModuleList, PropertyList,
+    List, ModuleList, PropertyList, VariableList,
-       Full, Properties, Modules, CustomModules, Commands, CompatCommands,
+    Full, Properties, Variables, Modules, CustomModules, Commands, 
-       Copyright, Version };
+    CompatCommands, Copyright, Version };
 
   /** Forms of documentation output.  */
   enum Form { TextForm, HTMLForm, ManForm, UsageForm };

Source/cmDocumentationFormatterHTML.cxx

@@ -97,6 +97,21 @@ void cmDocumentationFormatterHTML
 
   const std::vector<cmDocumentationEntry> &entries = 
     section.GetEntries();
+
+  os << "<ul>\n";
+  for(std::vector<cmDocumentationEntry>::const_iterator op 
+        = entries.begin(); op != entries.end(); ++ op )
+    {
+    if(op->Name.size())
+      {
+      os << "    <li><a href=\"#command_"
+         << op->Name.c_str() << "\"><b><code>";
+      this->PrintHTMLEscapes(os, op->Name.c_str());
+      os << "</code></b></a></li>";
+      }
+    }
+  os << "</ul>\n" ;
+
   for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin(); 
       op != entries.end();)
     {
@@ -108,9 +123,10 @@ void cmDocumentationFormatterHTML
         os << "  <li>\n";
         if(op->Name.size())
           {
-          os << "    <b><code>";
+          os << "    <a name=\"command_"<< 
+            op->Name.c_str() << "\"><b><code>";
           this->PrintHTMLEscapes(os, op->Name.c_str());
-          os << "</code></b>: ";
+          os << "</code></b></a>: ";
           }
         this->PrintHTMLEscapes(os, op->Brief.c_str());
         if(op->Full.size())

Source/cmDocumentationSection.h

@@ -59,6 +59,9 @@ public:
 
   /** prepend some documentation to this section */
   void Prepend(const char *[][3]);
+  void Prepend(const std::vector<cmDocumentationEntry> &entries)
+  { this->Entries.insert(this->Entries.begin(),
+                         entries.begin(),entries.end()); }
 
   
 private:

Source/cmakemain.cxx

@@ -146,7 +146,7 @@ static const char * cmDocumentationOptions[][3] =
    "page, HTML and plain text."},
   {"--help-property prop [file]", 
    "Print help for a single property and exit.",
-   "Full documentation specific to the given module is displayed."
+   "Full documentation specific to the given property 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 and plain text."},
@@ -162,6 +162,24 @@ static const char * cmDocumentationOptions[][3] =
    "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 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 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 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 and plain text."},
   {0,0,0}
 };
 
@@ -318,6 +336,12 @@ int do_cmake(int ac, char** av)
     doc.AppendSection("Compatibility Commands",compatCommands);
     doc.SetSections(propDocs);
 
+    cmDocumentationEntry e;
+    e.Brief = 
+      "variables defined by cmake, that give information about the project, "
+      "and cmake";
+    doc.PrependSection("Variables that Provide Information",e);
+
     doc.SetSeeAlsoList(cmDocumentationSeeAlso);
     int result = doc.PrintRequestedDocumentation(std::cout)? 0:1;
 

Utilities/CMakeLists.txt

@@ -47,6 +47,9 @@ ADD_CUSTOM_COMMAND(
        --help-properties ${CMake_BINARY_DIR}/Docs/cmake-properties.txt
        --help-properties ${CMake_BINARY_DIR}/Docs/cmake-properties.html
        --help-properties ${CMake_BINARY_DIR}/Docs/cmakeprops.1
+       --help-variables ${CMake_BINARY_DIR}/Docs/cmake-variables.txt
+       --help-variables ${CMake_BINARY_DIR}/Docs/cmake-variables.html
+       --help-variables ${CMake_BINARY_DIR}/Docs/cmakevars.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/cmakemodules.1
@@ -65,6 +68,7 @@ INSTALL_FILES(${CMAKE_MAN_DIR}/man1 FILES
               ${CMake_BINARY_DIR}/Docs/cmakecommands.1
               ${CMake_BINARY_DIR}/Docs/cmakecompat.1
               ${CMake_BINARY_DIR}/Docs/cmakeprops.1
+              ${CMake_BINARY_DIR}/Docs/cmakevars.1
               ${CMake_BINARY_DIR}/Docs/cmakemodules.1)
 
 INSTALL_FILES(${CMAKE_DOC_DIR} FILES
@@ -72,7 +76,9 @@ INSTALL_FILES(${CMAKE_DOC_DIR} FILES
     ${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-variables.txt
+    ${CMake_BINARY_DIR}/Docs/cmake-variables.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