Hi, attached you can find a patch against current cmake cvs which adds support for generating the documentation as docbook file. (the patch is not yet ready to apply, it must still be cleaned up and documentation for that feature has to be added).
docook is useful as a bse format to convert the documentation to whatever format you like: html, pdf, ... (AFAIK). Can this e.g. in some way be used with Qt assistant ? For techbase.kde.org ? CMake generates docbook if the given filename ends with ".docbook": cmake --help-commands commands.docbook or cmake -DCMAKE_MODULE_PATH=/opt/kde4/share/apps/cmake/modules/ --help-custom-modules kdemods.cmake Please have a look and test, please also have a look at the generated docbook, I'm no specialist in this. Alex P.S. Allen: there is currently an issue with building KDE with cmake cvs (fix coming soon), so please use this only for testing the documentation
Index: CMakeLists.txt =================================================================== RCS file: /cvsroot/CMake/CMake/Source/CMakeLists.txt,v retrieving revision 1.393 diff -b -u -p -r1.393 CMakeLists.txt --- CMakeLists.txt 7 Feb 2008 21:14:05 -0000 1.393 +++ CMakeLists.txt 17 Feb 2008 19:06:07 -0000 @@ -115,6 +115,7 @@ SET(SRCS cmDocumentation.cxx cmDocumentationFormatter.cxx cmDocumentationFormatterHTML.cxx + cmDocumentationFormatterDocbook.cxx cmDocumentationFormatterMan.cxx cmDocumentationFormatterText.cxx cmDocumentationFormatterUsage.cxx Index: cmDocumentation.cxx =================================================================== RCS file: /cvsroot/CMake/CMake/Source/cmDocumentation.cxx,v retrieving revision 1.66 diff -b -u -p -r1.66 cmDocumentation.cxx --- cmDocumentation.cxx 17 Feb 2008 19:04:01 -0000 1.66 +++ cmDocumentation.cxx 17 Feb 2008 19:06:07 -0000 @@ -3,8 +3,8 @@ Program: CMake - Cross-Platform Makefile Generator Module: $RCSfile: cmDocumentation.cxx,v $ Language: C++ - Date: $Date: 2008/02/17 19:04:01 $ - Version: $Revision: 1.66 $ + Date: $Date: 2008/01/14 22:05:09 $ + Version: $Revision: 1.65 $ Copyright (c) 2002 Kitware, Inc., Insight Consortium. All rights reserved. See Copyright.txt or http://www.cmake.org/HTML/Copyright.html for details. @@ -324,6 +324,7 @@ void cmDocumentation::ClearSections() bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os) { if ((this->CurrentFormatter->GetForm() != HTMLForm) + && (this->CurrentFormatter->GetForm() != DocbookForm) && (this->CurrentFormatter->GetForm() != ManForm)) { this->PrintVersion(os); @@ -636,6 +637,11 @@ cmDocumentation::Form cmDocumentation::G return cmDocumentation::HTMLForm; } + if (ext == ".DOCBOOK") + { + return cmDocumentation::DocbookForm; + } + // ".1" to ".9" should be manpages if ((ext.length()==2) && (ext[1] >='1') && (ext[1]<='9')) { @@ -1373,6 +1379,9 @@ void cmDocumentation::SetForm(Form f) case HTMLForm: this->CurrentFormatter = &this->HTMLFormatter; break; + case DocbookForm: + this->CurrentFormatter = &this->DocbookFormatter; + break; case ManForm: this->CurrentFormatter = &this->ManFormatter; break; Index: cmDocumentation.h =================================================================== RCS file: /cvsroot/CMake/CMake/Source/cmDocumentation.h,v retrieving revision 1.31 diff -b -u -p -r1.31 cmDocumentation.h --- cmDocumentation.h 24 Oct 2007 15:36:47 -0000 1.31 +++ cmDocumentation.h 17 Feb 2008 19:06:08 -0000 @@ -21,6 +21,7 @@ #include "cmProperty.h" #include "cmDocumentationFormatter.h" #include "cmDocumentationFormatterHTML.h" +#include "cmDocumentationFormatterDocbook.h" #include "cmDocumentationFormatterMan.h" #include "cmDocumentationFormatterText.h" #include "cmDocumentationFormatterUsage.h" @@ -176,6 +177,7 @@ private: std::vector<RequestedHelpItem> RequestedHelpItems; cmDocumentationFormatter* CurrentFormatter; cmDocumentationFormatterHTML HTMLFormatter; + cmDocumentationFormatterDocbook DocbookFormatter; cmDocumentationFormatterMan ManFormatter; cmDocumentationFormatterText TextFormatter; cmDocumentationFormatterUsage UsageFormatter; Index: cmDocumentationFormatter.h =================================================================== RCS file: /cvsroot/CMake/CMake/Source/cmDocumentationFormatter.h,v retrieving revision 1.5 diff -b -u -p -r1.5 cmDocumentationFormatter.h --- cmDocumentationFormatter.h 24 Oct 2007 15:36:47 -0000 1.5 +++ cmDocumentationFormatter.h 17 Feb 2008 19:06:08 -0000 @@ -36,7 +36,7 @@ public: CompatCommands, Copyright, Version }; /** Forms of documentation output. */ - enum Form { TextForm, HTMLForm, ManForm, UsageForm }; + enum Form { TextForm, HTMLForm, ManForm, UsageForm, DocbookForm }; }; class cmDocumentationSection; Index: cmDocumentationFormatterDocbook.cxx =================================================================== RCS file: cmDocumentationFormatterDocbook.cxx diff -N cmDocumentationFormatterDocbook.cxx --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ cmDocumentationFormatterDocbook.cxx 17 Feb 2008 19:06:08 -0000 @@ -0,0 +1,252 @@ +/*========================================================================= + + Program: CMake - Cross-Platform Makefile Generator + Module: $RCSfile: cmDocumentationFormatterHTML.cxx,v $ + Language: C++ + Date: $Date: 2007/11/27 20:59:22 $ + Version: $Revision: 1.7 $ + + Copyright (c) 2002 Kitware, Inc., Insight Consortium. All rights reserved. + See Copyright.txt or http://www.cmake.org/HTML/Copyright.html for details. + + This software is distributed WITHOUT ANY WARRANTY; without even + the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR + PURPOSE. See the above copyright notices for more information. + +=========================================================================*/ +#include "cmDocumentationFormatterDocbook.h" +#include "cmDocumentationSection.h" +//---------------------------------------------------------------------------- + +static bool cmDocumentationIsHyperlinkCharDocbook(char c) +{ + // This is not a complete list but works for CMake documentation. + return ((c >= 'A' && c <= 'Z') || + (c >= 'a' && c <= 'z') || + (c >= '0' && c <= '9') || + c == '-' || c == '.' || c == '/' || c == '~' || c == '@' || + c == ':' || c == '_' || c == '&' || c == '?' || c == '='); +} + +//---------------------------------------------------------------------------- +static void cmDocumentationPrintDocbookChar(std::ostream& os, char c) +{ + // Use an escape sequence if necessary. + switch(c) + { + case '<': + os << "<"; + break; + case '>': + os << ">"; + break; + case '&': + os << "&"; + break; + default: + os << c; + } +} + +//---------------------------------------------------------------------------- +const char* cmDocumentationPrintDocbookLink(std::ostream& os,const char* begin) +{ + // Look for the end of the link. + const char* end = begin; + while(cmDocumentationIsHyperlinkCharDocbook(*end)) + { + ++end; + } + + // Print the hyperlink itself. + os << "<ulink url=\""; //<ulink url="http://www.cmake.org"; /> + for(const char* c = begin; c != end; ++c) + { + cmDocumentationPrintDocbookChar(os, *c); + } + os << "\" />"; + + return end; +} + +//---------------------------------------------------------------------------- +void cmDocumentationPrintDocbookEscapes(std::ostream& os, const char* text) +{ + // Hyperlink prefixes. + static const char* hyperlinks[] = {"http://";, "ftp://";, "mailto:", 0}; + + // Print each character. + for(const char* p = text; *p;) + { + // Handle hyperlinks specially to make them active. + bool found_hyperlink = false; + for(const char** h = hyperlinks; !found_hyperlink && *h; ++h) + { + if(strncmp(p, *h, strlen(*h)) == 0) + { + p = cmDocumentationPrintDocbookLink(os, p); + found_hyperlink = true; + } + } + + // Print other characters normally. + if(!found_hyperlink) + { + cmDocumentationPrintDocbookChar(os, *p++); + } + } +} + + +cmDocumentationFormatterDocbook::cmDocumentationFormatterDocbook() +:cmDocumentationFormatter() +{ +} + +void cmDocumentationFormatterDocbook +::PrintSection(std::ostream& os, + const cmDocumentationSection §ion, + const char* name) +{ + 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"; + } + } + + const std::vector<cmDocumentationEntry> &entries = + section.GetEntries(); + + os << "<itemizedlist>\n"; + for(std::vector<cmDocumentationEntry>::const_iterator op + = entries.begin(); op != entries.end(); ++ op ) + { + if(op->Name.size()) + { + os << " <listitem><link linkend=\"command_"; + cmDocumentationPrintDocbookEscapes(os, op->Name.c_str()); + os << "\"><emphasis><literal>"; + cmDocumentationPrintDocbookEscapes(os, op->Name.c_str()); +// os << op->Name.c_str(); +// cmDocumentationFormatterHTML::PrintHTMLEscapes(os, op->Name.c_str()); + os << "</literal></emphasis></link></listitem>"; + } + } + os << "</itemizedlist>\n" ; + + for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin(); + op != entries.end();) + { + if(op->Name.size()) + { + for(;op != entries.end() && op->Name.size(); ++op) + { + if(op->Name.size()) + { + os << " <para id=\"command_"; + cmDocumentationPrintDocbookEscapes(os, op->Name.c_str()); + + // make sure that each id exists only once, e.g. + // command_COMPILE_DEFINITIONS exists at least twice. 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 = "command_"; + 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> "; + } + cmDocumentationPrintDocbookEscapes(os, op->Brief.c_str()); + if(op->Name.size()) + { + os << "</para>\n"; + } + + if(op->Full.size()) + { + os << "\n "; // <br> + this->PrintFormatted(os, op->Full.c_str()); + } + os << "\n"; + } + } + else + { + this->PrintFormatted(os, op->Brief.c_str()); + os << "\n"; + ++op; + } + } + if(name) + { + os << "</sect1>\n"; + } +} + +void cmDocumentationFormatterDocbook::PrintPreformatted(std::ostream& os, + const char* text) +{ + os << "<programlisting>"; + cmDocumentationPrintDocbookEscapes(os, text); +// os << text; +// cmDocumentationFormatterHTML::PrintHTMLEscapes(os, text); + os << "</programlisting>\n "; +} + +void cmDocumentationFormatterDocbook::PrintParagraph(std::ostream& os, + const char* text) +{ + os << "<para>"; + cmDocumentationPrintDocbookEscapes(os, text); +// os << text; +// cmDocumentationFormatterHTML::PrintHTMLEscapes(os, text); + os << "</para>"; +} + +//---------------------------------------------------------------------------- +void cmDocumentationFormatterDocbook::PrintHeader(const char* name, + std::ostream& os) +{ + 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" + "<!ENTITY % addindex \"IGNORE\">\n" + "<!ENTITY % English \"INCLUDE\"> ]>\n" + "<article>\n" + "<articleinfo>\n" + "<title>" << name << "</title>\n" + "</articleinfo>\n"; +} + +//---------------------------------------------------------------------------- +void cmDocumentationFormatterDocbook::PrintFooter(std::ostream& os) +{ + os << "</article>\n"; +} + Index: cmDocumentationFormatterDocbook.h =================================================================== RCS file: cmDocumentationFormatterDocbook.h diff -N cmDocumentationFormatterDocbook.h --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ cmDocumentationFormatterDocbook.h 17 Feb 2008 19:06:08 -0000 @@ -0,0 +1,45 @@ +/*========================================================================= + + Program: CMake - Cross-Platform Makefile Generator + Module: $RCSfile: cmDocumentationFormatterHTML.h,v $ + Language: C++ + Date: $Date: 2007/10/22 16:48:39 $ + Version: $Revision: 1.2 $ + + Copyright (c) 2002 Kitware, Inc., Insight Consortium. All rights reserved. + See Copyright.txt or http://www.cmake.org/HTML/Copyright.html for details. + + This software is distributed WITHOUT ANY WARRANTY; without even + the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR + PURPOSE. See the above copyright notices for more information. + +=========================================================================*/ +#ifndef _cmDocumentationFormatterDocbook_h +#define _cmDocumentationFormatterDocbook_h + +#include "cmStandardIncludes.h" + +#include "cmDocumentationFormatter.h" + +/** Class to print the documentation as Docbook. + http://www.oasis-open.org/docbook/xml/4.2/ */ +class cmDocumentationFormatterDocbook : public cmDocumentationFormatter +{ +public: + cmDocumentationFormatterDocbook(); + + virtual cmDocumentationEnums::Form GetForm() const + { return cmDocumentationEnums::DocbookForm;} + + virtual void PrintHeader(const char* name, std::ostream& os); + virtual void PrintFooter(std::ostream& os); + virtual void PrintSection(std::ostream& os, + const cmDocumentationSection& section, + const char* name); + virtual void PrintPreformatted(std::ostream& os, const char* text); + virtual void PrintParagraph(std::ostream& os, const char* text); +private: + std::set<std::string> EmittedLinkIds; +}; + +#endif
_______________________________________________ CMake mailing list CMake@cmake.org http://www.cmake.org/mailman/listinfo/cmake
