3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
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.78.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">
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>
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>
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>
30 Within the Boost community there are several styles of documenting. Most libraries
31 nowadays are using QuickBook, the WikiWiki style documentation.
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.
39 Doxygen is able to generate XML (besides the normal HTML output), containing
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.
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
57 The process is as following:
59 <div class="orderedlist"><ol class="orderedlist" type="1">
61 call doxygen to go from C++ to XML
64 call <span class="emphasis"><em>doxygen_xml2qbk</em></span> to go from XML to QuickBook
67 call bjam to from QuickBook to HTML
68 <div class="orderedlist"><ol class="orderedlist" type="a">
70 bjam translates QuickBook to BoostBook
73 bjam then translates from BoostBook to DocBook
76 bjam then translates from DocBook to HTML
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).
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
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.
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>
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.
111 So the C++ code might look like this:
113 <pre class="programlisting">/*!
114 \brief Some explanation
116 \details Some details
117 \tparam Geometry Description of the template parameter
118 \param geometry Description of the variable
120 \qbk{ [include reference/more_documentation.qbk] }
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.
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:
133 <pre class="programlisting">/*!
138 [area_with_strategy_output]
140 [heading Available Strategies]
141 [link geometry.reference.strategies.strategy_area_surveyor Surveyor (cartesian)]
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.
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>
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.
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>
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
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>
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...
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
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.
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>
210 This is for Doxygen alone and is not related to <span class="emphasis"><em>doxygen_xml2qbk</em></span>
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
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.
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
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
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.
244 So this is why we did enclose in the \qbk alias above:
246 <pre class="programlisting">[heading Example]
248 [area_with_strategy_output]
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).
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.
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).
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-2014 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>)
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>