From 1d9889c5d34d83b269697c0b09e840bf83066e6f Mon Sep 17 00:00:00 2001 From: Alexander Neundorf Date: Fri, 22 Jun 2007 08:44:51 -0400 Subject: 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 | 106 +++++++++++++++++++++++++++++++++++++++++++-- Source/cmDocumentation.h | 7 +++ Source/cmake.cxx | 11 ++++- Source/cmake.h | 11 ++++- 4 files changed, 128 insertions(+), 7 deletions(-) diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index 16ae84b..0c1a472 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -44,6 +44,48 @@ static const cmDocumentationEntry cmDocumentationStandardOptions[] = }; //---------------------------------------------------------------------------- +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[] = { {0, @@ -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()); + } } //---------------------------------------------------------------------------- @@ -637,6 +679,13 @@ void cmDocumentation::SetCommandsSection(const cmDocumentationEntry* section) } //---------------------------------------------------------------------------- +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, diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h index d97f77f..9962297 100644 --- a/Source/cmDocumentation.h +++ b/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, diff --git a/Source/cmake.cxx b/Source/cmake.cxx index cc21e1d..378b6c9 100644 --- a/Source/cmake.cxx +++ b/Source/cmake.cxx @@ -2135,12 +2135,19 @@ void cmake::UpdateProgress(const char *msg, float prog) } } -void cmake::GetCommandDocumentation( - std::vector& v) const +void cmake::GetCommandDocumentation(std::vector& 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(), diff --git a/Source/cmake.h b/Source/cmake.h index 6b1f756..1abb1e8 100644 --- a/Source/cmake.h +++ b/Source/cmake.h @@ -239,7 +239,16 @@ class cmake ///! Get the variable watch object cmVariableWatch* GetVariableWatch() { return this->VariableWatch; } - void GetCommandDocumentation(std::vector&) 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& entries, + bool withCurrentCommands = true, + bool withCompatCommands = true) const; void GetPropertiesDocumentation(std::vector&); void GetGeneratorDocumentation(std::vector&); -- cgit v0.12