Re: doc: new chapter about header files

[Bruno Haible]

Eric Blake wrote:
> 2007-04-27  Eric Blake  <address@hidden>
> 
>       * doc/headers/assert.texi (assert.h): Document assert module use.
> 
> --- doc/headers/assert.texi   27 Apr 2007 19:57:14 -0000      1.1
> +++ doc/headers/assert.texi   27 Apr 2007 20:04:47 -0000
> @@ -1,10 +1,13 @@
>  @node assert.h
>  @section @file{assert.h}
>  
> -Gnulib module: ---
> +Gnulib module: @code{assert}
>  
>  Portability problems fixed by Gnulib:
>  @itemize
> address@hidden
> +Not a portability problem, per se, but allow the installer to disable
> +assertions through "configure --disable-assert".
>  @end itemize
>  
>  Portability problems not fixed by Gnulib:

Hmm, this doc/headers/ chapter (and the doc/functions/ chapter that will come
after it) should IMO really be devoted to the portability problems and their
fix/workaround status in gnulib. The 'assert' module is categorized as
"Enhancement over ANSI C" in MODULES.html; I therefore think its doc belongs
in a separate doc/assert.texi that is included separately by gnulib.texi.

However, some "see also" references at the end of these doc/headers/*.texi
files are OK. For example, it's natural to have references from a header
file's description to each of the functions that it declares according to
POSIX.

Bruno