From ffcc9fbea6f90ba0a512602b8e4aa2d9f12fb30f Mon Sep 17 00:00:00 2001
From: Daniel Pfeifer <daniel@pfeifer-mail.de>
Date: Sun, 2 Sep 2012 23:21:35 +0200
Subject: [PATCH] Add tests for validating generated docbook documentation

---
 Tests/CMakeTests/CMakeLists.txt        | 16 ++++++++++++++++
 Tests/CMakeTests/ValidateDocBook.cmake | 16 ++++++++++++++++
 2 files changed, 32 insertions(+)
 create mode 100644 Tests/CMakeTests/ValidateDocBook.cmake

diff --git a/Tests/CMakeTests/CMakeLists.txt b/Tests/CMakeTests/CMakeLists.txt
index d34d4a6..163c965 100644
--- a/Tests/CMakeTests/CMakeLists.txt
+++ b/Tests/CMakeTests/CMakeLists.txt
@@ -32,6 +32,22 @@ AddCMakeTest(ProcessorCount "")
 AddCMakeTest(PushCheckState "")
 AddCMakeTest(While "")
 
+find_package(LibXml2)
+if(LIBXML2_XMLLINT_EXECUTABLE)
+  function(validate_docbook name)
+    add_test(NAME CMake.ValidateDocBook.${name}
+      COMMAND ${CMAKE_EXECUTABLE}
+        -DNAME=${name}
+        -DCOMMAND=$<TARGET_FILE:${name}>
+        -DXMLLINT=${LIBXML2_XMLLINT_EXECUTABLE}
+        -P "${CMAKE_CURRENT_SOURCE_DIR}/ValidateDocBook.cmake"
+      )
+  endfunction()
+  validate_docbook(cmake)
+  validate_docbook(cpack)
+  validate_docbook(ctest)
+endif()
+
 AddCMakeTest(FileDownload "")
 set_property(TEST CMake.FileDownload PROPERTY
   PASS_REGULAR_EXPRESSION "file already exists with expected MD5 sum"
diff --git a/Tests/CMakeTests/ValidateDocBook.cmake b/Tests/CMakeTests/ValidateDocBook.cmake
new file mode 100644
index 0000000..5a5a0dd
--- /dev/null
+++ b/Tests/CMakeTests/ValidateDocBook.cmake
@@ -0,0 +1,16 @@
+set(dbk_file temporary-${NAME}-documentation.docbook)
+
+execute_process(
+  COMMAND ${COMMAND} --help-full ${dbk_file}
+  )
+
+execute_process(
+  COMMAND ${XMLLINT} --valid --noout ${dbk_file}
+  RESULT_VARIABLE result
+  )
+
+file(REMOVE ${dbk_file})
+
+if(NOT result EQUAL 0)
+  message(FATAL_ERROR "${NAME} generates invalid docbook documentation!")
+endif()
-- 
1.7.12

From 693f7092ff0e9d71f632c614b2a5ee852f3d83a0 Mon Sep 17 00:00:00 2001
From: Daniel Pfeifer <daniel@pfeifer-mail.de>
Date: Mon, 3 Sep 2012 00:03:28 +0200
Subject: [PATCH 1/2] fix DocBook documentation formatter

---
 Source/cmDocumentationFormatterDocbook.cxx | 173 ++++++++++++++---------------
 Source/cmDocumentationFormatterDocbook.h   |   2 +
 2 files changed, 83 insertions(+), 92 deletions(-)

diff --git a/Source/cmDocumentationFormatterDocbook.cxx b/Source/cmDocumentationFormatterDocbook.cxx
index eabdbc1..ebe7be2 100644
--- a/Source/cmDocumentationFormatterDocbook.cxx
+++ b/Source/cmDocumentationFormatterDocbook.cxx
@@ -11,6 +11,8 @@
 ============================================================================*/
 #include "cmDocumentationFormatterDocbook.h"
 #include "cmDocumentationSection.h"
+#include <algorithm>
+#include <cctype>
 //----------------------------------------------------------------------------
 
 // this function is a copy of the one in the HTML formatter
@@ -94,151 +96,112 @@ void cmDocumentationPrintDocbookEscapes(std::ostream& os, const char* text)
     }
 }
 
-
+//----------------------------------------------------------------------------
 cmDocumentationFormatterDocbook::cmDocumentationFormatterDocbook()
 :cmDocumentationFormatter()
 {
 }
 
+//----------------------------------------------------------------------------
 void cmDocumentationFormatterDocbook
 ::PrintSection(std::ostream& os,
                const cmDocumentationSection &section,
                const char* name)
 {
-  if(name)
+  const std::vector<cmDocumentationEntry> &entries = section.GetEntries();
+
+  // empty sections are not allowed in docbook.
+  // we could cheat by writing just a <para/>, but what's the point?
+  if(entries.empty())
     {
-    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";
-      }
+    return;
     }
 
-  std::string prefix = this->ComputeSectionLinkPrefix(name);
+  os << "<sect1 id=\"";
+  this->PrintId(os, 0, name);
+  os << "\">\n<title>" << name << "</title>\n";
 
-  const std::vector<cmDocumentationEntry> &entries =
-    section.GetEntries();
+  std::string prefix = this->ComputeSectionLinkPrefix(name);
 
-  if (!entries.empty())
+  bool hasSubSections = false;
+  for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
+      op != entries.end(); ++op)
     {
-    os << "<itemizedlist>\n";
-    for(std::vector<cmDocumentationEntry>::const_iterator op
-          = entries.begin(); op != entries.end(); ++ op )
+    if(op->Name.size())
       {
-      if(op->Name.size())
-        {
-        os << "    <listitem><link linkend=\"" << prefix << "_";
-        cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
-        os << "\"><emphasis><literal>";
-        cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
-        os << "</literal></emphasis></link></listitem>\n";
-        }
+      hasSubSections = true;
+      break;
       }
-    os << "</itemizedlist>\n" ;
     }
 
   for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
-      op != entries.end();)
+      op != entries.end(); ++op)
     {
     if(op->Name.size())
       {
-      for(;op != entries.end() && op->Name.size(); ++op)
+      os << "<sect2 id=\"";
+      this->PrintId(os, prefix.c_str(), op->Name);
+      os << "\">\n<title>";
+      cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
+      os << "</title>\n";
+      if(op->Full.size())
         {
-        if(op->Name.size())
-          {
-          os << "    <para id=\"" << prefix << "_";
-          cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
-
-          // make sure that each id exists only once.  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 = prefix;
-          id += "_";
-          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> ";
-          }
+        os << "<abstract>\n<para>";
         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";
+        os << "</para>\n</abstract>\n";
+        this->PrintFormatted(os, op->Full.c_str());
+        }
+      else
+        {
+        this->PrintFormatted(os, op->Brief.c_str());
         }
+      os << "</sect2>\n";
+      }
+    else if(hasSubSections && op == entries.begin())
+      {
+      os << "<abstract>\n";
+      this->PrintFormatted(os, op->Brief.c_str());
+      os << "</abstract>\n";
       }
     else
       {
       this->PrintFormatted(os, op->Brief.c_str());
-      os << "\n";
-      ++op;
       }
     }
-  if(name)
-    {
-    os << "</sect1>\n";
-    }
+  os << "</sect1>\n";
 }
 
-void cmDocumentationFormatterDocbook::PrintPreformatted(std::ostream& os,
-                                                     const char* text)
+//----------------------------------------------------------------------------
+void cmDocumentationFormatterDocbook
+::PrintPreformatted(std::ostream& os, const char* text)
 {
   os << "<literallayout>";
   cmDocumentationPrintDocbookEscapes(os, text);
-  os << "</literallayout>\n    ";
+  os << "</literallayout>\n";
 }
 
-void cmDocumentationFormatterDocbook::PrintParagraph(std::ostream& os,
-                                                  const char* text)
+void cmDocumentationFormatterDocbook
+::PrintParagraph(std::ostream& os, const char* text)
 {
   os << "<para>";
   cmDocumentationPrintDocbookEscapes(os, text);
-  os << "</para>";
+  os << "</para>\n";
 }
 
 //----------------------------------------------------------------------------
-void cmDocumentationFormatterDocbook::PrintHeader(const char* docname,
-                                                  const char* appname,
-                                                  std::ostream& os)
+void cmDocumentationFormatterDocbook
+::PrintHeader(const char* docname, const char* appname, std::ostream& os)
 {
+  this->docname = docname;
+
   // 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"
+        "<!DOCTYPE article PUBLIC \"-//OASIS//DTD DocBook V4.5//EN\" "
+        "\"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\" [\n"
         "<!ENTITY % addindex \"IGNORE\">\n"
         "<!ENTITY % English \"INCLUDE\"> ]>\n"
         "<article>\n"
@@ -253,3 +216,29 @@ void cmDocumentationFormatterDocbook::PrintFooter(std::ostream& os)
   os << "</article>\n";
 }
 
+//----------------------------------------------------------------------------
+void cmDocumentationFormatterDocbook
+::PrintId(std::ostream& os, const char* prefix, std::string id)
+{
+  std::replace_if(id.begin(), id.end(), std::not1(std::ptr_fun(isalnum)), '_');
+  if(prefix)
+    {
+    id.insert(0, 1, '.');
+    id.insert(0, prefix);
+    }
+  os << this->docname << '.' << id;
+
+  // make sure that each id exists only once.  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
+  if (this->EmittedLinkIds.find(id) == this->EmittedLinkIds.end())
+    {
+    this->EmittedLinkIds.insert(id);
+    }
+  else
+    {
+    static unsigned int i=0;
+    os << i++;
+    }
+}
diff --git a/Source/cmDocumentationFormatterDocbook.h b/Source/cmDocumentationFormatterDocbook.h
index 213948d..6c96900 100644
--- a/Source/cmDocumentationFormatterDocbook.h
+++ b/Source/cmDocumentationFormatterDocbook.h
@@ -35,7 +35,9 @@ public:
   virtual void PrintPreformatted(std::ostream& os, const char* text);
   virtual void PrintParagraph(std::ostream& os, const char* text);
 private:
+  void PrintId(std::ostream& os, const char* prefix, std::string id);
   std::set<std::string> EmittedLinkIds;
+  std::string docname;
 };
 
 #endif
-- 
1.7.12

From 28675bfbfba59eacb4b880c75333cc2479f50a2c Mon Sep 17 00:00:00 2001
From: Daniel Pfeifer <daniel@pfeifer-mail.de>
Date: Mon, 3 Sep 2012 00:05:03 +0200
Subject: [PATCH 2/2] remove documentation that causes invalid docbook

---
 Source/cmDocumentation.cxx | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx
index 1b042ae..db646c1 100644
--- a/Source/cmDocumentation.cxx
+++ b/Source/cmDocumentation.cxx
@@ -91,10 +91,6 @@ static const char *cmPropertiesDocumentationDescription[][3] =
 static const char *cmCompatCommandsDocumentationDescription[][3] =
 {
   {0,
-   "  CMake Compatibility Listfile Commands - "
-   "Obsolete commands supported by CMake for compatibility.", 0},
-//  CMAKE_DOCUMENTATION_OVERVIEW,
-  {0,
   "This is the documentation for now obsolete listfile commands from previous "
   "CMake versions, which are still supported for compatibility reasons. You "
   "should instead use the newer, faster and shinier new commands. ;-)", 0},
@@ -148,13 +144,6 @@ static const char *cmDocumentationStandardSeeAlso[][3] =
    "The list is member-post-only but one may sign up on the CMake web page. "
    "Please first read the full documentation at "
    "http://www.cmake.org before posting questions to the list."},
-  {0,
-   "Summary of helpful links:\n"
-   "  Home: http://www.cmake.org\n"
-   "  Docs: http://www.cmake.org/HTML/Documentation.html\n"
-   "  Mail: http://www.cmake.org/HTML/MailingLists.html\n"
-   "  FAQ:  http://www.cmake.org/Wiki/CMake_FAQ\n"
-   , 0},
   {0,0,0}
 };
 
-- 
1.7.12

From 4a134ac6ac48a9388bb664c9667d332ab7ca881c Mon Sep 17 00:00:00 2001
Message-Id: <4a134ac6ac48a9388bb664c9667d332ab7ca881c.1346681732.git.brad.king@kitware.com>
From: Brad King <brad.king@kitware.com>
Date: Mon, 3 Sep 2012 10:14:17 -0400
Subject: [PATCH] WIP: Add CMake.Docbook test to validate docbook xml (#13508)

TODO: Put dependencies of docbookx.dtd in Utilities/xml.
---
 Utilities/CMakeLists.txt   |    6 ++
 Utilities/xml/docbookx.dtd |  165 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 171 insertions(+)
 create mode 100644 Utilities/xml/docbookx.dtd

diff --git a/Utilities/CMakeLists.txt b/Utilities/CMakeLists.txt
index 233d5e2..4f818f4 100644
--- a/Utilities/CMakeLists.txt
+++ b/Utilities/CMakeLists.txt
@@ -68,6 +68,7 @@ macro(ADD_DOCS target dependency)
       ${CMake_BINARY_DIR}/Docs/${target}.docbook
       )
     list(APPEND HTML_FILES ${CMake_BINARY_DIR}/Docs/${target}.html)
+    list(APPEND DOCBOOK_FILES ${CMake_BINARY_DIR}/Docs/${target}.docbook)
   endif()
 endmacro()
 
@@ -152,6 +153,11 @@ if(BUILD_TESTING)
         ${LIBXML2_XMLLINT_EXECUTABLE} --valid --noout --nonet --path .
         ${HTML_FILES}
         )
+      add_test(CMake.Docbook
+        ${CMAKE_CMAKE_COMMAND} -E chdir ${CMAKE_CURRENT_SOURCE_DIR}/xml
+        ${LIBXML2_XMLLINT_EXECUTABLE} --valid --noout --nonet --path .
+        ${DOCBOOK_FILES}
+        )
     endif()
   endif()
 endif()
diff --git a/Utilities/xml/docbookx.dtd b/Utilities/xml/docbookx.dtd
new file mode 100644
index 0000000..885a760
--- /dev/null
+++ b/Utilities/xml/docbookx.dtd
@@ -0,0 +1,165 @@
+<!-- ...................................................................... -->
+<!-- DocBook XML DTD V4.2 ................................................. -->
+<!-- File docbookx.dtd .................................................... -->
+
+<!-- Copyright 1992-2002 HaL Computer Systems, Inc.,
+     O'Reilly & Associates, Inc., ArborText, Inc., Fujitsu Software
+     Corporation, Norman Walsh, Sun Microsystems, Inc., and the
+     Organization for the Advancement of Structured Information
+     Standards (OASIS).
+
+     $Id: docbookx.dtd,v 1.13 2002/07/17 15:26:16 nwalsh Exp $
+
+     Permission to use, copy, modify and distribute the DocBook XML DTD
+     and its accompanying documentation for any purpose and without fee
+     is hereby granted in perpetuity, provided that the above copyright
+     notice and this paragraph appear in all copies.  The copyright
+     holders make no representation about the suitability of the DTD for
+     any purpose.  It is provided "as is" without expressed or implied
+     warranty.
+
+     If you modify the DocBook DTD in any way, except for declaring and
+     referencing additional sets of general entities and declaring
+     additional notations, label your DTD as a variant of DocBook.  See
+     the maintenance documentation for more information.
+
+     Please direct all questions, bug reports, or suggestions for
+     changes to the docbook@lists.oasis-open.org mailing list. For more
+     information, see http://www.oasis-open.org/docbook/.
+-->
+
+<!-- ...................................................................... -->
+
+<!-- This is the driver file for V4.2 of the DocBook DTD.
+     Please use the following formal public identifier to identify it:
+
+     "-//OASIS//DTD DocBook XML V4.2//EN"
+
+     For example, if your document's top-level element is Book, and
+     you are using DocBook directly, use the FPI in the DOCTYPE
+     declaration:
+
+     <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+                    [...]>
+
+     Or, if you have a higher-level driver file that customizes DocBook,
+     use the FPI in the parameter entity declaration:
+
+     <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+     %DocBookDTD;
+
+     See the documentation for detailed information on the parameter
+     entity and module scheme used in DocBook, customizing DocBook and
+     planning for interchange, and changes made since the last release
+     of DocBook.
+-->
+
+<!-- ...................................................................... -->
+<!-- Enable SGML features ................................................. -->
+
+<!ENTITY % sgml.features "IGNORE">
+<![%sgml.features;[
+<!ENTITY % xml.features "IGNORE">
+]]>
+<!ENTITY % xml.features "INCLUDE">
+
+<![%sgml.features;[
+<![%xml.features;[
+
+<!-- ERROR: Exactly one of xml.features and sgml.features must be turned on! -->
+<!ENTITY % dbnotn SYSTEM "http://www.oasis-open.org/docbook/xml/configerror.txt">
+<!ENTITY % dbcent SYSTEM "http://www.oasis-open.org/docbook/xml/configerror.txt">
+<!ENTITY % dbpool SYSTEM "http://www.oasis-open.org/docbook/xml/configerror.txt">
+<!ENTITY % dbhier SYSTEM "http://www.oasis-open.org/docbook/xml/configerror.txt">
+<!ENTITY % dbgenent SYSTEM "http://www.oasis-open.org/docbook/xml/configerror.txt">
+
+]]>
+]]>
+
+<![%sgml.features;[
+<!ENTITY % ho "- O">
+<!ENTITY % hh "- -">
+]]>
+
+<![%xml.features;[
+<!ENTITY % ho "">
+<!ENTITY % hh "">
+]]>
+
+<!-- ...................................................................... -->
+<!-- Notation declarations ................................................ -->
+
+<!ENTITY % dbnotn.module "INCLUDE">
+<![%dbnotn.module;[
+<!ENTITY % dbnotn PUBLIC
+"-//OASIS//ENTITIES DocBook Notations V4.2//EN"
+"dbnotnx.mod">
+%dbnotn;
+]]>
+
+<!-- ...................................................................... -->
+<!-- ISO character entity sets ............................................ -->
+
+<!ENTITY % dbcent.module "INCLUDE">
+<![%dbcent.module;[
+
+<![%sgml.features;[
+<!ENTITY euro "[euro  ]"><!-- euro sign, U+20AC NEW -->
+]]>
+<![%xml.features;[
+<!ENTITY euro "&#x20AC;"><!-- euro sign, U+20AC NEW -->
+]]>
+
+<!ENTITY % dbcent PUBLIC
+"-//OASIS//ENTITIES DocBook Character Entities V4.2//EN"
+"dbcentx.mod">
+%dbcent;
+]]>
+
+<!-- ...................................................................... -->
+<!-- DTD modules .......................................................... -->
+
+<!-- Information pool .............. -->
+
+<!ENTITY % dbpool.module "INCLUDE">
+<![ %dbpool.module; [
+<!ENTITY % dbpool PUBLIC
+"-//OASIS//ELEMENTS DocBook Information Pool V4.2//EN"
+"dbpoolx.mod">
+%dbpool;
+]]>
+
+<!-- Redeclaration placeholder ..... -->
+
+<!ENTITY % intermod.redecl.module "IGNORE">
+<![%intermod.redecl.module;[
+<!-- Defining rdbmods here makes some buggy XML parsers happy. -->
+<!ENTITY % rdbmods "">
+%rdbmods;
+<!--end of intermod.redecl.module-->]]>
+
+<!-- Document hierarchy ............ -->
+
+<!ENTITY % dbhier.module "INCLUDE">
+<![ %dbhier.module; [
+<!ENTITY % dbhier PUBLIC
+"-//OASIS//ELEMENTS DocBook Document Hierarchy V4.2//EN"
+"dbhierx.mod">
+%dbhier;
+]]>
+
+<!-- ...................................................................... -->
+<!-- Other general entities ............................................... -->
+
+<!ENTITY % dbgenent.module "INCLUDE">
+<![ %dbgenent.module; [
+<!ENTITY % dbgenent PUBLIC
+"-//OASIS//ENTITIES DocBook Additional General Entities V4.2//EN"
+"dbgenent.mod">
+%dbgenent;
+]]>
+
+<!-- End of DocBook XML DTD V4.2 .......................................... -->
+<!-- ...................................................................... -->
-- 
1.7.10.4

From 74775c28214106d9f52ec5aaa7217f59d7b097a9 Mon Sep 17 00:00:00 2001
From: Daniel Pfeifer <daniel@pfeifer-mail.de>
Date: Fri, 7 Sep 2012 10:34:34 +0200
Subject: [PATCH 1/7] Remove table of contents from generated DocBook

When DocBook is transformed (eg. to PDF, HTML, ...), a TOC is generated from the
document's layout. The TOC-like list that the docbook formatter used to generate
was both redundant and invalid.
---
 Source/cmDocumentationFormatterDocbook.cxx | 18 ------------------
 1 file changed, 18 deletions(-)

diff --git a/Source/cmDocumentationFormatterDocbook.cxx b/Source/cmDocumentationFormatterDocbook.cxx
index eabdbc1..af32d38 100644
--- a/Source/cmDocumentationFormatterDocbook.cxx
+++ b/Source/cmDocumentationFormatterDocbook.cxx
@@ -129,24 +129,6 @@ void cmDocumentationFormatterDocbook
   const std::vector<cmDocumentationEntry> &entries =
     section.GetEntries();
 
-  if (!entries.empty())
-    {
-    os << "<itemizedlist>\n";
-    for(std::vector<cmDocumentationEntry>::const_iterator op
-          = entries.begin(); op != entries.end(); ++ op )
-      {
-      if(op->Name.size())
-        {
-        os << "    <listitem><link linkend=\"" << prefix << "_";
-        cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
-        os << "\"><emphasis><literal>";
-        cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
-        os << "</literal></emphasis></link></listitem>\n";
-        }
-      }
-    os << "</itemizedlist>\n" ;
-    }
-
   for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
       op != entries.end();)
     {
-- 
1.7.11.msysgit.1

From 00875c561f58c3169757f9e64e148200b4ac380d Mon Sep 17 00:00:00 2001
From: Daniel Pfeifer <daniel@pfeifer-mail.de>
Date: Fri, 7 Sep 2012 10:35:08 +0200
Subject: [PATCH 2/7] Factor out code to write valid DocBook IDs

Attributes in XML may contain alphanumeric characters, underscores, colons and
dots. When DocBook is chunked, the dot is often used as a path separator.
To generate a valid ID, we take the title of the section, transform all
non-alphanumeric characters to underscores and then add a prefix separated with
dots. We also add the document name as a prefix, in order to 'xinclude'
eg. cmake.docbook and ctest.docbook in the same document.
IDs are written in multiple places, so the code is factored to a function.
---
 Source/cmDocumentationFormatterDocbook.cxx | 72 +++++++++++++++---------------
 Source/cmDocumentationFormatterDocbook.h   |  2 +
 2 files changed, 37 insertions(+), 37 deletions(-)

diff --git a/Source/cmDocumentationFormatterDocbook.cxx b/Source/cmDocumentationFormatterDocbook.cxx
index af32d38..c3cd132 100644
--- a/Source/cmDocumentationFormatterDocbook.cxx
+++ b/Source/cmDocumentationFormatterDocbook.cxx
@@ -11,6 +11,8 @@
 ============================================================================*/
 #include "cmDocumentationFormatterDocbook.h"
 #include "cmDocumentationSection.h"
+#include <algorithm>
+#include <cctype>
 //----------------------------------------------------------------------------
 
 // this function is a copy of the one in the HTML formatter
@@ -107,21 +109,9 @@ void cmDocumentationFormatterDocbook
 {
   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";
-      }
+    os << "<sect1 id=\"";
+    this->PrintId(os, 0, name);
+    os << "\">\n<title>" << name << "</title>\n";
     }
 
   std::string prefix = this->ComputeSectionLinkPrefix(name);
@@ -138,28 +128,8 @@ void cmDocumentationFormatterDocbook
         {
         if(op->Name.size())
           {
-          os << "    <para id=\"" << prefix << "_";
-          cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
-
-          // make sure that each id exists only once.  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 = prefix;
-          id += "_";
-          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 << "    <para id=\"";
+          this->PrintId(os, prefix.c_str(), op->Name);
           os << "\"><sect2><title>";
           cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
           os << "</title></sect2> ";
@@ -213,6 +183,8 @@ void cmDocumentationFormatterDocbook::PrintHeader(const char* docname,
                                                   const char* appname,
                                                   std::ostream& os)
 {
+  this->docname = docname;
+
   // 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.
@@ -235,3 +207,29 @@ void cmDocumentationFormatterDocbook::PrintFooter(std::ostream& os)
   os << "</article>\n";
 }
 
+//----------------------------------------------------------------------------
+void cmDocumentationFormatterDocbook
+::PrintId(std::ostream& os, const char* prefix, std::string id)
+{
+  std::replace_if(id.begin(), id.end(), std::not1(std::ptr_fun(isalnum)), '_');
+  if(prefix)
+    {
+    id.insert(0, 1, '.');
+    id.insert(0, prefix);
+    }
+  os << this->docname << '.' << id;
+
+  // make sure that each id exists only once.  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
+  if (this->EmittedLinkIds.find(id) == this->EmittedLinkIds.end())
+    {
+    this->EmittedLinkIds.insert(id);
+    }
+  else
+    {
+    static unsigned int i=0;
+    os << i++;
+    }
+}
diff --git a/Source/cmDocumentationFormatterDocbook.h b/Source/cmDocumentationFormatterDocbook.h
index 213948d..6c96900 100644
--- a/Source/cmDocumentationFormatterDocbook.h
+++ b/Source/cmDocumentationFormatterDocbook.h
@@ -35,7 +35,9 @@ public:
   virtual void PrintPreformatted(std::ostream& os, const char* text);
   virtual void PrintParagraph(std::ostream& os, const char* text);
 private:
+  void PrintId(std::ostream& os, const char* prefix, std::string id);
   std::set<std::string> EmittedLinkIds;
+  std::string docname;
 };
 
 #endif
-- 
1.7.11.msysgit.1

From 2a5c64c1e3cae93163e831439ebcc10a849e3dce Mon Sep 17 00:00:00 2001
From: Daniel Pfeifer <daniel@pfeifer-mail.de>
Date: Fri, 7 Sep 2012 10:35:55 +0200
Subject: [PATCH 3/7] Fixed the DocBook output for sections.

The DocBook formatter used to generate something like:

  <para id="section"><sect2><title>Title</title></sect2>Some Text</para>

Which was completely wrong. In DocBook, a section should look like this:

  <sect2 id="section"><title>Title</title><para>Some Text</para></sect2>
---
 Source/cmDocumentationFormatterDocbook.cxx | 39 ++++++++++++------------------
 1 file changed, 15 insertions(+), 24 deletions(-)

diff --git a/Source/cmDocumentationFormatterDocbook.cxx b/Source/cmDocumentationFormatterDocbook.cxx
index c3cd132..c1782a3 100644
--- a/Source/cmDocumentationFormatterDocbook.cxx
+++ b/Source/cmDocumentationFormatterDocbook.cxx
@@ -120,40 +120,31 @@ void cmDocumentationFormatterDocbook
     section.GetEntries();
 
   for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
-      op != entries.end();)
+      op != entries.end(); ++op)
     {
     if(op->Name.size())
       {
-      for(;op != entries.end() && op->Name.size(); ++op)
+      os << "<sect2 id=\"";
+      this->PrintId(os, prefix.c_str(), op->Name);
+      os << "\">\n<title>";
+      cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
+      os << "</title>\n";
+      if(op->Full.size())
         {
-        if(op->Name.size())
-          {
-          os << "    <para id=\"";
-          this->PrintId(os, prefix.c_str(), op->Name);
-          os << "\"><sect2><title>";
-          cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
-          os << "</title></sect2> ";
-          }
+        os << "<abstract>\n<para>";
         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";
+        os << "</para>\n</abstract>\n";
+        this->PrintFormatted(os, op->Full.c_str());
         }
+      else
+        {
+        this->PrintFormatted(os, op->Brief.c_str());
+        }
+      os << "</sect2>\n";
       }
     else
       {
       this->PrintFormatted(os, op->Brief.c_str());
-      os << "\n";
-      ++op;
       }
     }
   if(name)
-- 
1.7.11.msysgit.1

From 2474e1afe0df6eeed0b74e75008a048fcd9a4517 Mon Sep 17 00:00:00 2001
From: Daniel Pfeifer <daniel@pfeifer-mail.de>
Date: Fri, 7 Sep 2012 10:41:49 +0200
Subject: [PATCH 4/7] Cleanup of DocBook formatter and generated DocBook

Comment and whitespace changes, changed docbook version to 4.5, changed
<literallayout> to <programlisting> (the latter implies a fixed-size font).
---
 Source/cmDocumentationFormatterDocbook.cxx | 48 +++++++++++++++---------------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/Source/cmDocumentationFormatterDocbook.cxx b/Source/cmDocumentationFormatterDocbook.cxx
index c1782a3..5169337 100644
--- a/Source/cmDocumentationFormatterDocbook.cxx
+++ b/Source/cmDocumentationFormatterDocbook.cxx
@@ -96,28 +96,24 @@ void cmDocumentationPrintDocbookEscapes(std::ostream& os, const char* text)
     }
 }
 
-
+//----------------------------------------------------------------------------
 cmDocumentationFormatterDocbook::cmDocumentationFormatterDocbook()
 :cmDocumentationFormatter()
 {
 }
 
+//----------------------------------------------------------------------------
 void cmDocumentationFormatterDocbook
 ::PrintSection(std::ostream& os,
                const cmDocumentationSection &section,
                const char* name)
 {
-  if(name)
-    {
-    os << "<sect1 id=\"";
-    this->PrintId(os, 0, name);
-    os << "\">\n<title>" << name << "</title>\n";
-    }
+  os << "<sect1 id=\"";
+  this->PrintId(os, 0, name);
+  os << "\">\n<title>" << name << "</title>\n";
 
   std::string prefix = this->ComputeSectionLinkPrefix(name);
-
-  const std::vector<cmDocumentationEntry> &entries =
-    section.GetEntries();
+  const std::vector<cmDocumentationEntry> &entries = section.GetEntries();
 
   for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
       op != entries.end(); ++op)
@@ -147,32 +143,36 @@ void cmDocumentationFormatterDocbook
       this->PrintFormatted(os, op->Brief.c_str());
       }
     }
-  if(name)
+
+  // empty sections are not allowed in docbook.
+  if(entries.empty())
     {
-    os << "</sect1>\n";
+    os << "<para/>\n";
     }
+
+  os << "</sect1>\n";
 }
 
-void cmDocumentationFormatterDocbook::PrintPreformatted(std::ostream& os,
-                                                     const char* text)
+//----------------------------------------------------------------------------
+void cmDocumentationFormatterDocbook
+::PrintPreformatted(std::ostream& os, const char* text)
 {
-  os << "<literallayout>";
+  os << "<programlisting>";
   cmDocumentationPrintDocbookEscapes(os, text);
-  os << "</literallayout>\n    ";
+  os << "</programlisting>\n";
 }
 
-void cmDocumentationFormatterDocbook::PrintParagraph(std::ostream& os,
-                                                  const char* text)
+void cmDocumentationFormatterDocbook
+::PrintParagraph(std::ostream& os, const char* text)
 {
   os << "<para>";
   cmDocumentationPrintDocbookEscapes(os, text);
-  os << "</para>";
+  os << "</para>\n";
 }
 
 //----------------------------------------------------------------------------
-void cmDocumentationFormatterDocbook::PrintHeader(const char* docname,
-                                                  const char* appname,
-                                                  std::ostream& os)
+void cmDocumentationFormatterDocbook
+::PrintHeader(const char* docname, const char* appname, std::ostream& os)
 {
   this->docname = docname;
 
@@ -182,8 +182,8 @@ void cmDocumentationFormatterDocbook::PrintHeader(const char* docname,
   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"
+        "<!DOCTYPE article PUBLIC \"-//OASIS//DTD DocBook V4.5//EN\" "
+        "\"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\" [\n"
         "<!ENTITY % addindex \"IGNORE\">\n"
         "<!ENTITY % English \"INCLUDE\"> ]>\n"
         "<article>\n"
-- 
1.7.11.msysgit.1

From aac62164e5b252fff406da15f8e731b0cb68218f Mon Sep 17 00:00:00 2001
From: Daniel Pfeifer <daniel@pfeifer-mail.de>
Date: Fri, 7 Sep 2012 10:55:58 +0200
Subject: [PATCH 5/7] Add support for <abstract> at section level 1 in DocBook
 formatter.

If a section has subsections (ie. subelemens with a title), all elements before
the first title are written inside an <abstract>.
Also wrap <programlisting> in <para>, to allow preformatted output in abstracts.
---
 Source/cmDocumentationFormatterDocbook.cxx | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/Source/cmDocumentationFormatterDocbook.cxx b/Source/cmDocumentationFormatterDocbook.cxx
index 5169337..8aeaccd 100644
--- a/Source/cmDocumentationFormatterDocbook.cxx
+++ b/Source/cmDocumentationFormatterDocbook.cxx
@@ -115,11 +115,28 @@ void cmDocumentationFormatterDocbook
   std::string prefix = this->ComputeSectionLinkPrefix(name);
   const std::vector<cmDocumentationEntry> &entries = section.GetEntries();
 
+  bool hasSubSections = false;
   for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
       op != entries.end(); ++op)
     {
     if(op->Name.size())
       {
+      hasSubSections = true;
+      break;
+      }
+    }
+ 
+  bool inAbstract = false;
+  for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
+      op != entries.end(); ++op)
+    {
+    if(op->Name.size())
+      {
+      if(inAbstract)
+        {
+        os << "</abstract>\n";
+        inAbstract = false;
+        }
       os << "<sect2 id=\"";
       this->PrintId(os, prefix.c_str(), op->Name);
       os << "\">\n<title>";
@@ -140,6 +157,11 @@ void cmDocumentationFormatterDocbook
       }
     else
       {
+      if(hasSubSections && op == entries.begin())
+        {
+        os << "<abstract>\n";
+        inAbstract = true;
+        }
       this->PrintFormatted(os, op->Brief.c_str());
       }
     }
@@ -157,9 +179,9 @@ void cmDocumentationFormatterDocbook
 void cmDocumentationFormatterDocbook
 ::PrintPreformatted(std::ostream& os, const char* text)
 {
-  os << "<programlisting>";
+  os << "<para>\n<programlisting>";
   cmDocumentationPrintDocbookEscapes(os, text);
-  os << "</programlisting>\n";
+  os << "</programlisting>\n</para>\n";
 }
 
 void cmDocumentationFormatterDocbook
-- 
1.7.11.msysgit.1

From e84258936f4fa0eb84c0362a301bc8f5d0dccc48 Mon Sep 17 00:00:00 2001
From: Daniel Pfeifer <daniel@pfeifer-mail.de>
Date: Fri, 7 Sep 2012 13:00:31 +0200
Subject: [PATCH 7/7] Fix offending part of cmDocumentation that caused
 invalid DocBook

If a subsection with a title is added, all subsequent subsections need a title too.
---
 Source/cmDocumentation.cxx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx
index 1b042ae..cb40abc 100644
--- a/Source/cmDocumentation.cxx
+++ b/Source/cmDocumentation.cxx
@@ -148,8 +148,7 @@ static const char *cmDocumentationStandardSeeAlso[][3] =
    "The list is member-post-only but one may sign up on the CMake web page. "
    "Please first read the full documentation at "
    "http://www.cmake.org before posting questions to the list."},
-  {0,
-   "Summary of helpful links:\n"
+  {"Summary of helpful links",
    "  Home: http://www.cmake.org\n"
    "  Docs: http://www.cmake.org/HTML/Documentation.html\n"
    "  Mail: http://www.cmake.org/HTML/MailingLists.html\n"
-- 
1.7.11.msysgit.1