Re: [boost] [Review] GGL review starts today, November 5th

Subject: Re: [boost] [Review] GGL review starts today, November 5th
From: Thomas Klimpel (Thomas.Klimpel_at_[hidden])
Date: 2009-11-11 12:45:02

Hi,
This is not yet a review. (There will be a real review, and I see no reasons why it should not be positive.)

1)

I wonder whether it would be possible to change the name "GGL" to "Boost.Geometry". Sure, it is no problem for the initialized to know what "GGL" can do, but the newcomer is just confronted with yet another acronym that tells him nothing.

I first thought that this change of name would disturb existing users of the library, but found out that they will have to change their code anyway:
using namespace ggl;
must be replaced with
using namespace boost::ggl;
and
#include <ggl/ggl.hpp>
must be replaced with
#include <boost/ggl/ggl.hpp>
after the library has been accepted into boost.

The same is true for the library itself, so the change from "ggl" to "boost::geometry" or "boost/geometry" is probably not more work than the change from "ggl" to "boost::ggl" and "boost/ggl"

Then I thought that the name GGL might be a reference to GIL. So I looked into the GIL library to find out why it emphasizes the "generic" part so much. It turned out that there is not a single best representation for images, and that GIL itself provides multiple different representations. This is a bit similar to STL that provides multiple containers, because there is not a single best container. GGL on the other hand provides just one point, linestring, linear_ring, polygon, box and segment class template, because the representation isn't really the challenge in the context of geometry. This is all perfect, but I just think that the "generic" in case of GGL refers to all the different "legacy" classes that essentially all use the same underlying representation of the geometry (point, box, ...), but are incompatible because of different names and conventions, whereas the generic in GIL and STL refers to fundamentally different representations of the underlying object that is unavoidable in principle.

The bottom line is that I think a real name should be preferred over an acronym if there is not a very good reason to use an acronym. I just tried to explain why I can't see this very good reason in this case.

2)

A second remark concerns the OGC names. Let's take the following code from 07_graph_route_example.cpp to illustrate:

    // Init a bounding box, lateron used to define SVG map
    ggl::box_2d box;
    ggl::assign_inverse(box);

    // Read the cities
    typedef boost::tuple<point_type, std::string, vertex_type> city_type;
    std::vector<city_type> cities;
    read_wkt<point_type>("data/cities.wkt", cities, box);

...

// Read an ASCII file containing WKT's, fill a vector of tuples
// The tuples consist of at least <0> a geometry and <1> an identifying string
template <typename Geometry, typename Tuple, typename Box>
void read_wkt(std::string const& filename, std::vector<Tuple>& tuples, Box& box)
{
...
 
               ggl::combine(box, ggl::make_envelope<Box>(geometry));
...
}

What does "ggl::assign_inverse" and "make_envelope" do? These are apparently OGC names, but I spend quite some time trying to verify that this is indeed the case. In fact, I just ended up accepting that this is probably indeed that case. These OGC names are OK, but ask yourself the question whether you would be able to understand the quoted code if you would not already know what "ggl::assign_inverse" and "make_envelope" do (I know it's easy to look it up in the documentation, but that is not the point). In fact, I will not tell you now, but I tried to be fair when quoting the source code, so as not to remove potentially clarifying comments or context.

The bottom line is that when the OGC conventions already force me to accept confusing names, it would at least be nice to know how I can verify that these are indeed OGC names. What are the reference documents I have to read to learn this?

Regards,
Thomas