ENH: add support for creating the documentation in docbook format

(http://www.oasis-open.org/docbook/xml/4.2/), which users can then convert
to other formats.
Tested with meinproc from KDE, which generates HTML pages which look good.

Alex

Source/CMakeLists.txt

@@ -115,6 +115,7 @@ SET(SRCS
   cmDocumentation.cxx
   cmDocumentationFormatter.cxx
   cmDocumentationFormatterHTML.cxx
+  cmDocumentationFormatterDocbook.cxx
   cmDocumentationFormatterMan.cxx
   cmDocumentationFormatterText.cxx
   cmDocumentationFormatterUsage.cxx

Source/cmDocumentation.cxx

@@ -324,6 +324,7 @@ void cmDocumentation::ClearSections()
 bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os)
 {
   if ((this->CurrentFormatter->GetForm() != HTMLForm) 
+       && (this->CurrentFormatter->GetForm() != DocbookForm)
        && (this->CurrentFormatter->GetForm() != ManForm))
     {
     this->PrintVersion(os);
@@ -636,6 +637,11 @@ cmDocumentation::Form cmDocumentation::GetFormFromFilename(
     return cmDocumentation::HTMLForm;
     }
 
+  if (ext == ".DOCBOOK")
+    {
+    return cmDocumentation::DocbookForm;
+    }
+
   // ".1" to ".9" should be manpages
   if ((ext.length()==2) && (ext[1] >='1') && (ext[1]<='9'))
     {
@@ -1216,7 +1222,8 @@ bool cmDocumentation::PrintDocumentationCustomModules(std::ostream& os)
   this->CreateCustomModulesSection();
   this->AddSectionToPrint("Description");
   this->AddSectionToPrint("Custom CMake Modules");
-  this->AddSectionToPrint("Copyright");
+// the custom modules are most probably not under Kitware's copyright, Alex
+//  this->AddSectionToPrint("Copyright");
   this->AddSectionToPrint("See Also");
 
   this->CurrentFormatter->PrintHeader(this->GetNameString(), os);
@@ -1373,6 +1380,9 @@ void cmDocumentation::SetForm(Form f)
     case HTMLForm:
       this->CurrentFormatter = &this->HTMLFormatter;
       break;
+    case DocbookForm:
+      this->CurrentFormatter = &this->DocbookFormatter;
+      break;
     case ManForm:
       this->CurrentFormatter = &this->ManFormatter;
       break;

Source/cmDocumentation.h

@@ -21,6 +21,7 @@
 #include "cmProperty.h"
 #include "cmDocumentationFormatter.h"
 #include "cmDocumentationFormatterHTML.h"
+#include "cmDocumentationFormatterDocbook.h"
 #include "cmDocumentationFormatterMan.h"
 #include "cmDocumentationFormatterText.h"
 #include "cmDocumentationFormatterUsage.h"
@@ -176,6 +177,7 @@ private:
   std::vector<RequestedHelpItem> RequestedHelpItems;
   cmDocumentationFormatter* CurrentFormatter;
   cmDocumentationFormatterHTML HTMLFormatter;
+  cmDocumentationFormatterDocbook DocbookFormatter;
   cmDocumentationFormatterMan ManFormatter;
   cmDocumentationFormatterText TextFormatter;
   cmDocumentationFormatterUsage UsageFormatter;

Source/cmDocumentationFormatter.h

@@ -36,7 +36,7 @@ public:
     CompatCommands, Copyright, Version };
 
   /** Forms of documentation output.  */
-  enum Form { TextForm, HTMLForm, ManForm, UsageForm };
+  enum Form { TextForm, HTMLForm, ManForm, UsageForm, DocbookForm };
 };
 
 class cmDocumentationSection;

Source/cmDocumentationFormatterDocbook.cxx

@@ -0,0 +1,254 @@
+/*=========================================================================
+
+  Program:   CMake - Cross-Platform Makefile Generator
+  Module:    $RCSfile$
+  Language:  C++
+  Date:      $Date$
+  Version:   $Revision$
+
+  Copyright (c) 2002 Kitware, Inc., Insight Consortium.  All rights reserved.
+  See Copyright.txt or http://www.cmake.org/HTML/Copyright.html for details.
+
+     This software is distributed WITHOUT ANY WARRANTY; without even 
+     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
+     PURPOSE.  See the above copyright notices for more information.
+
+=========================================================================*/
+#include "cmDocumentationFormatterDocbook.h"
+#include "cmDocumentationSection.h"
+//----------------------------------------------------------------------------
+
+// this function is a copy of the one in the HTML formatter
+// the three functions below are slightly modified copies
+static bool cmDocumentationIsHyperlinkCharDocbook(char c)
+{
+  // This is not a complete list but works for CMake documentation.
+  return ((c >= 'A' && c <= 'Z') ||
+          (c >= 'a' && c <= 'z') ||
+          (c >= '0' && c <= '9') ||
+          c == '-' || c == '.' || c == '/' || c == '~' || c == '@' ||
+          c == ':' || c == '_' || c == '&' || c == '?' || c == '=');
+}
+
+//----------------------------------------------------------------------------
+static void cmDocumentationPrintDocbookChar(std::ostream& os, char c)
+{
+  // Use an escape sequence if necessary.
+  switch(c)
+  {
+    case '<':
+      os << "&lt;";
+      break;
+    case '>': 
+      os << "&gt;";
+      break;
+    case '&':
+      os << "&amp;";
+      break;
+    default:
+      os << c;
+  }
+}
+
+//----------------------------------------------------------------------------
+const char* cmDocumentationPrintDocbookLink(std::ostream& os,const char* begin)
+{
+  // Look for the end of the link.
+  const char* end = begin;
+  while(cmDocumentationIsHyperlinkCharDocbook(*end))
+    {
+    ++end;
+    }
+
+  // Print the hyperlink itself.
+  os << "<ulink url=\"";
+  for(const char* c = begin; c != end; ++c)
+    {
+    cmDocumentationPrintDocbookChar(os, *c);
+    }
+  os << "\" />";
+
+  return end;
+}
+
+//----------------------------------------------------------------------------
+void cmDocumentationPrintDocbookEscapes(std::ostream& os, const char* text)
+{
+  // Hyperlink prefixes.
+  static const char* hyperlinks[] = {"http://", "ftp://", "mailto:", 0};
+
+  // Print each character.
+  for(const char* p = text; *p;)
+    {
+    // Handle hyperlinks specially to make them active.
+    bool found_hyperlink = false;
+    for(const char** h = hyperlinks; !found_hyperlink && *h; ++h)
+      {
+      if(strncmp(p, *h, strlen(*h)) == 0)
+        {
+        p = cmDocumentationPrintDocbookLink(os, p);
+        found_hyperlink = true;
+        }
+      }
+
+    // Print other characters normally.
+    if(!found_hyperlink)
+      {
+      cmDocumentationPrintDocbookChar(os, *p++);
+      }
+    }
+}
+
+
+cmDocumentationFormatterDocbook::cmDocumentationFormatterDocbook()
+:cmDocumentationFormatter()
+{
+}
+
+void cmDocumentationFormatterDocbook
+::PrintSection(std::ostream& os,
+               const cmDocumentationSection &section,
+               const char* name)
+{
+  if(name)
+    {
+    std::string id = "section_";
+    id += name;
+    if (this->EmittedLinkIds.find(id) == this->EmittedLinkIds.end())
+      {
+      this->EmittedLinkIds.insert(id);
+      os << "<sect1 id=\"section_" << name << "\">\n"
+            "<title>\n" << name << "</title>\n";
+      }
+    else
+      {
+      static unsigned int i=0;
+      i++;
+      os << "<sect1 id=\"section_" << name << i << "\">\n"
+            "<title>\n" << name << "</title>\n";
+      }
+    }
+
+  const std::vector<cmDocumentationEntry> &entries = 
+    section.GetEntries();
+
+  os << "<itemizedlist>\n";
+  for(std::vector<cmDocumentationEntry>::const_iterator op 
+        = entries.begin(); op != entries.end(); ++ op )
+    {
+    if(op->Name.size())
+      {
+      os << "    <listitem><link linkend=\"command_";
+      cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
+      os << "\"><emphasis><literal>";
+      cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
+      os << "</literal></emphasis></link></listitem>";
+      }
+    }
+  os << "</itemizedlist>\n" ;
+
+  for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin(); 
+      op != entries.end();)
+    {
+    if(op->Name.size())
+      {
+      for(;op != entries.end() && op->Name.size(); ++op)
+        {
+        if(op->Name.size())
+          {
+          os << "    <para id=\"command_";
+          cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
+
+          // make sure that each id exists only once, e.g. 
+          // command_COMPILE_DEFINITIONS exists at least twice. Since it seems
+          // not easily possible to determine which link refers to which id, 
+          // we have at least to make sure that the duplicated id's get a 
+          // different name (by appending an increasing number), Alex
+          std::string id = "command_";
+          id += op->Name;
+          if (this->EmittedLinkIds.find(id) == this->EmittedLinkIds.end())
+            {
+            this->EmittedLinkIds.insert(id);
+            }
+          else
+            {
+            static unsigned int i=0;
+            i++;
+            os << i;
+            }
+          // continue as normal...
+
+          os << "\"><sect2><title>";
+          cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
+          os << "</title></sect2> ";
+          }
+        cmDocumentationPrintDocbookEscapes(os, op->Brief.c_str());
+        if(op->Name.size())
+          {
+          os << "</para>\n";
+          }
+
+        if(op->Full.size())
+          {
+          // a line break seems to be simply a line break with docbook
+          os << "\n    ";  
+          this->PrintFormatted(os, op->Full.c_str());
+          }
+        os << "\n";
+        }
+      }
+    else
+      {
+      this->PrintFormatted(os, op->Brief.c_str());
+      os << "\n";
+      ++op;
+      }
+    }
+  if(name)
+    {
+    os << "</sect1>\n";
+    }
+}
+
+void cmDocumentationFormatterDocbook::PrintPreformatted(std::ostream& os, 
+                                                     const char* text)
+{
+  os << "<literallayout>";
+  cmDocumentationPrintDocbookEscapes(os, text);
+  os << "</literallayout>\n    ";
+}
+
+void cmDocumentationFormatterDocbook::PrintParagraph(std::ostream& os, 
+                                                  const char* text)
+{
+  os << "<para>";
+  cmDocumentationPrintDocbookEscapes(os, text);
+  os << "</para>";
+}
+
+//----------------------------------------------------------------------------
+void cmDocumentationFormatterDocbook::PrintHeader(const char* name, 
+                                               std::ostream& os)
+{
+  // this one is used to ensure that we don't create multiple link targets
+  // with the same name. We can clear it here since we are at the 
+  // start of a document here.
+  this->EmittedLinkIds.clear();
+
+  os << "<?xml version=\"1.0\" ?>\n"
+        "<!DOCTYPE article PUBLIC \"-//OASIS//DTD DocBook V4.2//EN\" "
+        "\"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd\" [\n"
+        "<!ENTITY % addindex \"IGNORE\">\n"
+        "<!ENTITY % English \"INCLUDE\"> ]>\n"
+        "<article>\n"
+        "<articleinfo>\n"
+        "<title>" << name << "</title>\n"
+        "</articleinfo>\n";
+}
+
+//----------------------------------------------------------------------------
+void cmDocumentationFormatterDocbook::PrintFooter(std::ostream& os)
+{
+  os << "</article>\n";
+}
+

Source/cmDocumentationFormatterDocbook.h

@@ -0,0 +1,45 @@
+/*=========================================================================
+
+  Program:   CMake - Cross-Platform Makefile Generator
+  Module:    $RCSfile$
+  Language:  C++
+  Date:      $Date$
+  Version:   $Revision$
+
+  Copyright (c) 2002 Kitware, Inc., Insight Consortium.  All rights reserved.
+  See Copyright.txt or http://www.cmake.org/HTML/Copyright.html for details.
+
+     This software is distributed WITHOUT ANY WARRANTY; without even 
+     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
+     PURPOSE.  See the above copyright notices for more information.
+
+=========================================================================*/
+#ifndef _cmDocumentationFormatterDocbook_h
+#define _cmDocumentationFormatterDocbook_h
+
+#include "cmStandardIncludes.h"
+
+#include "cmDocumentationFormatter.h"
+
+/** Class to print the documentation as Docbook.
+ http://www.oasis-open.org/docbook/xml/4.2/   */
+class cmDocumentationFormatterDocbook : public cmDocumentationFormatter
+{
+public:
+  cmDocumentationFormatterDocbook();
+
+  virtual cmDocumentationEnums::Form GetForm() const
+                                  { return cmDocumentationEnums::DocbookForm;}
+
+  virtual void PrintHeader(const char* name, std::ostream& os);
+  virtual void PrintFooter(std::ostream& os);
+  virtual void PrintSection(std::ostream& os,
+                            const cmDocumentationSection& section,
+                            const char* name);
+  virtual void PrintPreformatted(std::ostream& os, const char* text);
+  virtual void PrintParagraph(std::ostream& os, const char* text);
+private:
+  std::set<std::string> EmittedLinkIds;
+};
+
+#endif

Source/cmDocumentationFormatterHTML.cxx

@@ -32,24 +32,23 @@ static bool cmDocumentationIsHyperlinkChar(char c)
 static void cmDocumentationPrintHTMLChar(std::ostream& os, char c)
 {
   // Use an escape sequence if necessary.
-  static std::map<char,std::string> escapes;
-  if (escapes.empty())
+  switch (c)
     {
-    escapes['<'] = "&lt;";
-    escapes['>'] = "&gt;";
-    escapes['&'] = "&amp;";
-    escapes['\n'] = "<br>";
-    }
-
-  if (escapes.find(c) == escapes.end())
-    {
-    // No escape sequence is needed.
-    os << c;
-    return;
-    }
-    
-  os << escapes[c];
-  return;
+    case '<': 
+      os << "&lt;";
+      break;
+    case '>':
+      os << "&gt;";
+      break;
+    case '&':
+      os << "&amp;";
+      break;
+    case '\n':
+      os << "<br>";
+      break;
+    default:
+      os << c;
+  }
 }
 
 //----------------------------------------------------------------------------

Source/cmakemain.cxx

@@ -105,81 +105,81 @@ static const char * cmDocumentationOptions[][3] =
    "Full documentation specific to the given command is displayed. "
    "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 and plain text."},
+   "page, HTML, DocBook and plain text."},
   {"--help-command-list [file]", "List available listfile commands and exit.",
    "The list contains all commands for which help may be obtained by using "
    "the --help-command argument followed by a command name. "
    "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 and plain text."},
+   "page, HTML, DocBook and plain text."},
   {"--help-commands [file]", "Print help for all commands and exit.",
    "Full documentation specific for all current command is displayed."
    "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 and plain text."},
+   "page, HTML, DocBook and plain text."},
   {"--help-compatcommands [file]", "Print help for compatibility commands. ",
    "Full documentation specific for all compatibility commands is displayed."
    "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 and plain text."},
+   "page, HTML, DocBook and plain text."},
   {"--help-module module [file]", "Print help for a single module and exit.",
    "Full documentation specific to the given module is displayed."
    "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 and plain text."},
+   "page, HTML, DocBook and plain text."},
   {"--help-module-list [file]", "List available modules and exit.",
    "The list contains all modules for which help may be obtained by using "
    "the --help-module argument followed by a module name. "
    "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 and plain text."},
+   "page, HTML, DocBook and plain text."},
   {"--help-modules [file]", "Print help for all modules and exit.",
    "Full documentation for all modules is displayed. "
    "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 and plain text."},
+   "page, HTML, DocBook and plain text."},
   {"--help-custom-modules [file]" , "Print help for all custom modules and "
    "exit.",
    "Full documentation for all custom modules is displayed. "
    "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 and plain text."},
+   "page, HTML, DocBook and plain text."},
   {"--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 "
    "format is determined depending on the filename suffix. Supported are man "
-   "page, HTML and plain text."},
+   "page, HTML, DocBook and plain text."},
   {"--help-property-list [file]", "List available properties and exit.",
    "The list contains all properties for which help may be obtained by using "
    "the --help-property argument followed by a property name.  If a file is "
    "specified, the help is written into it."
    "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 and plain text."},
+   "page, HTML, DocBook and plain text."},
   {"--help-properties [file]", "Print help for all properties and exit.",
    "Full documentation for all properties is displayed."
    "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 and plain text."},
+   "page, HTML, DocBook and plain text."},
   {"--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 "
    "format is determined depending on the filename suffix. Supported are man "
-   "page, HTML and plain text."},
+   "page, HTML, DocBook and plain text."},
   {"--help-variable-list [file]", "List documented variables and exit.",
    "The list contains all variables for which help may be obtained by using "
    "the --help-variable argument followed by a variable name.  If a file is "
    "specified, the help is written into it."
    "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 and plain text."},
+   "page, HTML, DocBook and plain text."},
   {"--help-variables [file]", "Print help for all variables and exit.",
    "Full documentation for all variables is displayed."
    "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 and plain text."},
+   "page, HTML, DocBook and plain text."},
   {0,0,0}
 };
 
@@ -187,7 +187,13 @@ static const char * cmDocumentationOptions[][3] =
 static const char * cmDocumentationSeeAlso[][3] =
 {
   {0, "ccmake", 0},
+  {0, "cpack", 0},
   {0, "ctest", 0},
+  {0, "cmakecommands", 0},
+  {0, "cmakecompat", 0},
+  {0, "cmakemodules", 0},
+  {0, "cmakeprops", 0},
+  {0, "cmakevars", 0},
   {0, 0, 0}
 };