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