[Boost-commit] svn:boost r56785 - in sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input: images pages sourcecode

Subject: [Boost-commit] svn:boost r56785 - in sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input: images pages sourcecode
From: barend.gehrels_at_[hidden]
Date: 2009-10-13 12:08:41

Author: barendgehrels
Date: 2009-10-13 12:08:35 EDT (Tue, 13 Oct 2009)
New Revision: 56785
URL: http://svn.boost.org/trac/boost/changeset/56785

Log:
Added doc and example folders
Some doc changes in sources plus some moves to extension
Added:
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/07_graph_route_example_svg.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/07_graph_route_example_text.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/centroid_polygon.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/centroid_ring.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/clip_linestring.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/clip_polygon.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/clip_segment_segment.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/combine_box_box.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/combine_box_point.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/convexhull_polygon_polygon.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/envelope_polygon.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/linestring.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/multi_polygon.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/output_main.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/polygon.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/simplify_example.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/simplify_linestring.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/speed_comparison.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/union_box_box.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/within_polygon.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/within_polygon_example.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/within_ring.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/x04_qt_example_output.png   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/pages/
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/pages/doxygen_design_cross_section.hpp   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/pages/doxygen_examples.hpp   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/pages/doxygen_mainpage.hpp   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/pages/doxygen_pages.hpp   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_2.cpp   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_2.vcproj   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_examples.cpp   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_examples.sln   (contents, props changed)
   sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_examples.vcproj   (contents, props changed)

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/07_graph_route_example_svg.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/07_graph_route_example_text.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/centroid_polygon.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/centroid_ring.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/clip_linestring.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/clip_polygon.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/clip_segment_segment.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/combine_box_box.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/combine_box_point.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/convexhull_polygon_polygon.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/envelope_polygon.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/linestring.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/multi_polygon.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/output_main.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/polygon.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/simplify_example.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/simplify_linestring.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/speed_comparison.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/union_box_box.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/within_polygon.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/within_polygon_example.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/within_ring.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/images/x04_qt_example_output.png
==============================================================================
Binary file. No diff available.

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/pages/doxygen_design_cross_section.hpp
==============================================================================
--- (empty file)
+++ sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/pages/doxygen_design_cross_section.hpp	2009-10-13 12:08:35 EDT (Tue, 13 Oct 2009)
@@ -0,0 +1,820 @@
+// Generic Geometry Library
+//
+// Copyright Barend Gehrels 1995-2009, Geodan Holding B.V. Amsterdam, the Netherlands.
+// Copyright Bruno Lalande 2008, 2009
+// Use, modification and distribution is subject to the Boost Software License,
+// Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+
+#ifndef _DOXYGEN_DESIGN_RATIONALE_HPP
+#define _DOXYGEN_DESIGN_RATIONALE_HPP
+
+
+//---------------------------------------------------------------------------------------------------
+
+/*!
+\page design Design rationale
+
+
+
+
+\section par1 Introduction
+
+Suppose you need C++ software to calculate the distance between two points. You might define a struct:
+
+\code
+struct mypoint
+{
+    double x, y;
+};
+\endcode
+
+And a function, containing the algorithm:
+\code
+double distance(mypoint const& a,
+                mypoint const& b)
+{
+    double dx = a.x - b.x;
+    double dy = a.y - b.y;
+    return sqrt(dx * dx + dy * dy);
+}
+\endcode
+
+Quite simple, and it is usable, but not generic. For a library it has to be designed way further. The design above can only be used for 2D points, for the struct point (and no other struct), in a Cartesian coordinate system.
+A generic library should be able to calculate the distance:
+- for any point class or struct, not on just this ‘mypoint’ type
+- in more than two dimensions
+- for other coordinate systems, e.g. over the earth or over a sphere
+- between a point and a line or between other geometry combinations
+- in higher precision than ‘double’
+- avoiding the square root: often we don’t want to do that because it is a relatively expensive function, and for comparing distances it is not necessary.
+In this page we will make the design step by step more generic.
+
+
+
+
+
+
+\section par2 Using templates
+The distance function can be changed into a template function. This is trivial and allows calculating the distance between other point types than just ‘mypoint’. We add two template parameters, allowing input of two different point types.
+
+\code
+template <typename P1, typename P2>
+double distance(P1 const& a, P2 const& b)
+{
+    double dx = a.x - b.x;
+    double dy = a.y - b.y;
+    return sqrt(dx * dx + dy * dy);
+}
+\endcode
+
+This template version is slightly better, but not much. Consider a C++ class where member variables are protected… Such a class does not allow to access .x and .y directly. So this paragraph is short and we just go on.
+
+
+
+
+\section par3 Using traits
+We need to take a generic approach and allow any point type as input to the distance function. Instead of accessing .x and .y, we will add a few levels of indirection, using a traits system.
+The function then becomes:
+\code
+template <typename P1, typename P2>
+double distance(P1 const& a, P2 const& b)
+{
+    double dx = get<0>(a) - get<0>(b);
+    double dy = get<1>(a) - get<1>(b);
+    return sqrt(dx * dx + dy * dy);
+}
+\endcode
+
+This adapted distance function uses a generic get function, with dimension as a template parameter, to access the coordinates of a point. This get forwards to the traits system, defined as following:
+\code
+namespace traits
+{
+    template <typename P, int D>
+    struct access {};
+}
+\endcode
+
+which is then specialized for our ‘mypoint’ type, implementing a static method called ‘get’:
+\code
+namespace traits
+{
+    template <>
+    struct access<mypoint, 0>
+    {
+        static double get(mypoint const& p)
+        {
+            return p.x;
+        }
+    };
+    // same for 1: p.y
+    ...
+}
+\endcode
+
+Calling traits::access<point, 0>::get(a) now returns us our x-coordinate. Nice? It is too verbose for a function like this, used so often in the library. We can shorten the syntax by adding an extra function:
+template <int D, typename P>
+\code
+inline double get(P const& p)
+{
+    return traits::access<P, D>::get(p);
+}
+\endcode
+
+This enables us to call get<0>(a), for any point having the traits::access specialization, as shown in the distance algorithm at the start of this paragraph.
+So we wanted to enable classes with methods like .x(), and they are supported as long as there is a specialization of the access struct with a static get function returning .x() for dimension 0, and similar for 1 and .y().
+Alternatively we can have, in the traits class, the dimension as a template parameter in a member template function:
+
+\code
+template <>
+struct access<mypoint>
+{
+    template <int D>
+    static double get(mypoint const& p)
+    // either return x/y using an if-clause
+    // or call a detail-struct specialized
+    //   per dimension
+};
+\endcode
+
+This alternative gives in the end the same functionality, either using an if-clause (slower), or adding another level of indirection. <b>This last version is used in GGL</b>
+
+
+
+
+
+
+\section par4 Dimension agnosticism
+Now we can calculate the distance between points in 2D, points of any structure or class. However, we wanted to have 3D as well. So we have to make it dimension agnostic.
+This complicates our distance function. We can use a for-loop to walk through dimensions, but for loops have another performance than the addition which was there originally. However, we can make more usage of templates and make the distance algorithm as following, more complex but attractive for template fans:
+\code
+template <typename P1, typename P2, int D>
+struct pythagoras
+{
+    static double apply(P1 const& a,
+        P2 const& b)
+    {
+        double d = get<D-1>(a) - get<D-1>(b);
+        return d * d + pythagoras
+                <P1, P2, D-1>
+            ::apply(a, b);
+   }
+};
+
+template <typename P1, typename P2 >
+struct pythagoras<P1, P2, 0>
+{
+    static double apply(P1 const&,
+            P2 const&)
+    {
+        return 0;
+    }
+};
+\endcode
+
+The distance function is calling that pythagoras struct, specifying the number of dimensions:
+\code
+template <typename P1, typename P2>
+double distance(P1 const& a, P2 const& b)
+{
+    BOOST_STATIC_ASSERT((
+        dimension<P1>::value
+        == dimension<P2>::value ));
+
+    return sqrt(pythagoras
+        <P1, P2, dimension<P1>::value>
+        :: apply(a, b));
+}
+\endcode
+
+The dimension which is referred to is defined using another traits class:
+\code
+namespace traits
+{
+    template <typename P>
+    struct dimension {};
+}
+\endcode
+
+which has to be specialized again for the struct  ‘mypoint’. Because it only has to publish a value, we conveniently derive it from the Boost Meta-Programming Library (MPL) class boost::mpl::int_:
+\code
+namespace traits
+{
+    template <>
+    struct dimension<mypoint>
+        : boost::mpl::int_<2>
+    {};
+}
+\endcode
+
+Like the free get function, the library also contains a dimension meta-function.
+\code
+template <typename P>
+struct dimension : traits::dimension<P>
+{};
+\endcode
+
+Below is explained why the extra declaration is useful.
+Now we have agnosticism in the number of dimensions. Our more generic distance function now accepts points of three or more dimensions. The compile-time assertion will prevent point a having two dimension and point b having three dimensions.
+
+
+
+
+
+
+
+\section par5 Coordinate type
+We assumed double above. What if our points are in integer? We can easily add a traits class, and we will do that. However, the distance between two integer coordinates can still be a fractionized value. Besides that, a design goal was to avoid square roots. We handle these cases below, in another paragraph. For the moment we keep returning double, but we allow integer coordinates for our point types.
+To define the coordinate type, we add another traits class, coordinate_type, which should be specialized by the library user:
+\code
+namespace traits
+{
+    template <typename P>
+    struct coordinate_type{};
+
+    // specialization for our mypoint
+    template <>
+    struct coordinate_type<mypoint>
+    {
+        typedef double type;
+    };
+}
+\endcode
+
+Like the access function, where we had a free get function, we add a proxy here as well. A longer version is presented later on, the short function would look like this:
+
+\code
+template <typename P>
+struct coordinate_type :    traits::coordinate_type<P> {};
+\endcode
+
+We now can modify our distance algorithm again. Because it still returns double, we only modify the Pythagoras computation class.  It should return the coordinate type of its input. But… it has two input, possibly different, point types. They might also differ in their coordinate types. Not that that is very likely, but we’re designing a generic library and we should handle those strange cases.
+We have to choose one of the coordinate types and of course we select the one with the highest precision. This is not worked out here, it would be too long, and it is not related to geometry. We just assume that there is a meta-function select_most_precise selecting the best type.
+So our computation class becomes:
+\code
+template <typename P1, typename P2, int D>
+struct pythagoras
+{
+    typedef typename select_most_precise
+        <
+            typename coordinate_type<P1>::type,
+            typename coordinate_type<P2>::type
+        >::type computation_type;
+
+    static computation_type apply(
+            P1 const& a, P2 const& b)
+    {
+        computation_type d
+            = get<D-1>(a) - get<D-1>(b);
+        return d * d + pythagoras
+                <P1, P2, D-1>
+            ::apply(a, b);
+   }
+};
+\endcode
+
+
+
+
+
+\section par6 Different geometries
+We’ve designed a dimension agnostic system supporting any point-type of any coordinate type. There are still some tweaks but they will be worked out later.
+Now we will see how we calculate the distance between a point and a polygon, or between a point and a line-segment. These formulae are more complex, and the influence on design is even larger.
+We don’t want to add a function with another name:
+\code
+template <typename P, typename S>
+double distance_point_segment(P const& p,
+                S const& s)
+\endcode
+
+We want to be generic, the distance function has to be called from code not knowing the type of geometry it handles, so it has to be named distance. We also cannot create an overload because that would be ambiguous, having the same template signature.
+There are two solutions:
+- tag dispatching
+- SFINAE
+We select tag dispatching because it fits into the traits system, and also because SFINAE has several drawbacks, listed in another paragraph.
+With tag dispatching the distance algorithm inspects the type of geometry of the input parameters. The distance function will be changed into this:
+\code
+template <typename G1, typename G2>
+double distance(G1 const& g1, G2 const& g2)
+{
+    return dispatch::distance
+        <
+            typename tag<G1>::type,
+            typename tag<G2>::type,
+            G1, G2
+        >::apply(g1, g2);
+}
+\endcode
+
+It is referring to the tag meta-function and forwarding the call to the apply method of a dispatch::distance structure. The tag meta-function is another traits class, and should be specialized for per point type, both shown here:
+\code
+namespace traits
+{
+    template <typename G>
+    struct tag {};
+
+    // specialization
+    template <>
+    struct tag<mypoint>
+    {
+        typedef point_tag type;
+    };
+}
+\endcode
+
+// Free meta-function, like
+// coordinate_system and get:
+\code
+template <typename G>
+struct tag : traits::tag<G> {};
+\endcode
+
+Tags (point_tag, segment_tag, etc) are empty structures with the purpose to specialize a dispatch struct. The dispatch struct for distance, and its specializations, are all defined in a separate namespace and look like the following:
+
+\code
+namespace dispatch {
+template < typename Tag1, typename Tag2, typename G1, typename G2 >
+struct distance
+{};
+
+template <typename P1, typename P2>
+struct distance < point_tag, point_tag, P1, P2 >
+{
+    static double apply(P1 const& a,
+            P2 const& b)
+    {
+        // here we call pythagoras
+        // exactly like we did before
+        ...
+    }
+};
+
+template <typename P, typename S>
+struct distance
+<
+    point_tag, segment_tag, P, S
+>
+{
+    static double apply(P const& p,
+            S const& s)
+    {
+        // here we refer to another function
+        // implementing point-segment
+        // calculations in 2 or 3
+        // dimensions...
+        ...
+    }
+};
+// here we might have many more
+// specializations,
+// for point-polygon, box-circle, etc.
+
+} // namespace
+\endcode
+
+So yes, it is possible; the distance algorithm is generic now in the sense that it also supports different geometry types. One drawback: we have to define two dispatch specializations for point - segment and for segment - point separately. That will also be solved, in the paragraph reversibility below.
+The example below shows where we are now: different point types, geometry types, dimensions.
+\code
+point a(1,1);
+point b(2,2);
+std::cout << distance(a,b) << std::endl;
+segment s1(0,0,5,3);
+std::cout << distance(a, s1) << std::endl;
+rgb red(255, 0, 0);
+rbc orange(255, 128, 0);
+std::cout << "color distance: " << distance(red, orange) << std::endl;
+\endcode
+
+
+
+
+
+\section par7 Kernel revisited
+
+We described above that we had a traits class coordinate_type, defined in namespace traits, and defined a separate coordinate_type class as well. This was actually not really necessary before, because the only difference was namespace clause. But now that we have another geometry type, a segment in this case, it is essential. We can call the coordinate_type meta-function for any geometry type, point, segment, polygon, etc, implemented again by tag dispatching:
+
+\code
+template <typename G>
+struct coordinate_type
+{
+    typedef typename
+        dispatch::coordinate_type
+        <
+            typename tag<G>::type, G
+        >::type type;
+};
+\endcode
+
+Inside the dispatch namespace this meta-function is implemented twice: a generic version and one specialization for points. The specialization for points calls the traits class. The generic version calls the point-specialization, as a sort of recursive meta-function definition:
+
+\code
+namespace dispatch
+{
+
+// Version for any geometry:
+template <typename GeometryTag, typename G>
+struct coordinate_type
+{
+    typedef typename point_type
+        <
+            GeometryTag, G
+        >::type point_type;
+
+    // Call specialization on point-tag
+    typedef typename coordinate_type < point_tag, point_type >::type type;
+};
+
+// Specialization for point-type:
+template <typename P>
+struct coordinate_type<point_tag, P>
+{
+    typedef typename
+        traits::coordinate_type<P>::type
+        type;
+};
+\endcode
+
+
+So it calls another meta-function point_type. This is not elaborated in here but realize that it is available for all geometry types, and typedefs the point type which makes up the geometry, calling it type.
+
+The same applies for the meta-function dimension and for the upcoming meta-function coordinate system.
+
+
+
+
+
+\section par8 Coordinate system
+Until here we assumed a Cartesian system. But we know that the Earth is not flat. Calculating a distance between two GPS-points with the system above would result in nonsense. So we again extend our design. We define for each point type a coordinate system type, using the traits system again. Then we make the calculation dependant on that coordinate system.
+
+Coordinate system is similar to coordinate type, a meta-function, calling a dispatch function to have it for any geometry-type, forwarding to its point-specialization, and finally calling a traits class, defining a typedef type with a coordinate system. We don’t show that all here again. We only show the definition of a few coordinate systems:
+\code
+struct cartesian {};
+
+template<typename DegreeOrRadian>
+struct geographic
+{
+    typedef DegreeOrRadian units;
+};
+\endcode
+
+So Cartesian is simple, for geographic we can also select if its coordinates stored in degrees or in radians.
+
+The distance function now will change: it will select the computation method for the corresponding coordinate system and then call the dispatch struct for distance. We call the computation method specialized for coordinate systems a strategy. So the new version of the distance function is:
+
+\code
+template <typename G1, typename G2>
+double distance(G1 const& g1, G2 const& g2)
+{
+    typedef typename strategy_distance
+        <
+            typename coordinate_system<G1>::type,
+            typename coordinate_system<G2>::type,
+            typename point_type<G1>::type,
+            typename point_type<G2>::type,
+            dimension<G1>::value
+        >::type strategy;
+
+    return dispatch::distance
+        <
+            typename tag<G1>::type,
+            typename tag<G2>::type,
+            G1, G2, strategy
+        >::apply(g1, g2, strategy());
+}
+\endcode
+
+The strategy_distance mentioned here is a struct with specializations for different coordinate systems.
+
+\code
+template <typename T1, typename T2,
+    typename P1, typename P2, int D>
+struct strategy_distance
+{
+    typedef void type;
+};
+
+template <typename P1, typename P2, int D>
+struct strategy_distance
+<cartesian, cartesian, P1, P2, D>
+{
+    typedef pythagoras<P1, P2, D> type;
+};
+\endcode
+
+So here is our Pythagoras again, now defined as a strategy. The distance dispatch function just calls its apply method.
+
+So this is an important step: for spherical or geographical coordinate systems, another strategy (computation method) can be implemented. For spherical coordinate systems we have the haversine formula. So it is specialized like this
+\code
+template <typename P1, typename P2,
+    int D = 2>
+struct strategy_distance<spherical, spherical, P1, P2, D>
+{
+    typedef haversine<P1, P2> type;
+};
+
+// struct haversine with apply function
+// is omitted here
+\endcode
+
+For geography, we have some alternatives for distance calculation. There is the Andoyer method[*], fast and precise, and there is the Vincenty method[*], slower and more precise, and there are some less precise approaches as well.
+We have to define one strategy as the default strategy.
+Besides that, we modify our design again and add an overload for the distance algorithm, taking a strategy. That enables us to call distance with any strategy, not just the default strategy but also specified strategies.
+This new overload distance function also has the advantage that the strategy can be constructed outside the distance function. Because it was constructed inside above, it could not have construction parameters. But for Andoyer or Vincenty, or the haversine formula, it certainly makes sense to have a constructor taking the radius of the earth as a parameter.
+So the distance overloaded function is:
+
+\code
+template <typename G1, typename G2, typename S>
+double distance(G1 const& g1, G2 const& g2, S const& strategy)
+{
+    return dispatch::distance
+        <
+            typename tag<G1>::type,
+            typename tag<G2>::type,
+            G1, G2, S
+        >::apply(g1, g2, strategy);
+}
+\endcode
+
+The strategy has to have a method apply taking two points as argument. [[[for points!]]]
+
+We do not list all implementations here, Vincenty would cover half a page of mathematics, but you will understand the idea. We can call distance like this:
+\code
+distance(c1, c2)
+\endcode
+
+where c1,c2 are Cartesian points, or like this:
+
+\code
+distance(g1, g2)
+\endcode
+
+where g1,g2 are Geographic points, calling the default strategy for Geographic points (e.g. Andoyer), and like this:
+
+\code
+distance(g1, g2, vincenty<G1, G2>(6275))
+\endcode
+
+where a strategy is specified explicitly and constructed with a radius.
+
+
+
+
+
+
+
+
+
+
+\section par9 Point concept
+The five traits classes mentioned in the paragraphs above form together the Point Concept. Any point type for which specializations are implemented in the traits namespace should be handled correctly by the library. So the Point concept consists of:
+ * a specialization for traits::tag
+ * a specialization for traits::coordinate_system
+ * a specialization for traits::coordinate_type
+ * a specialization for traits::dimension
+ * a specialization for traits::access
+The last one is a class, containing a function, the first four are meta-functions.
+So we now have agnosticism for the number of dimensions, agnosticism for coordinate systems, our design can handle any coordinate type, and it can handle different geometry types.
+Furthermore we can specify our own strategies, the code will not compile in case of two points with different dimensions (because of the assertion), and it will not compile for two points with different coordinate systems (because there is no specialization).
+We still have the distance function returning double. Next paragraph will solve that.
+
+
+
+\section par10 Return type
+We promised that calling sqrt was not always necessary. So we define a distance result struct that contains the squared value and is convertible to a double value.
+This, however, only has to be done for Pythagoras. The spherical distance functions do not take the square root so for them it is not necessary to avoid the expensive square root call; they can just return their distance.
+So the distance result struct is dependant on strategy, therefore made a member type of the strategy, looking like this:
+\code
+template<typename T = double>
+struct cartesian_distance
+{
+    T sq;
+    explicit cartesian_distance(T const& v)
+        : sq (v) {}
+
+    inline operator T() const
+    {
+        return std::sqrt(sq);
+    }
+};
+\endcode
+
+It also has operators defined to compare itself to other results without taking the square root.
+Each strategy should define its return type, within the strategy class, e.g.:
+
+\code
+    typedef cartesian_distance<T>                   return_type;
+\endcode
+or:
+
+\code
+    typedef double return_type
+\endcode
+
+for Pythagoras and spherical, respectively.
+
+Again our distance function will be modified, as expected, to reflect the new return type. For the overload with a strategy it is not complex:
+\code
+template < typename G1, typename G2, typename Strategy >
+typename Strategy::return_type distance( G1 const& G1 , G2 const& G2 , S const& strategy)
+\endcode
+
+But for the one without strategy we have to select strategy, coordinate type, etc. It would be spacious to do it in one line so we add a separate meta-function:
+\code
+template <typename G1, typename G2 = G1>
+struct distance_result
+{
+    typedef typename point_type<G1>::type P1;
+    typedef typename point_type<G2>::type P2;
+    typedef typename strategy_distance
+        <
+            typename cs_tag<P1>::type,
+            typename cs_tag<P2>::type,
+            P1, P2>::type S;
+
+    typedef typename S::return_type type;
+};
+\endcode
+
+and modify our distance function:
+\code
+template <typename G1, typename G2>
+inline typename distance_result
+    <G1, G2>::type
+    distance(G1 const& G1, G2 const& G2)
+\endcode
+
+Of course also the apply functions in the dispatch specializations will return a result like this, they have a strategy as a template parameter everywhere, making the less verbose version possible.
+
+
+
+
+\section par11 Reversibility
+Our dispatch::distance class was specialized for <point_tag, segment_tag>. Library users can also call the distance function with a segment and a point, in that order. Actually, there are many geometry types (polygon, box, linestring), how to implement all those without duplicating all tag dispatching functions?
+The answer is that we automatically reverse the arguments, if appropriate. For distance it is appropriate because distance is a commutative function.
+We add a meta-function geometry_id, which has specializations for each geometry type, just derived from boost::mpl::int_, such that it can be ordered. Point is 1, segment is e.g. 2.
+
+Then we add a meta-function reverse_dispatch:
+\code
+template <typename G1, typename G2>
+struct reverse_dispatch :   detail::reverse_dispatch
+<
+    geometry_id<G1>::type::value,
+    geometry_id<G2>::type::value
+> {};
+\endcode
+
+Because of the order in geometry_id, we can arrange (template) parameters in that order, in specializations. So the detail structure looks like:
+\code
+namespace detail
+{
+    template <int Id1, int Id2>
+    struct reverse_dispatch
+        : boost::mpl::if_c
+        <
+            (Id1 > Id2),
+            boost::true_type,
+            boost::false_type
+        > {};
+\endcode
+
+And our distance function will be modified again with some template meta-programming:
+We get
+\code
+return boost::mpl::if_c
+    <
+        ggl::reverse_dispatch <G1, G2>::type::value,
+        dispatch::distance_reversed
+            <
+                typename tag<G1>::type,
+                typename tag<G2>::type,
+                G1, G2,
+                // strategy
+            >,
+        dispatch::distance
+            <
+                typename tag<G1>::type,
+                typename tag<G2>::type,
+                G1, G2,
+                // strategy
+        >
+    >::type::apply(g1, g2, s);
+\endcode
+
+Where the dispatch::distance_reversed is a specific struct, forwarding its call to dispatch::distance, reversing all its template arguments and function arguments.
+
+
+\section par13 Multi
+Consider Hawaii as a multi_polygon: it is a set of islands (polygons), forming together one entity. The shortest distance from a ship to Hawaii is the shortest distance to the closest island. That algorithm also holds for the shortest distance from a point to a multi-line or a multi-point.
+So we don't want to implement that functionality three times. Instead we add a meta-function, is_multi, which is always true for a multi-geometry (multi-point, multi-linestring, multi-polygon) and always false for the single versions.
+
+\code
+template <typename Geometry>
+struct is_multi : core_dispatch::is_multi<typename tag<Geometry>::type>
+{};
+
+
+namespace dispatch
+{
+
+template <typename GeometryTag>
+struct is_multi : boost::false_type {};
+
+template <>
+struct is_multi<multi_point_tag> : boost::true_type {};
+
+
+template <>
+struct is_multi<multi_linestring_tag> : boost::true_type {};
+
+
+template <>
+struct is_multi<multi_polygon_tag> : boost::true_type {};
+
+
+
+
+} // namespace dispatch
+\endcode
+
+
+Now we can specialize on is_multi, so we add two boolean IsMulti's, one for each geometry type, to our distance dispatch struct and make the call to them in the distance function:
+
+// specialization:
+
+\code
+template <typename GeometryTag1, typename GeometryTag2,
+       typename G1, typename G2, typename Strategy>
+struct distance<GeometryTag1, GeometryTag2, G1, G2, strategy_tag_distance_point_point, Strategy, false, true>
+   : detail::distance::distance_single_to_multi<G1, G2, Strategy>
+{};
+\endcode
+
+
+
+
+If that relatively simple change is done, we have to do one thing: implement the single-to-multi distance implementation structure
+
+\code
+template<typename Geometry, typename MultiGeometry, typename Strategy>
+struct distance_single_to_multi
+{
+   typedef typename Strategy::return_type return_type;
+
+   static return_type apply(Geometry const& geometry,
+               MultiGeometry const& multi,
+               Strategy const& strategy)
+   {
+       using namespace boost;
+
+       return_type mindist = make_distance_result<return_type>(
+                       numeric::bounds<typename select_coordinate_type<Geometry, MultiGeometry>::type>::highest());
+
+       typedef typename range_const_iterator<MultiGeometry>::type iterator;
+       for(iterator it = begin(multi); it != end(multi); ++it)
+       {
+           return_type dist = ggl::distance(geometry, *it);
+           if (dist < mindist)
+           {
+               mindist = dist;
+           }
+       }
+
+       return mindist;
+   }
+};
+\endcode
+
+
+
+which iterates over a collection of multi-shapes, and returns the shortest distance. Another function can implement the multi-to-multi function. Note that because of reversibility we don't have to implement the multi-to-single version (as long as multi's always have an higher ID than single's).
+
+
+
+\section par14 Sfinae
+Instead of tag dispatching we alternatively could have chosen for SFINAE, mentioned above. With SFINAE (Substitution Failure Is Not An Error) we add optional parameters to the distance function, which sole use is to make an overload invalid for other geometry types than specified. So like:
+\code
+template <typename P1, typename P2>
+inline double distance(P1 const& p1, P2 const& p2
+    , typename boost::enable_if <is_point<P1>   >::type* = 0
+    , typename boost::enable_if <is_point<P2>   >::type* = 0
+    )
+    {
+        return impl::distance::point_to_point(p1, p2);
+    }
+\endcode
+
+There would then be overloads for point-segment, point-polygon, etc.
+This SFINAE:
+- can be done on functions but not on structs (meta-functions). So the coordinate_type meta-function would still have to use tag dispatching
+- gives often compiler troubles and headaches: if a user makes an error somewhere, the compiler will not select any of the methods, and/or it will give completely incomprehensible error listings, just because of this SFINAE
+- does not support partial specializations because it is a function. The tag-dispatching function is of course also not supporting that, but it forwards its call to the dispatch struct where partial specializations (and member template functions) are possible. The SFINAE could do that as well but then: why not just add one tag more and have tag dispatching instead?
+- is a trick to deceive the compiler. “As a language behavior it was designed to avoid programs becoming ill-formed” [2], while tag dispatching is based on specialization, a core feature of C++
+- looks more ugly
+- is simply not necessary because we have tag dispatching :-)
+
+
+
+
+*/
+
+#endif // _DOXYGEN_DESIGN_RATIONALE_HPP

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/pages/doxygen_examples.hpp
==============================================================================
--- (empty file)
+++ sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/pages/doxygen_examples.hpp	2009-10-13 12:08:35 EDT (Tue, 13 Oct 2009)
@@ -0,0 +1,207 @@
+// Generic Geometry Library
+//
+// Copyright Barend Gehrels 1995-2009, Geodan Holding B.V. Amsterdam, the Netherlands.
+// Copyright Bruno Lalande 2008, 2009
+// Use, modification and distribution is subject to the Boost Software License,
+// Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+
+#ifndef _DOXYGEN_EXAMPLES_HPP
+#define _DOXYGEN_EXAMPLES_HPP
+
+
+/*!
+
+
+\example 01_point_example.cpp
+In most cases the documentation gives small examples of how to use the algorithms or classes.
+The point example is a slightly larger example giving the an idea of how to use different
+algorithms from the library, related to points. It shows
+- the usage of include files
+- how to declare points, using different coordinate types
+- how to construct points, specifying coordinates, initializing to zero or to infinite
+- how to compare points to each other
+- how points can be streamed as OGC text
+- calculating the distance from point to point
+
+
+*/
+
+
+//---------------------------------------------------------------------------------------------------
+
+/*!
+\example 02_linestring_example.cpp
+The linestring example shows how linestrings can be declared and used and shows some more algorithms.
+One of the important concepts of the Generic Geometry Library is that it is totally built upon the standard
+library, using the standard containers such as std::vector.
+
+A linestring is, as explained elsewhere in this documentation, not much more than a vector of points.
+Most algorithms run on linestrings, but can also run on any iterator pair. And all algorithms
+on std::vector can be used on geometry::linestring.
+
+The sample shows this, shows some algorithms:
+- geometry::envelope
+- geometry::length
+- geometry::distance
+- geometry::simplify
+- geometry::for_each
+- geometry::intersection
+
+This documentation illustrates the simplify algorithm and the intersection algorithm with some pictures.
+
+The simplify algorithm simplifies a linestring. Simplification means that the less important points
+are removed from the line and that the points that are most important for the shape of a line are
+kept. Simplification is done using the well known Douglas Peucker algorithm. The library user can
+specify the distance or tolerance, which indicates how much the linestring should be simplified.
+
+The image below shows the original and simplified linestring:
+\image html simplify_linestring.png
+The blue line is the original linestring; the red line is the simplified line which has one point less.
+In geographical applications simplification can reduce a linestring to its basic form containing only
+10% of its original points.
+
+The intersection algorithm intersects two geometries which each other, delivering a third geometry.
+In the case of the example a linestring is intersected with a box. Intersection with a box is often
+called a clip. The image below illustrates the intersection.
+\image html clip_linestring.png
+The yellow line is intersected with the blue box.
+The intersection result, painted in red, contains three linestrings.
+*/
+
+//---------------------------------------------------------------------------------------------------
+
+/*!
+\example 03_polygon_example.cpp
+The polygon example shows some examples of what can be done with polygons in the Generic Geometry Library:
+* the outer ring and the inner rings
+* how to calculate the area of a polygon
+* how to get the centroid, and how to get an often more interesting label point
+* how to correct the polygon such that it is clockwise and closed
+* within: the well-known point in polygon algorithm
+* how to use polygons which use another container, or which use different containers for points and for inner rings
+* how polygons can be intersected, or clipped, using a clipping box
+
+The illustrations below show the usage of the within algorithm and the intersection algorithm.
+
+The within algorithm results in true if a point lies completly within a polygon. If it lies exactly
+on a border it is not considered as within and if it is inside a hole it is also not within the
+polygon. This is illustrated below, where only the point in the middle is within the polygon.
+
+\image html within_polygon.png
+
+The clipping algorithm, called intersection, is illustrated below:
+
+\image html clip_polygon.png
+
+The yellow polygon, containing a hole, is clipped with the blue rectangle, resulting in a
+multi_polygon of three polygons, drawn in red. The hole is vanished.
+
+include polygon_example.cpp
+*/
+
+
+//---------------------------------------------------------------------------------------------------
+ /*!
+\example 06_transformation_example.cpp
+This sample demonstrates the usage of transformations in the Generic Geometry Library.
+Behind the screens this is done using with the uBLAS matrix/vector library.
+*/
+
+//---------------------------------------------------------------------------------------------------
+
+/*!
+\example 07_graph_route_example.cpp
+The graph route example shows how GGL can be combined with Boost.Graph. The sample does the following things:
+- it reads roads (included in the distribution, stored on disk in the form of a text file containing geometries and names)
+- it reads cities
+- it creates a graph from the roads
+- it connects each city to the nearest vertex in the graph
+- it calculates the shortest route between each pair of cities
+- it outputs the distance over the road, and also of the air
+- it creates an SVG image with the roads, the cities, and the first calculated route
+
+Note that this example is useful, but it is only an example. It could be built in many different ways.
+For example:
+- the roads/cities could be read from a database using SOCI, or from a shapefile using shapelib
+- it could support oneway roads and roads on different levels (disconnected bridges)
+- it currently uses tuples but that could be anything
+- etc
+
+The SVG looks like:
+\image html 07_graph_route_example_svg.png
+
+The output screen looks like:
+\image html 07_graph_route_example_text.png
+
+
+*/
+
+
+//---------------------------------------------------------------------------------------------------
+ /*!
+\example c01_custom_point_example.cpp
+This sample demonstrates that custom points can be made as well. This sample contains many points, derived
+from boost::tuple, created from scratch, read only points, legacy points, etc.
+*/
+
+//---------------------------------------------------------------------------------------------------
+ /*!
+\example c02_custom_box_example.cpp
+Besides custom points, custom boxes are possible as shown in this example.
+*/
+
+//---------------------------------------------------------------------------------------------------
+/*
+\example c03_custom_linestring_example.cpp
+GPS tracks are shown in this example: a custom linestring with GPS points
+*/
+
+//---------------------------------------------------------------------------------------------------
+ /*!
+\example c04_a_custom_triangle_example.cpp
+The \b custom triangle \b example goes even further and implements a custom ring, where the area calculation
+algorithm is optimized for a triangle
+*/
+
+//---------------------------------------------------------------------------------------------------
+ /*!
+\example c05_custom_point_pointer_example.cpp
+This example shows how GGL can be used to adapt a pointer-to-a-point, used e.g. in a linestring
+*/
+
+//---------------------------------------------------------------------------------------------------
+ /*!
+\example c04_b_custom_triangle_example.cpp
+This second custom triangle example shows an alternative implementation for a custom shape, showing a
+partial specialization for the area calculation.
+*/`
+
+
+//---------------------------------------------------------------------------------------------------
+ /*!
+\example x01_qt_example.cpp
+This sample demonstrates that by usage of concepts, external geometries can be handled
+by GGL, just calling by a one-line registration macro. In this case for the Qt Widget Library.
+
+The example, code shown below, results in this window-output:
+\image html x01_qt_example_output.png
+*/
+
+
+
+//---------------------------------------------------------------------------------------------------
+ /*!
+\example x03_a_soci_example.cpp
+First example showing how to get spatial data from a database using SOCI and put them into GGL
+*/
+
+
+//---------------------------------------------------------------------------------------------------
+ /*!
+\example x03_b_soci_example.cpp
+Second example showing how to get polygons from a database using SOCI and put them into GGL, using WKT.
+In the near future this will also be possible using WKB.
+*/
+
+#endif // _DOXYGEN_EXAMPLES_HPP

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/pages/doxygen_mainpage.hpp
==============================================================================
--- (empty file)
+++ sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/pages/doxygen_mainpage.hpp	2009-10-13 12:08:35 EDT (Tue, 13 Oct 2009)
@@ -0,0 +1,94 @@
+// Generic Geometry Library
+//
+// Copyright Barend Gehrels 1995-2009, Geodan Holding B.V. Amsterdam, the Netherlands.
+// Copyright Bruno Lalande 2008, 2009
+// Use, modification and distribution is subject to the Boost Software License,
+// Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+
+#ifndef _DOXYGEN_MAINPAGE_HPP
+#define _DOXYGEN_MAINPAGE_HPP
+
+
+/*!
+\mainpage Generic Geometry Library
+
+\section header Generic Geometry Library
+
+<em>Copyright © 1995-2009 <b>Barend Gehrels</b>, Geodan, Amsterdam, the Netherlands.\n
+Copyright © 2008-2009 <b>Bruno Lalande</b>, Paris, France.\n
+Copyright © 2009 <b>Mateusz Loskot</b>, Cadcorp, London, UK.\n
+Distributed under the Boost Software License, Version 1.0.\n
+(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+</em>
+
+\section intro Introduction
+The Generic Geometry Library, GGL (currently in "Formal Review Request") defines concepts for geometries and implements some algorithms on such geometries.
+
+GGL contains a dimension-agnostic, coordinate-system-agnostic and scalable kernel,  based on concepts, meta-functions and tag- dispatching.
+On top of that kernel, algorithms are built: area, length, perimeter, centroid, convex hull, intersection (clipping), within (point in polygon), distance, envelope (bounding box), simplify, transform, convert, and more. The library is also designed to support high precision arithmetic numbers, such as GMP.
+
+GGL contains instantiable geometry classes, but library users can also use their own. Using registration macros or traits classes their geometries can be adapted to fulfil the GGL-concepts.
+
+The GGL might be used in all domains where geometry plays a role: mapping and GIS, gaming, computer graphics and widgets, robotics, astronomy... The core is designed to be as generic as possible and support those domains. However, for now the development has been mostly GIS-oriented.
+
+GGL supports the extension model, the same way as GIL also applies it. An extension is (mostly) something more specific to domains like mentioned above.
+
+The library follows existing conventions:
+- conventions from boost
+- conventions from the std library
+- conventions and names from one of the OGC standards on Geometry
+
+This Generic Geometry Library (ggl) is now being proposed to the Boost Library Collection
+
+The library can be downloaded from the Boost Sandbox,
+go to the \ref download "Download page" for more information.
+
+\section quickstart Quick start
+It is not possible to show the whole library at a glance. A few very small examples are shown below.
+
+It should be possible to use a very small part of the library,
+for example only the distance between two points.
+
+\dontinclude doxygen_2.cpp
+\skip example_for_main_page()
+\skipline int a
+\until endl;
+
+Other often used algorithms are point-in-polygon:
+\skipline ring_2d
+\until endl;
+
+or area:
+\skip area
+\until endl;
+
+It is possible, by the nature of a template library, to mix the point types declared above:
+\skip double d2
+\until endl;
+
+The pieces above generate this output:
+\image html output_main.png
+
+
+It is also possible to use non-Cartesian points.
+For example: points on a sphere. When then an algorithm such as distance
+is used the library "inspects" that it is handling spherical
+points and calculates the distance over the sphere, instead of applying the Pythagorean theorem.
+
+Finally an example from a totally different domain: developing window-based applications, for example
+using QtWidgets. We check if two rectangles overlap and if so,
+move the second one to another place:
+\skip QRect
+\until }
+
+Many more examples are on the page \b Examples
+
+
+*/
+
+
+
+
+
+#endif // _DOXYGEN_MAINPAGE_HPP

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/pages/doxygen_pages.hpp
==============================================================================
--- (empty file)
+++ sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/pages/doxygen_pages.hpp	2009-10-13 12:08:35 EDT (Tue, 13 Oct 2009)
@@ -0,0 +1,396 @@
+// Generic Geometry Library
+//
+// Copyright Barend Gehrels 1995-2009, Geodan Holding B.V. Amsterdam, the Netherlands.
+// Copyright Bruno Lalande 2008, 2009
+// Use, modification and distribution is subject to the Boost Software License,
+// Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+
+#ifndef _DOXYGEN_PAGES_HPP
+#define _DOXYGEN_PAGES_HPP
+
+
+//---------------------------------------------------------------------------------------------------
+
+/*!
+\page concepts Concepts
+
+All geometries are handled as concepts. They are specified by a set of traits classes in the traits namespace.
+
+This means that geometries provided by library users, or legacy geometries, or plain arrays, or boost tuples,
+all can be handled by the Generic Geometry Library. That is why it is called generic. Also std::vector of points
+or tuples can be handled as either a linestring or a linear ring (polygon without holes).
+
+There are concepts for
+- points
+- box
+- n-sphere (meaning circle or sphere)
+- linestring
+- ring (linear ring, a polygon without holes)
+- polygon
+- segment
+
+The library uses the generic functionality internally. So it should work with any geometry, as long as the
+necessary traits classes are provided.
+
+For a valid point five traits classes are necessary:
+- there should be a tag traits class indicating that it is a point
+- there should be a coordinate_type traits class indicating what arithmetic type its coordinates are
+- there should be a dimension traits class indicating the number of its dimensions (coordinate axes)
+- there should be a coordinate system traits class defining in which coordinate system it lives
+- there should be an access traits class, having a get (for a ConstPoint) and a set (for a mutable Point) function
+
+These traits class can be implemented in the code, but easier is it to use the registration macro's as
+shown in example c01 (custom points).
+
+For a valid linestring there is only one traits class required:
+- there should be a tag traits class indicating that it is a linestring
+
+For the rest a linestring is modelled as a range, so a std::vector, std::deque, boost::array, ggl::linestring,
+iterator pair or c-array will do. If a linestring is modified it is using the standard library (push_back). If that
+is not intended, optionally another traits class can be defined:
+- there might be a use_std traits class indicating that it does not use the standard library (for modifications)
+
+If that traits class is defined, there should also be two other traits classs
+- there should then be clear traits class to make a linestring empty
+- there should then be a append_point traits class to add a poitn to a linestring
+
+There are also concepts for boxes, n-spheres, segments, rings and polygons.
+
+
+The Generic Geometry Library uses Boost Concept Check Library (BCCL) and Meta Programming Language (MPL) to define
+and check concepts. The Generic Geometry Library uses the Boost Range Library to iterate through standard containers,
+boost arrays, c-arrays.
+
+*/
+
+
+
+
+
+
+//---------------------------------------------------------------------------------------------------
+
+/*!
+\page compiling Compiling
+
+\section compiling_intro Compiling the Generic Geometry Library
+
+The Generic Geometry Library is a Header Only library. So just including the headerfiles is enough
+to use the algorithms. Nothing has to be linked.
+
+The Generic Geometry Library is only dependant on (header only) Boost libraries. Download the Boost
+Library Collection from www.boost.org, adapt include path to include Boost.
+
+\section platforms Platforms
+
+The library currently compiles successfully on the following platforms:
+- MS Visual Studio 2008 (Express Edition)
+- MS Visual Studio 2005 (Express Edition)
+- gcc version 3.4
+- gcc version 4 (tested are 4.1, 4.2, 4.4)
+
+
+\section convenient_includes Convenient includes
+
+This section concentrates on how to include the Generic Geometry Library.
+
+The most convenient headerfile including all algorithms and strategies is geometry.hpp:
+- \#include <ggl/ggl.hpp> It is not absolutely necessary to include this headerfile, it is also possible to
+  include the algorithm headerfiles separately. However, it is convenient and used in most cases.
+
+
+An often used headerfile is geometries.hpp:
+- \#include <ggl/geometries/geometries.hpp> This includes all default geometries: point, linestring,
+  polygon, linear_ring, box, circle/sphere. It is not included in the "geometry.hpp" headerfile because
+  users are allowed to use their own geometries. However, for library users who want to use the provided
+  geometries it is most useful.
+
+
+For users using only Cartesian points, with floating point coordinates (double), in 2D or 3D, you can use instead:
+- \#include <ggl/geometries/cartesian2d.hpp> This includes all 2D Cartesian geometries: point_2d, linestring_2d,
+  etc. Using this headerfile the library seems to be a non-template library, so it is convenient for users that
+  are not so into the template world.
+
+
+
+
+\section advanced_includes Advanced includes
+
+This section is for users who have their own geometries and want to use algorithms from the Generic Geometry Library.
+
+
+If you want to use your own points it makes sense to use the registration macro's:
+- \#include <ggl/geometries/register/point.hpp> macro's for point registration
+- \#include <ggl/geometries/register/box.hpp> macro's for box registration
+
+
+If you are using standard containers containing points and want to handle them as a linestring
+- \#include <ggl/geometries/adapted/std_as_linestring.hpp> allows you to use things like \c std::vector<point_2d>
+  and put them as parameters into algorithms.
+
+
+If you are using boost tuples and want to handle them as Cartesian points
+- \#include <ggl/geometries/adapted/tuple_cartesian.hpp>
+
+
+\section performance Performance findtuning
+The enumeration below is not exhaustive but can contain hints to improve the performance
+- For Microsoft, set the define _SECURE_SCL=0
+- For Microsoft, set the define _HAS_ITERATOR_DEBUGGING=0
+- Barend's measurements indicate that MSVC 2005 generates faster code than MSVC 2008
+- Using StlPort results in significant faster code than Microsoft's standard library
+- Of course turn on compiler optimizations, compile in release mode
+
+*/
+
+
+//---------------------------------------------------------------------------------------------------
+
+/*!
+\page performance Performance
+
+\section performance_comparison Performance results
+The performance has been tested for some algorithms and it seems that the Generic Geometry Library performs well,
+indicating that the template-based approach and consequent usage of inline functions and the std:: library
+is a sound approach. Measurements and comparisons (still in concept) are here:
+http://trac.osgeo.org/ggl/wiki/Performance
+
+\section performance-notes Performance notes
+In the page about compiling the library there are some hints provided which might improve the performance.
+
+Furthermore it is important to realize that if you're about to do calculations with two geometries, for
+example a point-in-polygon or an intersection, it is very useful to first calculate and store all bounding
+boxes (envelopes), and then before doing a point-in-polygon check if the point is in the bounding box. Checking if a
+point is within a box is of course much faster than visiting all vertices of a polygon.
+
+The storage of bounding boxes is, on purpose, not done within the library because it would break the possibility
+to use standard vectors of points for linestrings or rings. The library might get a traits system in the future
+where geometries might tell their boundaries to the algorithms, this however would be an optional system.
+*/
+
+
+
+
+
+//---------------------------------------------------------------------------------------------------
+
+/*!
+\page DSV DSV (Delimiter Separated Values)
+DSV is a text representation of a geometry, explained here: http://en.wikipedia.org/wiki/Delimiter-separated_values
+DSV can represent a point, a linestring, a polygon, or multi versions of those.
+
+It is currently just a utility in the library, used in samples and tests, to get some textual output
+of a geometry.
+
+*/
+
+//---------------------------------------------------------------------------------------------------
+
+
+/*!
+\page OGC OGC (Open Geospatial Consortium)
+OGC is the Open Geospatial Consortium, the standardization committee
+on Geospatial Interoperability and GIS (Geographical Information Systems).
+OGC geometries are used in many environments and databases.
+
+The Generic Geometry Library uses OGC conventions
+for algorithms and for geometry type names. Note that though OGC is concentrating on GIS,
+the conventions followed here are 'geometry only', the so-called 'simple features'
+(simple in the sense that polygons are not allowed to have self-intersections).
+
+OGC specifies a library based on inheritance, as opposed to this library, which is a generic template based library
+where data classes are separated from the algorithms.
+Therefore this library is not an OGC implementation in the strict sense.
+
+\section Classes
+OGC defines the following geometry classes,
+which are implemented as concepts (and as geometries) the Generic Geometry Library:
+- \ref ggl::point "point": a point. The point defined here is dimensionally agnostic.
+Library users does not have to use this point, they might also use their own points as long as it meets the concepts.
+- \ref ggl::linestring "linestring": Sequence of point values with linear interpolation
+between points. Note that library users does not have to use this type. Algorithms works on iterators, so
+all algorithms also accept iterators on a vector (or other container) of points.
+- \ref ggl::linear_ring "linear_ring": Sequence of point values with linear interpolation
+between points, which is closed and not self-intersecting
+- \ref ggl::polygon "polygon": Plane figure, consisting of an outer ring and zero or more
+inner rings. So basically a polygon which might have holes.
+<em>Note that this definition is different from several other polygon definitions and libraries,
+where polygons are not allowed to have holes. These polygons are comparable to the linear_ring above</em>
+
+The following geometries were in the first preview, because they are defined in OGC, but not in the current preview
+(they will be added again).
+- \b multi_point: collection of points
+- \b multi_linestring: collection of linestrings
+- \b multi_polygon: collection of polygons
+
+The naming of these classes is used in:
+- WKT (Well-Known Text)
+- KML (Google Maps)
+- GML
+- many GIS/geometry libraries
+
+and in many databases:
+- Oracle Spatial
+- SQL Server 2008
+- PostGreSQL
+- MySQL
+- MonetDB
+
+Besides this the Generic Geometry Library provides the following additional classes:
+- \ref ggl::box "box": Box, used for selections and for envelopes (bounding boxes)
+- \ref ggl::nsphere "n-sphere", meaning circle" and "sphere". Circle is convenient for selections
+- \ref ggl::segment "segment": Segment, helper class, used for e.g. intersections
+
+
+\section Algorithms
+The Generic Geometry Library implements the following OGC algorithms, which are applicable to most or all geometries
+- \b area: Returns the area of surface-geometries
+- \b as_text: Represents the geometry as a Well Known Text (named "wkt")
+- \b centroid: Returns a point geometry: the centroid on surface-geometries
+- \b convex_hull: Returns true if the geometry is simple (doesn't intersect itself)
+- \b coordinate_dimension: Returns the number of geometry coordinate values
+- \b distance: Returns the distance between two geometries
+- \b envelope: Returns the bounding box of a geometry
+- \b intersection: Returns a geometry containing the intersection between two geometries (currently only with boxes)
+- \b length: Returns the length of curve-type geometries
+- \b num_points: Returns the number of points
+- \b topological_dimension: Returns the topological dimension
+- \b within: Returns true if one geometry falls completely within another geometry
+
+Readers might notice that many OGC algorithms, especially the more complex ones, are not yet implemented and that is true.
+Much work has been done on the generic structure of the library, algorithms still have to be worked on.
+On the other hand many algorithms are implemented for different coordinate systems (distance is implemented using
+four strategies: Pythagoras, Andoyer, Vincenty and haversine, there is the "spherical polygon area").
+
+\section Differences
+The Generic Geometry Library does not implement the OGC Simple Feature interface exactly and completely.
+There are many differences. Below the most important differences are listed.
+- In OGC all operations are class methods. The Generic  Geometry Library is a template library and defines the algorithms
+as generic functions.
+- In OGC a point is defined by an x-coordinate value, a y-coordinate value and possibly a z-coordinate value
+and a measured value. In the Generic Geometry Library the basic point defines coordinates in a neutral way,
+so there is no x, no y.
+- in OGC all geometries have additional members, such as SRID, measured. These
+properties are not defined in the Generic Geometry Library. Library users can implement them, if necessary,
+in derived classes.
+- In OGC the envelope returns a geometry, in the Generic Geometry Library it returns a box
+- The OGC algorithm asText is named "wkt" and to stream manipulators in streamwkt
+
+
+More information on OGC can be found on their website, http://www.opengeospatial.org
+and on Wikipedia http://en.wikipedia.org/wiki/Open_Geospatial_Consortium
+*/
+
+
+//---------------------------------------------------------------------------------------------------
+
+/*!
+\page status Status and preview
+
+\section introduction Introduction
+
+The Generic Geometry Library is currently in its fourth preview.
+
+The first preview was a template 2D geometry library providing its own geometries and algorithms working on
+those geometries. Those geometries are still provided but not essential anymore.
+
+The second preview didn't asume points with .x() and .y() anymore. It provided strategies,
+operating on specific point types. So point_xy (cartesian points) were
+handled different from point_ll (latlong points). That is still the case (now using a coordinate system meta-function)
+
+The third preview introducted the point concept, library users could use their own points with the algorithms
+provided by the library.
+
+So this is the fourth preview and implements concepts for all geometries. Besides that tag dispatching is
+introduced internally. All algorithms are now really generic, there are only two distance functions, one with two
+geometries and one with two geometries and a strategy. Those two will do. Internally they are first splitted
+per geometry, so point-to-point distance and point-to-linestring distance, etc. Then they are splitted per
+coordinate system, so Cartesian points have another distance calculation then spherical points. Finally those
+strategies, as they are called, are applied.
+
+\section changes4 Changes since preview 3
+- there are now typedefs for the more common geometries, such as point_2d or ring_ll_deg
+- all geometries are optional, everything is working with concepts
+- the convex hull algorithm has been added and can be calculated for linestrings (ranges, point sequences), polygons
+- map projections (92 !) have been added, they are converted to C++ template classes from PROJ4
+- transformations have been added, to go from one coordinate system to another
+- conversions have been added, to go from one geometry type to another (e.g. BOX to POLYGON)
+- edit functionality have been added, to edit coordinate values or to add points
+- parsing of latitude longitude coordinate values have been added
+- the "selected" algorithm have been added
+- many examples have been added
+- many tests have been added
+
+\b Breaking \b changes
+Because the library was in preview, and it still is, there are some major changes which might influence library user's
+code. Although there are many changes internally, the changes for users should be relatively small:
+- all algorithms accepting linestrings are now modelled to get the linestring itself. In the previous version
+  the .begin(), end() had to be specified, That is now not necessary anymore because the Boost Range Library is used
+  internally, and tag dispatching is used to distinguish geometries internally
+- the "grow" utility is now splitted into buffer (growing a box with a value was in fact a buffer) and a combine.
+- there was a generic "get" function with a const ref and a non const ref. This is splitted into "get" and "set"
+- there might be more changes, please contact if anything is unclear
+
+\section changes5 Changes since preview 4
+The change from preview 3 to preview 4 was major and many things have been addressed. Concepts are everywhere,
+algorithms are really generic, not dependant on geometry type. The library is coordinate agnostic and dimensional
+agnostic.So the design is stable, in that sense.
+However, there are changes:
+- implementation of spatial set relations (intersection, union)
+- move of GIS-specific code to extension/gis
+- move of map projections to extensions/gis/projections
+- implementation of SVG in extensions/SVG
+- review of all code, conform Boost code guidelines, no tabs, template parameters, etc.
+- other small changes.
+
+
+
+If people are interested in helping with the library, be it by coding, by testing, by commenting or otherwise, they
+are very welcome.
+
+\section history History
+Geodan started in 1995 with a Geographic Library, called geolib or also GGL (Geodan Geographic Library).
+Since then hundreds of projects have
+been done using this geolib, and the geolib have been extended to fit the needs of its users. Geolib
+can be used in different environments: in Windows applications, as a DLL (ggl32.dll), in
+Web Map Servers (SclMapServer), Web Feature Servers or more specific programs.
+
+In 2007-2009 the Geometry part has been revised and completely templatized.
+From 2008 Bruno Lalande, already a Boost contributor, joined and helped
+to make the library more generic and to define clear concepts.
+It is now called Generic Geometry Library, abbreviated to GGL.
+From 2009 Mateusz Loskot, an active member of Geospatial Open Source communities,
+joined and helped with reviewing code, guidelines, WKB, iterators, and the Wiki and ticket system
+
+The library is now called Generic Geometry Library, abbreviated to GGL.
+The Generic Geometry Library is Open Source and is proposed to the Boost community.
+
+
+*/
+
+
+//---------------------------------------------------------------------------------------------------
+
+/*!
+\page download Download the Generic Geometry Library
+
+The library can be downloaded from Boost SVN. There is anonymous SVN access.
+
+The command
+
+<tt>svn co https://svn.boost.org/svn/boost/sandbox/ggl ggl</tt>
+
+will download the library to your machine.
+
+Current "formal review request" version is here:
+https://svn.boost.org/svn/boost/sandbox/ggl/formal_review_request
+
+
+*/
+
+
+
+
+
+#endif // _DOXYGEN_PAGES_HPP

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_2.cpp
==============================================================================
--- (empty file)
+++ sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_2.cpp	2009-10-13 12:08:35 EDT (Tue, 13 Oct 2009)
@@ -0,0 +1,158 @@
+// Generic Geometry Library
+//
+// Copyright Barend Gehrels 1995-2009, Geodan Holding B.V. Amsterdam, the Netherlands.
+// Copyright Bruno Lalande 2008, 2009
+// Use, modification and distribution is subject to the Boost Software License,
+// Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+//
+// Doxygen Examples, referred to from the sources
+
+#include <boost/tuple/tuple.hpp>
+
+#if defined(_MSC_VER)
+// We deliberately mix float/double's here so turn off warning
+//#pragma warning( disable : 4244 )
+#endif // defined(_MSC_VER)
+
+#include <ggl/ggl.hpp>
+#include <ggl/algorithms/overlaps.hpp>
+#include <ggl/geometries/geometries.hpp>
+#include <ggl/geometries/cartesian2d.hpp>
+#include <ggl/geometries/register/point.hpp>
+#include <ggl/geometries/adapted/tuple_cartesian.hpp>
+#include <ggl/geometries/adapted/c_array_cartesian.hpp>
+#include <ggl/geometries/adapted/std_as_linestring.hpp>
+
+
+// Small QRect simulations following http://doc.trolltech.com/4.4/qrect.html
+// Todo: once work the traits out further, would be nice if there is a real example of this.
+// However for the example it makes no difference, it will work any way.
+struct QPoint
+{
+    int x, y;
+    // In Qt these are methods but for example below it makes no difference
+};
+
+struct QRect
+{
+    int x, y, width, height;
+    QRect(int _x, int _y, int w, int h)
+        : x(_x), y(_y), width(w), height(h)
+    {}
+    // In Qt these are methods but that will work as well, requires changing traits below
+};
+
+
+// Would be get/set with x(),y(),setX(),setY()
+GEOMETRY_REGISTER_POINT_2D(QPoint, int, cs::cartesian, x, y)
+
+
+// Register the QT rectangle. The macro(s) does not offer (yet) enough flexibility to do this in one line,
+// but the traits classes do their job perfectly.
+namespace ggl
+{
+    namespace traits
+    {
+
+        template <> struct tag<QRect> { typedef box_tag type; };
+        template <> struct point_type<QRect> { typedef QPoint type; };
+
+        template <size_t C, size_t D>
+        struct indexed_access<QRect, C, D>
+        {
+            static inline int get(const QRect& qr)
+            {
+                // Would be: x(), y(), width(), height()
+                return C == min_corner && D == 0 ? qr.x
+                        : C == min_corner && D == 1 ? qr.y
+                        : C == max_corner && D == 0 ? qr.x + qr.width
+                        : C == max_corner && D == 1 ? qr.y + qr.height
+                        : 0;
+            }
+
+            static inline void set(QRect& qr, const int& value)
+            {
+                // Would be: setX, setY, setWidth, setHeight
+                if (C == min_corner && D == 0) qr.x = value;
+                else if (C == min_corner && D == 1) qr.y = value;
+                else if (C == max_corner && D == 0) qr.width = value - qr.x;
+                else if (C == max_corner && D == 1) qr.height = value - qr.y;
+            }
+        };
+
+    }
+}
+
+
+void example_for_main_page()
+{
+    using namespace ggl;
+
+    int a[2] = {1,1};
+    int b[2] = {2,3};
+    double d = distance(a, b);
+    std::cout << "Distance a-b is:" << d << std::endl;
+
+    ring_2d poly;
+    double points[][2] = {{2.0, 1.3}, {4.1, 3.0}, {5.3, 2.6}, {2.9, 0.7}, {2.0, 1.3}};
+    append(poly, points);
+    boost::tuple<double, double> p = boost::make_tuple(3.7, 2.0);
+    std::cout << "Point p is in polygon? " << (within(p, poly) ? "YES" : "NO")  << std::endl;
+
+    std::cout << "Area: " << area(poly) << std::endl;
+
+    double d2 = distance(a, p);
+    std::cout << "Distance a-p is:" << d2 << std::endl;
+
+    /***
+    Now extension
+    point_ll_deg  amsterdam, paris;
+    parse(amsterdam, "52 22 23 N", "4 53 32 E");
+    parse(paris, "48 52 0 N", "2 19 59 E");
+    std::cout << "Distance A'dam-Paris: " << distance(amsterdam, paris) / 1000.0 << " kilometers " << std::endl;
+    ***/
+
+    QRect r1(100, 200, 15, 15);
+    QRect r2(110, 210, 20, 20);
+    if (overlaps(r1, r2))
+    {
+        assign(r2, 200, 300, 220, 320);
+    }
+}
+
+
+void example_for_transform()
+{
+    using namespace ggl;
+
+    typedef point<double, 3, cs::cartesian> XYZ;
+    typedef point<double, 3, cs::spherical<degree> >  SPH;
+    XYZ p;
+
+    SPH sph1, sph2;
+    assign(sph1, 12.5, 41.90, 1.0);
+    // Go from spherical to Cartesian-3D:
+    transform(sph1, p);
+    // Go back from Cartesian 3D to spherical:
+    transform(p, sph2);
+
+    std::cout << dsv(p) << " <-> " << dsv(sph2) << std::endl;
+
+    typedef point_xy<double> XY;
+    typedef point_xy<int> PIXEL;
+    XY xy(50, 50);
+    strategy::transform::map_transformer<XY, PIXEL, false> map(0, 0, 100, 100, 1024, 768);
+    PIXEL pix;
+    transform(xy, pix, map);
+    std::cout << pix.x() << "," << pix.y() << std::endl;
+
+}
+
+
+int main(void)
+{
+    example_for_main_page();
+    example_for_transform();
+    return 0;
+}

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_2.vcproj
==============================================================================
--- (empty file)
+++ sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_2.vcproj	2009-10-13 12:08:35 EDT (Tue, 13 Oct 2009)
@@ -0,0 +1,182 @@
+<?xml version="1.0" encoding="Windows-1252"?>
+<VisualStudioProject
+	ProjectType="Visual C++"
+	Version="8.00"
+	Name="doxygen_2"
+	ProjectGUID="{6CF6A521-57E0-4DA4-9D17-ED5D29E4208C}"
+	RootNamespace="doxygen_2"
+	Keyword="Win32Proj"
+	>
+	<Platforms>
+		<Platform
+			Name="Win32"
+		/>
+	</Platforms>
+	<ToolFiles>
+	</ToolFiles>
+	<Configurations>
+		<Configuration
+			Name="Debug|Win32"
+			OutputDirectory="$(SolutionDir)$(ConfigurationName)"
+			IntermediateDirectory="$(ConfigurationName)\doxygen_2"
+			ConfigurationType="1"
+			InheritedPropertySheets=".\boost.vsprops"
+			CharacterSet="1"
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				Optimization="0"
+				AdditionalIncludeDirectories="../../../../../boost"
+				PreprocessorDefinitions="WIN32;_DEBUG;_CONSOLE"
+				MinimalRebuild="true"
+				RuntimeLibrary="3"
+				UsePrecompiledHeader="0"
+				DebugInformationFormat="3"
+			/>
+			<Tool
+				Name="VCManagedResourceCompilerTool"
+			/>
+			<Tool
+				Name="VCResourceCompilerTool"
+			/>
+			<Tool
+				Name="VCPreLinkEventTool"
+			/>
+			<Tool
+				Name="VCLinkerTool"
+				AdditionalDependencies="kernel32.lib $(NoInherit)"
+				LinkIncremental="2"
+				GenerateDebugInformation="true"
+				SubSystem="1"
+				TargetMachine="1"
+			/>
+			<Tool
+				Name="VCALinkTool"
+			/>
+			<Tool
+				Name="VCManifestTool"
+			/>
+			<Tool
+				Name="VCXDCMakeTool"
+			/>
+			<Tool
+				Name="VCBscMakeTool"
+			/>
+			<Tool
+				Name="VCFxCopTool"
+			/>
+			<Tool
+				Name="VCAppVerifierTool"
+			/>
+			<Tool
+				Name="VCWebDeploymentTool"
+			/>
+			<Tool
+				Name="VCPostBuildEventTool"
+				CommandLine=""
+			/>
+		</Configuration>
+		<Configuration
+			Name="Release|Win32"
+			OutputDirectory="$(SolutionDir)$(ConfigurationName)"
+			IntermediateDirectory="$(ConfigurationName)\doxygen_2"
+			ConfigurationType="1"
+			InheritedPropertySheets=".\boost.vsprops"
+			CharacterSet="1"
+			WholeProgramOptimization="1"
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				AdditionalIncludeDirectories="../../../../../boost"
+				PreprocessorDefinitions="WIN32;NDEBUG;_CONSOLE"
+				RuntimeLibrary="2"
+				UsePrecompiledHeader="0"
+				DebugInformationFormat="3"
+			/>
+			<Tool
+				Name="VCManagedResourceCompilerTool"
+			/>
+			<Tool
+				Name="VCResourceCompilerTool"
+			/>
+			<Tool
+				Name="VCPreLinkEventTool"
+			/>
+			<Tool
+				Name="VCLinkerTool"
+				AdditionalDependencies="kernel32.lib $(NoInherit)"
+				LinkIncremental="1"
+				GenerateDebugInformation="true"
+				SubSystem="1"
+				OptimizeReferences="2"
+				EnableCOMDATFolding="2"
+				TargetMachine="1"
+			/>
+			<Tool
+				Name="VCALinkTool"
+			/>
+			<Tool
+				Name="VCManifestTool"
+			/>
+			<Tool
+				Name="VCXDCMakeTool"
+			/>
+			<Tool
+				Name="VCBscMakeTool"
+			/>
+			<Tool
+				Name="VCFxCopTool"
+			/>
+			<Tool
+				Name="VCAppVerifierTool"
+			/>
+			<Tool
+				Name="VCWebDeploymentTool"
+			/>
+			<Tool
+				Name="VCPostBuildEventTool"
+				CommandLine=""
+			/>
+		</Configuration>
+	</Configurations>
+	<References>
+	</References>
+	<Files>
+		<File
+			RelativePath=".\doxygen_2.cpp"
+			>
+		</File>
+	</Files>
+	<Globals>
+	</Globals>
+</VisualStudioProject>

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_examples.cpp
==============================================================================
--- (empty file)
+++ sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_examples.cpp	2009-10-13 12:08:35 EDT (Tue, 13 Oct 2009)
@@ -0,0 +1,670 @@
+// Generic Geometry Library
+//
+// Copyright Barend Gehrels 1995-2009, Geodan Holding B.V. Amsterdam, the Netherlands.
+// Copyright Bruno Lalande 2008, 2009
+// Use, modification and distribution is subject to the Boost Software License,
+// Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+//
+// Doxygen Examples, referred to from the sources
+
+#include <boost/tuple/tuple.hpp>
+
+#if defined(_MSC_VER)
+// We deliberately mix float/double's here so turn off warning
+#pragma warning( disable : 4244 )
+#endif // defined(_MSC_VER)
+
+#include <ggl/ggl.hpp>
+#include <ggl/geometries/geometries.hpp>
+#include <ggl/geometries/adapted/std_as_linestring.hpp>
+
+#include <ggl/extensions/gis/io/wkt/wkt.hpp>
+
+
+// All functions below are referred to in the source of the Geometry Library.
+// Don't rename them.
+
+void example_area_polygon()
+{
+    ggl::polygon<ggl::point_xy<double> > poly;
+    ggl::read_wkt("POLYGON((0 0,0 7,4 2,2 0,0 0))", poly);
+    std::cout << "Polygon area is "
+        << ggl::area(poly)
+        << " square units" << std::endl;
+
+    /*
+    Extension, other coordinate system:
+    ggl::polygon<ggl::point_ll<float, ggl::cs::geographic<ggl::degree> > > poly_ll;
+    ggl::read_wkt("POLYGON((4 51,4 52,5 52,5 51,4 51))", poly_ll);
+    std::cout << "Polygon area is "
+        << ggl::area(poly_ll)/(1000*1000)
+        << " square kilometers " << std::endl;
+    */
+}
+
+void example_as_wkt_point()
+{
+    typedef ggl::point_xy<double> P;
+    P p(5.12, 6.34);
+    // Points can be streamed like this:
+    std::cout << ggl::dsv<P>(p) << std::endl;
+
+    // or like this:
+    std::cout << ggl::dsv(p) << std::endl;
+
+    // or (with extension) like this:
+    std::cout << ggl::wkt(p) << std::endl;
+}
+
+void example_as_wkt_vector()
+{
+    std::vector<ggl::point_xy<int> > v;
+    ggl::read_wkt<ggl::point_xy<int> >("linestring(1 1,2 2,3 3,4 4)", std::back_inserter(v));
+
+    std::cout << ggl::dsv(std::make_pair(v.begin(), v.end())) << std::endl;
+}
+
+
+void example_centroid_polygon()
+{
+    ggl::polygon<ggl::point_xy<double> > poly;
+    ggl::read_wkt("POLYGON((0 0,0 7,4 2,2 0,0 0))", poly);
+    // Center of polygon might have different type then points of polygon
+    ggl::point_xy<float> center;
+    ggl::centroid(poly, center);
+    std::cout << "Centroid: " << center.x() << "," << center.y() << std::endl;
+}
+
+
+void example_distance_point_point()
+{
+    ggl::point_xy<double> p1(1, 1);
+    ggl::point_xy<double> p2(2, 3);
+    std::cout << "Distance p1-p2 is "
+        << ggl::distance(p1, p2)
+        << " units" << std::endl;
+
+    /*
+    Extension, other coordinate system:
+    // Read 2 Dutch cities from WKT texts (in decimal degrees)
+    ggl::point_ll<double, ggl::cs::geographic<ggl::degree> >  a, r;
+    ggl::read_wkt("POINT(4.89222 52.3731)", a);
+    ggl::read_wkt("POINT(4.47917 51.9308)", r);
+
+    std::cout << "Distance Amsterdam-Rotterdam is "
+        << ggl::distance(a, r) / 1000.0
+        << " kilometers " << std::endl;
+    */
+}
+
+void example_distance_point_point_strategy()
+{
+    /*
+    Extension, other coordinate system:
+    typedef ggl::point_ll<double, ggl::cs::geographic<ggl::degree> > LL;
+    LL a, r;
+    ggl::read_wkt("POINT(4.89222 52.3731)", a);
+    ggl::read_wkt("POINT(4.47917 51.9308)", r);
+
+    std::cout << "Distance Amsterdam-Rotterdam is "
+        << ggl::distance(a, r,
+                ggl::strategy::distance::vincenty<LL>() )
+                 / 1000.0
+        << " kilometers " << std::endl;
+    */
+}
+
+void example_from_wkt_point()
+{
+    ggl::point_xy<int> point;
+    ggl::read_wkt("Point(1 2)", point);
+    std::cout << point.x() << "," << point.y() << std::endl;
+}
+
+void example_from_wkt_output_iterator()
+{
+    std::vector<ggl::point_xy<int> > v;
+    ggl::read_wkt<ggl::point_xy<int> >("linestring(1 1,2 2,3 3,4 4)", std::back_inserter(v));
+    std::cout << "vector has " << v.size() << " coordinates" << std::endl;
+}
+
+void example_from_wkt_linestring()
+{
+    ggl::linestring<ggl::point_xy<double> > line;
+    ggl::read_wkt("linestring(1 1,2 2,3 3,4 4)", line);
+    std::cout << "linestring has " << line.size() << " coordinates" << std::endl;
+}
+
+void example_from_wkt_polygon()
+{
+    ggl::polygon<ggl::point_xy<double> > poly;
+    ggl::read_wkt("POLYGON((0 0,0 1,1 1,1 0,0 0))", poly);
+    std::cout << "Polygon has " << poly.outer().size() << " coordinates in outer ring" << std::endl;
+}
+
+void example_point_ll_convert()
+{
+    /*
+    Extension, other coordinate system:
+    ggl::point_ll<double, ggl::cs::geographic<ggl::degree> > deg(ggl::latitude<>(33.0), ggl::longitude<>(-118.0));
+    ggl::point_ll<double, ggl::cs::geographic<ggl::radian> > rad;
+    ggl::transform(deg, rad);
+
+    std::cout << "point in radians: " << rad << std::endl;
+    */
+}
+
+void example_intersection_linestring1()
+{
+    typedef ggl::point_xy<double> P;
+    ggl::linestring<P> line;
+    ggl::read_wkt("linestring(1.1 1.1, 2.5 2.1, 3.1 3.1, 4.9 1.1, 3.1 1.9)", line);
+    ggl::box<P> cb(P(1.5, 1.5), P(4.5, 2.5));
+    std::cout << "Clipped linestring(s) " << std::endl;
+    /*
+    TODO: does not work because streamwkt is now extension and not included
+        so make other construct
+    ggl::intersection<ggl::linestring<P> > (cb, line,
+            std::ostream_iterator<ggl::linestring<P> >(std::cout, "\n"));
+    */
+}
+
+void example_intersection_linestring2()
+{
+    typedef ggl::point_xy<double> P;
+    std::vector<P> vector_in;
+    ggl::read_wkt<P>("linestring(1.1 1.1, 2.5 2.1, 3.1 3.1, 4.9 1.1, 3.1 1.9)",
+                    std::back_inserter(vector_in));
+
+    ggl::box<P> cb(P(1.5, 1.5), P(4.5, 2.5));
+    typedef std::vector<std::vector<P> > VV;
+    VV vector_out;
+    ggl::intersection<std::vector<P>  >(cb, vector_in, std::back_inserter(vector_out));
+
+    std::cout << "Clipped vector(s) " << std::endl;
+    for (VV::const_iterator it = vector_out.begin(); it != vector_out.end(); it++)
+    {
+        std::copy(it->begin(), it->end(), std::ostream_iterator<P>(std::cout, " "));
+        std::cout << std::endl;
+    }
+}
+
+
+
+
+
+void example_intersection_polygon1()
+{
+    typedef ggl::point_xy<double> P;
+    typedef std::vector<ggl::polygon<P> > PV;
+
+    ggl::box<P> cb(P(1.5, 1.5), P(4.5, 2.5));
+    ggl::polygon<P> poly;
+    ggl::read_wkt("POLYGON((2 1.3,2.4 1.7,2.8 1.8,3.4 1.2,3.7 1.6,3.4 2,4.1 3,5.3 2.6,5.4 1.2,4.9 0.8,2.9 0.7,2 1.3)"
+            ",(4 2,4.2 1.4,4.8 1.9,4.4 2.2,4 2))", poly);
+
+    PV v;
+    ggl::intersection<ggl::polygon<P> >(cb, poly, std::back_inserter(v));
+
+    std::cout << "Clipped polygon(s) " << std::endl;
+    for (PV::const_iterator it = v.begin(); it != v.end(); it++)
+    {
+        std::cout << ggl::dsv(*it) << std::endl;
+    }
+}
+
+void example_simplify_linestring1()
+{
+    ggl::linestring<ggl::point_xy<double> > line, simplified;
+    ggl::read_wkt("linestring(1.1 1.1, 2.5 2.1, 3.1 3.1, 4.9 1.1, 3.1 1.9)", line);
+    ggl::simplify(line, std::back_inserter(simplified), 0.5);
+    std::cout
+        << "  original line: " << ggl::dsv(line) << std::endl
+        << "simplified line: " << ggl::dsv(simplified) << std::endl;
+}
+
+void example_simplify_linestring2()
+{
+    typedef ggl::point_xy<double> P;
+    typedef ggl::linestring<P> L;
+    L line;
+
+    ggl::read_wkt("linestring(1.1 1.1, 2.5 2.1, 3.1 3.1, 4.9 1.1, 3.1 1.9)", line);
+
+    typedef ggl::strategy::distance::xy_point_segment<P, ggl::segment<const P> > DS;
+    typedef std::ostream_iterator<P> OUT;
+    typedef ggl::strategy::simplify::douglas_peucker<L, OUT, DS> simplification;
+    ggl::simplify(line, OUT(std::cout, "\n"), 0.5, simplification());
+}
+
+
+
+void example_within()
+{
+    ggl::polygon<ggl::point_xy<double> > poly;
+    ggl::read_wkt("POLYGON((0 0,0 7,4 2,2 0,0 0))", poly);
+    ggl::point_xy<float> point(3, 3);
+    std::cout << "Point is "
+        << (ggl::within(point, poly) ? "IN" : "NOT in")
+        << " polygon"
+        << std::endl;
+}
+
+/*
+void example_within_strategy()
+{
+    // TO BE UPDATED/FINISHED
+    typedef ggl::point_xy<double> P;
+    typedef ggl::polygon<P> POLY;
+    P p;
+    std::cout << within(p, poly, strategy::within::cross_count<P>) << std::endl;
+}
+*/
+
+void example_length_linestring()
+{
+    using namespace ggl;
+    linestring<point_xy<double> > line;
+    read_wkt("linestring(0 0,1 1,4 8,3 2)", line);
+    std::cout << "linestring length is "
+        << length(line)
+        << " units" << std::endl;
+
+    /*
+    Extension, other coordinate system:
+    // Linestring in latlong, filled with
+    // explicit degree-minute-second values
+    typedef point_ll<float, ggl::cs::geographic<ggl::degree> > LL;
+    linestring<LL> line_ll;
+    line_ll.push_back(LL(
+        latitude<float>(dms<north, float>(52, 22, 23)),
+        longitude<float>(dms<east, float>(4, 53, 32))));
+    line_ll.push_back(LL(
+        latitude<float>(dms<north, float>(51, 55, 51)),
+        longitude<float>(dms<east, float>(4, 28, 45))));
+    line_ll.push_back(LL(
+        latitude<float>(dms<north, float>(52, 4, 48)),
+        longitude<float>(dms<east, float>(4, 18, 0))));
+    std::cout << "linestring length is "
+        << length(line_ll) / 1000
+        << " kilometers " << std::endl;
+        */
+}
+
+void example_length_linestring_iterators1()
+{
+    ggl::linestring<ggl::point_xy<double> > line;
+    ggl::read_wkt("linestring(0 0,1 1,4 8,3 2)", line);
+    std::cout << "linestring length is "
+        << ggl::length(line)
+        << " units" << std::endl;
+}
+
+void example_length_linestring_iterators2()
+{
+    std::vector<ggl::point_xy<double> > line;
+    ggl::read_wkt<ggl::point_xy<double> >("linestring(0 0,1 1,4 8,3 2)", std::back_inserter(line));
+    std::cout << "linestring length is "
+        << ggl::length(line)
+        << " units" << std::endl;
+}
+
+void example_length_linestring_iterators3()
+{
+    /*
+    Extension, other coordinate system:
+    using namespace ggl;
+    typedef point_ll<float, ggl::cs::geographic<ggl::degree> > LL;
+    std::deque<LL> line;
+    ggl::read_wkt<LL>("linestring(0 51,1 51,2 52)", std::back_inserter(line));
+    std::cout << "linestring length is "
+        << 0.001 * ggl::length(line, ggl::strategy::distance::vincenty<LL>())
+        << " kilometers" << std::endl;
+    */
+}
+
+
+void example_length_linestring_strategy()
+{
+    /*
+    Extension, other coordinate system:
+    using namespace ggl;
+    typedef point_ll<float, ggl::cs::geographic<ggl::degree> > LL;
+    linestring<LL> line_ll;
+    line_ll.push_back(LL(latitude<float>(dms<north, float>(52, 22, 23)), longitude<float>(dms<east, float>(4, 53, 32))));
+    line_ll.push_back(LL(latitude<float>(dms<north, float>(51, 55, 51)), longitude<float>(dms<east, float>(4, 28, 45))));
+    line_ll.push_back(LL(latitude<float>(dms<north, float>(52, 4, 48)), longitude<float>(dms<east, float>(4, 18, 0))));
+    std::cout << "linestring length is "
+        << length(line_ll, strategy::distance::vincenty<LL, LL>() )/(1000)
+        << " kilometers " << std::endl;
+    */
+}
+
+
+void example_envelope_linestring()
+{
+    ggl::linestring<ggl::point_xy<double> > line;
+    ggl::read_wkt("linestring(0 0,1 1,4 8,3 2)", line);
+    ggl::box<ggl::point_xy<double> > box;
+    ggl::envelope(line, box);
+
+    std::cout << "envelope is " << ggl::dsv(box) << std::endl;
+}
+
+void example_envelope_polygon()
+{
+    /*
+    Extension, other coordinate system:
+    using namespace ggl;
+    typedef point_ll<double, ggl::cs::geographic<ggl::degree> >  LL;
+
+    // Wrangel island, 180 meridian crossing island above Siberia.
+    polygon<LL> wrangel;
+    wrangel.outer().push_back(LL(latitude<>(dms<north>(70, 47, 7)), longitude<>(dms<west>(178, 47, 9))));
+    wrangel.outer().push_back(LL(latitude<>(dms<north>(71, 14, 0)), longitude<>(dms<east>(177, 28, 33))));
+    wrangel.outer().push_back(LL(latitude<>(dms<north>(71, 34, 24)), longitude<>(dms<east>(179, 44, 37))));
+    // Close it
+    wrangel.outer().push_back(wrangel.outer().front());
+
+    ggl::box<LL> box;
+    ggl::envelope(wrangel, box);
+
+    dms<cd_lat> minlat(box.min_corner().lat());
+    dms<cd_lon> minlon(box.min_corner().lon());
+
+    dms<cd_lat> maxlat(box.max_corner().lat());
+    dms<cd_lon> maxlon(box.max_corner().lon());
+
+    std::cout << wrangel << std::endl;
+    std::cout << "min: " << minlat.get_dms() << " , " << minlon.get_dms() << std::endl;
+    std::cout << "max: " << maxlat.get_dms() << " , " << maxlon.get_dms() << std::endl;
+    */
+}
+
+
+void example_dms()
+{
+    /*
+    Extension, other coordinate system:
+    // Construction with degree/minute/seconds
+    ggl::dms<ggl::east> d1(4, 53, 32.5);
+
+    // Explicit conversion to double.
+    std::cout << d1.as_value() << std::endl;
+
+    // Conversion to string, with optional strings
+    std::cout << d1.get_dms(" deg ", " min ", " sec") << std::endl;
+
+    // Combination with latitude/longitude and cardinal directions
+    {
+        using namespace ggl;
+        point_ll<double, ggl::cs::geographic<ggl::degree> > canberra(
+            latitude<>(dms<south>(35, 18, 27)),
+            longitude<>(dms<east>(149, 7, 27.9)));
+        std::cout << canberra << std::endl;
+    }
+    */
+}
+
+void example_point_ll_construct()
+{
+    /*
+    Extension, other coordinate system:
+    using namespace ggl;
+    typedef point_ll<double, ggl::cs::geographic<ggl::degree> > ll;
+
+    // Constructions in both orders possible
+    ll juneau(
+        latitude<>(dms<north>(58, 21, 5)),
+        longitude<>(dms<west>(134, 30, 42)));
+    ll wladiwostok(
+        longitude<>(dms<east>(131, 54)),
+        latitude<>(dms<north>(43, 8))
+        );
+    */
+}
+
+namespace example_loop1
+{
+    // Class functor
+    template <typename P>
+    struct perimeter
+    {
+        struct summation
+        {
+            double sum;
+            summation() : sum(0) {}
+        };
+
+        bool operator()(const ggl::segment<const P>& segment, summation& s) const
+        {
+            std::cout << "from " << segment.first << " to " << segment.second << std::endl;
+            s.sum += ggl::distance(segment.first, segment.second);
+            return true;
+        }
+    };
+
+    void example()
+    {
+        typedef ggl::point_xy<double> P;
+        ggl::polygon<P> poly;
+        ggl::read_wkt("POLYGON((0 0,0 7,4 2,2 0,0 0))", poly);
+        perimeter<P>::summation peri;
+        ggl::loop(poly.outer(), perimeter<P>(), peri);
+        std::cout << "Perimeter: " << peri.sum << std::endl;
+    }
+} //:\\
+
+
+namespace example_loop2
+{
+    struct summation
+    {
+        double sum;
+        summation() : sum(0) {}
+    };
+
+    // Function functor
+    template <typename P>
+    bool perimeter(const ggl::segment<const P>& segment, summation& s)
+    {
+        std::cout << "from " << segment.first << " to " << segment.second << std::endl;
+        s.sum += ggl::distance(segment.first, segment.second);
+        return true;
+    }
+
+    void example()
+    {
+        /*
+        Extension, other coordinate system:
+        typedef ggl::point_ll<double, ggl::cs::geographic<ggl::degree> > P;
+        ggl::polygon<P> poly;
+        ggl::read_wkt("POLYGON((-178.786 70.7853,177.476 71.2333,179.744 71.5733,-178.786 70.7853))", poly);
+        summation peri;
+        ggl::loop(poly.outer(), perimeter<P>, peri);
+        std::cout << "Perimeter: " << peri.sum/1000.0 << " km" << std::endl;
+        */
+    }
+} //:\\
+
+
+
+struct example_point_1
+{
+    // Example point, for example a legacy point defining somewhere an x and an y coordinate
+    double x, y;
+};
+
+
+namespace ggl
+{
+    namespace traits
+    {
+        template <int I> struct accessor;
+
+        template <> struct accessor<0>
+        {
+            inline static double get(const example_point_1& p) { return p.x; }
+            inline static void set(example_point_1& p, const double& value) { p.x = value; }
+        };
+
+        template <> struct accessor<1>
+        {
+            inline static double get(const example_point_1& p) { return p.y; }
+            inline static void set(example_point_1& p, const double& value) { p.y = value; }
+        };
+
+        // For legacy points, define the necessary structs coordinate (with typedef),
+        // dimension (with value) and access (with get function).
+        // Be sure to define them within the namespace ggl::traits
+        template <> struct tag<example_point_1> { typedef point_tag type; };
+        template <> struct coordinate_type<example_point_1> { typedef double type; };
+        template <> struct coordinate_system<example_point_1> { typedef cs::cartesian type; };
+        template <> struct dimension<example_point_1>: boost::mpl::int_<2> {};
+        template <> struct access<example_point_1>
+        {
+            template <int I>
+            static double get(const example_point_1& p)
+            { return accessor<I>::get(p); }
+
+            template <int I>
+            static void set(example_point_1& p, const double& value)
+            { accessor<I>::set(p, value); }
+        };
+    }
+}
+
+namespace example_own_point1
+{
+    // The first way to check a concept at compile time: checking if the input is parameter
+    // or return type is OK.
+    template <typename P>
+    BOOST_CONCEPT_REQUIRES(((ggl::concept::Point<P>)), (void))
+    test1(P& p)
+    {
+    }
+
+    // The second way to check a concept at compile time: checking if the provided type,
+    // inside the function, if OK
+    template <typename P>
+    void test2(P& p)
+    {
+        BOOST_CONCEPT_ASSERT((ggl::concept::Point<P>));
+    }
+
+
+    void example()
+    {
+        example_point_1 p;
+        test1(p);
+        test2(p);
+    }
+} //:\\
+
+
+
+namespace example_own_point2
+{
+    struct example_point_2: boost::tuple<float, float>
+    {
+        example_point_2(float x, float y)
+        {
+            get<0>() = x;
+            get<1>() = y;
+        }
+    };
+}
+
+// WILL BE CONVERTED TO MACRO
+namespace ggl
+{
+    namespace traits
+    {
+        using namespace example_own_point2;
+
+        template <> struct tag<example_point_2  > { typedef point_tag type; };
+        template <> struct coordinate_type<example_point_2 > { typedef float type; };
+        template <> struct coordinate_system<example_point_2 > { typedef ggl::cs::cartesian type; };
+        template <> struct dimension<example_point_2 > : boost::mpl::int_<2> {};
+        template <> struct access<example_point_2 >
+        {
+            template <int I>
+            static inline float get(const example_point_2& p) { return p.get<I>(); }
+
+            template <int I>
+            static inline void set(example_point_2& p, const float& value) { p.get<I>() = value; }
+        };
+
+        // The library user has
+        // 1) either to specify the coordinate system
+        // 2) or include <ggl/geometries/adapted/tuple__at_.hpp> where @=cartesian,geographic,...
+    }
+}
+
+
+namespace example_own_point2
+{
+
+
+    template <typename P>
+    BOOST_CONCEPT_REQUIRES(((ggl::concept::ConstPoint<P>)), (float))
+    test3(P& p)
+    {
+        return ggl::get<0>(p);
+    }
+
+    void example()
+    {
+        example_point_2 p(1,2);
+        test3(p);
+    }
+} //:\\
+
+
+
+int main(void)
+{
+    example_area_polygon();
+
+    example_centroid_polygon();
+
+    example_distance_point_point();
+    example_distance_point_point_strategy();
+
+    example_from_wkt_point();
+    example_from_wkt_output_iterator();
+    example_from_wkt_linestring();
+    example_from_wkt_polygon();
+
+    example_as_wkt_point();
+
+    example_intersection_linestring1();
+    example_intersection_linestring2();
+    example_intersection_polygon1();
+
+    example_simplify_linestring1();
+    example_simplify_linestring2();
+
+    example_length_linestring();
+    example_length_linestring_iterators1();
+    example_length_linestring_iterators2();
+    example_length_linestring_iterators3();
+    example_length_linestring_strategy();
+
+    example_envelope_linestring();
+    example_envelope_polygon();
+
+    example_within();
+
+    example_point_ll_convert();
+    example_point_ll_construct();
+    example_dms();
+
+    example_loop1::example();
+    example_loop2::example();
+    example_own_point1::example();
+    example_own_point2::example();
+
+    return 0;
+}

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_examples.sln
==============================================================================
--- (empty file)
+++ sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_examples.sln	2009-10-13 12:08:35 EDT (Tue, 13 Oct 2009)
@@ -0,0 +1,25 @@
+Microsoft Visual Studio Solution File, Format Version 9.00
+# Visual C++ Express 2005
+Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "doxygen_examples", "doxygen_examples.vcproj", "{861F130D-2849-4B50-B240-049DBD9D3F18}"
+EndProject
+Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "doxygen_2", "doxygen_2.vcproj", "{6CF6A521-57E0-4DA4-9D17-ED5D29E4208C}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Win32 = Debug|Win32
+		Release|Win32 = Release|Win32
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{861F130D-2849-4B50-B240-049DBD9D3F18}.Debug|Win32.ActiveCfg = Debug|Win32
+		{861F130D-2849-4B50-B240-049DBD9D3F18}.Debug|Win32.Build.0 = Debug|Win32
+		{861F130D-2849-4B50-B240-049DBD9D3F18}.Release|Win32.ActiveCfg = Release|Win32
+		{861F130D-2849-4B50-B240-049DBD9D3F18}.Release|Win32.Build.0 = Release|Win32
+		{6CF6A521-57E0-4DA4-9D17-ED5D29E4208C}.Debug|Win32.ActiveCfg = Debug|Win32
+		{6CF6A521-57E0-4DA4-9D17-ED5D29E4208C}.Debug|Win32.Build.0 = Debug|Win32
+		{6CF6A521-57E0-4DA4-9D17-ED5D29E4208C}.Release|Win32.ActiveCfg = Release|Win32
+		{6CF6A521-57E0-4DA4-9D17-ED5D29E4208C}.Release|Win32.Build.0 = Release|Win32
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+EndGlobal

Added: sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_examples.vcproj
==============================================================================
--- (empty file)
+++ sandbox/ggl/formal_review_request/libs/ggl/doc/doxygen_input/sourcecode/doxygen_examples.vcproj	2009-10-13 12:08:35 EDT (Tue, 13 Oct 2009)
@@ -0,0 +1,198 @@
+<?xml version="1.0" encoding="Windows-1252"?>
+<VisualStudioProject
+	ProjectType="Visual C++"
+	Version="8.00"
+	Name="doxygen_examples"
+	ProjectGUID="{861F130D-2849-4B50-B240-049DBD9D3F18}"
+	RootNamespace="doxygen_examples"
+	Keyword="Win32Proj"
+	>
+	<Platforms>
+		<Platform
+			Name="Win32"
+		/>
+	</Platforms>
+	<ToolFiles>
+	</ToolFiles>
+	<Configurations>
+		<Configuration
+			Name="Debug|Win32"
+			OutputDirectory="$(SolutionDir)$(ConfigurationName)"
+			IntermediateDirectory="$(ConfigurationName)\doxygen_examples"
+			ConfigurationType="1"
+			InheritedPropertySheets=".\boost.vsprops"
+			CharacterSet="1"
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				Optimization="0"
+				AdditionalIncludeDirectories="../../../../../boost"
+				PreprocessorDefinitions="WIN32;_DEBUG;_CONSOLE"
+				MinimalRebuild="true"
+				RuntimeLibrary="3"
+				UsePrecompiledHeader="0"
+				DebugInformationFormat="3"
+			/>
+			<Tool
+				Name="VCManagedResourceCompilerTool"
+			/>
+			<Tool
+				Name="VCResourceCompilerTool"
+			/>
+			<Tool
+				Name="VCPreLinkEventTool"
+			/>
+			<Tool
+				Name="VCLinkerTool"
+				AdditionalDependencies="kernel32.lib $(NoInherit)"
+				LinkIncremental="2"
+				GenerateDebugInformation="true"
+				SubSystem="1"
+				TargetMachine="1"
+			/>
+			<Tool
+				Name="VCALinkTool"
+			/>
+			<Tool
+				Name="VCManifestTool"
+			/>
+			<Tool
+				Name="VCXDCMakeTool"
+			/>
+			<Tool
+				Name="VCBscMakeTool"
+			/>
+			<Tool
+				Name="VCFxCopTool"
+			/>
+			<Tool
+				Name="VCAppVerifierTool"
+			/>
+			<Tool
+				Name="VCWebDeploymentTool"
+			/>
+			<Tool
+				Name="VCPostBuildEventTool"
+				CommandLine="cd ../doc&#x0D;&#x0A;doxygen&#x0D;&#x0A;"
+			/>
+		</Configuration>
+		<Configuration
+			Name="Release|Win32"
+			OutputDirectory="$(SolutionDir)$(ConfigurationName)"
+			IntermediateDirectory="$(ConfigurationName)\doxygen_examples"
+			ConfigurationType="1"
+			InheritedPropertySheets=".\boost.vsprops"
+			CharacterSet="1"
+			WholeProgramOptimization="1"
+			>
+			<Tool
+				Name="VCPreBuildEventTool"
+			/>
+			<Tool
+				Name="VCCustomBuildTool"
+			/>
+			<Tool
+				Name="VCXMLDataGeneratorTool"
+			/>
+			<Tool
+				Name="VCWebServiceProxyGeneratorTool"
+			/>
+			<Tool
+				Name="VCMIDLTool"
+			/>
+			<Tool
+				Name="VCCLCompilerTool"
+				AdditionalIncludeDirectories="../../../../../boost"
+				PreprocessorDefinitions="WIN32;NDEBUG;_CONSOLE"
+				RuntimeLibrary="2"
+				UsePrecompiledHeader="0"
+				DebugInformationFormat="3"
+			/>
+			<Tool
+				Name="VCManagedResourceCompilerTool"
+			/>
+			<Tool
+				Name="VCResourceCompilerTool"
+			/>
+			<Tool
+				Name="VCPreLinkEventTool"
+			/>
+			<Tool
+				Name="VCLinkerTool"
+				AdditionalDependencies="kernel32.lib $(NoInherit)"
+				LinkIncremental="1"
+				GenerateDebugInformation="true"
+				SubSystem="1"
+				OptimizeReferences="2"
+				EnableCOMDATFolding="2"
+				TargetMachine="1"
+			/>
+			<Tool
+				Name="VCALinkTool"
+			/>
+			<Tool
+				Name="VCManifestTool"
+			/>
+			<Tool
+				Name="VCXDCMakeTool"
+			/>
+			<Tool
+				Name="VCBscMakeTool"
+			/>
+			<Tool
+				Name="VCFxCopTool"
+			/>
+			<Tool
+				Name="VCAppVerifierTool"
+			/>
+			<Tool
+				Name="VCWebDeploymentTool"
+			/>
+			<Tool
+				Name="VCPostBuildEventTool"
+				CommandLine="cd ../doc&#x0D;&#x0A;doxygen&#x0D;&#x0A;"
+			/>
+		</Configuration>
+	</Configurations>
+	<References>
+	</References>
+	<Files>
+		<Filter
+			Name="Doxygen Files"
+			>
+			<File
+				RelativePath="../pages/doxygen_examples.hpp"
+				>
+			</File>
+			<File
+				RelativePath="../pages/doxygen_mainpage.hpp"
+				>
+			</File>
+			<File
+				RelativePath="../pages/doxygen_pages.hpp"
+				>
+			</File>
+		</Filter>
+		<File
+			RelativePath=".\doxygen_examples.cpp"
+			>
+		</File>
+	</Files>
+	<Globals>
+	</Globals>
+</VisualStudioProject>