Re: documentation structure (was: Re: test-memmem takes waaay too long)

[Bruno Haible]

Eric Blake wrote:
> I'm installing these two commits:
> 
> * modules/memmem-tests (configure.ac): Check for alarm.
> * tests/test-memmem.c (main): Avoid alarm on platforms that lack it.

Thanks for these.

> * doc/functions/memmem.texi: New file.
> * doc/gnulib.texi (Function Substitutes): Add memmem.

Hmm, this puts the description of 'memmem' into the chapter about
"ISO C and POSIX Function Substitutes". This is inappropriate, IMO.

If we extend these chapters to contain random functions not covered
by POSIX, then we need to add 'gcd', all of the Unicode string functions,
etc. - there is no limit to what this chapter contains, and the person
who looks for portability problems of well-known functions is lost.

I'm therefore in favour of putting this description under "Particular Modules".

If gnulib implements a significant number of functions specified by glibc
- strsignal was just mentioned - then I'm in favour two additional chapters
  * GNU libc Header File Substitutes
  * GNU libc Function Substitutes
that makes it clear that these are not POSIX inventions but glibc or BSD
or SysV inventions.

Opinions (before I provide a patch)?

Bruno