Source/cmDocumentationFormatterDocbook.cxx

   1 /*=========================================================================
   2
   3   Program:   CMake - Cross-Platform Makefile Generator
   4   Module:    $RCSfile: cmDocumentationFormatterDocbook.cxx,v $
   5   Language:  C++
   6   Date:      $Date: 2009-01-10 14:01:37 $
   7   Version:   $Revision: 1.5 $
   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   std::string prefix = this->ComputeSectionLinkPrefix(name);
 133
 134   const std::vector<cmDocumentationEntry> &entries =
 135     section.GetEntries();
 136
 137   if (!entries.empty())
 138     {
 139     os << "<itemizedlist>\n";
 140     for(std::vector<cmDocumentationEntry>::const_iterator op
 141           = entries.begin(); op != entries.end(); ++ op )
 142       {
 143       if(op->Name.size())
 144         {
 145         os << "    <listitem><link linkend=\"" << prefix << "_";
 146         cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
 147         os << "\"><emphasis><literal>";
 148         cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
 149         os << "</literal></emphasis></link></listitem>\n";
 150         }
 151       }
 152     os << "</itemizedlist>\n" ;
 153     }
 154
 155   for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
 156       op != entries.end();)
 157     {
 158     if(op->Name.size())
 159       {
 160       for(;op != entries.end() && op->Name.size(); ++op)
 161         {
 162         if(op->Name.size())
 163           {
 164           os << "    <para id=\"" << prefix << "_";
 165           cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
 166
 167           // make sure that each id exists only once.  Since it seems
 168           // not easily possible to determine which link refers to which id,
 169           // we have at least to make sure that the duplicated id's get a
 170           // different name (by appending an increasing number), Alex
 171           std::string id = prefix;
 172           id += "_";
 173           id += op->Name;
 174           if (this->EmittedLinkIds.find(id) == this->EmittedLinkIds.end())
 175             {
 176             this->EmittedLinkIds.insert(id);
 177             }
 178           else
 179             {
 180             static unsigned int i=0;
 181             i++;
 182             os << i;
 183             }
 184           // continue as normal...
 185
 186           os << "\"><sect2><title>";
 187           cmDocumentationPrintDocbookEscapes(os, op->Name.c_str());
 188           os << "</title></sect2> ";
 189           }
 190         cmDocumentationPrintDocbookEscapes(os, op->Brief.c_str());
 191         if(op->Name.size())
 192           {
 193           os << "</para>\n";
 194           }
 195
 196         if(op->Full.size())
 197           {
 198           // a line break seems to be simply a line break with docbook
 199           os << "\n    ";
 200           this->PrintFormatted(os, op->Full.c_str());
 201           }
 202         os << "\n";
 203         }
 204       }
 205     else
 206       {
 207       this->PrintFormatted(os, op->Brief.c_str());
 208       os << "\n";
 209       ++op;
 210       }
 211     }
 212   if(name)
 213     {
 214     os << "</sect1>\n";
 215     }
 216 }
 217
 218 void cmDocumentationFormatterDocbook::PrintPreformatted(std::ostream& os,
 219                                                      const char* text)
 220 {
 221   os << "<literallayout>";
 222   cmDocumentationPrintDocbookEscapes(os, text);
 223   os << "</literallayout>\n    ";
 224 }
 225
 226 void cmDocumentationFormatterDocbook::PrintParagraph(std::ostream& os,
 227                                                   const char* text)
 228 {
 229   os << "<para>";
 230   cmDocumentationPrintDocbookEscapes(os, text);
 231   os << "</para>";
 232 }
 233
 234 //----------------------------------------------------------------------------
 235 void cmDocumentationFormatterDocbook::PrintHeader(const char* docname,
 236                                                   const char* appname,
 237                                                   std::ostream& os)
 238 {
 239   // this one is used to ensure that we don't create multiple link targets
 240   // with the same name. We can clear it here since we are at the
 241   // start of a document here.
 242   this->EmittedLinkIds.clear();
 243
 244   os << "<?xml version=\"1.0\" ?>\n"
 245         "<!DOCTYPE article PUBLIC \"-//OASIS//DTD DocBook V4.2//EN\" "
 246         "\"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd\" [\n"
 247         "<!ENTITY % addindex \"IGNORE\">\n"
 248         "<!ENTITY % English \"INCLUDE\"> ]>\n"
 249         "<article>\n"
 250         "<articleinfo>\n"
 251         "<title>" << docname << " - " << appname << "</title>\n"
 252         "</articleinfo>\n";
 253 }
 254
 255 //----------------------------------------------------------------------------
 256 void cmDocumentationFormatterDocbook::PrintFooter(std::ostream& os)
 257 {
 258   os << "</article>\n";
 259 }
 260