To me, the doubling in the path has to be a mistake, but then, so many packages do it.
No, it's not a mistake, it is done that way on purpose. In particular, it is done that way so that the underlay/overlay functionality works properly.
As one example, assume you don't have the double-directory. Also assume you have Humble installed to /opt/ros/humble , and you have the packages ros-humble-foo and ros-humble-bar installed. In that case, the include files are /opt/ros/humble/include/foo/header.hpp and /opt/ros/humble/include/bar/header.hpp . Further, let's say that you include header files from both projects foo and bar, like:
#include foo/header.hpp
#include bar/header.hpp
And then you have in your CMakeLists.txt the following:
find_package(foo REQUIRED)
In this case, things will actually compile correctly, because the find_package foo added in the include directory like -I/opt/ros/humble/include. But that's not correct; the find_package(bar REQUIRED)is missing. This is one pretty trivial example, but there are a lot more of these problems that pop up, and the solution we used is to add the extra directory. You can see a lot more about the development of this and the problems that you might face at https://github.com/ros2/ros2/issues/1150 and https://colcon.readthedocs.io/en/rele...
All of that said, we only ever had time to make these fixes to the core packages; a lot of the community packages don't have this fix, even though they should. That will probably take quite a while to fix.
But the docs also seem to suggest single ${PROJECT_NAME}
This is a bug. Can you point out where that is, and/or make a PR to fix that?
