CMakeLua/Source/cmDocumentationFormatterDocbook.cxx

   1 /*=========================================================================
   2
   3   Program:   CMake - Cross-Platform Makefile Generator
   4   Module:    $RCSfile: cmDocumentationFormatterDocbook.cxx,v $
   5   Language:  C++
   6   Date:      $Date: 2008/02/19 19:33:43 $
   7   Version:   $Revision: 1.1 $
   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 #include "cmDocumentationFormatterDocbook.h"
  18 #include "cmDocumentationSection.h"
  19 //----------------------------------------------------------------------------
  20
  21 // this function is a copy of the one in the HTML formatter
  22 // the three functions below are slightly modified copies
  23 static bool cmDocumentationIsHyperlinkCharDocbook(char c)
  24 {
  25   // This is not a complete list but works for CMake documentation.
  26   return ((c >= 'A' && c <= 'Z') ||
  27           (c >= 'a' && c <= 'z') ||
  28           (c >= '0' && c <= '9') ||
  29           c == '-' || c == '.' || c == '/' || c == '~' || c == '@' ||
  30           c == ':' || c == '_' || c == '&' || c == '?' || c == '=');
  31 }
  32
  33 //----------------------------------------------------------------------------
  34 static void cmDocumentationPrintDocbookChar(std::ostream& os, char c)
  35 {
  36   // Use an escape sequence if necessary.
  37   switch(c)
  38   {
  39     case '<':
  40       os << "&lt;";
  41       break;
  42     case '>':
  43       os << "&gt;";
  44       break;
  45     case '&':
  46       os << "&amp;";
  47       break;
  48     default:
  49       os << c;
  50   }
  51 }
  52
  53 //----------------------------------------------------------------------------
  54 const char* cmDocumentationPrintDocbookLink(std::ostream& os,const char* begin)
  55 {
  56   // Look for the end of the link.
  57   const char* end = begin;
  58   while(cmDocumentationIsHyperlinkCharDocbook(*end))
  59     {
  60     ++end;
  61     }
  62
  63   // Print the hyperlink itself.
  64   os << "<ulink url=\"";
  65   for(const char* c = begin; c != end; ++c)
  66     {
  67     cmDocumentationPrintDocbookChar(os, *c);
  68     }
  69   os << "\" />";
  70
  71   return end;
  72 }
  73
  74 //----------------------------------------------------------------------------
  75 void cmDocumentationPrintDocbookEscapes(std::ostream& os, const char* text)
  76 {
  77   // Hyperlink prefixes.
  78   static const char* hyperlinks[] = {"http://", "ftp://", "mailto:", 0};
  79
  80   // Print each character.
  81   for(const char* p = text; *p;)
  82     {
  83     // Handle hyperlinks specially to make them active.
  84     bool found_hyperlink = false;
  85     for(const char** h = hyperlinks; !found_hyperlink && *h; ++h)
  86       {
  87       if(strncmp(p, *h, strlen(*h)) == 0)
  88         {
  89         p = cmDocumentationPrintDocbookLink(os, p);
  90         found_hyperlink = true;
  91         }
  92       }
  93
  94     // Print other characters normally.
  95     if(!found_hyperlink)
  96       {
  97       cmDocumentationPrintDocbookChar(os, *p++);
  98       }
  99     }
 100 }
 101
 102
 103 cmDocumentationFormatterDocbook::cmDocumentationFormatterDocbook()
 104 :cmDocumentationFormatter()
 105 {
 106 }
 107
 108 void cmDocumentationFormatterDocbook
 109 ::PrintSection(std::ostream& os,
 110                const cmDocumentationSection &section,
 111                const char* name)
 112 {
 113   if(name)
 114     {
 115     std::string id = "section_";
 116     id += name;
 117     if (this->EmittedLinkIds.find(id) == this->EmittedLinkIds.end())
 118       {
 119       this->EmittedLinkIds.insert(id);
 120       os << "<sect1 id=\"section_" << name << "\">\n"
 121             "<title>\n" << name << "</title>\n";
 122       }
 123     else
 124       {
 125       static unsigned int i=0;
 126       i++;
 127       os << "<sect1 id=\"section_" << name << i << "\">\n"
 128             "<title>\n" << name << "</title>\n";
 129       }
 130     }
 131
 132   const std::vector<cmDocumentationEntry> &entries =
 133     section.GetEntries();
 134
 135   os << "<itemizedlist>\n";
 136   for(std::vector<cmDocumentationEntry>::const_iterator op
 137         = entries.begin(); op != entries.end(); ++ op )
 138     {
 139     if(op->Name.size())
 140       {
 141       os << "    <listitem><link linkend=\"command_";
 142       cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
 143       os << "\"><emphasis><literal>";
 144       cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
 145       os << "</literal></emphasis></link></listitem>";
 146       }
 147     }
 148   os << "</itemizedlist>\n" ;
 149
 150   for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
 151       op != entries.end();)
 152     {
 153     if(op->Name.size())
 154       {
 155       for(;op != entries.end() && op->Name.size(); ++op)
 156         {
 157         if(op->Name.size())
 158           {
 159           os << "    <para id=\"command_";
 160           cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
 161
 162           // make sure that each id exists only once, e.g.
 163           // command_COMPILE_DEFINITIONS exists at least twice. Since it seems
 164           // not easily possible to determine which link refers to which id,
 165           // we have at least to make sure that the duplicated id's get a
 166           // different name (by appending an increasing number), Alex
 167           std::string id = "command_";
 168           id += op->Name;
 169           if (this->EmittedLinkIds.find(id) == this->EmittedLinkIds.end())
 170             {
 171             this->EmittedLinkIds.insert(id);
 172             }
 173           else
 174             {
 175             static unsigned int i=0;
 176             i++;
 177             os << i;
 178             }
 179           // continue as normal...
 180
 181           os << "\"><sect2><title>";
 182           cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
 183           os << "</title></sect2> ";
 184           }
 185         cmDocumentationPrintDocbookEscapes(os, op->Brief.c_str());
 186         if(op->Name.size())
 187           {
 188           os << "</para>\n";
 189           }
 190
 191         if(op->Full.size())
 192           {
 193           // a line break seems to be simply a line break with docbook
 194           os << "\n    ";
 195           this->PrintFormatted(os, op->Full.c_str());
 196           }
 197         os << "\n";
 198         }
 199       }
 200     else
 201       {
 202       this->PrintFormatted(os, op->Brief.c_str());
 203       os << "\n";
 204       ++op;
 205       }
 206     }
 207   if(name)
 208     {
 209     os << "</sect1>\n";
 210     }
 211 }
 212
 213 void cmDocumentationFormatterDocbook::PrintPreformatted(std::ostream& os,
 214                                                      const char* text)
 215 {
 216   os << "<literallayout>";
 217   cmDocumentationPrintDocbookEscapes(os, text);
 218   os << "</literallayout>\n    ";
 219 }
 220
 221 void cmDocumentationFormatterDocbook::PrintParagraph(std::ostream& os,
 222                                                   const char* text)
 223 {
 224   os << "<para>";
 225   cmDocumentationPrintDocbookEscapes(os, text);
 226   os << "</para>";
 227 }
 228
 229 //----------------------------------------------------------------------------
 230 void cmDocumentationFormatterDocbook::PrintHeader(const char* name,
 231                                                std::ostream& os)
 232 {
 233   // this one is used to ensure that we don't create multiple link targets
 234   // with the same name. We can clear it here since we are at the
 235   // start of a document here.
 236   this->EmittedLinkIds.clear();
 237
 238   os << "<?xml version=\"1.0\" ?>\n"
 239         "<!DOCTYPE article PUBLIC \"-//OASIS//DTD DocBook V4.2//EN\" "
 240         "\"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd\" [\n"
 241         "<!ENTITY % addindex \"IGNORE\">\n"
 242         "<!ENTITY % English \"INCLUDE\"> ]>\n"
 243         "<article>\n"
 244         "<articleinfo>\n"
 245         "<title>" << name << "</title>\n"
 246         "</articleinfo>\n";
 247 }
 248
 249 //----------------------------------------------------------------------------
 250 void cmDocumentationFormatterDocbook::PrintFooter(std::ostream& os)
 251 {
 252   os << "</article>\n";
 253 }
 254