Re: [PATCH] math: Silence -Winclude-next-absolute-path warning.

[Bruno Haible <bruno@clisp.org>]

Paul Eggert wrote:
> > writing #include <...> everywhere has
> > very little benefit.
> 
> There is a benefit: it's simpler and would avoid future problems like 
> the one just fixed.

There is also a drawback: Remember why we took the habit of putting all
  #include <system-header.h>
before all
  #include "application-header.h" ?
That is because due to the _GNU_SOURCE, _ALL_SOURCE, etc. macros that
our omnipresent 'extensions' module defines, the system header files define
all sorts of non-standardized symbols, which occasionally lead to
conflicts with application headers. #including the application headers
after the system header guarantees that the application header can do
  #define SP mySP
or
  #define UP myUP
to get rid of the conflict.

If the programmer were to use #include <...> everywhere and — quite
likely — sort the include statements alphabetically, then half of the
time (on average) this conflict resolution will not work out.

> Whatever guideline we use, either the contributors need to learn the 
> guideline, or we can politely adjust their code once contributed.

The larger part of the problem is not with Gnulib, but with the > 100
packages that use Gnulib. We can occasionally ask / force them to make
one-liner changes on our behalf. But they would not accept if we tell
them to diverge significantly from de-facto conventions that are already
in place for 40 years.

The purpose of this de-facto convention (to use #include <...> only for
system headers) was to avoid the need to add -I options in the Makefile,
here and there. At a time when VPATH builds were not common.

> Currently we have more-complicated guideline, which is that one should 
> use #include <...> for include files in category A, and that you can use 
> either style for files in category B, and that these categories are 
> explained somewhere in the documentation.

True. But this more complicated guideline is already in the programmers'
brains, just with a set A that is a little bit smaller than the one Gnulib
needs. The Gnulib documentation is telling the programmer to adjust their
remembered rule for #include, to accommodate essentially only <error.h>.

> (Also, a file may migrate from 
> category B to category A in the future; this isn't explained yet....)

True, but it won't happen often. Probably once in 2 years, or less
frequently.

Bruno