search

boostorg / gil

Boost.GIL - Generic Image Library | Requires C++14 since Boost 1.80
https://boostorg.github.io/gil
Boost Software License 1.0
178 stars 164 forks source link

docs: update gradient tutorial #703

Closed marco-langer closed 2 years ago

marco-langer commented 2 years ago

Description

This PR updates the gradient tutorial with currently used style (east-const, trailing return types, alias declarations) and fixes some other minor issues.

Currently a draft, I will update it in the next days.

Tasklist

marco-langer commented 2 years ago

PR is ready for review.

Some of the code snippets didn't compile anymore, because the referenced functions either moved into the detail namespace (like channel_convert_to_unsigned) or did not exist anymore at all (like in the mandelbrot example). I replaced the mandelbrot snippet with the mandelbrot example from the example directory and changed the tutorial accordingly to calculate the gradient of the luminosity of a rgb8 image rather than the gradient of a grayscale image.

Now all code snippets compile without warnings.

mloskot commented 2 years ago

Some of the code snippets didn't compile anymore

Maintenance of the documentation snippets is a bit of PITA. Some Boost projects switched to AsciiDoc and link snippets from .cpp files which are compile-tested by CI jobs, For example, see Boost.Build's example/hello and its readme.adoc.

I'm not sure if similar is feasible using reStructuredText, or we should switch over to AsciiDoc ;)

Now all code snippets compile without warnings.

Sweet, thank you!

marco-langer commented 2 years ago

Regarding this channel_convert_to_unsigned, which is now in the detail namespace, but also still referenced in this tutorial:

Maybe one should think to pull it out of the detail namespace again, if it is that useful for client code? I don't know the rational why it was moved into the detail namespace at all (this was done 15 years ago!).

mloskot commented 2 years ago

Good catch @marco-langer I have created a new issue #706 to address your questions in future. Meanwhile, let's keep it in the detail - it is easy to move a thing out of detail but the other way around is much harder :)