From c2f0aac146f6b990940240891b959dc1f394e80c Mon Sep 17 00:00:00 2001 From: Ken Martin Date: Wed, 24 Oct 2007 11:36:47 -0400 Subject: [PATCH] ENH: some more cleanup, fixes, and patch for HTML output --- Source/MFCDialog/CMakeSetup.cpp | 7 +- Source/cmDocumentation.cxx | 185 +++++++++++++++++++----- Source/cmDocumentation.h | 12 +- Source/cmDocumentationFormatter.h | 8 +- Source/cmDocumentationFormatterHTML.cxx | 20 ++- Source/cmDocumentationSection.h | 3 + Source/cmakemain.cxx | 26 +++- Utilities/CMakeLists.txt | 8 +- 8 files changed, 223 insertions(+), 46 deletions(-) diff --git a/Source/MFCDialog/CMakeSetup.cpp b/Source/MFCDialog/CMakeSetup.cpp index 63fa23d85..6d25ba2a4 100644 --- a/Source/MFCDialog/CMakeSetup.cpp +++ b/Source/MFCDialog/CMakeSetup.cpp @@ -115,19 +115,22 @@ BOOL CMakeSetup::InitInstance() doc.SetCMakeRoot(hcm.GetCacheDefinition("CMAKE_ROOT")); std::vector commands; std::vector compatCommands; + std::map propDocs; std::vector 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.SetSection("Options",cmDocumentationOptions); + doc.AppendSection("Generators",generators); + doc.PrependSection("Options",cmDocumentationOptions); doc.SetSection("Commands",commands); doc.SetSection("Compatilbility Commands", compatCommands); + doc.SetSections(propDocs); return (doc.PrintRequestedDocumentation(std::cout)? 0:1); } diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index cde3223ac..4b75f5cb5 100644 --- a/Source/cmDocumentation.cxx +++ b/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"); - this->PrintDocumentationList(os,"Properties on Directories"); - this->PrintDocumentationList(os,"Properties on Targets"); - this->PrintDocumentationList(os,"Properties on Tests"); - this->PrintDocumentationList(os,"Properties on Source Files"); + for (std::vector::iterator i = + this->PropertySections.begin(); + i != this->PropertySections.end(); ++i) + { + this->PrintDocumentationList(os,i->c_str()); + } + return true; + case cmDocumentation::VariableList: + for (std::vector::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 &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 docsVec; + docsVec.push_back(docs); + this->AppendSection(name,docsVec); +} + +//---------------------------------------------------------------------------- +void cmDocumentation::PrependSection(const char *name, + cmDocumentationEntry &docs) +{ + + std::vector 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::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")) - { - 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")) + + if (done) { 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::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"); - this->AddSectionToPrint("Properties on Directories"); - this->AddSectionToPrint("Properties on Targets"); - this->AddSectionToPrint("Properties on Tests"); - this->AddSectionToPrint("Properties on Source Files"); + for (std::vector::iterator i = + this->PropertySections.begin(); + i != this->PropertySections.end(); ++i) + { + 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::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"); - emitted.insert("Properties of Global Scope"); - this->AddSectionToPrint("Properties on Directories"); - emitted.insert("Properties on Directories"); - this->AddSectionToPrint("Properties on Targets"); - emitted.insert("Properties on Targets"); - this->AddSectionToPrint("Properties on Tests"); - emitted.insert("Properties on Tests"); - this->AddSectionToPrint("Properties on Source Files"); - emitted.insert("Properties on Source Files"); + for (std::vector::iterator i = + this->PropertySections.begin(); + i != this->PropertySections.end(); ++i) + { + this->AddSectionToPrint(i->c_str()); + emitted.insert(i->c_str()); + } emitted.insert("Copyright"); emitted.insert("See Also"); diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h index 99000eed9..7974aced2 100644 --- a/Source/cmDocumentation.h +++ b/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 &docs); + void PrependSection(const char *sectionName, + cmDocumentationEntry &docs); void AppendSection(const char *sectionName, const char *docs[][3]); void AppendSection(const char *sectionName, std::vector &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 PropertySections; + std::vector VariableSections; }; #endif diff --git a/Source/cmDocumentationFormatter.h b/Source/cmDocumentationFormatter.h index 8ffd0649d..b44026a8d 100644 --- a/Source/cmDocumentationFormatter.h +++ b/Source/cmDocumentationFormatter.h @@ -30,10 +30,10 @@ class cmDocumentationEnums public: /** Types of help provided. */ enum Type - { None, Usage, Single, SingleModule, SingleProperty, - List, ModuleList, PropertyList, - Full, Properties, Modules, CustomModules, Commands, CompatCommands, - Copyright, Version }; + { None, Usage, Single, SingleModule, SingleProperty, SingleVariable, + List, ModuleList, PropertyList, VariableList, + Full, Properties, Variables, Modules, CustomModules, Commands, + CompatCommands, Copyright, Version }; /** Forms of documentation output. */ enum Form { TextForm, HTMLForm, ManForm, UsageForm }; diff --git a/Source/cmDocumentationFormatterHTML.cxx b/Source/cmDocumentationFormatterHTML.cxx index 34511831a..a1745d3fc 100644 --- a/Source/cmDocumentationFormatterHTML.cxx +++ b/Source/cmDocumentationFormatterHTML.cxx @@ -97,6 +97,21 @@ void cmDocumentationFormatterHTML const std::vector &entries = section.GetEntries(); + + os << "\n" ; + for(std::vector::const_iterator op = entries.begin(); op != entries.end();) { @@ -108,9 +123,10 @@ void cmDocumentationFormatterHTML os << "
  • \n"; if(op->Name.size()) { - os << " "; + os << " Name.c_str() << "\">"; this->PrintHTMLEscapes(os, op->Name.c_str()); - os << ": "; + os << ": "; } this->PrintHTMLEscapes(os, op->Brief.c_str()); if(op->Full.size()) diff --git a/Source/cmDocumentationSection.h b/Source/cmDocumentationSection.h index 97a15af1a..e7c5df099 100644 --- a/Source/cmDocumentationSection.h +++ b/Source/cmDocumentationSection.h @@ -59,6 +59,9 @@ public: /** prepend some documentation to this section */ void Prepend(const char *[][3]); + void Prepend(const std::vector &entries) + { this->Entries.insert(this->Entries.begin(), + entries.begin(),entries.end()); } private: diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx index e676430d4..9e81a42a1 100644 --- a/Source/cmakemain.cxx +++ b/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; diff --git a/Utilities/CMakeLists.txt b/Utilities/CMakeLists.txt index 9d96c2f98..7cc35e41f 100644 --- a/Utilities/CMakeLists.txt +++ b/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