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

5 files changed, 95 insertions, 64 deletions

diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx
index 904a157..1b042ae 100644
--- a/Source/cmDocumentation.cxx
+++ b/Source/cmDocumentation.cxx
@@ -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:
diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h
index 11bef16..e180f60 100644
--- a/Source/cmDocumentation.h
+++ b/Source/cmDocumentation.h
@@ -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;
diff --git a/Source/cmDocumentationFormatterMan.cxx b/Source/cmDocumentationFormatterMan.cxx
index 79a3b25..4123c85 100644
--- a/Source/cmDocumentationFormatterMan.cxx
+++ b/Source/cmDocumentationFormatterMan.cxx
@@ -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()
diff --git a/Source/cmDocumentationFormatterMan.h b/Source/cmDocumentationFormatterMan.h
index 11b5acb..b3d069c 100644
--- a/Source/cmDocumentationFormatterMan.h
+++ b/Source/cmDocumentationFormatterMan.h
@@ -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
diff --git a/Source/cmakemain.cxx b/Source/cmakemain.cxx
index c3de8ca..11a4267 100644
--- a/Source/cmakemain.cxx
+++ b/Source/cmakemain.cxx
@@ -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 )
             {