Geometry Boost List: Re: [geometry] specializing traits::tag for io operations and html code documentation

Subject: Re: [geometry] specializing traits::tag for io operations and html code documentation
From: Tomislav Maric (tomislav.maric_at_[hidden])
Date: 2013-05-24 04:44:42

Hi Barend,

wow, thank you very much for all the information you provided, I will
study it in detail and conform the vtk io to the way its done in
boost.geometry.

Best regards,
Tomislav

On 05/23/2013 11:18 PM, Barend Gehrels wrote:
> Hi Tomislav,
>
>
>
> On 23-5-2013 13:21, Tomislav Maric wrote:
>> Hi,
>>
>> I have a question about the tag dispatching engine. In the code I wrote
>> for vtk, I defined vtk_writer tags and simple dispatching, but now I
>> noticed in "tag.hpp" that each geometry needs to specialize traits::tag.
>
> That is correct.
>
>> Reading again wkt.hpp, I found in the wkt_manipulator:
>>
>>      template <typename Char, typename Traits>
>>      inline friend std::basic_ostream<Char, Traits>& operator<<(
>>              std::basic_ostream<Char, Traits>& os,
>>              wkt_manipulator const& m)
>>      {
>>          dispatch::wkt
>>              <
>>                  typename tag<Geometry>::type,
>>                  Geometry
>>              >::apply(os, m.m_geometry);
>>          os.flush();
>>          return os;
>>      }
>
> That is right. I already noticed that your code did not follow exactly
> this model. Did not yet mail about it because your code seemed to work
> fine. But this code above is, in general how we do it (actually: how
> we did it, more about that later).  It is best described here:
>
> http://www.boost.org/doc/libs/1_53_0/libs/geometry/doc/html/geometry/design.html
>
>
> (there is also a pdf-paper about it:
> http://trac.osgeo.org/ggl/wiki/BoostCon , especially the 2010 paper).
> This design rationale describes how (and why) we use tag dispatching.
> Note we dispatch by type, not by instance (like you did). That gives
> also the possibility to use tag-dispatching in metafunctions (for
> example).
>
> See also this blog-page, describing just the system:
> http://barendgehrels.blogspot.nl/2010/10/tag-dispatching-by-type-tag-dispatching.html
>
>
>
> Bruno enhanced the system by making the take a default template
> parameter. See for example the code in area.hpp, where it is like
> (extract):
>
> template
> <
>     typename Geometry,
>     typename Tag = typename tag<Geometry>::type
> >
> struct area
> {
> // ...
> };
>
> This is not yet applied to WKT, but the difference is small and will
> be clear. Maybe area is a (slightly) better starting point then WKT.
>
>
>> And above it, there are structs that specialize the apply function for
>> different geometries. If I understood it right the geometries that are
>> streamed in wkt are wrapped in wkt_*geometry* (e.g. wkt_box).
>
> The last convention (wkt_box) is just the naming of helper functions,
> it can be anything (e.g. wkt_range, wkt_poly). But basically, yes, in
> namespace dispatch there is a structure specialized for all tags,
> implementing the functionality or forwarding to helper functions.
>
>>
>> I will need more time to wrap (pun intended :) ) my head around how
>> formatting works if I want to make the vtk IO have the same design as
>> the wkt.
>
> Hope this mail and the doc helps.
>
>> Is there a way I can generate Doxygen-like documentation of
>> boost.geometry that shows all possible information about how the code is
>> organized with cross-links? Searching through source helps, but having
>> 20 tabs opened in a web browser might be more informative.
>
> Yes there is. In boost/libs/geometry/doc/doxy there is a doxyfile. You
> can start doxygen exactly from there, and get output in doxygen_output.
>
> We postprocess this to make quickbook documentation, so the focus is
> not on doxygen itself, but it is still working. But the details
> (dispatch and implementation details) are skipped, so I don't know if
> it is really useful for your current purpose...
>
> Regards, Barend
>
>
>
> _______________________________________________
> Geometry mailing list
> Geometry_at_[hidden]
> http://lists.boost.org/mailman/listinfo.cgi/geometry