Source/cmDocumentation.cxx

   1 /*=========================================================================
   2
   3   Program:   CMake - Cross-Platform Makefile Generator
   4   Module:    $RCSfile: cmDocumentation.cxx,v $
   5   Language:  C++
   6   Date:      $Date: 2009-03-10 15:11:15 $
   7   Version:   $Revision: 1.75 $
   8
   9   Copyright (c) 2002 Kitware, Inc., Insight Consortium.  All rights reserved.
  10   See Copyright.txt or http://www.cmake.org/HTML/Copyright.html for details.
  11
  12      This software is distributed WITHOUT ANY WARRANTY; without even
  13      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  14      PURPOSE.  See the above copyright notices for more information.
  15
  16 =========================================================================*/
  17 #include "cmDocumentation.h"
  18
  19 #include "cmSystemTools.h"
  20 #include "cmVersion.h"
  21 #include <cmsys/Directory.hxx>
  22
  23
  24 //----------------------------------------------------------------------------
  25 static const char *cmDocumentationStandardOptions[][3] =
  26 {
  27   {"--copyright [file]", "Print the CMake copyright and exit.",
  28    "If a file is specified, the copyright is written into it."},
  29   {"--help", "Print usage information and exit.",
  30    "Usage describes the basic command line interface and its options."},
  31   {"--help-full [file]", "Print full help and exit.",
  32    "Full help displays most of the documentation provided by the UNIX "
  33    "man page.  It is provided for use on non-UNIX platforms, but is "
  34    "also convenient if the man page is not installed.  If a file is "
  35    "specified, the help is written into it."},
  36   {"--help-html [file]", "Print full help in HTML format.",
  37    "This option is used by CMake authors to help produce web pages.  "
  38    "If a file is specified, the help is written into it."},
  39   {"--help-man [file]", "Print full help as a UNIX man page and exit.",
  40    "This option is used by the cmake build to generate the UNIX man page.  "
  41    "If a file is specified, the help is written into it."},
  42   {"--version [file]", "Show program name/version banner and exit.",
  43    "If a file is specified, the version is written into it."},
  44   {0,0,0}
  45 };
  46
  47 //----------------------------------------------------------------------------
  48 static const char *cmModulesDocumentationDescription[][3] =
  49 {
  50   {0,
  51   "  CMake Modules - Modules coming with CMake, the Cross-Platform Makefile "
  52   "Generator.", 0},
  53 //  CMAKE_DOCUMENTATION_OVERVIEW,
  54   {0,
  55   "This is the documentation for the modules and scripts coming with CMake. "
  56   "Using these modules you can check the computer system for "
  57   "installed software packages, features of the compiler and the "
  58   "existance of headers to name just a few.", 0},
  59   {0,0,0}
  60 };
  61
  62 //----------------------------------------------------------------------------
  63 static const char *cmCustomModulesDocumentationDescription[][3] =
  64 {
  65   {0,
  66   "  Custom CMake Modules - Additional Modules for CMake.", 0},
  67 //  CMAKE_DOCUMENTATION_OVERVIEW,
  68   {0,
  69   "This is the documentation for additional modules and scripts for CMake. "
  70   "Using these modules you can check the computer system for "
  71   "installed software packages, features of the compiler and the "
  72   "existance of headers to name just a few.", 0},
  73   {0,0,0}
  74 };
  75
  76 //----------------------------------------------------------------------------
  77 static const char *cmPropertiesDocumentationDescription[][3] =
  78 {
  79   {0,
  80    "  CMake Properties - Properties supported by CMake, "
  81    "the Cross-Platform Makefile Generator.", 0},
  82 //  CMAKE_DOCUMENTATION_OVERVIEW,
  83   {0,
  84    "This is the documentation for the properties supported by CMake. "
  85    "Properties can have different scopes. They can either be assigned to a "
  86    "source file, a directory, a target or globally to CMake. By modifying the "
  87    "values of properties the behaviour of the build system can be customized.",
  88    0},
  89   {0,0,0}
  90 };
  91
  92 //----------------------------------------------------------------------------
  93 static const char *cmCompatCommandsDocumentationDescription[][3] =
  94 {
  95   {0,
  96    "  CMake Compatibility Listfile Commands - "
  97    "Obsolete commands supported by CMake for compatibility.", 0},
  98 //  CMAKE_DOCUMENTATION_OVERVIEW,
  99   {0,
 100   "This is the documentation for now obsolete listfile commands from previous "
 101   "CMake versions, which are still supported for compatibility reasons. You "
 102   "should instead use the newer, faster and shinier new commands. ;-)", 0},
 103   {0,0,0}
 104 };
 105
 106 //----------------------------------------------------------------------------
 107 static const char *cmDocumentationModulesHeader[][3] =
 108 {
 109   {0,
 110    "The following modules are provided with CMake. "
 111    "They can be used with INCLUDE(ModuleName).", 0},
 112   {0,0,0}
 113 };
 114
 115 //----------------------------------------------------------------------------
 116 static const char *cmDocumentationCustomModulesHeader[][3] =
 117 {
 118   {0,
 119    "The following modules are also available for CMake. "
 120    "They can be used with INCLUDE(ModuleName).", 0},
 121   {0,0,0}
 122 };
 123
 124 //----------------------------------------------------------------------------
 125 static const char *cmDocumentationGeneratorsHeader[][3] =
 126 {
 127   {0,
 128    "The following generators are available on this platform:", 0},
 129   {0,0,0}
 130 };
 131
 132 //----------------------------------------------------------------------------
 133 static const char *cmDocumentationStandardSeeAlso[][3] =
 134 {
 135   {0,
 136    "The following resources are available to get help using CMake:", 0},
 137   {"Home Page",
 138    "http://www.cmake.org",
 139    "The primary starting point for learning about CMake."},
 140   {"Frequently Asked Questions",
 141    "http://www.cmake.org/Wiki/CMake_FAQ",
 142    "A Wiki is provided containing answers to frequently asked questions. "},
 143   {"Online Documentation",
 144    "http://www.cmake.org/HTML/Documentation.html",
 145    "Links to available documentation may be found on this web page."},
 146   {"Mailing List",
 147    "http://www.cmake.org/HTML/MailingLists.html",
 148    "For help and discussion about using cmake, a mailing list is provided at "
 149    "cmake@cmake.org. "
 150    "The list is member-post-only but one may sign up on the CMake web page. "
 151    "Please first read the full documentation at "
 152    "http://www.cmake.org before posting questions to the list."},
 153   {0,
 154    "Summary of helpful links:\n"
 155    "  Home: http://www.cmake.org\n"
 156    "  Docs: http://www.cmake.org/HTML/Documentation.html\n"
 157    "  Mail: http://www.cmake.org/HTML/MailingLists.html\n"
 158    "  FAQ:  http://www.cmake.org/Wiki/CMake_FAQ\n"
 159    , 0},
 160   {0,0,0}
 161 };
 162
 163 //----------------------------------------------------------------------------
 164 static const char *cmDocumentationCopyright[][3] =
 165 {
 166   {0,
 167    "Copyright (c) 2002 Kitware, Inc., Insight Consortium.  "
 168    "All rights reserved.", 0},
 169   {0,
 170    "Redistribution and use in source and binary forms, with or without "
 171    "modification, are permitted provided that the following conditions are "
 172    "met:", 0},
 173   {"",
 174    "Redistributions of source code must retain the above copyright notice, "
 175    "this list of conditions and the following disclaimer.", 0},
 176   {"",
 177    "Redistributions in binary form must reproduce the above copyright "
 178    "notice, this list of conditions and the following disclaimer in the "
 179    "documentation and/or other materials provided with the distribution.",
 180    0},
 181   {"",
 182    "The names of Kitware, Inc., the Insight Consortium, or the names of "
 183    "any consortium members, or of any contributors, may not be used to "
 184    "endorse or promote products derived from this software without "
 185    "specific prior written permission.", 0},
 186   {"",
 187    "Modified source versions must be plainly marked as such, and must "
 188    "not be misrepresented as being the original software.", 0},
 189   {0,
 190    "THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "
 191    "``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT "
 192    "LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR "
 193    "A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR "
 194    "CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, "
 195    "EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, "
 196    "PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR "
 197    "PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF "
 198    "LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING "
 199    "NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS "
 200    "SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.", 0},
 201   {0, 0, 0}
 202 };
 203
 204 //----------------------------------------------------------------------------
 205 #define DOCUMENT_INTRO(type, default_name, desc) \
 206   static char const *cmDocumentation##type##Intro[2] = { default_name, desc };
 207 #define GET_DOCUMENT_INTRO(type) cmDocumentation##type##Intro
 208
 209 DOCUMENT_INTRO(Modules, "cmakemodules",
 210   "Reference of available CMake modules.");
 211 DOCUMENT_INTRO(CustomModules, "cmakecustommodules",
 212   "Reference of available CMake custom modules.");
 213 DOCUMENT_INTRO(Policies, "cmakepolicies",
 214   "Reference of CMake policies.");
 215 DOCUMENT_INTRO(Properties, "cmakeprops",
 216   "Reference of CMake properties.");
 217 DOCUMENT_INTRO(Variables, "cmakevars",
 218   "Reference of CMake variables.");
 219 DOCUMENT_INTRO(Commands, "cmakecommands",
 220   "Reference of available CMake commands.");
 221 DOCUMENT_INTRO(CompatCommands, "cmakecompat",
 222   "Reference of CMake compatibility commands.");
 223
 224 //----------------------------------------------------------------------------
 225 cmDocumentation::cmDocumentation()
 226 :CurrentFormatter(0)
 227 {
 228   this->SetForm(TextForm);
 229
 230   cmDocumentationSection *sec;
 231
 232   sec = new cmDocumentationSection("Author","AUTHOR");
 233   sec->Append(cmDocumentationEntry
 234               (0,
 235                "This manual page was generated by the \"--help-man\" option.",
 236                0));
 237   this->AllSections["Author"] = sec;
 238
 239   sec = new cmDocumentationSection("Copyright","COPYRIGHT");
 240   sec->Append(cmDocumentationCopyright);
 241   this->AllSections["Copyright"] = sec;
 242
 243   sec = new cmDocumentationSection("See Also","SEE ALSO");
 244   sec->Append(cmDocumentationStandardSeeAlso);
 245   this->AllSections["Standard See Also"] = sec;
 246
 247   sec = new cmDocumentationSection("Options","OPTIONS");
 248   sec->Append(cmDocumentationStandardOptions);
 249   this->AllSections["Options"] = sec;
 250
 251   sec = new cmDocumentationSection("Properties","PROPERTIES");
 252   sec->Append(cmPropertiesDocumentationDescription);
 253   this->AllSections["Properties Description"] = sec;
 254
 255   sec = new cmDocumentationSection("Generators","GENERATORS");
 256   sec->Append(cmDocumentationGeneratorsHeader);
 257   this->AllSections["Generators"] = sec;
 258
 259   sec = new cmDocumentationSection("Compatibility Commands",
 260                                    "COMPATIBILITY COMMANDS");
 261   sec->Append(cmCompatCommandsDocumentationDescription);
 262   this->AllSections["Compatibility Commands"] = sec;
 263
 264
 265   this->PropertySections.push_back("Properties of Global Scope");
 266   this->PropertySections.push_back("Properties on Directories");
 267   this->PropertySections.push_back("Properties on Targets");
 268   this->PropertySections.push_back("Properties on Tests");
 269   this->PropertySections.push_back("Properties on Source Files");
 270   this->PropertySections.push_back("Properties on Cache Entries");
 271
 272   this->VariableSections.push_back("Variables that Provide Information");
 273   this->VariableSections.push_back("Variables That Change Behavior");
 274   this->VariableSections.push_back("Variables That Describe the System");
 275   this->VariableSections.push_back("Variables that Control the Build");
 276   this->VariableSections.push_back("Variables for Languages");
 277 }
 278
 279 //----------------------------------------------------------------------------
 280 cmDocumentation::~cmDocumentation()
 281 {
 282   for(std::vector< char* >::iterator i = this->ModuleStrings.begin();
 283       i != this->ModuleStrings.end(); ++i)
 284     {
 285     delete [] *i;
 286     }
 287   for(std::map<std::string,cmDocumentationSection *>::iterator i =
 288         this->AllSections.begin();
 289       i != this->AllSections.end(); ++i)
 290     {
 291     delete i->second;
 292     }
 293 }
 294
 295 //----------------------------------------------------------------------------
 296 bool cmDocumentation::PrintCopyright(std::ostream& os)
 297 {
 298   cmDocumentationSection *sec = this->AllSections["Copyright"];
 299   const std::vector<cmDocumentationEntry> &entries = sec->GetEntries();
 300   for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
 301       op != entries.end(); ++op)
 302     {
 303     if(op->Name.size())
 304       {
 305       os << " * ";
 306       this->TextFormatter.SetIndent("    ");
 307       this->TextFormatter.PrintColumn(os, op->Brief.c_str());
 308       }
 309     else
 310       {
 311       this->TextFormatter.SetIndent("");
 312       this->TextFormatter.PrintColumn(os, op->Brief.c_str());
 313       }
 314     os << "\n";
 315     }
 316   return true;
 317 }
 318
 319 //----------------------------------------------------------------------------
 320 bool cmDocumentation::PrintVersion(std::ostream& os)
 321 {
 322   os << this->GetNameString() << " version "
 323      << cmVersion::GetCMakeVersion() << "\n";
 324   return true;
 325 }
 326
 327 //----------------------------------------------------------------------------
 328 void cmDocumentation::AddSectionToPrint(const char *section)
 329 {
 330   if (this->AllSections.find(section) != this->AllSections.end())
 331     {
 332     this->PrintSections.push_back(this->AllSections[section]);
 333     }
 334 }
 335
 336 //----------------------------------------------------------------------------
 337 void cmDocumentation::ClearSections()
 338 {
 339   this->PrintSections.erase(this->PrintSections.begin(),
 340                             this->PrintSections.end());
 341   this->ModulesFound.clear();
 342 }
 343
 344 //----------------------------------------------------------------------------
 345 void cmDocumentation::AddDocumentIntroToPrint(const char* intro[2])
 346 {
 347   const char* docname = this->GetDocName(false);
 348   if(intro && docname)
 349     {
 350     cmDocumentationSection* section;
 351     std::string desc("");
 352
 353     desc += docname;
 354     desc += " - ";
 355     desc += intro[1];
 356
 357     section = new cmDocumentationSection("Introduction", "NAME");
 358     section->Append(0, desc.c_str(), 0);
 359     this->PrintSections.push_back(section);
 360     }
 361 }
 362
 363 //----------------------------------------------------------------------------
 364 bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os,
 365                                          const char* docname)
 366 {
 367   if ((this->CurrentFormatter->GetForm() != HTMLForm)
 368        && (this->CurrentFormatter->GetForm() != DocbookForm)
 369        && (this->CurrentFormatter->GetForm() != ManForm))
 370     {
 371     this->PrintVersion(os);
 372     }
 373
 374   // Handle Document Name. docname==0 disables intro.
 375   this->SetDocName("");
 376   if (docname)
 377     {
 378     if (*docname)
 379       this->SetDocName(docname);
 380     else // empty string was given. select default if possible
 381       this->SetDocName(this->GetDefaultDocName(ht));
 382     }
 383
 384   switch (ht)
 385     {
 386     case cmDocumentation::Usage:
 387       return this->PrintDocumentationUsage(os);
 388     case cmDocumentation::Single:
 389       return this->PrintDocumentationSingle(os);
 390     case cmDocumentation::SingleModule:
 391       return this->PrintDocumentationSingleModule(os);
 392     case cmDocumentation::SinglePolicy:
 393       return this->PrintDocumentationSinglePolicy(os);
 394     case cmDocumentation::SingleProperty:
 395       return this->PrintDocumentationSingleProperty(os);
 396     case cmDocumentation::SingleVariable:
 397       return this->PrintDocumentationSingleVariable(os);
 398     case cmDocumentation::List:
 399       this->PrintDocumentationList(os,"Commands");
 400       this->PrintDocumentationList(os,"Compatibility Commands");
 401       return true;
 402     case cmDocumentation::ModuleList:
 403       // find the modules first, print the custom module docs only if
 404       // any custom modules have been found actually, Alex
 405       this->CreateCustomModulesSection();
 406       this->CreateModulesSection();
 407       if (this->AllSections.find("Custom CMake Modules")
 408          != this->AllSections.end())
 409         {
 410         this->PrintDocumentationList(os,"Custom CMake Modules");
 411         }
 412       this->PrintDocumentationList(os,"Modules");
 413       return true;
 414     case cmDocumentation::PropertyList:
 415       this->PrintDocumentationList(os,"Properties Description");
 416       for (std::vector<std::string>::iterator i =
 417              this->PropertySections.begin();
 418            i != this->PropertySections.end(); ++i)
 419         {
 420         this->PrintDocumentationList(os,i->c_str());
 421         }
 422       return true;
 423     case cmDocumentation::VariableList:
 424       for (std::vector<std::string>::iterator i =
 425              this->VariableSections.begin();
 426            i != this->VariableSections.end(); ++i)
 427         {
 428         this->PrintDocumentationList(os,i->c_str());
 429         }
 430       return true;
 431     case cmDocumentation::Full:
 432       return this->PrintDocumentationFull(os);
 433     case cmDocumentation::Modules:
 434       return this->PrintDocumentationModules(os);
 435     case cmDocumentation::CustomModules:
 436       return this->PrintDocumentationCustomModules(os);
 437     case cmDocumentation::Policies:
 438       return this->PrintDocumentationPolicies(os);
 439     case cmDocumentation::Properties:
 440       return this->PrintDocumentationProperties(os);
 441     case cmDocumentation::Variables:
 442       return this->PrintDocumentationVariables(os);
 443     case cmDocumentation::Commands:
 444       return this->PrintDocumentationCurrentCommands(os);
 445     case cmDocumentation::CompatCommands:
 446       return this->PrintDocumentationCompatCommands(os);
 447
 448     case cmDocumentation::Copyright:
 449       return this->PrintCopyright(os);
 450     case cmDocumentation::Version:
 451       return true;
 452     default: return false;
 453     }
 454 }
 455
 456 //----------------------------------------------------------------------------
 457 bool cmDocumentation::CreateModulesSection()
 458 {
 459   cmDocumentationSection *sec =
 460     new cmDocumentationSection("Standard CMake Modules", "MODULES");
 461   this->AllSections["Modules"] = sec;
 462   std::string cmakeModules = this->CMakeRoot;
 463   cmakeModules += "/Modules";
 464   cmsys::Directory dir;
 465   dir.Load(cmakeModules.c_str());
 466   if (dir.GetNumberOfFiles() > 0)
 467     {
 468     sec->Append(cmDocumentationModulesHeader[0]);
 469     sec->Append(cmModulesDocumentationDescription);
 470     this->CreateModuleDocsForDir(dir, *this->AllSections["Modules"]);
 471     }
 472   return true;
 473 }
 474
 475 //----------------------------------------------------------------------------
 476 bool cmDocumentation::CreateCustomModulesSection()
 477 {
 478   bool sectionHasHeader = false;
 479
 480   std::vector<std::string> dirs;
 481   cmSystemTools::ExpandListArgument(this->CMakeModulePath, dirs);
 482
 483   for(std::vector<std::string>::const_iterator dirIt = dirs.begin();
 484       dirIt != dirs.end();
 485       ++dirIt)
 486     {
 487     cmsys::Directory dir;
 488     dir.Load(dirIt->c_str());
 489     if (dir.GetNumberOfFiles() > 0)
 490       {
 491       if (!sectionHasHeader)
 492         {
 493         cmDocumentationSection *sec =
 494           new cmDocumentationSection("Custom CMake Modules","CUSTOM MODULES");
 495         this->AllSections["Custom CMake Modules"] = sec;
 496         sec->Append(cmDocumentationCustomModulesHeader[0]);
 497         sec->Append(cmCustomModulesDocumentationDescription);
 498         sectionHasHeader = true;
 499         }
 500       this->CreateModuleDocsForDir
 501         (dir, *this->AllSections["Custom CMake Modules"]);
 502       }
 503     }
 504
 505   return true;
 506 }
 507
 508 //----------------------------------------------------------------------------
 509 void cmDocumentation
 510 ::CreateModuleDocsForDir(cmsys::Directory& dir,
 511                          cmDocumentationSection &moduleSection)
 512 {
 513   // sort the files alphabetically, so the docs for one module are easier
 514   // to find than if they are in random order
 515   std::vector<std::string> sortedFiles;
 516   for(unsigned int i = 0; i < dir.GetNumberOfFiles(); ++i)
 517   {
 518     sortedFiles.push_back(dir.GetFile(i));
 519   }
 520   std::sort(sortedFiles.begin(), sortedFiles.end());
 521
 522   for(std::vector<std::string>::const_iterator fname = sortedFiles.begin();
 523       fname!=sortedFiles.end(); ++fname)
 524     {
 525     if(fname->length() > 6)
 526       {
 527       if(fname->substr(fname->length()-6, 6) == ".cmake")
 528         {
 529         std::string moduleName = fname->substr(0, fname->length()-6);
 530         // this check is to avoid creating documentation for the modules with
 531         // the same name in multiple directories of CMAKE_MODULE_PATH
 532         if (this->ModulesFound.find(moduleName) == this->ModulesFound.end())
 533           {
 534           this->ModulesFound.insert(moduleName);
 535           std::string path = dir.GetPath();
 536           path += "/";
 537           path += (*fname);
 538           this->CreateSingleModule(path.c_str(), moduleName.c_str(),
 539                                    moduleSection);
 540           }
 541         }
 542       }
 543     }
 544 }
 545
 546 //----------------------------------------------------------------------------
 547 bool cmDocumentation::CreateSingleModule(const char* fname,
 548                                          const char* moduleName,
 549                                          cmDocumentationSection &moduleSection)
 550 {
 551   std::ifstream fin(fname);
 552   if(!fin)
 553     {
 554     std::cerr << "Internal error: can not open module." << fname << std::endl;
 555     return false;
 556     }
 557   std::string line;
 558   std::string text;
 559   std::string brief;
 560   brief = " ";
 561   bool newParagraph = true;
 562   while ( fin && cmSystemTools::GetLineFromStream(fin, line) )
 563     {
 564     if(line.size() && line[0] == '#')
 565       {
 566       // blank line
 567       if(line.size() <= 2)
 568         {
 569         text += "\n";
 570         newParagraph = true;
 571         }
 572       else if(line[2] == '-')
 573         {
 574         brief = line.c_str()+4;
 575         }
 576       else
 577         {
 578         // two spaces
 579         if(line[1] == ' ' && line[2] == ' ')
 580           {
 581           if(!newParagraph)
 582             {
 583             text += "\n";
 584             newParagraph = true;
 585             }
 586           // Skip #, and leave space for preformatted
 587           text += line.c_str()+1;
 588           text += "\n";
 589           }
 590         else if(line[1] == ' ')
 591           {
 592           if(!newParagraph)
 593             {
 594             text += " ";
 595             }
 596           newParagraph = false;
 597           // skip # and space
 598           text += line.c_str()+2;
 599           }
 600         else
 601           {
 602           if(!newParagraph)
 603             {
 604             text += " ";
 605             }
 606           newParagraph = false;
 607           // skip #
 608           text += line.c_str()+1;
 609           }
 610         }
 611       }
 612     else
 613       {
 614       if(text.length() < 2 && brief.length() == 1)
 615         {
 616         return false;
 617         }
 618       char* pname = strcpy(new char[strlen(moduleName)+1], moduleName);
 619       char* ptext = strcpy(new char[text.length()+1], text.c_str());
 620       this->ModuleStrings.push_back(pname);
 621       this->ModuleStrings.push_back(ptext);
 622       char* pbrief = strcpy(new char[brief.length()+1], brief.c_str());
 623       this->ModuleStrings.push_back(pbrief);
 624       moduleSection.Append(pname, pbrief, ptext);
 625       return true;
 626       }
 627     }
 628   return true;
 629 }
 630
 631
 632 //----------------------------------------------------------------------------
 633 bool cmDocumentation::PrintRequestedDocumentation(std::ostream& os)
 634 {
 635   bool result = true;
 636
 637   // Loop over requested documentation types.
 638   for(std::vector<RequestedHelpItem>::const_iterator
 639       i = this->RequestedHelpItems.begin();
 640       i != this->RequestedHelpItems.end();
 641       ++i)
 642     {
 643     this->SetForm(i->HelpForm);
 644     this->CurrentArgument = i->Argument;
 645     // If a file name was given, use it.  Otherwise, default to the
 646     // given stream.
 647     std::ofstream* fout = 0;
 648     std::ostream* s = &os;
 649     std::string docname("");
 650     if(i->Filename.length() > 0)
 651       {
 652       fout = new std::ofstream(i->Filename.c_str(), std::ios::out);
 653       if(fout)
 654         {
 655         s = fout;
 656         }
 657       else
 658         {
 659         result = false;
 660         }
 661       if(i->Filename != "-")
 662         {
 663         docname = cmSystemTools::GetFilenameWithoutLastExtension(i->Filename);
 664         }
 665       }
 666
 667     // Print this documentation type to the stream.
 668     if(!this->PrintDocumentation(i->HelpType, *s, docname.c_str()) || !*s)
 669       {
 670       result = false;
 671       }
 672
 673     // Close the file if we wrote one.
 674     if(fout)
 675       {
 676       delete fout;
 677       }
 678     }
 679   return result;
 680 }
 681
 682 #define GET_OPT_ARGUMENT(target)                      \
 683      if((i+1 < argc) && !this->IsOption(argv[i+1]))   \
 684         {                                             \
 685         target = argv[i+1];                           \
 686         i = i+1;                                      \
 687         };
 688
 689
 690 cmDocumentation::Form cmDocumentation::GetFormFromFilename(
 691                                                    const std::string& filename)
 692 {
 693   std::string ext = cmSystemTools::GetFilenameLastExtension(filename);
 694   ext = cmSystemTools::UpperCase(ext);
 695   if ((ext == ".HTM") || (ext == ".HTML"))
 696     {
 697     return cmDocumentation::HTMLForm;
 698     }
 699
 700   if (ext == ".DOCBOOK")
 701     {
 702     return cmDocumentation::DocbookForm;
 703     }
 704
 705   // ".1" to ".9" should be manpages
 706   if ((ext.length()==2) && (ext[1] >='1') && (ext[1]<='9'))
 707     {
 708     return cmDocumentation::ManForm;
 709     }
 710
 711   return cmDocumentation::TextForm;
 712 }
 713
 714 //----------------------------------------------------------------------------
 715 bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
 716                                    const char* exitOpt)
 717 {
 718   // Providing zero arguments gives usage information.
 719   if(argc == 1)
 720     {
 721     RequestedHelpItem help;
 722     help.HelpType = cmDocumentation::Usage;
 723     help.HelpForm = cmDocumentation::UsageForm;
 724     this->RequestedHelpItems.push_back(help);
 725     return true;
 726     }
 727
 728   // Search for supported help options.
 729
 730   bool result = false;
 731   for(int i=1; i < argc; ++i)
 732     {
 733     if(exitOpt && strcmp(argv[i], exitOpt) == 0)
 734       {
 735       return result;
 736       }
 737     RequestedHelpItem help;
 738     // Check if this is a supported help option.
 739     if((strcmp(argv[i], "-help") == 0) ||
 740        (strcmp(argv[i], "--help") == 0) ||
 741        (strcmp(argv[i], "/?") == 0) ||
 742        (strcmp(argv[i], "-usage") == 0) ||
 743        (strcmp(argv[i], "-h") == 0) ||
 744        (strcmp(argv[i], "-H") == 0))
 745       {
 746       help.HelpType = cmDocumentation::Usage;
 747       help.HelpForm = cmDocumentation::UsageForm;
 748       GET_OPT_ARGUMENT(help.Argument);
 749       help.Argument = cmSystemTools::LowerCase(help.Argument);
 750       // special case for single command
 751       if (!help.Argument.empty())
 752         {
 753         help.HelpType = cmDocumentation::Single;
 754         }
 755       }
 756     else if(strcmp(argv[i], "--help-properties") == 0)
 757       {
 758       help.HelpType = cmDocumentation::Properties;
 759       GET_OPT_ARGUMENT(help.Filename);
 760       help.HelpForm = this->GetFormFromFilename(help.Filename);
 761       }
 762     else if(strcmp(argv[i], "--help-policies") == 0)
 763       {
 764       help.HelpType = cmDocumentation::Policies;
 765       GET_OPT_ARGUMENT(help.Filename);
 766       help.HelpForm = this->GetFormFromFilename(help.Filename);
 767       }
 768     else if(strcmp(argv[i], "--help-variables") == 0)
 769       {
 770       help.HelpType = cmDocumentation::Variables;
 771       GET_OPT_ARGUMENT(help.Filename);
 772       help.HelpForm = this->GetFormFromFilename(help.Filename);
 773       }
 774     else if(strcmp(argv[i], "--help-modules") == 0)
 775       {
 776       help.HelpType = cmDocumentation::Modules;
 777       GET_OPT_ARGUMENT(help.Filename);
 778       help.HelpForm = this->GetFormFromFilename(help.Filename);
 779       }
 780     else if(strcmp(argv[i], "--help-custom-modules") == 0)
 781       {
 782       help.HelpType = cmDocumentation::CustomModules;
 783       GET_OPT_ARGUMENT(help.Filename);
 784       help.HelpForm = this->GetFormFromFilename(help.Filename);
 785       }
 786     else if(strcmp(argv[i], "--help-commands") == 0)
 787       {
 788       help.HelpType = cmDocumentation::Commands;
 789       GET_OPT_ARGUMENT(help.Filename);
 790       help.HelpForm = this->GetFormFromFilename(help.Filename);
 791       }
 792     else if(strcmp(argv[i], "--help-compatcommands") == 0)
 793       {
 794       help.HelpType = cmDocumentation::CompatCommands;
 795       GET_OPT_ARGUMENT(help.Filename);
 796       help.HelpForm = this->GetFormFromFilename(help.Filename);
 797       }
 798     else if(strcmp(argv[i], "--help-full") == 0)
 799       {
 800       help.HelpType = cmDocumentation::Full;
 801       GET_OPT_ARGUMENT(help.Filename);
 802       help.HelpForm = this->GetFormFromFilename(help.Filename);
 803       }
 804     else if(strcmp(argv[i], "--help-html") == 0)
 805       {
 806       help.HelpType = cmDocumentation::Full;
 807       GET_OPT_ARGUMENT(help.Filename);
 808       help.HelpForm = cmDocumentation::HTMLForm;
 809       }
 810     else if(strcmp(argv[i], "--help-man") == 0)
 811       {
 812       help.HelpType = cmDocumentation::Full;
 813       GET_OPT_ARGUMENT(help.Filename);
 814       help.HelpForm = cmDocumentation::ManForm;
 815       }
 816     else if(strcmp(argv[i], "--help-command") == 0)
 817       {
 818       help.HelpType = cmDocumentation::Single;
 819       GET_OPT_ARGUMENT(help.Argument);
 820       GET_OPT_ARGUMENT(help.Filename);
 821       help.Argument = cmSystemTools::LowerCase(help.Argument);
 822       help.HelpForm = this->GetFormFromFilename(help.Filename);
 823       }
 824     else if(strcmp(argv[i], "--help-module") == 0)
 825       {
 826       help.HelpType = cmDocumentation::SingleModule;
 827       GET_OPT_ARGUMENT(help.Argument);
 828       GET_OPT_ARGUMENT(help.Filename);
 829       help.HelpForm = this->GetFormFromFilename(help.Filename);
 830       }
 831     else if(strcmp(argv[i], "--help-property") == 0)
 832       {
 833       help.HelpType = cmDocumentation::SingleProperty;
 834       GET_OPT_ARGUMENT(help.Argument);
 835       GET_OPT_ARGUMENT(help.Filename);
 836       help.HelpForm = this->GetFormFromFilename(help.Filename);
 837       }
 838     else if(strcmp(argv[i], "--help-policy") == 0)
 839       {
 840       help.HelpType = cmDocumentation::SinglePolicy;
 841       GET_OPT_ARGUMENT(help.Argument);
 842       GET_OPT_ARGUMENT(help.Filename);
 843       help.HelpForm = this->GetFormFromFilename(help.Filename);
 844       }
 845     else if(strcmp(argv[i], "--help-variable") == 0)
 846       {
 847       help.HelpType = cmDocumentation::SingleVariable;
 848       GET_OPT_ARGUMENT(help.Argument);
 849       GET_OPT_ARGUMENT(help.Filename);
 850       help.HelpForm = this->GetFormFromFilename(help.Filename);
 851       }
 852     else if(strcmp(argv[i], "--help-command-list") == 0)
 853       {
 854       help.HelpType = cmDocumentation::List;
 855       GET_OPT_ARGUMENT(help.Filename);
 856       help.HelpForm = cmDocumentation::TextForm;
 857       }
 858     else if(strcmp(argv[i], "--help-module-list") == 0)
 859       {
 860       help.HelpType = cmDocumentation::ModuleList;
 861       GET_OPT_ARGUMENT(help.Filename);
 862       help.HelpForm = cmDocumentation::TextForm;
 863       }
 864     else if(strcmp(argv[i], "--help-property-list") == 0)
 865       {
 866       help.HelpType = cmDocumentation::PropertyList;
 867       GET_OPT_ARGUMENT(help.Filename);
 868       help.HelpForm = cmDocumentation::TextForm;
 869       }
 870     else if(strcmp(argv[i], "--help-variable-list") == 0)
 871       {
 872       help.HelpType = cmDocumentation::VariableList;
 873       GET_OPT_ARGUMENT(help.Filename);
 874       help.HelpForm = cmDocumentation::TextForm;
 875       }
 876     else if(strcmp(argv[i], "--copyright") == 0)
 877       {
 878       help.HelpType = cmDocumentation::Copyright;
 879       GET_OPT_ARGUMENT(help.Filename);
 880       help.HelpForm = cmDocumentation::UsageForm;
 881       }
 882     else if((strcmp(argv[i], "--version") == 0) ||
 883             (strcmp(argv[i], "-version") == 0) ||
 884             (strcmp(argv[i], "/V") == 0))
 885       {
 886       help.HelpType = cmDocumentation::Version;
 887       GET_OPT_ARGUMENT(help.Filename);
 888       help.HelpForm = cmDocumentation::UsageForm;
 889       }
 890     if(help.HelpType != None)
 891       {
 892       // This is a help option.  See if there is a file name given.
 893       result = true;
 894       this->RequestedHelpItems.push_back(help);
 895       }
 896     }
 897   return result;
 898 }
 899
 900 //----------------------------------------------------------------------------
 901 void cmDocumentation::Print(Form f, std::ostream& os)
 902 {
 903   this->SetForm(f);
 904   this->Print(os);
 905 }
 906
 907 //----------------------------------------------------------------------------
 908 void cmDocumentation::Print(std::ostream& os)
 909 {
 910   // if the formatter supports it, print a master index for
 911   // all sections
 912   this->CurrentFormatter->PrintIndex(os, this->PrintSections);
 913   for(unsigned int i=0; i < this->PrintSections.size(); ++i)
 914     {
 915     std::string name = this->PrintSections[i]->
 916       GetName((this->CurrentFormatter->GetForm()));
 917     this->CurrentFormatter->PrintSection(os,*this->PrintSections[i],
 918                                          name.c_str());
 919     }
 920 }
 921
 922 //----------------------------------------------------------------------------
 923 void cmDocumentation::SetName(const char* name)
 924 {
 925   this->NameString = name?name:"";
 926 }
 927
 928 //----------------------------------------------------------------------------
 929 void cmDocumentation::SetDocName(const char *docname)
 930 {
 931   this->DocName = docname?docname:"";
 932 }
 933
 934 //----------------------------------------------------------------------------
 935 void cmDocumentation::SetSection(const char *name,
 936                                  cmDocumentationSection *section)
 937 {
 938   if (this->AllSections.find(name) != this->AllSections.end())
 939     {
 940     delete this->AllSections[name];
 941     }
 942   this->AllSections[name] = section;
 943 }
 944
 945 //----------------------------------------------------------------------------
 946 void cmDocumentation::SetSection(const char *name,
 947                                  std::vector<cmDocumentationEntry> &docs)
 948 {
 949   cmDocumentationSection *sec =
 950     new cmDocumentationSection(name,
 951                                cmSystemTools::UpperCase(name).c_str());
 952   sec->Append(docs);
 953   this->SetSection(name,sec);
 954 }
 955
 956 //----------------------------------------------------------------------------
 957 void cmDocumentation::SetSection(const char *name,
 958                                  const char *docs[][3])
 959 {
 960   cmDocumentationSection *sec =
 961     new cmDocumentationSection(name,
 962                                cmSystemTools::UpperCase(name).c_str());
 963   sec->Append(docs);
 964   this->SetSection(name,sec);
 965 }
 966
 967 //----------------------------------------------------------------------------
 968 void cmDocumentation
 969 ::SetSections(std::map<std::string,cmDocumentationSection *> &sections)
 970 {
 971   for (std::map<std::string,cmDocumentationSection *>::const_iterator
 972          it = sections.begin(); it != sections.end(); ++it)
 973     {
 974     this->SetSection(it->first.c_str(),it->second);
 975     }
 976 }
 977
 978 //----------------------------------------------------------------------------
 979 void cmDocumentation::PrependSection(const char *name,
 980                                      const char *docs[][3])
 981 {
 982   cmDocumentationSection *sec = 0;
 983   if (this->AllSections.find(name) == this->AllSections.end())
 984     {
 985     sec = new cmDocumentationSection
 986       (name, cmSystemTools::UpperCase(name).c_str());
 987     this->SetSection(name,sec);
 988     }
 989   else
 990     {
 991     sec = this->AllSections[name];
 992     }
 993   sec->Prepend(docs);
 994 }
 995
 996 //----------------------------------------------------------------------------
 997 void cmDocumentation::PrependSection(const char *name,
 998                                      std::vector<cmDocumentationEntry> &docs)
 999 {
1000   cmDocumentationSection *sec = 0;
1001   if (this->AllSections.find(name) == this->AllSections.end())
1002     {
1003     sec = new cmDocumentationSection
1004       (name, cmSystemTools::UpperCase(name).c_str());
1005     this->SetSection(name,sec);
1006     }
1007   else
1008     {
1009     sec = this->AllSections[name];
1010     }
1011   sec->Prepend(docs);
1012 }
1013
1014 //----------------------------------------------------------------------------
1015 void cmDocumentation::AppendSection(const char *name,
1016                                     const char *docs[][3])
1017 {
1018   cmDocumentationSection *sec = 0;
1019   if (this->AllSections.find(name) == this->AllSections.end())
1020     {
1021     sec = new cmDocumentationSection
1022       (name, cmSystemTools::UpperCase(name).c_str());
1023     this->SetSection(name,sec);
1024     }
1025   else
1026     {
1027     sec = this->AllSections[name];
1028     }
1029   sec->Append(docs);
1030 }
1031
1032 //----------------------------------------------------------------------------
1033 void cmDocumentation::AppendSection(const char *name,
1034                                     std::vector<cmDocumentationEntry> &docs)
1035 {
1036   cmDocumentationSection *sec = 0;
1037   if (this->AllSections.find(name) == this->AllSections.end())
1038     {
1039     sec = new cmDocumentationSection
1040       (name, cmSystemTools::UpperCase(name).c_str());
1041     this->SetSection(name,sec);
1042     }
1043   else
1044     {
1045     sec = this->AllSections[name];
1046     }
1047   sec->Append(docs);
1048 }
1049
1050 //----------------------------------------------------------------------------
1051 void cmDocumentation::AppendSection(const char *name,
1052                                     cmDocumentationEntry &docs)
1053 {
1054
1055   std::vector<cmDocumentationEntry> docsVec;
1056   docsVec.push_back(docs);
1057   this->AppendSection(name,docsVec);
1058 }
1059
1060 //----------------------------------------------------------------------------
1061 void cmDocumentation::PrependSection(const char *name,
1062                                      cmDocumentationEntry &docs)
1063 {
1064
1065   std::vector<cmDocumentationEntry> docsVec;
1066   docsVec.push_back(docs);
1067   this->PrependSection(name,docsVec);
1068 }
1069
1070 //----------------------------------------------------------------------------
1071 void cmDocumentation::SetSeeAlsoList(const char *data[][3])
1072 {
1073   cmDocumentationSection *sec =
1074     new cmDocumentationSection("See Also", "SEE ALSO");
1075   this->AllSections["See Also"] = sec;
1076   this->SeeAlsoString = ".B ";
1077   int i = 0;
1078   while(data[i][1])
1079     {
1080     this->SeeAlsoString += data[i][1];
1081     this->SeeAlsoString += data[i+1][1]? "(1), ":"(1)";
1082     ++i;
1083     }
1084   sec->Append(0,this->SeeAlsoString.c_str(),0);
1085   sec->Append(cmDocumentationStandardSeeAlso);
1086 }
1087
1088 //----------------------------------------------------------------------------
1089 bool cmDocumentation::PrintDocumentationGeneric(std::ostream& os,
1090                                                 const char *section)
1091 {
1092   if(this->AllSections.find(section) == this->AllSections.end())
1093     {
1094     os << "Internal error: " << section << " list is empty." << std::endl;
1095     return false;
1096     }
1097   if(this->CurrentArgument.length() == 0)
1098     {
1099     os << "Required argument missing.\n";
1100     return false;
1101     }
1102   const std::vector<cmDocumentationEntry> &entries =
1103     this->AllSections[section]->GetEntries();
1104   for(std::vector<cmDocumentationEntry>::const_iterator ei =
1105         entries.begin();
1106       ei != entries.end(); ++ei)
1107     {
1108     if(this->CurrentArgument == ei->Name)
1109       {
1110       this->PrintDocumentationCommand(os, *ei);
1111       return true;
1112       }
1113     }
1114   return false;
1115 }
1116
1117 //----------------------------------------------------------------------------
1118 bool cmDocumentation::PrintDocumentationSingle(std::ostream& os)
1119 {
1120   if (this->PrintDocumentationGeneric(os,"Commands"))
1121     {
1122     return true;
1123     }
1124   if (this->PrintDocumentationGeneric(os,"Compatibility Commands"))
1125     {
1126     return true;
1127     }
1128
1129   // Argument was not a command.  Complain.
1130   os << "Argument \"" << this->CurrentArgument.c_str()
1131      << "\" to --help-command is not a CMake command.  "
1132      << "Use --help-command-list to see all commands.\n";
1133   return false;
1134 }
1135
1136 //----------------------------------------------------------------------------
1137 bool cmDocumentation::PrintDocumentationSingleModule(std::ostream& os)
1138 {
1139   if(this->CurrentArgument.length() == 0)
1140     {
1141     os << "Argument --help-module needs a module name.\n";
1142     return false;
1143     }
1144
1145   std::string moduleName;
1146   // find the module
1147   std::vector<std::string> dirs;
1148   cmSystemTools::ExpandListArgument(this->CMakeModulePath, dirs);
1149   for(std::vector<std::string>::const_iterator dirIt = dirs.begin();
1150       dirIt != dirs.end();
1151       ++dirIt)
1152     {
1153     moduleName = *dirIt;
1154     moduleName += "/";
1155     moduleName += this->CurrentArgument;
1156     moduleName += ".cmake";
1157     if(cmSystemTools::FileExists(moduleName.c_str()))
1158       {
1159       break;
1160       }
1161     moduleName = "";
1162     }
1163
1164   if (moduleName.empty())
1165     {
1166     moduleName = this->CMakeRoot;
1167     moduleName += "/Modules/";
1168     moduleName += this->CurrentArgument;
1169     moduleName += ".cmake";
1170     if(!cmSystemTools::FileExists(moduleName.c_str()))
1171       {
1172       moduleName = "";
1173       }
1174     }
1175
1176   if(!moduleName.empty())
1177     {
1178     cmDocumentationSection *sec =
1179       new cmDocumentationSection("Standard CMake Modules", "MODULES");
1180     this->AllSections["Modules"] = sec;
1181     if (this->CreateSingleModule(moduleName.c_str(),
1182                                  this->CurrentArgument.c_str(),
1183                                  *this->AllSections["Modules"]))
1184       {
1185       this->PrintDocumentationCommand
1186         (os,  this->AllSections["Modules"]->GetEntries()[0]);
1187       os <<  "\n       Defined in: ";
1188       os << moduleName << "\n";
1189       return true;
1190       }
1191     }
1192
1193   // Argument was not a module.  Complain.
1194   os << "Argument \"" << this->CurrentArgument.c_str()
1195      << "\" to --help-module is not a CMake module.\n";
1196   return false;
1197 }
1198
1199 //----------------------------------------------------------------------------
1200 bool cmDocumentation::PrintDocumentationSingleProperty(std::ostream& os)
1201 {
1202   bool done = false;
1203   for (std::vector<std::string>::iterator i =
1204          this->PropertySections.begin();
1205        !done && i != this->PropertySections.end(); ++i)
1206     {
1207     done = this->PrintDocumentationGeneric(os,i->c_str());
1208     }
1209
1210   if (done)
1211     {
1212     return true;
1213     }
1214
1215   // Argument was not a command.  Complain.
1216   os << "Argument \"" << this->CurrentArgument.c_str()
1217      << "\" to --help-property is not a CMake property.  "
1218      << "Use --help-property-list to see all properties.\n";
1219   return false;
1220 }
1221
1222 //----------------------------------------------------------------------------
1223 bool cmDocumentation::PrintDocumentationSinglePolicy(std::ostream& os)
1224 {
1225   if (this->PrintDocumentationGeneric(os,"Policies"))
1226     {
1227     return true;
1228     }
1229
1230   // Argument was not a command.  Complain.
1231   os << "Argument \"" << this->CurrentArgument.c_str()
1232      << "\" to --help-policy is not a CMake policy.\n";
1233   return false;
1234 }
1235
1236 //----------------------------------------------------------------------------
1237 bool cmDocumentation::PrintDocumentationSingleVariable(std::ostream& os)
1238 {
1239   bool done = false;
1240   for (std::vector<std::string>::iterator i =
1241          this->VariableSections.begin();
1242        !done && i != this->VariableSections.end(); ++i)
1243     {
1244     done = this->PrintDocumentationGeneric(os,i->c_str());
1245     }
1246
1247   if (done)
1248     {
1249     return true;
1250     }
1251
1252   // Argument was not a command.  Complain.
1253   os << "Argument \"" << this->CurrentArgument.c_str()
1254      << "\" to --help-variable is not a defined variable.  "
1255      << "Use --help-variable-list to see all defined variables.\n";
1256   return false;
1257 }
1258
1259 //----------------------------------------------------------------------------
1260 bool cmDocumentation::PrintDocumentationList(std::ostream& os,
1261                                              const char *section)
1262 {
1263   if(this->AllSections.find(section) == this->AllSections.end())
1264     {
1265     os << "Internal error: " << section << " list is empty." << std::endl;
1266     return false;
1267     }
1268
1269   const std::vector<cmDocumentationEntry> &entries =
1270     this->AllSections[section]->GetEntries();
1271   for(std::vector<cmDocumentationEntry>::const_iterator ei =
1272         entries.begin();
1273       ei != entries.end(); ++ei)
1274     {
1275     if(ei->Name.size())
1276       {
1277       os << ei->Name << std::endl;
1278       }
1279     }
1280   return true;
1281 }
1282
1283 //----------------------------------------------------------------------------
1284 bool cmDocumentation::PrintDocumentationUsage(std::ostream& os)
1285 {
1286   this->ClearSections();
1287   this->AddSectionToPrint("Usage");
1288   this->AddSectionToPrint("Options");
1289   this->AddSectionToPrint("Generators");
1290   this->Print(os);
1291   return true;
1292 }
1293
1294 //----------------------------------------------------------------------------
1295 bool cmDocumentation::PrintDocumentationFull(std::ostream& os)
1296 {
1297   this->CreateFullDocumentation();
1298   this->CurrentFormatter->PrintHeader(GetNameString(), GetNameString(), os);
1299   this->Print(os);
1300   this->CurrentFormatter->PrintFooter(os);
1301   return true;
1302 }
1303
1304 //----------------------------------------------------------------------------
1305 bool cmDocumentation::PrintDocumentationModules(std::ostream& os)
1306 {
1307   this->ClearSections();
1308   this->CreateModulesSection();
1309   this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(Modules));
1310   this->AddSectionToPrint("Description");
1311   this->AddSectionToPrint("Modules");
1312   this->AddSectionToPrint("Copyright");
1313   this->AddSectionToPrint("See Also");
1314   this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
1315   this->Print(os);
1316   this->CurrentFormatter->PrintFooter(os);
1317   return true;
1318 }
1319
1320 //----------------------------------------------------------------------------
1321 bool cmDocumentation::PrintDocumentationCustomModules(std::ostream& os)
1322 {
1323   this->ClearSections();
1324   this->CreateCustomModulesSection();
1325   this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(CustomModules));
1326   this->AddSectionToPrint("Description");
1327   this->AddSectionToPrint("Custom CMake Modules");
1328 // the custom modules are most probably not under Kitware's copyright, Alex
1329 //  this->AddSectionToPrint("Copyright");
1330   this->AddSectionToPrint("See Also");
1331
1332   this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
1333   this->Print(os);
1334   this->CurrentFormatter->PrintFooter(os);
1335   return true;
1336 }
1337
1338 //----------------------------------------------------------------------------
1339 bool cmDocumentation::PrintDocumentationPolicies(std::ostream& os)
1340 {
1341   this->ClearSections();
1342   this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(Policies));
1343   this->AddSectionToPrint("Description");
1344   this->AddSectionToPrint("Policies");
1345   this->AddSectionToPrint("Copyright");
1346   this->AddSectionToPrint("See Also");
1347
1348   this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
1349   this->Print(os);
1350   this->CurrentFormatter->PrintFooter(os);
1351   return true;
1352 }
1353
1354 //----------------------------------------------------------------------------
1355 bool cmDocumentation::PrintDocumentationProperties(std::ostream& os)
1356 {
1357   this->ClearSections();
1358   this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(Properties));
1359   this->AddSectionToPrint("Properties Description");
1360   for (std::vector<std::string>::iterator i =
1361          this->PropertySections.begin();
1362        i != this->PropertySections.end(); ++i)
1363     {
1364     this->AddSectionToPrint(i->c_str());
1365     }
1366   this->AddSectionToPrint("Copyright");
1367   this->AddSectionToPrint("Standard See Also");
1368   this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
1369   this->Print(os);
1370   this->CurrentFormatter->PrintFooter(os);
1371   return true;
1372 }
1373
1374 //----------------------------------------------------------------------------
1375 bool cmDocumentation::PrintDocumentationVariables(std::ostream& os)
1376 {
1377   this->ClearSections();
1378   this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(Variables));
1379   for (std::vector<std::string>::iterator i =
1380          this->VariableSections.begin();
1381        i != this->VariableSections.end(); ++i)
1382     {
1383     this->AddSectionToPrint(i->c_str());
1384     }
1385   this->AddSectionToPrint("Copyright");
1386   this->AddSectionToPrint("Standard See Also");
1387   this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
1388   this->Print(os);
1389   this->CurrentFormatter->PrintFooter(os);
1390   return true;
1391 }
1392
1393 //----------------------------------------------------------------------------
1394 bool cmDocumentation::PrintDocumentationCurrentCommands(std::ostream& os)
1395 {
1396   this->ClearSections();
1397   this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(Commands));
1398   this->AddSectionToPrint("Commands");
1399   this->AddSectionToPrint("Copyright");
1400   this->AddSectionToPrint("Standard See Also");
1401   this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
1402   this->Print(os);
1403   this->CurrentFormatter->PrintFooter(os);
1404   return true;
1405 }
1406
1407 //----------------------------------------------------------------------------
1408 bool cmDocumentation::PrintDocumentationCompatCommands(std::ostream& os)
1409 {
1410   this->ClearSections();
1411   this->AddDocumentIntroToPrint(GET_DOCUMENT_INTRO(CompatCommands));
1412   this->AddSectionToPrint("Compatibility Commands Description");
1413   this->AddSectionToPrint("Compatibility Commands");
1414   this->AddSectionToPrint("Copyright");
1415   this->AddSectionToPrint("Standard See Also");
1416   this->CurrentFormatter->PrintHeader(GetDocName(), GetNameString(), os);
1417   this->Print(os);
1418   this->CurrentFormatter->PrintFooter(os);
1419   return true;
1420 }
1421
1422 //----------------------------------------------------------------------------
1423 void cmDocumentation
1424 ::PrintDocumentationCommand(std::ostream& os,
1425                             const cmDocumentationEntry &entry)
1426 {
1427   // the string "SingleItem" will be used in a few places to detect the case
1428   // that only the documentation for a single item is printed
1429   cmDocumentationSection *sec = new cmDocumentationSection("SingleItem","");
1430   sec->Append(entry);
1431   this->AllSections["temp"] = sec;
1432   this->ClearSections();
1433   this->AddSectionToPrint("temp");
1434   this->Print(os);
1435   this->AllSections.erase("temp");
1436   delete sec;
1437 }
1438
1439 //----------------------------------------------------------------------------
1440 void cmDocumentation::CreateFullDocumentation()
1441 {
1442   this->ClearSections();
1443   this->CreateCustomModulesSection();
1444   this->CreateModulesSection();
1445
1446   std::set<std::string> emitted;
1447   this->AddSectionToPrint("Name");
1448   emitted.insert("Name");
1449   this->AddSectionToPrint("Usage");
1450   emitted.insert("Usage");
1451   this->AddSectionToPrint("Description");
1452   emitted.insert("Description");
1453   this->AddSectionToPrint("Options");
1454   emitted.insert("Options");
1455   this->AddSectionToPrint("Generators");
1456   emitted.insert("Generators");
1457   this->AddSectionToPrint("Commands");
1458   emitted.insert("Commands");
1459
1460
1461   this->AddSectionToPrint("Properties Description");
1462   emitted.insert("Properties Description");
1463   for (std::vector<std::string>::iterator i =
1464          this->PropertySections.begin();
1465        i != this->PropertySections.end(); ++i)
1466     {
1467     this->AddSectionToPrint(i->c_str());
1468     emitted.insert(i->c_str());
1469     }
1470
1471   emitted.insert("Copyright");
1472   emitted.insert("See Also");
1473   emitted.insert("Standard See Also");
1474   emitted.insert("Author");
1475
1476   // add any sections not yet written out, or to be written out
1477   for (std::map<std::string, cmDocumentationSection*>::iterator i =
1478          this->AllSections.begin();
1479        i != this->AllSections.end(); ++i)
1480     {
1481     if (emitted.find(i->first) == emitted.end())
1482       {
1483       this->AddSectionToPrint(i->first.c_str());
1484       }
1485     }
1486
1487   this->AddSectionToPrint("Copyright");
1488
1489   if(this->CurrentFormatter->GetForm() == ManForm)
1490     {
1491     this->AddSectionToPrint("See Also");
1492     this->AddSectionToPrint("Author");
1493     }
1494   else
1495     {
1496     this->AddSectionToPrint("Standard See Also");
1497     }
1498 }
1499
1500 //----------------------------------------------------------------------------
1501 void cmDocumentation::SetForm(Form f)
1502 {
1503   switch(f)
1504   {
1505     case HTMLForm:
1506       this->CurrentFormatter = &this->HTMLFormatter;
1507       break;
1508     case DocbookForm:
1509       this->CurrentFormatter = &this->DocbookFormatter;
1510       break;
1511     case ManForm:
1512       this->CurrentFormatter = &this->ManFormatter;
1513       break;
1514     case TextForm:
1515       this->CurrentFormatter = &this->TextFormatter;
1516       break;
1517     case UsageForm:
1518       this->CurrentFormatter = & this->UsageFormatter;
1519       break;
1520   }
1521 }
1522
1523
1524 //----------------------------------------------------------------------------
1525 const char* cmDocumentation::GetNameString() const
1526 {
1527   if(this->NameString.length() > 0)
1528     {
1529     return this->NameString.c_str();
1530     }
1531   else
1532     {
1533     return "CMake";
1534     }
1535 }
1536
1537 //----------------------------------------------------------------------------
1538 const char* cmDocumentation::GetDocName(bool fallbackToNameString) const
1539 {
1540   if (this->DocName.length() > 0)
1541     {
1542     return this->DocName.c_str();
1543     }
1544   else if (fallbackToNameString)
1545     {
1546     return this->GetNameString();
1547     }
1548   else
1549     return 0;
1550 }
1551
1552 //----------------------------------------------------------------------------
1553 #define CASE_DEFAULT_DOCNAME(doctype) \
1554   case cmDocumentation::doctype : \
1555     return GET_DOCUMENT_INTRO(doctype)[0];
1556 const char* cmDocumentation::GetDefaultDocName(Type ht) const
1557 {
1558   switch (ht)
1559     {
1560     CASE_DEFAULT_DOCNAME(Modules)
1561     CASE_DEFAULT_DOCNAME(CustomModules)
1562     CASE_DEFAULT_DOCNAME(Policies)
1563     CASE_DEFAULT_DOCNAME(Properties)
1564     CASE_DEFAULT_DOCNAME(Variables)
1565     CASE_DEFAULT_DOCNAME(Commands)
1566     CASE_DEFAULT_DOCNAME(CompatCommands)
1567     default: break;
1568     }
1569   return 0;
1570 }
1571
1572 //----------------------------------------------------------------------------
1573 bool cmDocumentation::IsOption(const char* arg) const
1574 {
1575   return ((arg[0] == '-') || (strcmp(arg, "/V") == 0) ||
1576           (strcmp(arg, "/?") == 0));
1577 }