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-10-10 15:23:35 $
   7   Version:   $Revision: 1.35 $
   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.  exitOpt can be used for things like cmake -E, so that
  49    * all arguments after the -E are ignored and not searched for
  50    * help arguments.
  51    */
  52   bool CheckOptions(int argc, const char* const* argv,
  53                     const char* exitOpt =0);
  54
  55   /**
  56    * Print help requested on the command line.  Call after
  57    * CheckOptions returns true.  Returns true on success, and false
  58    * otherwise.  Failure can occur when output files specified on the
  59    * command line cannot be written.
  60    */
  61   bool PrintRequestedDocumentation(std::ostream& os);
  62
  63   /** Print help of the given type.  */
  64   bool PrintDocumentation(Type ht, std::ostream& os, const char* docname=0);
  65
  66   /** Set the program name for standard document generation.  */
  67   void SetName(const char* name);
  68
  69   /** Set a section of the documentation. Typical sections include Name,
  70       Usage, Description, Options, SeeAlso */
  71   void SetSection(const char *sectionName,
  72                   cmDocumentationSection *section);
  73   void SetSection(const char *sectionName,
  74                   std::vector<cmDocumentationEntry> &docs);
  75   void SetSection(const char *sectionName,
  76                   const char *docs[][3]);
  77   void SetSections(std::map<std::string,cmDocumentationSection *>
  78                    &sections);
  79
  80   /** Add the documentation to the beginning/end of the section */
  81   void PrependSection(const char *sectionName,
  82                       const char *docs[][3]);
  83   void PrependSection(const char *sectionName,
  84                       std::vector<cmDocumentationEntry> &docs);
  85   void PrependSection(const char *sectionName,
  86                       cmDocumentationEntry &docs);
  87   void AppendSection(const char *sectionName,
  88                      const char *docs[][3]);
  89   void AppendSection(const char *sectionName,
  90                      std::vector<cmDocumentationEntry> &docs);
  91   void AppendSection(const char *sectionName,
  92                      cmDocumentationEntry &docs);
  93
  94   /**
  95    * Print documentation in the given form.  All previously added
  96    * sections will be generated.
  97    */
  98   void Print(Form f, std::ostream& os);
  99
 100   /**
 101    * Print documentation in the current form.  All previously added
 102    * sections will be generated.
 103    */
 104   void Print(std::ostream& os);
 105
 106   /**
 107    * Add a section of documentation. This can be used to generate custom help
 108    * documents.
 109    */
 110   void AddSectionToPrint(const char *section);
 111
 112   void SetSeeAlsoList(const char *data[][3]);
 113
 114   /** Clear all previously added sections of help.  */
 115   void ClearSections();
 116
 117   /** Set cmake root so we can find installed files */
 118   void SetCMakeRoot(const char* root)  { this->CMakeRoot = root;}
 119
 120   /** Set CMAKE_MODULE_PATH so we can find additional cmake modules */
 121   void SetCMakeModulePath(const char* path)  { this->CMakeModulePath = path;}
 122
 123   static Form GetFormFromFilename(const std::string& filename);
 124
 125 private:
 126   void SetForm(Form f);
 127   void SetDocName(const char* docname);
 128
 129   bool CreateSingleModule(const char* fname,
 130                           const char* moduleName,
 131                           cmDocumentationSection &sec);
 132   void CreateModuleDocsForDir(cmsys::Directory& dir,
 133                               cmDocumentationSection &moduleSection);
 134   bool CreateModulesSection();
 135   bool CreateCustomModulesSection();
 136   void CreateFullDocumentation();
 137
 138   void AddDocumentIntroToPrint(const char* intro[2]);
 139
 140   bool PrintCopyright(std::ostream& os);
 141   bool PrintVersion(std::ostream& os);
 142   bool PrintDocumentationGeneric(std::ostream& os, const char *section);
 143   bool PrintDocumentationList(std::ostream& os, const char *section);
 144   bool PrintDocumentationSingle(std::ostream& os);
 145   bool PrintDocumentationSingleModule(std::ostream& os);
 146   bool PrintDocumentationSingleProperty(std::ostream& os);
 147   bool PrintDocumentationSinglePolicy(std::ostream& os);
 148   bool PrintDocumentationSingleVariable(std::ostream& os);
 149   bool PrintDocumentationUsage(std::ostream& os);
 150   bool PrintDocumentationFull(std::ostream& os);
 151   bool PrintDocumentationModules(std::ostream& os);
 152   bool PrintDocumentationCustomModules(std::ostream& os);
 153   bool PrintDocumentationPolicies(std::ostream& os);
 154   bool PrintDocumentationProperties(std::ostream& os);
 155   bool PrintDocumentationVariables(std::ostream& os);
 156   bool PrintDocumentationCurrentCommands(std::ostream& os);
 157   bool PrintDocumentationCompatCommands(std::ostream& os);
 158   void PrintDocumentationCommand(std::ostream& os,
 159                                  const cmDocumentationEntry &entry);
 160
 161
 162   const char* GetNameString() const;
 163   const char* GetDocName(bool fallbackToNameString = true) const;
 164   const char* GetDefaultDocName(Type ht) const;
 165   bool IsOption(const char* arg) const;
 166
 167   std::string NameString;
 168   std::string DocName;
 169   std::map<std::string,cmDocumentationSection*> AllSections;
 170
 171   std::string SeeAlsoString;
 172   std::string CMakeRoot;
 173   std::string CMakeModulePath;
 174   std::set<std::string> ModulesFound;
 175   std::vector< char* > ModuleStrings;
 176   std::vector<const cmDocumentationSection *> PrintSections;
 177   std::string CurrentArgument;
 178
 179   struct RequestedHelpItem
 180   {
 181     RequestedHelpItem():HelpForm(TextForm), HelpType(None) {}
 182     cmDocumentationEnums::Form HelpForm;
 183     cmDocumentationEnums::Type HelpType;
 184     std::string Filename;
 185     std::string Argument;
 186   };
 187
 188   std::vector<RequestedHelpItem> RequestedHelpItems;
 189   cmDocumentationFormatter* CurrentFormatter;
 190   cmDocumentationFormatterHTML HTMLFormatter;
 191   cmDocumentationFormatterDocbook DocbookFormatter;
 192   cmDocumentationFormatterMan ManFormatter;
 193   cmDocumentationFormatterText TextFormatter;
 194   cmDocumentationFormatterUsage UsageFormatter;
 195
 196   std::vector<std::string> PropertySections;
 197   std::vector<std::string> VariableSections;
 198 };
 199
 200 #endif