bug#21707: include-file cleanup for src directory

[Eli Zaretskii <eliz@gnu.org>]

> Cc: 21707@debbugs.gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Tue, 20 Oct 2015 11:50:34 -0700
> 
> Eli Zaretskii wrote:
> > Would it help if we avoid including any of our headers in any
> > other of our headers, so that the headers included by a particular C
> > file are visible by just looking at that single C file?
> 
> That would run afoul of a more important design goal, which is that we should be 
> able to include headers in any order.

Is that really more important?  Even standard C headers sometimes
require order, for example, sys/types.h should be included before
sys/stat.h.

> And anyway, compiling a typical C file ordinarily brings in oodles
> of system headers that the C file doesn't explicitly ask for

That is true, but C headers change much slower than our headers.  So
keeping track of the changes in our headers requires more attention
and work.

> so regardless of our style the only practical way to see what headers a 
> C file includes is to compile it and see what gcc -E outputs.

The problem with "gcc -E" is that it's system dependent.  I thought we
could perhaps come up with a method that would allow anyone easily see
which headers are needed on every supported platform, and thus lower
the probability of unintended breakage.

Of course, it isn't a catastrophe to continue the way we have been
doing this till now.

> Ideally a C source file should include all headers that define symbols the 
> source file directly uses, and no headers other than that. This should be true 
> for both .h and .c files. We're not there by a long shot, but that should be the 
> goal.

I think the real problem is to keep this state once we get there.
One-time efforts to rectify things are relatively easy; making that
stick is harder, especially since (AFAIU) there's no automated way for
producing a report about unnecessary headers.