Return to Question

For additional reading (and implicitly, support) there is an interesting movement inside the BOOST project as of January, 2024 to completely remove "the many, many problems that make libraries depend on the current source structure": https://lists.boost.org/Archives/boost/2024/01/255704.php

• AFAIK <> is reserved for system headers coming from the platform, and are strongly discouraged to be used by project code. The compilation only works because the C and C++ standard requires the compiler to search again as if the file was given with "" if it is not found on the first pass.
• It creates a review nightmare: the include file is neither at the path rooted at the directory where the including C or C++ file sits nor is it in any of the include locations, you have to repeat the search of the compiler to eventually find it somewhere, yet at this point in time you aren't really trusting yourself - the compiler could have searched differently.
• There are a number of multiple file names in the project tree: blue.h can be found at a number of locations and sometimes one blue.h serves as a dispatcher file for the inclusion of a more specific, the true blue.h down the directory tree. Which blue.h is selected is distinguished by #define PLATFORM macros and the like.
• It creates a monolithic, reorganization-resisting project structure, coupling C and C++ interfaces (which live in directory-less space as far as the language is concerned) with the file system.
• It spills over into new projects: As soon as one uses a header which itself includes other path-dependent headers, the new projects build script has to adapt to this usage.

• AFAIK <> is reserved for system headers coming from the platform, and are strongly discouraged to be used by project code. The compilation only works because the C and C++ standard requires the compiler to search again as if the file was given with "" if it is not found on the first pass.
• It creates a review nightmare: the include file is neither at the path rooted at the directory where the including C or C++ file sits nor is it in any of the include locations, you have to repeat the search of the compiler to eventually find it somewhere, yet at this point in time you aren't really trusting yourself - the compiler could have searched differently.
• There are a number of multiple file names in the project tree: blue.h can be found at a number of locations and sometimes one blue.h serves as a dispatcher file for the inclusion of a more specific, the true blue.h down the directory tree. Which blue.h is selected is distinguished by #define PLATFORM macros and the like.
• It creates a monolithic, reorganization-resisting project structure, coupling C and C++ interfaces (which live in directory-less space as far as the language is concerned) with the file system.
• It spills over into new projects by backfiring into the build system: As soon as one uses a header which itself includes other path-dependent headers, the new projects build script has to adapt to this usage.

PPPS: to give you an idea where carelessness regarding physical structure leads to, here a part of the include paths which are required to compile mbed-os which I mentioned before:

mbed-os/features/nanostack/mbed-mesh-api/ mbed-os/features/nanostack/sal-stack-nanostack-eventloop/ mbed-os/features/nanostack/mbed-mesh-api/mbed-mesh-api/ mbed-os/features/nanostack/mbed-mesh-api/source/include/ mbed-os/features/nanostack/nanostack-interface/ mbed-os/features/nanostack/sal-stack-nanostack-eventloop/nanostack-event-loop/ mbed-os/features/lwipstack/ mbed-os/features/lwipstack/lwip-sys/ mbed-os/features/lwipstack/lwip/src/include/ mbed-os/features/lwipstack/lwip/src/include/lwip/ 

Some of these paths are just starting points for a deeper reach (i.e. "sub/subsub/inc_this.hpp") and some are plain old "there you will find your includes" directories.

This leads to yet another counter argument to anything beyond the simple "set your include paths to where your include files are" rule: it is obviously impossible to communicate anything more complex over time and different coding cultures.