From 7c2b4e3a029ffe1205553fb80883434677167b2c Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 10 Jul 2003 23:15:45 -0400 Subject: ENH: Added SEE ALSO section to generated man page. Minor formatting improvements for generated text-only documentation. --- Source/cmDocumentation.cxx | 49 ++++++++++++++++++++++++++++++++++------------ Source/cmDocumentation.h | 5 +++++ Source/cmakemain.cxx | 15 +++++++++++++- 3 files changed, 55 insertions(+), 14 deletions(-) diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index fd34e47..d8bc34e 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -342,6 +342,22 @@ void cmDocumentation::SetGeneratorsSection(const cmDocumentationEntry* section) } //---------------------------------------------------------------------------- +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, const char* name) @@ -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); + this->AddSection("MAILING LIST", cmDocumentationMailingList); + if(!this->SeeAlsoSection.empty()) + { + this->AddSection("SEE ALSO", &this->SeeAlsoSection[0]); + } this->AddSection("AUTHOR", cmDocumentationAuthor); } diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h index 598b1d3..ddfbb44 100644 --- a/Source/cmDocumentation.h +++ b/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 OptionsSection; std::vector CommandsSection; std::vector GeneratorsSection; + std::vector SeeAlsoSection; + std::string SeeAlsoString; std::vector< const char* > Names; std::vector< const cmDocumentationEntry* > Sections; diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx index 784502a..5b142c3 100644 --- a/Source/cmakemain.cxx +++ b/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} }; @@ -67,6 +71,14 @@ static const cmDocumentationEntry cmDocumentationOptions[] = }; //---------------------------------------------------------------------------- +static const cmDocumentationEntry cmDocumentationSeeAlso[] = +{ + {0, "ccmake", 0}, + {0, "ctest", 0}, + {0, 0, 0} +}; + +//---------------------------------------------------------------------------- static const cmDocumentationEntry cmDocumentationNOTE[] = { {0, @@ -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 -- cgit v0.12