Commit 80a3273b authored by Brad King's avatar Brad King
Browse files

Drop all documentation formatters except Usage

We now need only the Usage formatter to support command-line options
that print basic usage, and the supporting indented=>preformatted markup
processor to support CMake message formatting.  Drop all other
documentation formatters and move the remaining code up into the top
cmDocumentationFormatter class.
parent b336a1eb
......@@ -159,12 +159,6 @@ set(SRCS
cmDependsJavaParserHelper.h
cmDocumentation.cxx
cmDocumentationFormatter.cxx
cmDocumentationFormatterHTML.cxx
cmDocumentationFormatterDocbook.cxx
cmDocumentationFormatterMan.cxx
cmDocumentationFormatterRST.cxx
cmDocumentationFormatterText.cxx
cmDocumentationFormatterUsage.cxx
cmDocumentationSection.cxx
cmDocumentCompileDefinitions.h
cmDocumentGeneratorExpressions.h
......
......@@ -56,9 +56,7 @@ static const char *cmDocumentationGeneratorsHeader[][3] =
//----------------------------------------------------------------------------
cmDocumentation::cmDocumentation()
:CurrentFormatter(0)
{
this->SetForm(TextForm, 0);
this->addCommonStandardDocSections();
this->ShowGenerators = true;
}
......@@ -82,22 +80,6 @@ bool cmDocumentation::PrintVersion(std::ostream& os)
return true;
}
//----------------------------------------------------------------------------
void cmDocumentation::AddSectionToPrint(const char *section)
{
if (this->AllSections.find(section) != this->AllSections.end())
{
this->PrintSections.push_back(this->AllSections[section]);
}
}
//----------------------------------------------------------------------------
void cmDocumentation::ClearSections()
{
this->PrintSections.erase(this->PrintSections.begin(),
this->PrintSections.end());
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os)
{
......@@ -147,7 +129,6 @@ bool cmDocumentation::PrintRequestedDocumentation(std::ostream& os)
i != this->RequestedHelpItems.end();
++i)
{
this->SetForm(i->HelpForm, i->ManSection);
this->CurrentArgument = i->Argument;
// If a file name was given, use it. Otherwise, default to the
// given stream.
......@@ -193,38 +174,27 @@ bool cmDocumentation::PrintRequestedDocumentation(std::ostream& os)
};
cmDocumentation::Form cmDocumentation::GetFormFromFilename(
const std::string& filename,
int* manSection)
void cmDocumentation::WarnFormFromFilename(
cmDocumentation::RequestedHelpItem& request)
{
std::string ext = cmSystemTools::GetFilenameLastExtension(filename);
std::string ext = cmSystemTools::GetFilenameLastExtension(request.Filename);
ext = cmSystemTools::UpperCase(ext);
if ((ext == ".HTM") || (ext == ".HTML"))
{
return cmDocumentation::HTMLForm;
request.HelpType = cmDocumentation::None;
cmSystemTools::Message("Warning: HTML help format no longer supported");
}
if (ext == ".DOCBOOK")
else if (ext == ".DOCBOOK")
{
return cmDocumentation::DocbookForm;
request.HelpType = cmDocumentation::None;
cmSystemTools::Message("Warning: Docbook help format no longer supported");
}
// ".1" to ".9" should be manpages
if ((ext.length()==2) && (ext[1] >='1') && (ext[1]<='9'))
else if ((ext.length()==2) && (ext[1] >='1') && (ext[1]<='9'))
{
if (manSection)
{
*manSection = ext[1] - '0';
}
return cmDocumentation::ManForm;
request.HelpType = cmDocumentation::None;
cmSystemTools::Message("Warning: Man help format no longer supported");
}
if (ext == ".RST")
{
return cmDocumentation::RSTForm;
}
return cmDocumentation::TextForm;
}
//----------------------------------------------------------------------------
......@@ -274,7 +244,6 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
{
RequestedHelpItem help;
help.HelpType = cmDocumentation::Usage;
help.HelpForm = cmDocumentation::UsageForm;
this->RequestedHelpItems.push_back(help);
return true;
}
......@@ -298,7 +267,6 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
(strcmp(argv[i], "-H") == 0))
{
help.HelpType = cmDocumentation::Usage;
help.HelpForm = cmDocumentation::UsageForm;
GET_OPT_ARGUMENT(help.Argument);
help.Argument = cmSystemTools::LowerCase(help.Argument);
// special case for single command
......@@ -312,32 +280,28 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
help.HelpType = cmDocumentation::OneManual;
help.Argument = "cmake-properties.7";
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
this->WarnFormFromFilename(help);
}
else if(strcmp(argv[i], "--help-policies") == 0)
{
help.HelpType = cmDocumentation::OneManual;
help.Argument = "cmake-policies.7";
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
this->WarnFormFromFilename(help);
}
else if(strcmp(argv[i], "--help-variables") == 0)
{
help.HelpType = cmDocumentation::OneManual;
help.Argument = "cmake-variables.7";
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
this->WarnFormFromFilename(help);
}
else if(strcmp(argv[i], "--help-modules") == 0)
{
help.HelpType = cmDocumentation::OneManual;
help.Argument = "cmake-modules.7";
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
this->WarnFormFromFilename(help);
}
else if(strcmp(argv[i], "--help-custom-modules") == 0)
{
......@@ -351,8 +315,7 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
help.HelpType = cmDocumentation::OneManual;
help.Argument = "cmake-commands.7";
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
this->WarnFormFromFilename(help);
}
else if(strcmp(argv[i], "--help-compatcommands") == 0)
{
......@@ -385,40 +348,35 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename);
help.Argument = cmSystemTools::LowerCase(help.Argument);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
this->WarnFormFromFilename(help);
}
else if(strcmp(argv[i], "--help-module") == 0)
{
help.HelpType = cmDocumentation::OneModule;
GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
this->WarnFormFromFilename(help);
}
else if(strcmp(argv[i], "--help-property") == 0)
{
help.HelpType = cmDocumentation::OneProperty;
GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
this->WarnFormFromFilename(help);
}
else if(strcmp(argv[i], "--help-policy") == 0)
{
help.HelpType = cmDocumentation::OnePolicy;
GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
this->WarnFormFromFilename(help);
}
else if(strcmp(argv[i], "--help-variable") == 0)
{
help.HelpType = cmDocumentation::OneVariable;
GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
this->WarnFormFromFilename(help);
}
else if(strcmp(argv[i], "--help-manual") == 0)
{
......@@ -431,31 +389,26 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
{
help.HelpType = cmDocumentation::ListCommands;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = cmDocumentation::TextForm;
}
else if(strcmp(argv[i], "--help-module-list") == 0)
{
help.HelpType = cmDocumentation::ListModules;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = cmDocumentation::TextForm;
}
else if(strcmp(argv[i], "--help-property-list") == 0)
{
help.HelpType = cmDocumentation::ListProperties;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = cmDocumentation::TextForm;
}
else if(strcmp(argv[i], "--help-variable-list") == 0)
{
help.HelpType = cmDocumentation::ListVariables;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = cmDocumentation::TextForm;
}
else if(strcmp(argv[i], "--help-policy-list") == 0)
{
help.HelpType = cmDocumentation::ListPolicies;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = cmDocumentation::TextForm;
}
else if(strcmp(argv[i], "--help-manual-list") == 0)
{
......@@ -474,7 +427,6 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
{
help.HelpType = cmDocumentation::Version;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = cmDocumentation::UsageForm;
}
if(help.HelpType != None)
{
......@@ -486,28 +438,6 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
return result;
}
//----------------------------------------------------------------------------
void cmDocumentation::Print(Form f, int manSection, std::ostream& os)
{
this->SetForm(f, manSection);
this->Print(os);
}
//----------------------------------------------------------------------------
void cmDocumentation::Print(std::ostream& os)
{
// if the formatter supports it, print a master index for
// all sections
this->CurrentFormatter->PrintIndex(os, this->PrintSections);
for(unsigned int i=0; i < this->PrintSections.size(); ++i)
{
std::string name = this->PrintSections[i]->
GetName((this->CurrentFormatter->GetForm()));
this->CurrentFormatter->PrintSection(os,*this->PrintSections[i],
name.c_str());
}
}
//----------------------------------------------------------------------------
void cmDocumentation::SetName(const char* name)
{
......@@ -864,45 +794,28 @@ bool cmDocumentation::PrintHelpListVariables(std::ostream& os)
//----------------------------------------------------------------------------
bool cmDocumentation::PrintDocumentationUsage(std::ostream& os)
{
this->ClearSections();
this->AddSectionToPrint("Usage");
this->AddSectionToPrint("Options");
if(this->ShowGenerators)
std::map<std::string,cmDocumentationSection*>::iterator si;
si = this->AllSections.find("Usage");
if(si != this->AllSections.end())
{
this->AddSectionToPrint("Generators");
this->Formatter.PrintSection(os, *si->second);
}
this->Print(os);
return true;
}
//----------------------------------------------------------------------------
void cmDocumentation::SetForm(Form f, int manSection)
{
switch(f)
si = this->AllSections.find("Options");
if(si != this->AllSections.end())
{
case HTMLForm:
this->CurrentFormatter = &this->HTMLFormatter;
break;
case DocbookForm:
this->CurrentFormatter = &this->DocbookFormatter;
break;
case ManForm:
this->ManFormatter.SetManSection(manSection);
this->CurrentFormatter = &this->ManFormatter;
break;
case RSTForm:
this->CurrentFormatter = &this->RSTFormatter;
break;
case TextForm:
this->CurrentFormatter = &this->TextFormatter;
break;
case UsageForm:
this->CurrentFormatter = & this->UsageFormatter;
break;
this->Formatter.PrintSection(os, *si->second);
}
if(this->ShowGenerators)
{
si = this->AllSections.find("Generators");
if(si != this->AllSections.end())
{
this->Formatter.PrintSection(os, *si->second);
}
}
return true;
}
//----------------------------------------------------------------------------
const char* cmDocumentation::GetNameString() const
{
......
......@@ -15,12 +15,6 @@
#include "cmStandardIncludes.h"
#include "cmProperty.h"
#include "cmDocumentationFormatter.h"
#include "cmDocumentationFormatterHTML.h"
#include "cmDocumentationFormatterDocbook.h"
#include "cmDocumentationFormatterMan.h"
#include "cmDocumentationFormatterRST.h"
#include "cmDocumentationFormatterText.h"
#include "cmDocumentationFormatterUsage.h"
#include "cmDocumentationSection.h"
#include "cmake.h"
......@@ -89,33 +83,9 @@ public:
void AppendSection(const char *sectionName,
cmDocumentationEntry &docs);
/**
* Print documentation in the given form. All previously added
* sections will be generated.
*/
void Print(Form f, int manSection, std::ostream& os);
/**
* Print documentation in the current form. All previously added
* sections will be generated.
*/
void Print(std::ostream& os);
/**
* Add a section of documentation. This can be used to generate custom help
* documents.
*/
void AddSectionToPrint(const char *section);
/** Clear all previously added sections of help. */
void ClearSections();
/** Set cmake root so we can find installed files */
void SetCMakeRoot(const char* root) { this->CMakeRoot = root;}
static Form GetFormFromFilename(const std::string& filename,
int* ManSection);
/** Add common (to all tools) documentation section(s) */
void addCommonStandardDocSections();
......@@ -129,7 +99,6 @@ public:
void addCPackStandardDocSections();
private:
void SetForm(Form f, int manSection);
void GlobHelp(std::vector<std::string>& files, std::string const& pattern);
void PrintNames(std::ostream& os, std::string const& pattern);
......@@ -159,27 +128,20 @@ private:
std::map<std::string,cmDocumentationSection*> AllSections;
std::string CMakeRoot;
std::vector<const cmDocumentationSection *> PrintSections;
std::string CurrentArgument;
struct RequestedHelpItem
{
RequestedHelpItem():HelpForm(TextForm), HelpType(None), ManSection(1) {}
cmDocumentationEnums::Form HelpForm;
RequestedHelpItem(): HelpType(None) {}
cmDocumentationEnums::Type HelpType;
std::string Filename;
std::string Argument;
int ManSection;
};
std::vector<RequestedHelpItem> RequestedHelpItems;
cmDocumentationFormatter* CurrentFormatter;
cmDocumentationFormatterHTML HTMLFormatter;
cmDocumentationFormatterDocbook DocbookFormatter;
cmDocumentationFormatterMan ManFormatter;
cmDocumentationFormatterRST RSTFormatter;
cmDocumentationFormatterText TextFormatter;
cmDocumentationFormatterUsage UsageFormatter;
cmDocumentationFormatter Formatter;
static void WarnFormFromFilename(RequestedHelpItem& request);
};
#endif
......@@ -11,7 +11,10 @@
============================================================================*/
#include "cmDocumentationFormatter.h"
cmDocumentationFormatter::cmDocumentationFormatter()
#include "cmDocumentationSection.h"
cmDocumentationFormatter::cmDocumentationFormatter():
TextWidth(77), TextIndent("")
{
}
......@@ -66,115 +69,162 @@ void cmDocumentationFormatter::PrintFormatted(std::ostream& os,
}
}
//----------------------------------------------------------------------------
std::string
cmDocumentationFormatter::ComputeSectionLinkPrefix(std::string const& name)
void cmDocumentationFormatter::PrintPreformatted(std::ostream& os,
const char* text)
{
// Map from section name to a prefix for links pointing within the
// section. For example, the commands section should have HTML
// links to each command with names like #command:ADD_EXECUTABLE.
if(name.find("Command") != name.npos)
{
return "command";
}
else if(name.find("Propert") != name.npos)
bool newline = true;
for(const char* ptr = text; *ptr; ++ptr)
{
if(name.find("Global") != name.npos)
if(newline && *ptr != '\n')
{
return "prop_gbl";
os << this->TextIndent;
newline = false;
}
else if(name.find("Direct") != name.npos)
os << *ptr;
if(*ptr == '\n')
{
return "prop_dir";
newline = true;
}
else if(name.find("Target") != name.npos)
{
return "prop_tgt";
}
else if(name.find("Test") != name.npos)
os << "\n";
}
void cmDocumentationFormatter::PrintParagraph(std::ostream& os,
const char* text)
{
os << this->TextIndent;
this->PrintColumn(os, text);
os << "\n";
}
void cmDocumentationFormatter::SetIndent(const char* indent)
{
this->TextIndent = indent;
}
void cmDocumentationFormatter::PrintColumn(std::ostream& os,
const char* text)
{
// Print text arranged in an indented column of fixed witdh.
const char* l = text;
long column = 0;
bool newSentence = false;
bool firstLine = true;
int width = this->TextWidth - static_cast<int>(strlen(this->TextIndent));
// Loop until the end of the text.
while(*l)
{
return "prop_test";
}
else if(name.find("Source") != name.npos)
// Parse the next word.
const char* r = l;
while(*r && (*r != '\n') && (*r != ' ')) { ++r; }
// Does it fit on this line?
if(r-l < (width-column-(newSentence?1:0)))
{
return "prop_sf";
}
else if(name.find("Cache") != name.npos)
// Word fits on this line.
if(r > l)
{
return "prop_cache";
}
return "property";
}
else if(name.find("Variable") != name.npos)
if(column)
{
if(name.find("Information") != name.npos)
// Not first word on line. Separate from the previous word
// by a space, or two if this is a new sentence.
if(newSentence)
{
return "var_info";
os << " ";
column += 2;
}
else if(name.find("Behavior") != name.npos)
else
{
return "var_cmake";
os << " ";
column += 1;
}
}
else if(name.find("Describe") != name.npos)
else
{
return "var_sys";
// First word on line. Print indentation unless this is the
// first line.
os << (firstLine?"":this->TextIndent);
}
else if(name.find("Control") != name.npos)
// Print the word.
os.write(l, static_cast<long>(r-l));
newSentence = (*(r-1) == '.');
}
if(*r == '\n')
{
return "var_build";
// Text provided a newline. Start a new line.
os << "\n";
++r;
column = 0;
firstLine = false;
}
else if(name.find("Languages") != name.npos)
else
{
return "var_lang";
// No provided newline. Continue this line.
column += static_cast<long>(r-l);
}
return "variable";
}
else if(name.find("Polic") != name.npos)
else
{
return "policy";
}
else if(name.find("Module") != name.npos)
// Word does not fit on this line. Start a new line.
os << "\n";
firstLine = false;
if(r > l)
{
return "module";
os << this->TextIndent;
os.write(l, static_cast<long>(r-l));
column = static_cast<long>(r-l);
newSentence = (*(r-1) == '.');
}
else if(name.find("Name") != name.npos ||
name.find("Introduction") != name.npos)
else
{
return "name";
column = 0;
}
else if(name.find("Usage") != name.npos)
{
return "usage";