View Issue Details [ Jump to Notes ]

Project

Tags

No tags attached.

cmake-cfs-htmldocs.patch [^] (3,869 bytes) 2010-02-26 08:42 [Show Content] [Hide Content]

diff -r -u --exclude '*~' cmake-2.8.0/Source/cmDocumentationFormatterHTML.cxx cmake-2.8.0.patched/Source/cmDocumentationFormatterHTML.cxx
--- cmake-2.8.0/Source/cmDocumentationFormatterHTML.cxx	2009-11-13 18:32:55.000000000 +0000
+++ cmake-2.8.0.patched/Source/cmDocumentationFormatterHTML.cxx	2010-02-26 13:36:20.455490858 +0000
@@ -39,7 +39,7 @@
       os << "&amp;";
       break;
     case '\n':
-      os << "<br>";
+      os << "<br />";
       break;
     default:
       os << c;
@@ -125,23 +125,33 @@
     {
     if (name)
       {
-      os << "<h2><a name=\"section_" << name << "\"/>" << name << "</h2>\n";
+      os << "<h2><a name=\"section_";
+      cmDocumentationPrintHTMLId(os, name);
+      os << "\"/>" << name << "</h2>\n";
       }
 
-    os << "<ul>\n";
+    // Is a list needed?
     for(std::vector<cmDocumentationEntry>::const_iterator op 
          = entries.begin(); op != entries.end(); ++ op )
       {
-      if(op->Name.size())
-         {
-         os << "    <li><a href=\"#" << prefix << ":";
-         cmDocumentationPrintHTMLId(os, op->Name.c_str());
-         os << "\"><b><code>";
-         this->PrintHTMLEscapes(os, op->Name.c_str());
-         os << "</code></b></a></li>";
-         }
+      if (op->Name.size())
+        {
+        os << "<ul>\n";
+        for(;op != entries.end() && op->Name.size(); ++op)
+          {
+          if(op->Name.size())
+            {
+            os << "    <li><a href=\"#" << prefix << ":";
+            cmDocumentationPrintHTMLId(os, op->Name.c_str());
+            os << "\"><b><code>";
+            this->PrintHTMLEscapes(os, op->Name.c_str());
+            os << "</code></b></a></li>";
+            }
+          }
+        os << "</ul>\n" ;
+        break; // Skip outer loop termination test
+        }
       }
-    os << "</ul>\n" ;
     }
 
   for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin(); 
@@ -164,7 +174,7 @@
         this->PrintHTMLEscapes(os, op->Brief.c_str());
         if(op->Full.size())
           {
-          os << "<br>\n    ";
+          os << "<br />\n    ";
           this->PrintFormatted(os, op->Full.c_str());
           }
         os << "\n";
@@ -194,6 +204,7 @@
 {
   os << "<p>";
   this->PrintHTMLEscapes(os, text);
+  os << "</p>\n";
 }
 
 //----------------------------------------------------------------------------
@@ -201,7 +212,12 @@
                                                const char* appname,
                                                std::ostream& os)
 {
-  os << "<html><head><title>";
+  os << "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\""
+     << " \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">\n";
+  os << "<html xmlns=\"http://www.w3.org/1999/xhtml\""
+     << " xml:lang=\"en\" lang=\"en\">\n";
+  os << "<head><meta http-equiv=\"Content-Type\" "
+     << "content=\"text/html;charset=utf-8\" /><title>";
   os << docname << " - " << appname;
   os << "</title></head><body>\n";
 }
@@ -253,16 +269,20 @@
     return;
     }
 
-  os << "<h2><a name=\"section_Index\"/>Master Index "
+  os << "<h2><a name=\"section_Index\">Master Index "
      << "CMake " << cmVersion::GetCMakeVersion()
-     << "</h2>\n";
-  os << "<ul>\n";
-  for(unsigned int i=0; i < sections.size(); ++i)
-    {
-    std::string name = sections[i]->
-      GetName((this->GetForm()));
-    os << "  <li><a href=\"#section_" 
-       << name << "\"<b>" << name << "</b></a></li>\n";
+     << "</a></h2>\n";
+  
+  if (!sections.empty())
+    {
+    os << "<ul>\n";
+    for(unsigned int i=0; i < sections.size(); ++i)
+      {
+      std::string name = sections[i]->GetName((this->GetForm()));
+      os << "  <li><a href=\"#section_";
+      cmDocumentationPrintHTMLId(os, name.c_str());
+      os << "\"><b>" << name << "</b></a></li>\n";
+      }
+    os << "</ul>\n";
     }
-  os << "</ul>\n";
 }

0001-Ensure-that-the-HTML-documentation-generated-by-CMak.patch [^] (4,683 bytes) 2010-03-01 07:22 [Show Content] [Hide Content]

From 707c547a8138d31b74a92db70c840aa91686a6c2 Mon Sep 17 00:00:00 2001
From: Simon Harvey <simon.harvey@cambridgeflowsolutions.com>
Date: Mon, 1 Mar 2010 12:15:25 +0000
Subject: [PATCH] Ensure that the HTML documentation generated by CMake is "XHTML 1.0 Strict"-compliant.
 - All tags are properly closed and DOCTYPE is specified
 - Useful for downstream XML-processors (e.g. for extracting section titles)
 Signed-off-by: Simon Harvey <simon.harvey@cambridgeflowsolutions.com>

---
 Source/cmDocumentationFormatterHTML.cxx |   66 ++++++++++++++++++++-----------
 1 files changed, 43 insertions(+), 23 deletions(-)

diff --git a/Source/cmDocumentationFormatterHTML.cxx b/Source/cmDocumentationFormatterHTML.cxx
index 09aff8d..4d3a44e 100644
--- a/Source/cmDocumentationFormatterHTML.cxx
+++ b/Source/cmDocumentationFormatterHTML.cxx
@@ -39,7 +39,7 @@ static void cmDocumentationPrintHTMLChar(std::ostream& os, char c)
       os << "&amp;";
       break;
     case '\n':
-      os << "<br>";
+      os << "<br />";
       break;
     default:
       os << c;
@@ -125,23 +125,33 @@ void cmDocumentationFormatterHTML
     {
     if (name)
       {
-      os << "<h2><a name=\"section_" << name << "\"/>" << name << "</h2>\n";
+      os << "<h2><a name=\"section_";
+      cmDocumentationPrintHTMLId(os, name);
+      os << "\"/>" << name << "</h2>\n";
       }
 
-    os << "<ul>\n";
+    // Is a list needed?
     for(std::vector<cmDocumentationEntry>::const_iterator op 
          = entries.begin(); op != entries.end(); ++ op )
       {
-      if(op->Name.size())
-         {
-         os << "    <li><a href=\"#" << prefix << ":";
-         cmDocumentationPrintHTMLId(os, op->Name.c_str());
-         os << "\"><b><code>";
-         this->PrintHTMLEscapes(os, op->Name.c_str());
-         os << "</code></b></a></li>";
-         }
+      if (op->Name.size())
+        {
+        os << "<ul>\n";
+        for(;op != entries.end() && op->Name.size(); ++op)
+          {
+          if(op->Name.size())
+            {
+            os << "    <li><a href=\"#" << prefix << ":";
+            cmDocumentationPrintHTMLId(os, op->Name.c_str());
+            os << "\"><b><code>";
+            this->PrintHTMLEscapes(os, op->Name.c_str());
+            os << "</code></b></a></li>";
+            }
+          }
+        os << "</ul>\n" ;
+        break; // Skip outer loop termination test
+        }
       }
-    os << "</ul>\n" ;
     }
 
   for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin(); 
@@ -164,7 +174,7 @@ void cmDocumentationFormatterHTML
         this->PrintHTMLEscapes(os, op->Brief.c_str());
         if(op->Full.size())
           {
-          os << "<br>\n    ";
+          os << "<br />\n    ";
           this->PrintFormatted(os, op->Full.c_str());
           }
         os << "\n";
@@ -194,6 +204,7 @@ void cmDocumentationFormatterHTML::PrintParagraph(std::ostream& os,
 {
   os << "<p>";
   this->PrintHTMLEscapes(os, text);
+  os << "</p>\n";
 }
 
 //----------------------------------------------------------------------------
@@ -201,7 +212,12 @@ void cmDocumentationFormatterHTML::PrintHeader(const char* docname,
                                                const char* appname,
                                                std::ostream& os)
 {
-  os << "<html><head><title>";
+  os << "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\""
+     << " \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">\n";
+  os << "<html xmlns=\"http://www.w3.org/1999/xhtml\""
+     << " xml:lang=\"en\" lang=\"en\">\n";
+  os << "<head><meta http-equiv=\"Content-Type\" "
+     << "content=\"text/html;charset=utf-8\" /><title>";
   os << docname << " - " << appname;
   os << "</title></head><body>\n";
 }
@@ -253,16 +269,20 @@ void cmDocumentationFormatterHTML
     return;
     }
 
-  os << "<h2><a name=\"section_Index\"/>Master Index "
+  os << "<h2><a name=\"section_Index\">Master Index "
      << "CMake " << cmVersion::GetCMakeVersion()
-     << "</h2>\n";
-  os << "<ul>\n";
-  for(unsigned int i=0; i < sections.size(); ++i)
+     << "</a></h2>\n";
+  
+  if (!sections.empty())
     {
-    std::string name = sections[i]->
-      GetName((this->GetForm()));
-    os << "  <li><a href=\"#section_" 
-       << name << "\"<b>" << name << "</b></a></li>\n";
+    os << "<ul>\n";
+    for(unsigned int i=0; i < sections.size(); ++i)
+      {
+      std::string name = sections[i]->GetName((this->GetForm()));
+      os << "  <li><a href=\"#section_";
+      cmDocumentationPrintHTMLId(os, name.c_str());
+      os << "\"><b>" << name << "</b></a></li>\n";
+      }
+    os << "</ul>\n";
     }
-  os << "</ul>\n";
 }
-- 
1.6.6.1

Relationships

related to

0010857

closed

Brad King

CMake.HTML test requires internet access

Notes
(0019642) simonh (reporter) 2010-02-26 08:45	I've uploaded a patch against 2.8.0 which addresses the above issues and makes the output "XHTML 1.0 Strict" compliant. This makes the output much easier for me to parse with our documentation generator - all tags are now correctly closed, i.e. fully XML compliant.

(0019651) Brad King (manager) 2010-02-26 13:50	Thanks! I have two requests: (1) CMake now uses Git, so we can credit you as author of the patch if we have a name and email address. Please either provide them here or clone the repository, create your commit, and use "git format-patch" to construct a new patch. http://www.cmake.org/Wiki/CMake/Git [^] (2) I'd like to add a test to CMake to validate the generated documentation. Can you suggest a command-line tool for xhtml validation?

(0019661) simonh (reporter) 2010-03-01 04:28	I'll take a look at (1) of 0010338:0019651 shortly. As for (2), I've used libxml2's xmllint, e.g. xmllint --valid --noout CMake.html This is part of a C-implemented XML library (part of Gnome). See http://xmlsoft.org/xmllint.html [^]

(0019662) simonh (reporter) 2010-03-01 07:23	Git patch now attached.

(0019664) Brad King (manager) 2010-03-01 08:58	Thanks. I've published it as commit 5771dd2f: http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=5771dd2f [^] with a couple other commits for cleanup and a test: http://cmake.org/gitweb?p=cmake.git;a=shortlog;h=370e5b94 [^]

Issue History
Date Modified	Username	Field	Change
2010-02-26 08:42	simonh	New Issue
2010-02-26 08:42	simonh	File Added: cmake-cfs-htmldocs.patch
2010-02-26 08:45	simonh	Note Added: 0019642
2010-02-26 13:18	Bill Hoffman	Status	new => assigned
2010-02-26 13:18	Bill Hoffman	Assigned To	=> Brad King
2010-02-26 13:50	Brad King	Note Added: 0019651
2010-03-01 04:28	simonh	Note Added: 0019661
2010-03-01 07:22	simonh	File Added: 0001-Ensure-that-the-HTML-documentation-generated-by-CMak.patch
2010-03-01 07:23	simonh	Note Added: 0019662
2010-03-01 08:58	Brad King	Note Added: 0019664
2010-03-01 08:58	Brad King	Status	assigned => closed
2010-03-01 08:58	Brad King	Resolution	open => fixed
2010-06-21 17:25	Brad King	Relationship added	related to 0010857