[GRASS-dev] Display library documentation?

[Moritz Lennert]

On 16/09/15 01:53, Vaclav Petras wrote:
>
>
> On Tue, Sep 15, 2015 at 6:06 AM, Moritz Lennert
> <mlennert at club.worldonline.be <mailto:mlennert at club.worldonline.be>> wrote:
>
>     On 14/09/15 15:53, Vaclav Petras wrote:
>
>         Hi,
>
>         is there some documentation on how to use the display library,
>         i.e. how
>         to write a d.* module?
>
>
>     I imagine you looked at
>     https://grass.osgeo.org/programming7/displaylib.html ?
>
>
>         I've tried reading d.vect code but I miss the
>         general rules and concepts like how to set color or which
>         coordinates
>
>
>     Have you checked display_shape() in shape.c and the individual
>     display_* functions in the relevant files (area.c, line.c) for the
>     different types of features ?
>
>     The color is set with D_RGB_color which takes a color struct as input.
>     Then the feature is drawn with
>     D_polygon_abs/D_polyline_abs/D_polydots_abs which take the
>     coordinates from the line struct Points which is filled with info
>     using Vect_read_line().
>
>         should be used when as well as information which functions should be
>         used in which case like what is the difference between D_symbol and
>         D_symbol2.
>
>
>      From the programmer's manual section on D_Symbol2:
>
>     "The same as D_symbol(), but it uses a primary and secondary color
>     instead of line and fill color. "
>
>
>
> Thanks Moritz, this is approximately as far as I got. I hoped I over
> looked something but apparently not. The documentation is in Doxygen
> format but it is just a list of functions. What is primary and secondary
> color, I can only guess from context, etc. and your sentence about
> feature drawing is the most detailed documentation we have now for the
> display library.
>
> So, I think that we have a big problem. It seems that the display
> library, despite its crucial role, is the most underdocumented library
> we have. In fact it is not documented at all. Others have some readmes
> with basic workflow, comments for functions or comments in code. Display
> library has nothing. Because of the level of abstraction for different
> drivers, its hard, at least for me, to guess the rules or even best
> practices for usage and because of the complexity or specificity of
> display modules, its hard to guess what is the general and effective way
> of doing things.
>
> Please, can somebody with some experience document some functions,
> provide examples or a complete d.example module? When having at least
> something I can then help with formatting or examples.
>


Glynn, as you are the one who significantly rewrote the display library, 
do you have any documentation or notes stored somewhere ?

Moritz