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

This commit is contained in:
Ken Martin 2007-10-24 11:36:47 -04:00
parent 328615716c
commit c2f0aac146
8 changed files with 223 additions and 46 deletions

View File

@ -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.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);
}

View File

@ -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<std::string>::iterator i =
this->PropertySections.begin();
i != this->PropertySections.end(); ++i)
{
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"))
{
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<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");
this->AddSectionToPrint("Properties on Directories");
this->AddSectionToPrint("Properties on Targets");
this->AddSectionToPrint("Properties on Tests");
this->AddSectionToPrint("Properties on Source Files");
for (std::vector<std::string>::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<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");
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<std::string>::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");

View File

@ -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,
@ -172,6 +180,8 @@ private:
cmDocumentationFormatterText TextFormatter;
cmDocumentationFormatterUsage UsageFormatter;
std::vector<std::string> PropertySections;
std::vector<std::string> VariableSections;
};
#endif

View File

@ -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 };

View File

@ -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())

View File

@ -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:

View File

@ -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;

View File

@ -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,6 +76,8 @@ 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-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