CMakeLua/Source/cmDocumentation.h

   1 /*=========================================================================
   2
   3   Program:   CMake - Cross-Platform Makefile Generator
   4   Module:    $RCSfile: cmDocumentation.h,v $
   5   Language:  C++
   6   Date:      $Date: 2008-03-04 14:16:33 $
   7   Version:   $Revision: 1.33 $
   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 #ifndef _cmDocumentation_h
  18 #define _cmDocumentation_h
  19
  20 #include "cmStandardIncludes.h"
  21 #include "cmProperty.h"
  22 #include "cmDocumentationFormatter.h"
  23 #include "cmDocumentationFormatterHTML.h"
  24 #include "cmDocumentationFormatterDocbook.h"
  25 #include "cmDocumentationFormatterMan.h"
  26 #include "cmDocumentationFormatterText.h"
  27 #include "cmDocumentationFormatterUsage.h"
  28 #include "cmDocumentationSection.h"
  29
  30 namespace cmsys
  31 {
  32   class Directory;
  33 }
  34
  35 /** Class to generate documentation.  */
  36 class cmDocumentation: public cmDocumentationEnums
  37 {
  38 public:
  39   cmDocumentation();
  40
  41   ~cmDocumentation();
  42   // High-level interface for standard documents:
  43
  44   /**
  45    * Check command line arguments for documentation options.  Returns
  46    * true if documentation options are found, and false otherwise.
  47    * When true is returned, PrintRequestedDocumentation should be
  48    * called.
  49    */
  50   bool CheckOptions(int argc, const char* const* argv);
  51
  52   /**
  53    * Print help requested on the command line.  Call after
  54    * CheckOptions returns true.  Returns true on success, and false
  55    * otherwise.  Failure can occur when output files specified on the
  56    * command line cannot be written.
  57    */
  58   bool PrintRequestedDocumentation(std::ostream& os);
  59
  60   /** Print help of the given type.  */
  61   bool PrintDocumentation(Type ht, std::ostream& os);
  62
  63   /** Set the program name for standard document generation.  */
  64   void SetName(const char* name);
  65
  66   /** Set a section of the documentation. Typical sections include Name,
  67       Usage, Description, Options, SeeAlso */
  68   void SetSection(const char *sectionName,
  69                   cmDocumentationSection *section);
  70   void SetSection(const char *sectionName,
  71                   std::vector<cmDocumentationEntry> &docs);
  72   void SetSection(const char *sectionName,
  73                   const char *docs[][3]);
  74   void SetSections(std::map<std::string,cmDocumentationSection *>
  75                    &sections);
  76
  77   /** Add the documentation to the beginning/end of the section */
  78   void PrependSection(const char *sectionName,
  79                       const char *docs[][3]);
  80   void PrependSection(const char *sectionName,
  81                       std::vector<cmDocumentationEntry> &docs);
  82   void PrependSection(const char *sectionName,
  83                       cmDocumentationEntry &docs);
  84   void AppendSection(const char *sectionName,
  85                      const char *docs[][3]);
  86   void AppendSection(const char *sectionName,
  87                      std::vector<cmDocumentationEntry> &docs);
  88   void AppendSection(const char *sectionName,
  89                      cmDocumentationEntry &docs);
  90
  91   /**
  92    * Print documentation in the given form.  All previously added
  93    * sections will be generated.
  94    */
  95   void Print(Form f, std::ostream& os);
  96
  97   /**
  98    * Print documentation in the current form.  All previously added
  99    * sections will be generated.
 100    */
 101   void Print(std::ostream& os);
 102
 103   /**
 104    * Add a section of documentation. This can be used to generate custom help
 105    * documents.
 106    */
 107   void AddSectionToPrint(const char *section);
 108
 109   void SetSeeAlsoList(const char *data[][3]);
 110
 111   /** Clear all previously added sections of help.  */
 112   void ClearSections();
 113
 114   /** Set cmake root so we can find installed files */
 115   void SetCMakeRoot(const char* root)  { this->CMakeRoot = root;}
 116
 117   /** Set CMAKE_MODULE_PATH so we can find additional cmake modules */
 118   void SetCMakeModulePath(const char* path)  { this->CMakeModulePath = path;}
 119
 120   static Form GetFormFromFilename(const std::string& filename);
 121
 122 private:
 123   void SetForm(Form f);
 124
 125   bool CreateSingleModule(const char* fname,
 126                           const char* moduleName,
 127                           cmDocumentationSection &sec);
 128   void CreateModuleDocsForDir(cmsys::Directory& dir,
 129                               cmDocumentationSection &moduleSection);
 130   bool CreateModulesSection();
 131   bool CreateCustomModulesSection();
 132   void CreateFullDocumentation();
 133
 134   bool PrintCopyright(std::ostream& os);
 135   bool PrintVersion(std::ostream& os);
 136   bool PrintDocumentationGeneric(std::ostream& os, const char *section);
 137   bool PrintDocumentationList(std::ostream& os, const char *section);
 138   bool PrintDocumentationSingle(std::ostream& os);
 139   bool PrintDocumentationSingleModule(std::ostream& os);
 140   bool PrintDocumentationSingleProperty(std::ostream& os);
 141   bool PrintDocumentationSinglePolicy(std::ostream& os);
 142   bool PrintDocumentationSingleVariable(std::ostream& os);
 143   bool PrintDocumentationUsage(std::ostream& os);
 144   bool PrintDocumentationFull(std::ostream& os);
 145   bool PrintDocumentationModules(std::ostream& os);
 146   bool PrintDocumentationCustomModules(std::ostream& os);
 147   bool PrintDocumentationPolicies(std::ostream& os);
 148   bool PrintDocumentationProperties(std::ostream& os);
 149   bool PrintDocumentationVariables(std::ostream& os);
 150   bool PrintDocumentationCurrentCommands(std::ostream& os);
 151   bool PrintDocumentationCompatCommands(std::ostream& os);
 152   void PrintDocumentationCommand(std::ostream& os,
 153                                  const cmDocumentationEntry &entry);
 154
 155
 156   const char* GetNameString() const;
 157   bool IsOption(const char* arg) const;
 158
 159   std::string NameString;
 160   std::map<std::string,cmDocumentationSection*> AllSections;
 161
 162   std::string SeeAlsoString;
 163   std::string CMakeRoot;
 164   std::string CMakeModulePath;
 165   std::set<std::string> ModulesFound;
 166   std::vector< char* > ModuleStrings;
 167   std::vector<const cmDocumentationSection *> PrintSections;
 168   std::string CurrentArgument;
 169
 170   struct RequestedHelpItem
 171   {
 172     RequestedHelpItem():HelpForm(TextForm), HelpType(None) {}
 173     cmDocumentationEnums::Form HelpForm;
 174     cmDocumentationEnums::Type HelpType;
 175     std::string Filename;
 176     std::string Argument;
 177   };
 178
 179   std::vector<RequestedHelpItem> RequestedHelpItems;
 180   cmDocumentationFormatter* CurrentFormatter;
 181   cmDocumentationFormatterHTML HTMLFormatter;
 182   cmDocumentationFormatterDocbook DocbookFormatter;
 183   cmDocumentationFormatterMan ManFormatter;
 184   cmDocumentationFormatterText TextFormatter;
 185   cmDocumentationFormatterUsage UsageFormatter;
 186
 187   std::vector<std::string> PropertySections;
 188   std::vector<std::string> VariableSections;
 189 };
 190
 191 #endif