[Cmake-commits] [cmake-commits] king committed cmDocumentation.cxx 1.72 1.73 cmDocumentation.h 1.34 1.35 cmDocumentationFormatter.cxx 1.3 1.4 cmDocumentationFormatter.h 1.9 1.10 cmDocumentationFormatterDocbook.cxx 1.3 1.4 cmDocumentationFormatterDocbook.h 1.1 1.2 cmDocumentationFormatterHTML.cxx 1.13 1.14 cmDocumentationFormatterHTML.h 1.3 1.4 cmDocumentationFormatterMan.cxx 1.5 1.6 cmDocumentationFormatterMan.h 1.2 1.3
cmake-commits at cmake.org
cmake-commits at cmake.org
Fri Oct 10 11:23:37 EDT 2008
Update of /cvsroot/CMake/CMake/Source
In directory public:/mounts/ram/cvs-serv20640/Source
Modified Files:
cmDocumentation.cxx cmDocumentation.h
cmDocumentationFormatter.cxx cmDocumentationFormatter.h
cmDocumentationFormatterDocbook.cxx
cmDocumentationFormatterDocbook.h
cmDocumentationFormatterHTML.cxx
cmDocumentationFormatterHTML.h cmDocumentationFormatterMan.cxx
cmDocumentationFormatterMan.h
Log Message:
ENH: Improve generated documentation formatting
Applying patch provided in issue #7797.
Fixes to man-pages:
- Character '-' must be espaced as '\-'
- Surround preformatted text with '.nf' and '.fi' to adjust filling
- Give every page a NAME section for indexing by mandb
- Pass the man page filename without extension to .TH in its header
Also added a title to the HTML header.
Index: cmDocumentation.h
===================================================================
RCS file: /cvsroot/CMake/CMake/Source/cmDocumentation.h,v
retrieving revision 1.34
retrieving revision 1.35
diff -C 2 -d -r1.34 -r1.35
*** cmDocumentation.h 19 Aug 2008 19:42:48 -0000 1.34
--- cmDocumentation.h 10 Oct 2008 15:23:35 -0000 1.35
***************
*** 62,66 ****
/** Print help of the given type. */
! bool PrintDocumentation(Type ht, std::ostream& os);
/** Set the program name for standard document generation. */
--- 62,66 ----
/** Print help of the given type. */
! bool PrintDocumentation(Type ht, std::ostream& os, const char* docname=0);
/** Set the program name for standard document generation. */
***************
*** 125,128 ****
--- 125,129 ----
private:
void SetForm(Form f);
+ void SetDocName(const char* docname);
bool CreateSingleModule(const char* fname,
***************
*** 135,138 ****
--- 136,141 ----
void CreateFullDocumentation();
+ void AddDocumentIntroToPrint(const char* intro[2]);
+
bool PrintCopyright(std::ostream& os);
bool PrintVersion(std::ostream& os);
***************
*** 158,164 ****
--- 161,170 ----
const char* GetNameString() const;
+ const char* GetDocName(bool fallbackToNameString = true) const;
+ const char* GetDefaultDocName(Type ht) const;
bool IsOption(const char* arg) const;
std::string NameString;
+ std::string DocName;
std::map<std::string,cmDocumentationSection*> AllSections;
Index: cmDocumentationFormatterHTML.cxx
===================================================================
RCS file: /cvsroot/CMake/CMake/Source/cmDocumentationFormatterHTML.cxx,v
retrieving revision 1.13
retrieving revision 1.14
diff -C 2 -d -r1.13 -r1.14
*** cmDocumentationFormatterHTML.cxx 21 Jul 2008 21:52:59 -0000 1.13
--- cmDocumentationFormatterHTML.cxx 10 Oct 2008 15:23:35 -0000 1.14
***************
*** 203,210 ****
//----------------------------------------------------------------------------
! void cmDocumentationFormatterHTML::PrintHeader(const char* /*name*/,
std::ostream& os)
{
! os << "<html><body>\n";
}
--- 203,213 ----
//----------------------------------------------------------------------------
! void cmDocumentationFormatterHTML::PrintHeader(const char* docname,
! const char* appname,
std::ostream& os)
{
! os << "<html><head><title>";
! os << docname << " - " << appname;
! os << "</title></head><body>\n";
}
Index: cmDocumentationFormatterHTML.h
===================================================================
RCS file: /cvsroot/CMake/CMake/Source/cmDocumentationFormatterHTML.h,v
retrieving revision 1.3
retrieving revision 1.4
diff -C 2 -d -r1.3 -r1.4
*** cmDocumentationFormatterHTML.h 5 Mar 2008 16:05:22 -0000 1.3
--- cmDocumentationFormatterHTML.h 10 Oct 2008 15:23:35 -0000 1.4
***************
*** 31,35 ****
{ return cmDocumentationEnums::HTMLForm;}
! virtual void PrintHeader(const char* name, std::ostream& os);
virtual void PrintFooter(std::ostream& os);
virtual void PrintSection(std::ostream& os,
--- 31,36 ----
{ return cmDocumentationEnums::HTMLForm;}
! virtual void PrintHeader(const char* docname, const char* appname,
! std::ostream& os);
virtual void PrintFooter(std::ostream& os);
virtual void PrintSection(std::ostream& os,
Index: cmDocumentationFormatter.cxx
===================================================================
RCS file: /cvsroot/CMake/CMake/Source/cmDocumentationFormatter.cxx,v
retrieving revision 1.3
retrieving revision 1.4
diff -C 2 -d -r1.3 -r1.4
*** cmDocumentationFormatter.cxx 21 Jul 2008 21:52:58 -0000 1.3
--- cmDocumentationFormatter.cxx 10 Oct 2008 15:23:35 -0000 1.4
***************
*** 119,123 ****
return "module";
}
! else if(name.find("Name") != name.npos)
{
return "name";
--- 119,124 ----
return "module";
}
! else if(name.find("Name") != name.npos ||
! name.find("Introduction") != name.npos)
{
return "name";
Index: cmDocumentation.cxx
===================================================================
RCS file: /cvsroot/CMake/CMake/Source/cmDocumentation.cxx,v
retrieving revision 1.72
retrieving revision 1.73
diff -C 2 -d -r1.72 -r1.73
*** cmDocumentation.cxx 10 Oct 2008 15:23:17 -0000 1.72
--- cmDocumentation.cxx 10 Oct 2008 15:23:35 -0000 1.73
***************
*** 203,206 ****
--- 203,226 ----
//----------------------------------------------------------------------------
+ #define DOCUMENT_INTRO(type, default_name, desc) \
+ static char const *cmDocumentation##type##Intro[2] = { default_name, desc };
+ #define GET_DOCUMENT_INTRO(type) cmDocumentation##type##Intro
+
+ DOCUMENT_INTRO(Modules, "cmakemodules",
+ "Reference of available CMake modules.");
+ DOCUMENT_INTRO(CustomModules, "cmakecustommodules",
+ "Reference of available CMake custom modules.");
+ DOCUMENT_INTRO(Policies, "cmakepolicies",
+ "Reference of CMake policies.");
+ DOCUMENT_INTRO(Properties, "cmakeprops",
+ "Reference of CMake properties.");
+ DOCUMENT_INTRO(Variables, "cmakevars",
+ "Reference of CMake variables.");
+ DOCUMENT_INTRO(Commands, "cmakecommands",
+ "Reference of available CMake commands.");
+ DOCUMENT_INTRO(CompatCommands, "cmakecompat",
+ "Reference of CMake compatibility commands.");
+
+ //----------------------------------------------------------------------------
cmDocumentation::cmDocumentation()
:CurrentFormatter(0)
***************
*** 322,326 ****
//----------------------------------------------------------------------------
! bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os)
{
if ((this->CurrentFormatter->GetForm() != HTMLForm)
--- 342,366 ----
//----------------------------------------------------------------------------
! void cmDocumentation::AddDocumentIntroToPrint(const char* intro[2])
! {
! const char* docname;
! if (intro && (docname = this->GetDocName(false)))
! {
! cmDocumentationSection* section;
! std::string desc("");
!
! desc += docname;
! desc += " - ";
! desc += intro[1];
!
! section = new cmDocumentationSection("Introduction", "NAME");
! section->Append(0, desc.c_str(), 0);
! this->PrintSections.push_back(section);
! }
! }
!
! //----------------------------------------------------------------------------
! bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os,
! const char* docname)
{
if ((this->CurrentFormatter->GetForm() != HTMLForm)
***************
*** 331,334 ****
--- 371,384 ----
}
+ // Handle Document Name. docname==0 disables intro.
+ this->SetDocName("");
+ if (docname)
+ {
+ if (*docname)
+ this->SetDocName(docname);
+ else // empty string was given. select default if possible
+ this->SetDocName(this->GetDefaultDocName(ht));
+ }
+
switch (ht)
{
***************
*** 596,599 ****
--- 646,650 ----
std::ofstream* fout = 0;
std::ostream* s = &os;
+ std::string docname("");
if(i->Filename.length() > 0)
{
***************
*** 607,614 ****
result = false;
}
}
// Print this documentation type to the stream.
! if(!this->PrintDocumentation(i->HelpType, *s) || !*s)
{
result = false;
--- 658,669 ----
result = false;
}
+ if(i->Filename != "-")
+ {
+ docname = cmSystemTools::GetFilenameWithoutLastExtension(i->Filename);
+ }
}
// Print this documentation type to the stream.
! if(!this->PrintDocumentation(i->HelpType, *s, docname.c_str()) || !*s)
{
result = false;
***************
*** 871,874 ****
--- 926,935 ----
//----------------------------------------------------------------------------
+ void cmDocumentation::SetDocName(const char *docname)
+ {
+ this->DocName = docname?docname:"";
+ }
+
+ //----------------------------------------------------------------------------
void cmDocumentation::SetSection(const char *name,
cmDocumentationSection *section)
***************
*** 1234,1238 ****
{
this->CreateFullDocumentation();
! this->CurrentFormatter->PrintHeader(GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
--- 1295,1299 ----
{
this->CreateFullDocumentation();
! this->CurrentFormatter->PrintHeader(GetNameString(), GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
***************
*** 1245,1253 ****
this->ClearSections();
this->CreateModulesSection();
this->AddSectionToPrint("Description");
this->AddSectionToPrint("Modules");
this->AddSectionToPrint("Copyright");
this->AddSectionToPrint("See Also");
! this->CurrentFormatter->PrintHeader(this->GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
--- 1306,1315 ----
this->ClearSections();
this->CreateModulesSection();
+ this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(Modules));
this->AddSectionToPrint("Description");
this->AddSectionToPrint("Modules");
this->AddSectionToPrint("Copyright");
this->AddSectionToPrint("See Also");
! this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
***************
*** 1260,1263 ****
--- 1322,1326 ----
this->ClearSections();
this->CreateCustomModulesSection();
+ this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(CustomModules));
this->AddSectionToPrint("Description");
this->AddSectionToPrint("Custom CMake Modules");
***************
*** 1266,1270 ****
this->AddSectionToPrint("See Also");
! this->CurrentFormatter->PrintHeader(this->GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
--- 1329,1333 ----
this->AddSectionToPrint("See Also");
! this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
***************
*** 1276,1279 ****
--- 1339,1343 ----
{
this->ClearSections();
+ this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(Policies));
this->AddSectionToPrint("Description");
this->AddSectionToPrint("Policies");
***************
*** 1281,1285 ****
this->AddSectionToPrint("See Also");
! this->CurrentFormatter->PrintHeader(this->GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
--- 1345,1349 ----
this->AddSectionToPrint("See Also");
! this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
***************
*** 1291,1294 ****
--- 1355,1359 ----
{
this->ClearSections();
+ this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(Properties));
this->AddSectionToPrint("Properties Description");
for (std::vector<std::string>::iterator i =
***************
*** 1300,1304 ****
this->AddSectionToPrint("Copyright");
this->AddSectionToPrint("Standard See Also");
! this->CurrentFormatter->PrintHeader(this->GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
--- 1365,1369 ----
this->AddSectionToPrint("Copyright");
this->AddSectionToPrint("Standard See Also");
! this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
***************
*** 1310,1313 ****
--- 1375,1379 ----
{
this->ClearSections();
+ this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(Variables));
for (std::vector<std::string>::iterator i =
this->VariableSections.begin();
***************
*** 1318,1322 ****
this->AddSectionToPrint("Copyright");
this->AddSectionToPrint("Standard See Also");
! this->CurrentFormatter->PrintHeader(this->GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
--- 1384,1388 ----
this->AddSectionToPrint("Copyright");
this->AddSectionToPrint("Standard See Also");
! this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
***************
*** 1328,1335 ****
{
this->ClearSections();
this->AddSectionToPrint("Commands");
this->AddSectionToPrint("Copyright");
this->AddSectionToPrint("Standard See Also");
! this->CurrentFormatter->PrintHeader(this->GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
--- 1394,1402 ----
{
this->ClearSections();
+ this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(Commands));
this->AddSectionToPrint("Commands");
this->AddSectionToPrint("Copyright");
this->AddSectionToPrint("Standard See Also");
! this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
***************
*** 1341,1349 ****
{
this->ClearSections();
this->AddSectionToPrint("Compatibility Commands Description");
this->AddSectionToPrint("Compatibility Commands");
this->AddSectionToPrint("Copyright");
this->AddSectionToPrint("Standard See Also");
! this->CurrentFormatter->PrintHeader(GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
--- 1408,1417 ----
{
this->ClearSections();
+ this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(CompatCommands));
this->AddSectionToPrint("Compatibility Commands Description");
this->AddSectionToPrint("Compatibility Commands");
this->AddSectionToPrint("Copyright");
this->AddSectionToPrint("Standard See Also");
! this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
this->Print(os);
this->CurrentFormatter->PrintFooter(os);
***************
*** 1467,1470 ****
--- 1535,1573 ----
//----------------------------------------------------------------------------
+ const char* cmDocumentation::GetDocName(bool fallbackToNameString) const
+ {
+ if (this->DocName.length() > 0)
+ {
+ return this->DocName.c_str();
+ }
+ else if (fallbackToNameString)
+ {
+ return this->GetNameString();
+ }
+ else
+ return 0;
+ }
+
+ //----------------------------------------------------------------------------
+ #define CASE_DEFAULT_DOCNAME(doctype) \
+ case cmDocumentation::doctype : \
+ return GET_DOCUMENT_INTRO(doctype)[0];
+ const char* cmDocumentation::GetDefaultDocName(Type ht) const
+ {
+ switch (ht)
+ {
+ CASE_DEFAULT_DOCNAME(Modules)
+ CASE_DEFAULT_DOCNAME(CustomModules)
+ CASE_DEFAULT_DOCNAME(Policies)
+ CASE_DEFAULT_DOCNAME(Properties)
+ CASE_DEFAULT_DOCNAME(Variables)
+ CASE_DEFAULT_DOCNAME(Commands)
+ CASE_DEFAULT_DOCNAME(CompatCommands)
+ default: break;
+ }
+ return 0;
+ }
+
+ //----------------------------------------------------------------------------
bool cmDocumentation::IsOption(const char* arg) const
{
Index: cmDocumentationFormatterDocbook.cxx
===================================================================
RCS file: /cvsroot/CMake/CMake/Source/cmDocumentationFormatterDocbook.cxx,v
retrieving revision 1.3
retrieving revision 1.4
diff -C 2 -d -r1.3 -r1.4
*** cmDocumentationFormatterDocbook.cxx 9 May 2008 21:50:45 -0000 1.3
--- cmDocumentationFormatterDocbook.cxx 10 Oct 2008 15:23:35 -0000 1.4
***************
*** 230,235 ****
//----------------------------------------------------------------------------
! void cmDocumentationFormatterDocbook::PrintHeader(const char* name,
! std::ostream& os)
{
// this one is used to ensure that we don't create multiple link targets
--- 230,236 ----
//----------------------------------------------------------------------------
! void cmDocumentationFormatterDocbook::PrintHeader(const char* docname,
! const char* appname,
! std::ostream& os)
{
// this one is used to ensure that we don't create multiple link targets
***************
*** 245,249 ****
"<article>\n"
"<articleinfo>\n"
! "<title>" << name << "</title>\n"
"</articleinfo>\n";
}
--- 246,250 ----
"<article>\n"
"<articleinfo>\n"
! "<title>" << docname << " - " << appname << "</title>\n"
"</articleinfo>\n";
}
Index: cmDocumentationFormatter.h
===================================================================
RCS file: /cvsroot/CMake/CMake/Source/cmDocumentationFormatter.h,v
retrieving revision 1.9
retrieving revision 1.10
diff -C 2 -d -r1.9 -r1.10
*** cmDocumentationFormatter.h 5 May 2008 16:02:36 -0000 1.9
--- cmDocumentationFormatter.h 10 Oct 2008 15:23:35 -0000 1.10
***************
*** 53,57 ****
virtual cmDocumentationEnums::Form GetForm() const = 0;
! virtual void PrintHeader(const char* /*name*/, std::ostream& /*os*/) {}
virtual void PrintFooter(std::ostream& /*os*/) {}
virtual void PrintSection(std::ostream& os,
--- 53,59 ----
virtual cmDocumentationEnums::Form GetForm() const = 0;
! virtual void PrintHeader(const char* /*docname*/,
! const char* /*appname*/,
! std::ostream& /*os*/) {}
virtual void PrintFooter(std::ostream& /*os*/) {}
virtual void PrintSection(std::ostream& os,
Index: cmDocumentationFormatterMan.cxx
===================================================================
RCS file: /cvsroot/CMake/CMake/Source/cmDocumentationFormatterMan.cxx,v
retrieving revision 1.5
retrieving revision 1.6
diff -C 2 -d -r1.5 -r1.6
*** cmDocumentationFormatterMan.cxx 22 Oct 2007 16:48:39 -0000 1.5
--- cmDocumentationFormatterMan.cxx 10 Oct 2008 15:23:35 -0000 1.6
***************
*** 58,67 ****
}
void cmDocumentationFormatterMan::PrintPreformatted(std::ostream& os,
const char* text)
{
std::string man_text = text;
! cmSystemTools::ReplaceString(man_text, "\\", "\\\\");
! os << man_text << "\n";
}
--- 58,76 ----
}
+ void cmDocumentationFormatterMan::EscapeText(std::string& man_text)
+ {
+ cmSystemTools::ReplaceString(man_text, "\\", "\\\\");
+ cmSystemTools::ReplaceString(man_text, "-", "\\-");
+ }
+
void cmDocumentationFormatterMan::PrintPreformatted(std::ostream& os,
const char* text)
{
std::string man_text = text;
! this->EscapeText(man_text);
! os << ".nf\n" << man_text;
! if (*text && man_text.at(man_text.length()-1) != '\n')
! os << "\n";
! os << ".fi\n";
}
***************
*** 70,74 ****
{
std::string man_text = text;
! cmSystemTools::ReplaceString(man_text, "\\", "\\\\");
os << man_text << "\n\n";
}
--- 79,83 ----
{
std::string man_text = text;
! this->EscapeText(man_text);
os << man_text << "\n\n";
}
***************
*** 76,85 ****
//----------------------------------------------------------------------------
! void cmDocumentationFormatterMan::PrintHeader(const char* name,
std::ostream& os)
{
! os << ".TH " << name << " 1 \""
<< cmSystemTools::GetCurrentDateTime("%B %d, %Y").c_str()
! << "\" \"" << name
<< " " << cmVersion::GetCMakeVersion()
<< "\"\n";
--- 85,99 ----
//----------------------------------------------------------------------------
! void cmDocumentationFormatterMan::PrintHeader(const char* docname,
! const char* appname,
std::ostream& os)
{
! std::string s_docname(docname), s_appname(appname);
!
! this->EscapeText(s_docname);
! this->EscapeText(s_appname);
! os << ".TH " << s_docname << " 1 \""
<< cmSystemTools::GetCurrentDateTime("%B %d, %Y").c_str()
! << "\" \"" << s_appname
<< " " << cmVersion::GetCMakeVersion()
<< "\"\n";
Index: cmDocumentationFormatterMan.h
===================================================================
RCS file: /cvsroot/CMake/CMake/Source/cmDocumentationFormatterMan.h,v
retrieving revision 1.2
retrieving revision 1.3
diff -C 2 -d -r1.2 -r1.3
*** cmDocumentationFormatterMan.h 22 Oct 2007 16:48:39 -0000 1.2
--- cmDocumentationFormatterMan.h 10 Oct 2008 15:23:35 -0000 1.3
***************
*** 31,35 ****
{ return cmDocumentationEnums::ManForm;}
! virtual void PrintHeader(const char* name, std::ostream& os);
virtual void PrintSection(std::ostream& os,
const cmDocumentationSection& section,
--- 31,36 ----
{ return cmDocumentationEnums::ManForm;}
! virtual void PrintHeader(const char* docname, const char* appname,
! std::ostream& os);
virtual void PrintSection(std::ostream& os,
const cmDocumentationSection& section,
***************
*** 37,40 ****
--- 38,44 ----
virtual void PrintPreformatted(std::ostream& os, const char* text);
virtual void PrintParagraph(std::ostream& os, const char* text);
+
+ private:
+ void EscapeText(std::string& man_text);
};
Index: cmDocumentationFormatterDocbook.h
===================================================================
RCS file: /cvsroot/CMake/CMake/Source/cmDocumentationFormatterDocbook.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -C 2 -d -r1.1 -r1.2
*** cmDocumentationFormatterDocbook.h 19 Feb 2008 19:33:43 -0000 1.1
--- cmDocumentationFormatterDocbook.h 10 Oct 2008 15:23:35 -0000 1.2
***************
*** 32,36 ****
{ return cmDocumentationEnums::DocbookForm;}
! virtual void PrintHeader(const char* name, std::ostream& os);
virtual void PrintFooter(std::ostream& os);
virtual void PrintSection(std::ostream& os,
--- 32,37 ----
{ return cmDocumentationEnums::DocbookForm;}
! virtual void PrintHeader(const char* docname, const char* appname,
! std::ostream& os);
virtual void PrintFooter(std::ostream& os);
virtual void PrintSection(std::ostream& os,
More information about the Cmake-commits
mailing list