ENH: handle HTML documentation for single items better: no warning about

ComputeSectionLinkPrefix, don't create an index for only one item

Alex
This commit is contained in:
Alexander Neundorf 2008-07-21 17:52:59 -04:00
parent 76878d928e
commit 4175b514fc
3 changed files with 37 additions and 16 deletions

View File

@ -1350,7 +1350,9 @@ void cmDocumentation
::PrintDocumentationCommand(std::ostream& os, ::PrintDocumentationCommand(std::ostream& os,
const cmDocumentationEntry &entry) const cmDocumentationEntry &entry)
{ {
cmDocumentationSection *sec = new cmDocumentationSection("",""); // the string "SingleItem" will be used in a few places to detect the case
// that only the documentation for a single item is printed
cmDocumentationSection *sec = new cmDocumentationSection("SingleItem","");
sec->Append(entry); sec->Append(entry);
this->AllSections["temp"] = sec; this->AllSections["temp"] = sec;
this->ClearSections(); this->ClearSections();

View File

@ -146,6 +146,10 @@ cmDocumentationFormatter::ComputeSectionLinkPrefix(std::string const& name)
{ {
return "see"; return "see";
} }
else if(name.find("SingleItem") != name.npos)
{
return "single_item";
}
else else
{ {
std::cerr std::cerr

View File

@ -117,30 +117,37 @@ void cmDocumentationFormatterHTML
const cmDocumentationSection &section, const cmDocumentationSection &section,
const char* name) const char* name)
{ {
if(name)
{
os << "<h2><a name=\"section_" << name << "\"/>" << name << "</h2>\n";
}
std::string prefix = this->ComputeSectionLinkPrefix(name); std::string prefix = this->ComputeSectionLinkPrefix(name);
const std::vector<cmDocumentationEntry> &entries = const std::vector<cmDocumentationEntry> &entries =
section.GetEntries(); section.GetEntries();
os << "<ul>\n"; // skip the index if the help for only a single item (--help-command,
for(std::vector<cmDocumentationEntry>::const_iterator op // --help-policy, --help-property, --help-module) is printed
= entries.begin(); op != entries.end(); ++ op ) bool isSingleItemHelp = ((name!=0) && (strcmp(name, "SingleItem")==0));
if (!isSingleItemHelp)
{ {
if(op->Name.size()) if (name)
{ {
os << " <li><a href=\"#" << prefix << ":"; os << "<h2><a name=\"section_" << name << "\"/>" << name << "</h2>\n";
cmDocumentationPrintHTMLId(os, op->Name.c_str());
os << "\"><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(); ++ op )
{
if(op->Name.size())
{
os << " <li><a href=\"#" << prefix << ":";
cmDocumentationPrintHTMLId(os, op->Name.c_str());
os << "\"><b><code>";
this->PrintHTMLEscapes(os, op->Name.c_str());
os << "</code></b></a></li>";
}
}
os << "</ul>\n" ;
} }
os << "</ul>\n" ;
for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin(); for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
op != entries.end();) op != entries.end();)
@ -240,6 +247,14 @@ void cmDocumentationFormatterHTML
::PrintIndex(std::ostream& os, ::PrintIndex(std::ostream& os,
std::vector<const cmDocumentationSection *>& sections) std::vector<const cmDocumentationSection *>& sections)
{ {
// skip the index if only the help for a single item is printed
if ((sections.size() == 1)
&& (sections[0]->GetName(this->GetForm()) != 0 )
&& (std::string(sections[0]->GetName(this->GetForm())) == "SingleItem"))
{
return;
}
os << "<h2><a name=\"section_Index\"/>Master Index</h2>\n"; os << "<h2><a name=\"section_Index\"/>Master Index</h2>\n";
os << "<ul>\n"; os << "<ul>\n";
for(unsigned int i=0; i < sections.size(); ++i) for(unsigned int i=0; i < sections.size(); ++i)