| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> |
| <title>About this Documentation</title> |
| <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> |
| <link rel="home" href="../index.html" title="Chapter 1. Geometry"> |
| <link rel="up" href="../index.html" title="Chapter 1. Geometry"> |
| <link rel="prev" href="release_notes.html" title="Release Notes"> |
| <link rel="next" href="acknowledgments.html" title="Acknowledgments"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table cellpadding="2" width="100%"><tr> |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> |
| <td align="center"><a href="../../../../../index.html">Home</a></td> |
| <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> |
| <td align="center"><a href="../../../../../more/index.htm">More</a></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <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> |
| </div> |
| <div class="section"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="geometry.aboutdoc"></a><a class="link" href="aboutdoc.html" title="About this Documentation">About this Documentation</a> |
| </h2></div></div></div> |
| <p> |
| Within the Boost community there are several styles of documenting. Most libraries |
| nowadays are using QuickBook, the WikiWiki style documentation. |
| </p> |
| <p> |
| Boost.Geometry started with Doxygen, and during review it was decided to go |
| to QuickBook. However, it was convenient to keep Doxygen also there: it does |
| a good job of connecting descriptions to function and class declarations. |
| </p> |
| <p> |
| Doxygen is able to generate XML (besides the normal HTML output), containing |
| all documentation. |
| </p> |
| <p> |
| So the challenge was to translate the XML generated by doxygen to QuickBook. |
| At least, translate parts of it. Boost contains currently two tools using XSLT |
| to go from Doxygen-XML to BoostBook, or to QuickBook. These tools are used |
| within Boost.Random and Boost.Asio (and maybe more). However, this XSLT process |
| was quite hard, did not deliver (yet) the wished results, and we are all C++ |
| programmers. So another tool was born, this time in C++ using RapidXML, going |
| from Doxygen-XML to QuickBook with the ability to mix both. |
| </p> |
| <h4> |
| <a name="geometry.aboutdoc.h0"></a> |
| <span class="phrase"><a name="geometry.aboutdoc.the_chain"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.the_chain">The |
| chain</a> |
| </h4> |
| <p> |
| The process is as following: |
| </p> |
| <div class="orderedlist"><ol class="orderedlist" type="1"> |
| <li class="listitem"> |
| call doxygen to go from C++ to XML |
| </li> |
| <li class="listitem"> |
| call <span class="emphasis"><em>doxygen_xml2qbk</em></span> to go from XML to QuickBook |
| </li> |
| <li class="listitem"> |
| call bjam to from QuickBook to HTML |
| <div class="orderedlist"><ol class="orderedlist" type="a"> |
| <li class="listitem"> |
| bjam translates QuickBook to BoostBook |
| </li> |
| <li class="listitem"> |
| bjam then translates from BoostBook to DocBook |
| </li> |
| <li class="listitem"> |
| bjam then translates from DocBook to HTML |
| </li> |
| </ol></div> |
| </li> |
| </ol></div> |
| <p> |
| This chain is currently called by "make_qbk.py", a Python script |
| which calls the chain above in the right order. Python ensures that the chain |
| can be handled in both Windows and Linux environments (it is probably possible |
| to call all parts with bjam too). |
| </p> |
| <h4> |
| <a name="geometry.aboutdoc.h1"></a> |
| <span class="phrase"><a name="geometry.aboutdoc.the_reference_matrix"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.the_reference_matrix">The |
| reference matrix</a> |
| </h4> |
| <p> |
| There reference matrix is the only thing written in BoostBook. It is an XML |
| file with an overview of all Boost.Geometry functionality. Presenting it like |
| this is not possible within QuickBook, therefore BoostBook XML is used here. |
| It is included by the QuickBook code. The Boost.Asio documentation contains |
| a similar reference matrix. |
| </p> |
| <h4> |
| <a name="geometry.aboutdoc.h2"></a> |
| <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 |
| QuickBook into C++ code</a> |
| </h4> |
| <p> |
| With Doxygen it is possible to define aliases. Specificly for <span class="emphasis"><em>doxygen_xml2qbk</em></span>, |
| the alias <span class="bold"><strong>\qbk{...}</strong></span> was defined. This alias |
| <span class="bold"><strong>\qbk{...}</strong></span> add some XML-tags around the text |
| inside the alias, such that that included part is recognizable by the converter. |
| </p> |
| <p> |
| So the C++ code might look like this: |
| </p> |
| <pre class="programlisting">/*! |
| \brief Some explanation |
| \ingroup some_group |
| \details Some details |
| \tparam Geometry Description of the template parameter |
| \param geometry Description of the variable |
| |
| \qbk{ [include reference/more_documentation.qbk] } |
| */ |
| </pre> |
| <p> |
| First you see normal Doxygen comments. The last line uses the alias \qbk{...} |
| to include a QuickBook file. So most of the documentation can be written in |
| that QuickBook file: behaviour, complexity, examples, related pages, etc. |
| </p> |
| <p> |
| In the example above a QuickBook include statement is used. But any QuickBook |
| code can be used, the QuickBook code does not have to be stored in a separate |
| file. Two more samples: |
| </p> |
| <pre class="programlisting">/*! |
| ... |
| \qbk{ |
| [heading Example] |
| [area_with_strategy] |
| [area_with_strategy_output] |
| |
| [heading Available Strategies] |
| [link geometry.reference.strategies.strategy_area_surveyor Surveyor (cartesian)] |
| } |
| */ |
| </pre> |
| <p> |
| In this example pieces of QuickBook are included, two headers, two examples |
| (this is the QuickBook way - the examples are defined elsewhere), and a link. |
| </p> |
| <h4> |
| <a name="geometry.aboutdoc.h3"></a> |
| <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 |
| within C++ issues</a> |
| </h4> |
| <p> |
| There are two issues: the comma and the asterisk. If within the <span class="bold"><strong>\qbk</strong></span> |
| alias a comma is used, it is recognized by Doxygen as another parameter, and |
| therefore will not deliver the correct results, or result into errors. This |
| is easily solvable by escaping comma's (by putting a backslash directly before |
| the comma, \, ). It within the <span class="bold"><strong>\qbk</strong></span> alias |
| an asterisk is used on the first line, it is interpreted by Doxygen as well. |
| This asterisk can be escaped as well, and this time it is <span class="emphasis"><em>doxygen_qbk2xml</em></span> |
| which handles this escape and translates it back into an asterisk. |
| </p> |
| <h4> |
| <a name="geometry.aboutdoc.h4"></a> |
| <span class="phrase"><a name="geometry.aboutdoc.overloads"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.overloads">Overloads</a> |
| </h4> |
| <p> |
| Boost.Geometry contains a lot of overloads, two functions with the same name |
| and, for example, a different number of parameters. Or, as another example, |
| a const and a non-const version. They can be marked specificly to the <span class="emphasis"><em>doxygen_xml2qbk</em></span> |
| tool with the \qbk alias, by adding a specific description for the overload. |
| So, for example, <span class="bold"><strong>\qbk{distinguish,with strategy}</strong></span> |
| will result in another page where the text "with strategy" is added, |
| and it is processed as "_with_strategy" within the QuickBook section |
| name. |
| </p> |
| <h4> |
| <a name="geometry.aboutdoc.h5"></a> |
| <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 |
| and sharing documentation</a> |
| </h4> |
| <p> |
| With overloads, part of the documentation must be shared, and other part must |
| not. The descriptions are often the same. But the examples are usually not. |
| So it is a balance between sharing documentation, including shared documentation, |
| avoiding too much separate QuickBook files containing pieces of documentation |
| and avoiding including too much QuickBook code within the C++ code... |
| </p> |
| <h4> |
| <a name="geometry.aboutdoc.h6"></a> |
| <span class="phrase"><a name="geometry.aboutdoc.doxygen_aliases"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.doxygen_aliases">Doxygen |
| aliases</a> |
| </h4> |
| <p> |
| While documenting a large library, it is unavoidable that you have to document |
| the same parameters in different places. For example, the template parameter |
| <span class="bold"><strong>Geometry</strong></span>, and the variable <span class="bold"><strong>geometry</strong></span>, |
| occur at least 100 times in our library. |
| </p> |
| <p> |
| To avoid repeating the same text again and again, Doxygen aliases are used. |
| So \tparam_geometry means that the generic description for a template parameter |
| geometry is inserted. \param_geometry does the same for a parameter. This is |
| all handled by Doxygen itself. The aliases can also be parameterized, for example: |
| <span class="bold"><strong>\return_calc{area}</strong></span> is expanded to: <span class="emphasis"><em>The |
| calculated area</em></span> |
| </p> |
| <p> |
| This is for Doxygen alone and is not related to <span class="emphasis"><em>doxygen_xml2qbk</em></span> |
| or QuickBook. |
| </p> |
| <h4> |
| <a name="geometry.aboutdoc.h7"></a> |
| <span class="phrase"><a name="geometry.aboutdoc.quickbook_macros"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.quickbook_macros">QuickBook |
| macros</a> |
| </h4> |
| <p> |
| QuickBook has the same functionality for the same purpose: macro's or templates |
| can be defined. Within Boost.Geometry this is used in the QuickBook parts of |
| the documentation. So the general rule would be: where it is possible to use |
| a Doxygen alias, we use a Doxygen alias. If we are outside the scope of Doxygen |
| and we want to define a macro, we use a QuickBook macro. |
| </p> |
| <p> |
| Stated otherwise, we don't use the generated Doxygen documentation, but if |
| we would, it would look correct and would not be unreadable by unexpanded QuickBook |
| macro's. |
| </p> |
| <h4> |
| <a name="geometry.aboutdoc.h8"></a> |
| <span class="phrase"><a name="geometry.aboutdoc.code_examples"></a></span><a class="link" href="aboutdoc.html#geometry.aboutdoc.code_examples">Code |
| examples</a> |
| </h4> |
| <p> |
| We favour the use of code examples within the generated documentation. Example |
| code must be correct, so examples must compile, run, and produce the correct |
| results. QuickBook has a nice solution to include and present C++ source code, |
| including syntax highlighting. So we generally present the example (a complete |
| example including necessary headerfiles) and the output. Asserts are not used |
| here, these are examples and no tests. |
| </p> |
| <p> |
| So this is why we did enclose in the \qbk alias above: |
| </p> |
| <pre class="programlisting">[heading Example] |
| [area_with_strategy] |
| [area_with_strategy_output] |
| </pre> |
| <p> |
| We define a heading, we include the example (here denoted by the name "area_with_strategy") |
| and we include the output of the sample "area_with_strategy_output". |
| Note that we simulate that the output is C++ code, a trick giving the appropriate |
| formatting (there might be other ways to get the same effect). |
| </p> |
| <p> |
| All these QuickBook examples are included in the doc/src/examples/* folders, |
| where also a Jamfile is present. Running bjam there ensures that nothing is |
| broken in the examples. |
| </p> |
| <p> |
| Some examples, if relevant, are accompagnied by images. The images are generated |
| by the example themselves (though marked as commented out for QuickBook), deliver |
| an SVG file which can be manually converted to a PNG (I'm using InkScape for |
| that which is quite convenient). |
| </p> |
| </div> |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> |
| <td align="left"></td> |
| <td align="right"><div class="copyright-footer">Copyright © 2009-2015 Barend Gehrels, Bruno Lalande, |
| Mateusz Loskot, Adam Wulkiewicz, Oracle and/or its affiliates<p> |
| Distributed under the Boost Software License, Version 1.0. (See accompanying |
| 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>) |
| </p> |
| </div></td> |
| </tr></table> |
| <hr> |
| <div class="spirit-nav"> |
| <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> |
| </div> |
| </body> |
| </html> |
