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: Mateusz Loskot (mateusz)
Date: 2010-03-14 20:32:08

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

Done.

> A section Strategies can be added below Algorithms

Done. There are two tables:
- Strategy Concepts
- Strategy

> A section Constants and Enumerations can be added, probably above 
> Algorithms, with things like min_corner, max_corner, clockwise, etc.

Done.

> It can also contain coordinate systems, degree/radian, which are not really 
> constants or enumerations, but empty classes having the same 
> functionality.

Done.

> There is some functionality which is not yet there:
> 
> - compare

Done, but without two files:
intersection_points.hpp
intersection_points_determinant.hpp
I'm not sure why, but Doxygen fails to generate valid XML if these
files are included in input.

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

I added Policies section between Algorithms and Strategies.
Perhaps they should go below Strategies.

Actually, firstly I wanted to keep order of the major sections
according to "from simple building blocks, to complex combinations:.
IOW, in order of how elements are being combined together.

Though now, after I've added load more of elements, I'm getting lost on
how to logically arrange the table of content (ToC) to make it
intuitive, to make it introducing the library gradually, etc.

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

Done.

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

I am going to document the extensions in similar way.
I mean, officially accepted exceptions.
I prepared section for extensions but it's empty now.
Perhaps, table of contents of extensions reference should be on
separate page?

> 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.

Yes, I have similar impression, though, I'm not sure if they
belong to Algorithms. Perhaps a separate category Utilities for
such general purpose tools?

> 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.

Source file and Doxygen output are fine. It's a mistake in quickref.xml.

Fixed.

> Is within a predicate?

Yes, of course, it is. Good catch. Fixed.

> The header For can be called for_each

Done.

Initially, I was thinking of "Loop" to keep more descriptive
headers than named after functions.

> 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.

I see. Then, I will follow up and remove them.

> If there is a subgroup Overlay, which is a good idea, it would 
> contain difference, sym_difference, intersection, union and dissolve.

Good point.

> Grouping is always difficult because there are always algorithms on
> which can be debated where it belongs.

Yes, it is difficult. I was following the original Doxygen output,
but generate for current trunk.

So, should I move them to Overlay?

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

I agree, they belong to same category. They feel more like
connected with Geometry Constructors.
What about moving them below the Constructors to category called
like  Geometry Modifiers?

> 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.

OK, so they will be moved once I add extensions.

> [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.

I personally understand the game dev approach. Working with vectors
makes it possible to unify operations better.

Though, I agree that for someone who is not used to that appraoch
it may be confusing.

> 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.

I thoroughly agree. I like Emil's library and it's my strong candidate
to use inside Geometry.

> 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).

What about supporting keeping both approaches, point-based and vector-based?

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org