ENH: Re-implemented document generation class to be more organized and more robust.

Source/CursesDialog/ccmake.cxx

@@ -30,8 +30,8 @@
 //----------------------------------------------------------------------------
 static const cmDocumentationEntry cmDocumentationName[] =
 {
-  {"ccmake",
+  {0,
-   "- Curses Interface for CMake.", 0},
+   "  ccmake - Curses Interface for CMake.", 0},
   {0,0,0}
 };
 
@@ -39,7 +39,7 @@ static const cmDocumentationEntry cmDocumentationName[] =
 static const cmDocumentationEntry cmDocumentationUsage[] =
 {
   {0,
-   "ccmake <path-to-source>", 0},
+   "  ccmake <path-to-source>", 0},
   {0,0,0}
 };
 
@@ -88,10 +88,15 @@ int main(int argc, char** argv)
   cmDocumentation doc;
   if(cmDocumentation::Type ht = doc.CheckOptions(argc, argv))
     {
-    doc.SetName(cmDocumentationName);
+    cmake hcm;
-    doc.SetUsage(cmDocumentationUsage);
+    std::vector<cmDocumentationEntry> commands;
-    doc.SetDescription(cmDocumentationDescription);
+    hcm.GetCommandDocumentation(commands);
-    doc.Print(ht, std::cout);
+    doc.SetNameSection(cmDocumentationName);
+    doc.SetUsageSection(cmDocumentationUsage);
+    doc.SetDescriptionSection(cmDocumentationDescription);
+    doc.SetOptionsSection(0);
+    doc.SetCommandsSection(&commands[0]);
+    doc.PrintDocumentation(ht, std::cout);
     return 0;
     }  
   

Source/cmDocumentation.h

@@ -25,45 +25,111 @@ class cmDocumentation
 public:
   cmDocumentation();
   
-  enum Type { None, Usage, Help, HelpHTML, Man, Copyright, Version };
+  // High-level interface for standard documents:
+  
+  /** Types of help provided.  */
+  enum Type { None, Usage, Full, HTML, Man, Copyright, Version };
+  
+  /**
+   * Check command line arguments for documentation options.  Returns
+   * the type of help to be provided.  If non-zero, the result should
+   * be passed to PrintDocumentation to produce the desired
+   * documentation.
+   */
+  Type CheckOptions(int argc, char** argv);
+  
+  /** Print help of the given type.  */
+  void PrintDocumentation(Type ht, std::ostream& os);
+  
+  /** Set the program name for standard document generation.  */
+  void SetNameSection(const cmDocumentationEntry*);
+
+  /** Set the program usage for standard document generation.  */
+  void SetUsageSection(const cmDocumentationEntry*);
+
+  /** Set the program description for standard document generation.  */
+  void SetDescriptionSection(const cmDocumentationEntry*);
+
+  /** Set the program options for standard document generation.  */
+  void SetOptionsSection(const cmDocumentationEntry*);
+  
+  /** Set the listfile commands for standard document generation.  */
+  void SetCommandsSection(const cmDocumentationEntry*);
+  
+  // Low-level interface for custom documents:
+  
+  /** Forms of documentation output.  */
+  enum Form { TextForm, HTMLForm, ManForm, UsageForm };
+  
+  /**
+   * Print documentation in the given form.  All previously added
+   * sections will be generated.
+   */
+  void Print(Form f, std::ostream& os);
+  
+  /**
+   * Add a section of documentation.  The cmDocumentationEntry pointer
+   * should point at an array terminated by an all zero ({0,0,0})
+   * entry.  This can be used to generate custom help documents.
+   */
+  void AddSection(const char* name, const cmDocumentationEntry* d);
+  
+  /** Clear all previously added sections of help.  */
+  void ClearSections();  
+private:
+  void PrintSection(std::ostream& os,
+                    const cmDocumentationEntry* section,
+                    const char* name);
+  void PrintSectionText(std::ostream& os,
+                        const cmDocumentationEntry* section,
+                        const char* name);
+  void PrintSectionHTML(std::ostream& os,
+                        const cmDocumentationEntry* section,
+                        const char* name);
+  void PrintSectionMan(std::ostream& os, const cmDocumentationEntry* section,
+                       const char* name);
+  void PrintSectionUsage(std::ostream& os,
+                         const cmDocumentationEntry* section,
+                         const char* name);
+  void PrintFormatted(std::ostream& os, const char* text);
+  void PrintPreformatted(std::ostream& os, const char* text);
+  void PrintPreformattedText(std::ostream& os, const char* text);
+  void PrintPreformattedHTML(std::ostream& os, const char* text);
+  void PrintPreformattedMan(std::ostream& os, const char* text);
+  void PrintParagraph(std::ostream& os, const char* text);
+  void PrintParagraphText(std::ostream& os, const char* text);
+  void PrintParagraphHTML(std::ostream& os, const char* text);
+  void PrintParagraphMan(std::ostream& os, const char* text);
+  void PrintColumn(std::ostream& os, const char* text);
+  void PrintHTMLEscapes(std::ostream& os, const char* text);
 
-  void Print(Type ht, std::ostream& os);
-  void PrintUsage(std::ostream& os);
-  void PrintHelp(std::ostream& os);
-  void PrintHelpHTML(std::ostream& os);
-  void PrintManPage(std::ostream& os);
   void PrintCopyright(std::ostream& os);
   void PrintVersion(std::ostream& os);
+  void PrintDocumentationUsage(std::ostream& os);
+  void PrintDocumentationFull(std::ostream& os);
+  void PrintDocumentationHTML(std::ostream& os);
+  void PrintDocumentationMan(std::ostream& os);
   
-  void SetCommands(const cmDocumentationEntry* d);
+  void CreateUsageDocumentation();
-  void SetDescription(const cmDocumentationEntry* d) {this->Description = d;}
+  void CreateFullDocumentation();
-  void SetName(const cmDocumentationEntry* d)        {this->Name = d;}
+  void CreateManDocumentation();
-  void SetOptions(const cmDocumentationEntry* d);
-  void SetUsage(const cmDocumentationEntry* d)       {this->UsageHelp = d;}
 
-  Type CheckOptions(int argc, char** argv);
+  void SetSection(const cmDocumentationEntry* header,
-private:
-  void PrintColumn(std::ostream& os, int width,
-                   const char* indent, const char* text);
-  void PrintManSection(std::ostream& os, const cmDocumentationEntry* section,
-                       const char* name);
-  void PrintHelpSection(std::ostream& os, const cmDocumentationEntry* section);
-  static void PrintHTMLEscapes(std::ostream& os, const char* text);
-  static void PrintHTMLPreformatted(std::ostream& os, const char* text);
-  void PrintFull(std::ostream& os, const char* text,
-                 void (*pPreform)(std::ostream&, const char*),
-                 void (*pNormal)(std::ostream&, const char*));
-  void PrintHelpHTMLSection(std::ostream& os,
                   const cmDocumentationEntry* section,
-                            const char* header);
+                  const cmDocumentationEntry* footer,
-  void PrintUsageSection(std::ostream& os,
+                  std::vector<cmDocumentationEntry>&);
-                         const cmDocumentationEntry* section);
 
-  std::vector<cmDocumentationEntry> Commands;
+  std::vector<cmDocumentationEntry> NameSection;
-  const cmDocumentationEntry* Description;
+  std::vector<cmDocumentationEntry> UsageSection;
-  const cmDocumentationEntry* Name;
+  std::vector<cmDocumentationEntry> DescriptionSection;
-  std::vector<cmDocumentationEntry> Options;
+  std::vector<cmDocumentationEntry> OptionsSection;
-  const cmDocumentationEntry* UsageHelp;
+  std::vector<cmDocumentationEntry> CommandsSection;
+  
+  std::vector< const char* > Names;
+  std::vector< const cmDocumentationEntry* > Sections;
+  Form CurrentForm;
+  const char* TextIndent;
+  int TextWidth;
 };
 
 #endif

Source/cmakemain.cxx

@@ -24,8 +24,8 @@
 //----------------------------------------------------------------------------
 static const cmDocumentationEntry cmDocumentationName[] =
 {
-  {"cmake",
+  {0,
-   "- Cross-Platform Makefile Generator.", 0},
+   "  cmake - Cross-Platform Makefile Generator.", 0},
   {0,0,0}
 };
 
@@ -33,7 +33,7 @@ static const cmDocumentationEntry cmDocumentationName[] =
 static const cmDocumentationEntry cmDocumentationUsage[] =
 {
   {0,
-   "cmake [options] <path-to-source>", 0},
+   "  cmake [options] <path-to-source>", 0},
   {0,0,0}
 };
 
@@ -74,12 +74,12 @@ int do_cmake(int ac, char** av)
     cmake hcm;
     std::vector<cmDocumentationEntry> commands;
     hcm.GetCommandDocumentation(commands);
-    doc.SetName(cmDocumentationName);
+    doc.SetNameSection(cmDocumentationName);
-    doc.SetUsage(cmDocumentationUsage);
+    doc.SetUsageSection(cmDocumentationUsage);
-    doc.SetDescription(cmDocumentationDescription);
+    doc.SetDescriptionSection(cmDocumentationDescription);
-    doc.SetOptions(cmDocumentationOptions);
+    doc.SetOptionsSection(cmDocumentationOptions);
-    doc.SetCommands(&commands[0]);
+    doc.SetCommandsSection(&commands[0]);
-    doc.Print(ht, std::cout);
+    doc.PrintDocumentation(ht, std::cout);
     return 0;
     }