Merge topic 'DetectManSection'

20e133e man documentation: detect man section from the given filename
38df155 documentation: preparation for making the man section configurable
e6a935f -remove trailing whitespace
This commit is contained in:
David Cole 2012-07-09 14:21:52 -04:00 committed by CMake Topic Stage
commit e6ce00a4ac
5 changed files with 95 additions and 64 deletions

View File

@ -221,7 +221,7 @@ DOCUMENT_INTRO(CompatCommands, "cmakecompat",
cmDocumentation::cmDocumentation()
:CurrentFormatter(0)
{
this->SetForm(TextForm);
this->SetForm(TextForm, 0);
this->addCommonStandardDocSections();
this->ShowGenerators = true;
}
@ -594,7 +594,7 @@ bool cmDocumentation::PrintRequestedDocumentation(std::ostream& os)
i != this->RequestedHelpItems.end();
++i)
{
this->SetForm(i->HelpForm);
this->SetForm(i->HelpForm, i->ManSection);
this->CurrentArgument = i->Argument;
// If a file name was given, use it. Otherwise, default to the
// given stream.
@ -642,7 +642,8 @@ bool cmDocumentation::PrintRequestedDocumentation(std::ostream& os)
cmDocumentation::Form cmDocumentation::GetFormFromFilename(
const std::string& filename)
const std::string& filename,
int* manSection)
{
std::string ext = cmSystemTools::GetFilenameLastExtension(filename);
ext = cmSystemTools::UpperCase(ext);
@ -659,6 +660,10 @@ cmDocumentation::Form cmDocumentation::GetFormFromFilename(
// ".1" to ".9" should be manpages
if ((ext.length()==2) && (ext[1] >='1') && (ext[1]<='9'))
{
if (manSection)
{
*manSection = ext[1] - '0';
}
return cmDocumentation::ManForm;
}
@ -1128,49 +1133,57 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
{
help.HelpType = cmDocumentation::Properties;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
}
else if(strcmp(argv[i], "--help-policies") == 0)
{
help.HelpType = cmDocumentation::Policies;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
}
else if(strcmp(argv[i], "--help-variables") == 0)
{
help.HelpType = cmDocumentation::Variables;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
}
else if(strcmp(argv[i], "--help-modules") == 0)
{
help.HelpType = cmDocumentation::Modules;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
}
else if(strcmp(argv[i], "--help-custom-modules") == 0)
{
help.HelpType = cmDocumentation::CustomModules;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
}
else if(strcmp(argv[i], "--help-commands") == 0)
{
help.HelpType = cmDocumentation::Commands;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
}
else if(strcmp(argv[i], "--help-compatcommands") == 0)
{
help.HelpType = cmDocumentation::CompatCommands;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
}
else if(strcmp(argv[i], "--help-full") == 0)
{
help.HelpType = cmDocumentation::Full;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
}
else if(strcmp(argv[i], "--help-html") == 0)
{
@ -1183,6 +1196,7 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
help.HelpType = cmDocumentation::Full;
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = cmDocumentation::ManForm;
help.ManSection = 1;
}
else if(strcmp(argv[i], "--help-command") == 0)
{
@ -1190,35 +1204,40 @@ 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.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
}
else if(strcmp(argv[i], "--help-module") == 0)
{
help.HelpType = cmDocumentation::SingleModule;
GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
}
else if(strcmp(argv[i], "--help-property") == 0)
{
help.HelpType = cmDocumentation::SingleProperty;
GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
}
else if(strcmp(argv[i], "--help-policy") == 0)
{
help.HelpType = cmDocumentation::SinglePolicy;
GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
}
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);
help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection);
}
else if(strcmp(argv[i], "--help-command-list") == 0)
{
@ -1269,9 +1288,9 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
}
//----------------------------------------------------------------------------
void cmDocumentation::Print(Form f, std::ostream& os)
void cmDocumentation::Print(Form f, int manSection, std::ostream& os)
{
this->SetForm(f);
this->SetForm(f, manSection);
this->Print(os);
}
@ -1879,7 +1898,7 @@ void cmDocumentation::CreateFullDocumentation()
}
//----------------------------------------------------------------------------
void cmDocumentation::SetForm(Form f)
void cmDocumentation::SetForm(Form f, int manSection)
{
switch(f)
{
@ -1890,6 +1909,7 @@ void cmDocumentation::SetForm(Form f)
this->CurrentFormatter = &this->DocbookFormatter;
break;
case ManForm:
this->ManFormatter.SetManSection(manSection);
this->CurrentFormatter = &this->ManFormatter;
break;
case TextForm:

View File

@ -33,7 +33,7 @@ class cmDocumentation: public cmDocumentationEnums
{
public:
cmDocumentation();
~cmDocumentation();
/**
@ -51,18 +51,18 @@ public:
typedef std::list<documentedModuleSectionPair_t> documentedModulesList_t;
// High-level interface for standard documents:
/**
* Check command line arguments for documentation options. Returns
* true if documentation options are found, and false otherwise.
* When true is returned, PrintRequestedDocumentation should be
* called. exitOpt can be used for things like cmake -E, so that
* called. exitOpt can be used for things like cmake -E, so that
* all arguments after the -E are ignored and not searched for
* help arguments.
*/
bool CheckOptions(int argc, const char* const* argv,
bool CheckOptions(int argc, const char* const* argv,
const char* exitOpt =0);
/**
* Print help requested on the command line. Call after
* CheckOptions returns true. Returns true on success, and false
@ -70,12 +70,12 @@ public:
* command line cannot be written.
*/
bool PrintRequestedDocumentation(std::ostream& os);
/** Print help of the given type. */
bool PrintDocumentation(Type ht, std::ostream& os, const char* docname=0);
void SetShowGenerators(bool showGen) { this->ShowGenerators = showGen; }
/** Set the program name for standard document generation. */
void SetName(const char* name);
@ -108,8 +108,8 @@ public:
* Print documentation in the given form. All previously added
* sections will be generated.
*/
void Print(Form f, std::ostream& os);
void Print(Form f, int manSection, std::ostream& os);
/**
* Print documentation in the current form. All previously added
* sections will be generated.
@ -125,15 +125,16 @@ public:
void SetSeeAlsoList(const char *data[][3]);
/** Clear all previously added sections of help. */
void ClearSections();
void ClearSections();
/** Set cmake root so we can find installed files */
void SetCMakeRoot(const char* root) { this->CMakeRoot = root;}
/** Set CMAKE_MODULE_PATH so we can find additional cmake modules */
void SetCMakeModulePath(const char* path) { this->CMakeModulePath = path;}
static Form GetFormFromFilename(const std::string& filename);
static Form GetFormFromFilename(const std::string& filename,
int* ManSection);
/** Add common (to all tools) documentation section(s) */
void addCommonStandardDocSections();
@ -190,13 +191,13 @@ public:
std::vector<cmDocumentationEntry>& commands,
cmake* cm);
private:
void SetForm(Form f);
void SetForm(Form f, int manSection);
void SetDocName(const char* docname);
bool CreateSingleModule(const char* fname,
bool CreateSingleModule(const char* fname,
const char* moduleName,
cmDocumentationSection &sec);
void CreateModuleDocsForDir(cmsys::Directory& dir,
void CreateModuleDocsForDir(cmsys::Directory& dir,
cmDocumentationSection &moduleSection);
bool CreateModulesSection();
bool CreateCustomModulesSection();
@ -236,7 +237,7 @@ private:
std::string NameString;
std::string DocName;
std::map<std::string,cmDocumentationSection*> AllSections;
std::string SeeAlsoString;
std::string CMakeRoot;
std::string CMakeModulePath;
@ -247,11 +248,12 @@ private:
struct RequestedHelpItem
{
RequestedHelpItem():HelpForm(TextForm), HelpType(None) {}
RequestedHelpItem():HelpForm(TextForm), HelpType(None), ManSection(1) {}
cmDocumentationEnums::Form HelpForm;
cmDocumentationEnums::Type HelpType;
std::string Filename;
std::string Argument;
int ManSection;
};
std::vector<RequestedHelpItem> RequestedHelpItems;

View File

@ -19,9 +19,15 @@
cmDocumentationFormatterMan::cmDocumentationFormatterMan()
:cmDocumentationFormatter()
,ManSection(1)
{
}
void cmDocumentationFormatterMan::SetManSection(int manSection)
{
this->ManSection = manSection;
}
void cmDocumentationFormatterMan
::PrintSection(std::ostream& os,
const cmDocumentationSection &section,
@ -32,9 +38,9 @@ void cmDocumentationFormatterMan
os << ".SH " << name << "\n";
}
const std::vector<cmDocumentationEntry> &entries =
const std::vector<cmDocumentationEntry> &entries =
section.GetEntries();
for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
op != entries.end(); ++op)
{
if(op->Name.size())
@ -58,7 +64,7 @@ void cmDocumentationFormatterMan::EscapeText(std::string& man_text)
cmSystemTools::ReplaceString(man_text, "-", "\\-");
}
void cmDocumentationFormatterMan::PrintPreformatted(std::ostream& os,
void cmDocumentationFormatterMan::PrintPreformatted(std::ostream& os,
const char* text)
{
std::string man_text = text;
@ -69,7 +75,7 @@ void cmDocumentationFormatterMan::PrintPreformatted(std::ostream& os,
os << ".fi\n\n";
}
void cmDocumentationFormatterMan::PrintParagraph(std::ostream& os,
void cmDocumentationFormatterMan::PrintParagraph(std::ostream& os,
const char* text)
{
std::string man_text = text;
@ -87,7 +93,7 @@ void cmDocumentationFormatterMan::PrintHeader(const char* docname,
this->EscapeText(s_docname);
this->EscapeText(s_appname);
os << ".TH " << s_docname << " 1 \""
os << ".TH " << s_docname << " " << this->ManSection << " \""
<< cmSystemTools::GetCurrentDateTime("%B %d, %Y").c_str()
<< "\" \"" << s_appname
<< " " << cmVersion::GetCMakeVersion()

View File

@ -22,6 +22,8 @@ class cmDocumentationFormatterMan : public cmDocumentationFormatter
public:
cmDocumentationFormatterMan();
void SetManSection(int manSection);
virtual cmDocumentationEnums::Form GetForm() const
{ return cmDocumentationEnums::ManForm;}
@ -35,6 +37,7 @@ public:
private:
void EscapeText(std::string& man_text);
int ManSection;
};
#endif

View File

@ -9,8 +9,8 @@
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the License for more information.
============================================================================*/
// include these first, otherwise there will be problems on Windows
// with GetCurrentDirectory() being redefined
// include these first, otherwise there will be problems on Windows
// with GetCurrentDirectory() being redefined
#ifdef CMAKE_BUILD_WITH_CMAKE
#include "cmDynamicLoader.h"
#include "cmDocumentation.h"
@ -183,7 +183,7 @@ 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, DocBook and plain text."},
{"--help-policy cmp [file]",
{"--help-policy cmp [file]",
"Print help for a single policy and exit.",
"Full documentation specific to the given policy is displayed."
"If a file is specified, the documentation is written into and the output "
@ -194,7 +194,7 @@ 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, DocBook and plain text."},
{"--help-property prop [file]",
{"--help-property prop [file]",
"Print help for a single property and exit.",
"Full documentation specific to the given property is displayed."
"If a file is specified, the documentation is written into and the output "
@ -212,7 +212,7 @@ 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, DocBook and plain text."},
{"--help-variable var [file]",
{"--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 "
@ -296,13 +296,13 @@ static std::string cmakemainGetStack(void *clientdata)
return msg;
}
static void cmakemainErrorCallback(const char* m, const char*, bool&,
static void cmakemainErrorCallback(const char* m, const char*, bool&,
void *clientdata)
{
std::cerr << m << cmakemainGetStack(clientdata) << std::endl << std::flush;
}
static void cmakemainProgressCallback(const char *m, float prog,
static void cmakemainProgressCallback(const char *m, float prog,
void* clientdata)
{
cmMakefile* mf = cmakemainGetMakefile(clientdata);
@ -348,7 +348,7 @@ int do_cmake(int ac, char** av)
if ( cmSystemTools::GetCurrentWorkingDirectory().size() == 0 )
{
std::cerr << "Current working directory cannot be established."
std::cerr << "Current working directory cannot be established."
<< std::endl;
nocwd = 1;
}
@ -357,13 +357,13 @@ int do_cmake(int ac, char** av)
cmDocumentation doc;
doc.addCMakeStandardDocSections();
if(doc.CheckOptions(ac, av, "-E") || nocwd)
{
{
// Construct and print requested documentation.
cmake hcm;
hcm.AddCMakePaths();
doc.SetCMakeRoot(hcm.GetCacheDefinition("CMAKE_ROOT"));
// the command line args are processed here so that you can do
// the command line args are processed here so that you can do
// -DCMAKE_MODULE_PATH=/some/path and have this value accessible here
std::vector<std::string> args;
for(int i =0; i < ac; ++i)
@ -401,7 +401,7 @@ int do_cmake(int ac, char** av)
doc.SetSections(propDocs);
cmDocumentationEntry e;
e.Brief =
e.Brief =
"variables defined by cmake, that give information about the project, "
"and cmake";
doc.PrependSection("Variables that Provide Information",e);
@ -418,7 +418,7 @@ int do_cmake(int ac, char** av)
{
doc.ClearSections();
doc.SetSection("NOTE", cmDocumentationNOTE);
doc.Print(cmDocumentation::UsageForm, std::cerr);
doc.Print(cmDocumentation::UsageForm, 0, std::cerr);
return 1;
}
return result;
@ -426,13 +426,13 @@ int do_cmake(int ac, char** av)
#else
if ( nocwd || ac == 1 )
{
std::cout <<
std::cout <<
"Bootstrap CMake should not be used outside CMake build process."
<< std::endl;
return 0;
}
#endif
bool wiz = false;
bool sysinfo = false;
bool command = false;
@ -453,7 +453,7 @@ int do_cmake(int ac, char** av)
sysinfo = true;
}
// if command has already been set, then
// do not eat the -E
// do not eat the -E
else if (!command && strcmp(av[i], "-E") == 0)
{
command = true;
@ -500,7 +500,7 @@ int do_cmake(int ac, char** av)
workingMode = cmake::FIND_PACKAGE_MODE;
args.push_back(av[i]);
}
else
else
{
args.push_back(av[i]);
}
@ -513,15 +513,15 @@ int do_cmake(int ac, char** av)
if (wiz)
{
cmakewizard wizard;
return wizard.RunWizard(args);
return wizard.RunWizard(args);
}
if (sysinfo)
{
cmake cm;
int ret = cm.GetSystemInformation(args);
return ret;
return ret;
}
cmake cm;
cmake cm;
cmSystemTools::SetErrorCallback(cmakemainErrorCallback, (void *)&cm);
cm.SetProgressCallback(cmakemainProgressCallback, (void *)&cm);
cm.SetWorkingMode(workingMode);
@ -529,7 +529,7 @@ int do_cmake(int ac, char** av)
int res = cm.Run(args, view_only);
if ( list_cached || list_all_cached )
{
cmCacheManager::CacheIterator it =
cmCacheManager::CacheIterator it =
cm.GetCacheManager()->GetCacheIterator();
std::cout << "-- Cache values" << std::endl;
for ( it.Begin(); !it.IsAtEnd(); it.Next() )
@ -545,8 +545,8 @@ int do_cmake(int ac, char** av)
{
std::cout << "// " << it.GetProperty("HELPSTRING") << std::endl;
}
std::cout << it.GetName() << ":" <<
cmCacheManager::TypeToString(it.GetType())
std::cout << it.GetName() << ":" <<
cmCacheManager::TypeToString(it.GetType())
<< "=" << it.GetValue() << std::endl;
if ( list_help )
{