diff options
Diffstat (limited to 'libs/geometry/doc/html/geometry/aboutdoc.html')
| -rwxr-xr-x | libs/geometry/doc/html/geometry/aboutdoc.html | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/libs/geometry/doc/html/geometry/aboutdoc.html b/libs/geometry/doc/html/geometry/aboutdoc.html new file mode 100755 index 0000000000..46e3953eb1 --- /dev/null +++ b/libs/geometry/doc/html/geometry/aboutdoc.html @@ -0,0 +1,282 @@ +<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.76.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><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><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><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><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><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><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><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><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><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-2012 Barend + Gehrels, Bruno Lalande, Mateusz Loskot<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> |