1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>About this Documentation</title> 5<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Chapter 1. Geometry"> 8<link rel="up" href="../index.html" title="Chapter 1. Geometry"> 9<link rel="prev" href="release_notes.html" title="Release Notes"> 10<link rel="next" href="acknowledgments.html" title="Acknowledgments"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="release_notes.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgments.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="geometry.aboutdoc"></a><a class="link" href="aboutdoc.html" title="About this Documentation">About this Documentation</a> 28</h2></div></div></div> 29<p> 30 Within the Boost community there are several styles of documenting. Most libraries 31 nowadays are using QuickBook, the WikiWiki style documentation. 32 </p> 33<p> 34 Boost.Geometry started with Doxygen, and during review it was decided to go 35 to QuickBook. However, it was convenient to keep Doxygen also there: it does 36 a good job of connecting descriptions to function and class declarations. 37 </p> 38<p> 39 Doxygen is able to generate XML (besides the normal HTML output), containing 40 all documentation. 41 </p> 42<p> 43 So the challenge was to translate the XML generated by doxygen to QuickBook. 44 At least, translate parts of it. Boost contains currently two tools using XSLT 45 to go from Doxygen-XML to BoostBook, or to QuickBook. These tools are used 46 within Boost.Random and Boost.Asio (and maybe more). However, this XSLT process 47 was quite hard, did not deliver (yet) the wished results, and we are all C++ 48 programmers. So another tool was born, this time in C++ using RapidXML, going 49 from Doxygen-XML to QuickBook with the ability to mix both. 50 </p> 51<h4> 52<a name="geometry.aboutdoc.h0"></a> 53 <span class="phrase"><a name="geometry.aboutdoc.the_chain"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.the_chain">The 54 chain</a> 55 </h4> 56<p> 57 The process is as following: 58 </p> 59<div class="orderedlist"><ol class="orderedlist" type="1"> 60<li class="listitem"> 61 call doxygen to go from C++ to XML 62 </li> 63<li class="listitem"> 64 call <span class="emphasis"><em>doxygen_xml2qbk</em></span> to go from XML to QuickBook 65 </li> 66<li class="listitem"> 67 call bjam to from QuickBook to HTML 68 <div class="orderedlist"><ol class="orderedlist" type="a"> 69<li class="listitem"> 70 bjam translates QuickBook to BoostBook 71 </li> 72<li class="listitem"> 73 bjam then translates from BoostBook to DocBook 74 </li> 75<li class="listitem"> 76 bjam then translates from DocBook to HTML 77 </li> 78</ol></div> 79 </li> 80</ol></div> 81<p> 82 This chain is currently called by "make_qbk.py", a Python script 83 which calls the chain above in the right order. Python ensures that the chain 84 can be handled in both Windows and Linux environments (it is probably possible 85 to call all parts with bjam too). 86 </p> 87<h4> 88<a name="geometry.aboutdoc.h1"></a> 89 <span class="phrase"><a name="geometry.aboutdoc.the_reference_matrix"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.the_reference_matrix">The 90 reference matrix</a> 91 </h4> 92<p> 93 There reference matrix is the only thing written in BoostBook. It is an XML 94 file with an overview of all Boost.Geometry functionality. Presenting it like 95 this is not possible within QuickBook, therefore BoostBook XML is used here. 96 It is included by the QuickBook code. The Boost.Asio documentation contains 97 a similar reference matrix. 98 </p> 99<h4> 100<a name="geometry.aboutdoc.h2"></a> 101 <span class="phrase"><a name="geometry.aboutdoc.mixing_quickbook_into_c___code"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.mixing_quickbook_into_c___code">Mixing 102 QuickBook into C++ code</a> 103 </h4> 104<p> 105 With Doxygen it is possible to define aliases. Specificly for <span class="emphasis"><em>doxygen_xml2qbk</em></span>, 106 the alias <span class="bold"><strong>\qbk{...}</strong></span> was defined. This alias 107 <span class="bold"><strong>\qbk{...}</strong></span> add some XML-tags around the text 108 inside the alias, such that that included part is recognizable by the converter. 109 </p> 110<p> 111 So the C++ code might look like this: 112 </p> 113<pre class="programlisting">/*! 114\brief Some explanation 115\ingroup some_group 116\details Some details 117\tparam Geometry Description of the template parameter 118\param geometry Description of the variable 119 120\qbk{ [include reference/more_documentation.qbk] } 121 */ 122</pre> 123<p> 124 First you see normal Doxygen comments. The last line uses the alias \qbk{...} 125 to include a QuickBook file. So most of the documentation can be written in 126 that QuickBook file: behaviour, complexity, examples, related pages, etc. 127 </p> 128<p> 129 In the example above a QuickBook include statement is used. But any QuickBook 130 code can be used, the QuickBook code does not have to be stored in a separate 131 file. Two more samples: 132 </p> 133<pre class="programlisting">/*! 134... 135\qbk{ 136[heading Example] 137[area_with_strategy] 138[area_with_strategy_output] 139 140[heading Available Strategies] 141[link geometry.reference.strategies.strategy_area_cartesian Cartesian] 142} 143 */ 144</pre> 145<p> 146 In this example pieces of QuickBook are included, two headers, two examples 147 (this is the QuickBook way - the examples are defined elsewhere), and a link. 148 </p> 149<h4> 150<a name="geometry.aboutdoc.h3"></a> 151 <span class="phrase"><a name="geometry.aboutdoc.quickbook_within_c___issues"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.quickbook_within_c___issues">QuickBook 152 within C++ issues</a> 153 </h4> 154<p> 155 There are two issues: the comma and the asterisk. If within the <span class="bold"><strong>\qbk</strong></span> 156 alias a comma is used, it is recognized by Doxygen as another parameter, and 157 therefore will not deliver the correct results, or result into errors. This 158 is easily solvable by escaping comma's (by putting a backslash directly before 159 the comma, \, ). It within the <span class="bold"><strong>\qbk</strong></span> alias 160 an asterisk is used on the first line, it is interpreted by Doxygen as well. 161 This asterisk can be escaped as well, and this time it is <span class="emphasis"><em>doxygen_qbk2xml</em></span> 162 which handles this escape and translates it back into an asterisk. 163 </p> 164<h4> 165<a name="geometry.aboutdoc.h4"></a> 166 <span class="phrase"><a name="geometry.aboutdoc.overloads"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.overloads">Overloads</a> 167 </h4> 168<p> 169 Boost.Geometry contains a lot of overloads, two functions with the same name 170 and, for example, a different number of parameters. Or, as another example, 171 a const and a non-const version. They can be marked specificly to the <span class="emphasis"><em>doxygen_xml2qbk</em></span> 172 tool with the \qbk alias, by adding a specific description for the overload. 173 So, for example, <span class="bold"><strong>\qbk{distinguish,with strategy}</strong></span> 174 will result in another page where the text "with strategy" is added, 175 and it is processed as "_with_strategy" within the QuickBook section 176 name. 177 </p> 178<h4> 179<a name="geometry.aboutdoc.h5"></a> 180 <span class="phrase"><a name="geometry.aboutdoc.overloads_and_sharing_documentation"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.overloads_and_sharing_documentation">Overloads 181 and sharing documentation</a> 182 </h4> 183<p> 184 With overloads, part of the documentation must be shared, and other part must 185 not. The descriptions are often the same. But the examples are usually not. 186 So it is a balance between sharing documentation, including shared documentation, 187 avoiding too much separate QuickBook files containing pieces of documentation 188 and avoiding including too much QuickBook code within the C++ code... 189 </p> 190<h4> 191<a name="geometry.aboutdoc.h6"></a> 192 <span class="phrase"><a name="geometry.aboutdoc.doxygen_aliases"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.doxygen_aliases">Doxygen 193 aliases</a> 194 </h4> 195<p> 196 While documenting a large library, it is unavoidable that you have to document 197 the same parameters in different places. For example, the template parameter 198 <span class="bold"><strong>Geometry</strong></span>, and the variable <span class="bold"><strong>geometry</strong></span>, 199 occur at least 100 times in our library. 200 </p> 201<p> 202 To avoid repeating the same text again and again, Doxygen aliases are used. 203 So \tparam_geometry means that the generic description for a template parameter 204 geometry is inserted. \param_geometry does the same for a parameter. This is 205 all handled by Doxygen itself. The aliases can also be parameterized, for example: 206 <span class="bold"><strong>\return_calc{area}</strong></span> is expanded to: <span class="emphasis"><em>The 207 calculated area</em></span> 208 </p> 209<p> 210 This is for Doxygen alone and is not related to <span class="emphasis"><em>doxygen_xml2qbk</em></span> 211 or QuickBook. 212 </p> 213<h4> 214<a name="geometry.aboutdoc.h7"></a> 215 <span class="phrase"><a name="geometry.aboutdoc.quickbook_macros"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.quickbook_macros">QuickBook 216 macros</a> 217 </h4> 218<p> 219 QuickBook has the same functionality for the same purpose: macro's or templates 220 can be defined. Within Boost.Geometry this is used in the QuickBook parts of 221 the documentation. So the general rule would be: where it is possible to use 222 a Doxygen alias, we use a Doxygen alias. If we are outside the scope of Doxygen 223 and we want to define a macro, we use a QuickBook macro. 224 </p> 225<p> 226 Stated otherwise, we don't use the generated Doxygen documentation, but if 227 we would, it would look correct and would not be unreadable by unexpanded QuickBook 228 macro's. 229 </p> 230<h4> 231<a name="geometry.aboutdoc.h8"></a> 232 <span class="phrase"><a name="geometry.aboutdoc.code_examples"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.code_examples">Code 233 examples</a> 234 </h4> 235<p> 236 We favour the use of code examples within the generated documentation. Example 237 code must be correct, so examples must compile, run, and produce the correct 238 results. QuickBook has a nice solution to include and present C++ source code, 239 including syntax highlighting. So we generally present the example (a complete 240 example including necessary headerfiles) and the output. Asserts are not used 241 here, these are examples and no tests. 242 </p> 243<p> 244 So this is why we did enclose in the \qbk alias above: 245 </p> 246<pre class="programlisting">[heading Example] 247[area_with_strategy] 248[area_with_strategy_output] 249</pre> 250<p> 251 We define a heading, we include the example (here denoted by the name "area_with_strategy") 252 and we include the output of the sample "area_with_strategy_output". 253 Note that we simulate that the output is C++ code, a trick giving the appropriate 254 formatting (there might be other ways to get the same effect). 255 </p> 256<p> 257 All these QuickBook examples are included in the doc/src/examples/* folders, 258 where also a Jamfile is present. Running bjam there ensures that nothing is 259 broken in the examples. 260 </p> 261<p> 262 Some examples, if relevant, are accompagnied by images. The images are generated 263 by the example themselves (though marked as commented out for QuickBook), deliver 264 an SVG file which can be manually converted to a PNG (I'm using InkScape for 265 that which is quite convenient). 266 </p> 267</div> 268<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 269<td align="left"></td> 270<td align="right"><div class="copyright-footer">Copyright © 2009-2019 Barend Gehrels, Bruno Lalande, Mateusz Loskot, Adam 271 Wulkiewicz, Oracle and/or its affiliates<p> 272 Distributed under the Boost Software License, Version 1.0. (See accompanying 273 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 274 </p> 275</div></td> 276</tr></table> 277<hr> 278<div class="spirit-nav"> 279<a accesskey="p" href="release_notes.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="acknowledgments.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 280</div> 281</body> 282</html> 283
