Geometry Boost List: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook

Subject: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook
From: barend (barend.gehrels)
Date: 2010-03-13 05:30:57

Hi Mateusz,

> Yesterday I managed to get first good results of processing 
> Doxygen XML output to Quickbook/Boostbook documentation.
> Here it is:
> http://mateusz.loskot.net/tmp/ggl/qbk/ 
[http://mateusz.loskot.net/tmp/ggl/qbk/]

Again, it is giving a very good overview.

So here my feedback, most things are details. Along the way it is a
 
whole list now but the main message is: I'm really enthousiastic about 
that page.

I like the main structure with Concepts first, then Models, then 
Algorithms, and I also like the structure within the main sections with 
separate headings and then the real functionality.

The Arithmetic section can (I think) put below the 
algorithms, reason will follow below [1]

A section Strategies can be added below Algorithms

A section Constants and Enumerations can be added, probably above 
Algorithms, with things like min_corner, max_corner, clockwise, etc. It 
can 
also contain coordinate systems, degree/radian, which are not really 
constants or enumerations, but empty classes having the same 
functionality.

There is 
some 
functionality which is not yet there:

- compare
 
(equal_to, greater, less) which are not algorithms but policies which 
can be 
used for std::functions like unique and sort

- manipulators such as boost::geometry::dsv (and in extensions 
there is 
more)

- iterators

Will we put the Extensions in this Register? I'm not sure about 
that, probably not.

There are some functions that I doubted recently if they are on the
 
right place in core, and these are: num_points, num_interior_rings. Now 
that I see them there, those are not really Access functions but more 
utilities, they probably can be moved to Algorithms if there are no 
objections.

point_type is listed twice, one directs to point_order. This is 
probably something in the source file which is Doxygen-tagged 
erroneously.

unique is also listed twice.

Is within a predicate?

The header For can be called for_each

The Overlay subsection will be moved to detail/overlay (in the 
source 
tree) and will then disappear automatically (probably, I don't 
know exactly how you configure this). The same for sectionalize which 
will 
move to detail/sections. Reason for this is that some of the reviewers 
stated that it was not always clear which functions are for end-users, 
and 
indeed, this functionality not really meant for end users.

If there is a subgroup Overlay, which is a good idea, it would 
contain 
difference, sym_difference, intersection, union and dissolve. Grouping 
is 
always difficult because there are always algorithms on which can be 
debated 
where it belongs.

Maybe we can group assign, append and clear together, they actually
 
form a sort of group together with make.

The parse is meant for latlong points, which are moved to an 
extension. 
I don't see the need for parse anymore here (I think it was not part of 
the 
review), so I propose to move it to extensions/algorithms/parse.

[1] This is not about this reference but about arithmetic. One of 
the 
reviewers, in an offlist review, meant that the arithmetic functions 
should 
be done on vectors and not on points. I mailed with Bruno about this. 
In game engines it is often done like here, so a point is sometimes used
 as 
a vector, and v.v. because they have the same functionality, and for 
performance reasons they should not be converted. I've a book about Math
 for 
Games and it states the same, often they are shared together. However, 
my 
opinion is that it is confusing to have one structure for two things. 
Calculating the dot product for points is something which sounds strange
 to 
me, for vectors it is obvious.

My (personal) favourite solution would be that the LA engine 
(with staticly sized vectors and matrices, based on concepts) proposed 
by 
Emil Dotchevski would be used for this functionality (provided that 
library 
is accepted). It would also replace our uBlas-usage (used by us in 
transform). I hope this library will be reviewed soon and accepted. It 
can then live as a companion of geometry: difference of two 
geometry::point 
-> la::vector, dot product, adding la::vector to geometry::point 
gives geometry::point, etc.

If this all is the case we can restructure the arithmetic, because 
dot/cross are more or less redundant, add_value etc also, add_point 
would be 
add_vector_to_point (or something like that, or not be renamed but 
restructured internally).

Regards, Barend
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/ggl/attachments/20100313/cdd3f05a/attachment.html