Re: request: pointer to the docs in the module file

[Bruno Haible]

Sam Steingold wrote:
> >> How do I find out where a module is documented?

Look at the gnulib manual TOC
  <http://www.gnu.org/software/gnulib/manual/html_node/index.html>
If it's not a ISO C / POSIX or GNU substitute module, then take a look
at the chapter "Particular Modules".

> I usually cannot tell right away
> whether a specific function is posix or glibc (e.g., I thought that
> mkdtemp was not in posix)

Either search in the above TOC. Or use the reference to POSIX
  <http://pubs.opengroup.org/onlinepubs/9699919799/>

Or do a "man ..." - the manual page often says to which standards a function
complies.

> Suppose I want to replace my very own maze of #ifdefs surrounding a call
> to a posix function foo() with a nice gnulib module foo.
> Right now I look for modules/foo

This is a good heuristic, because we try to be consistent in the naming of
modules. But there are a few inconsistent cases. Therefore it is more
reliable to go by the documentation's TOC.

> So, if I were using the mkdir module ..., I can use mkdir with
> 2 arguments on mingw too?

Yes.

> But which header file will defined mkdir with 2 arguments?

That's the 'Include' field of the module description. In modules/mkdir it reads:

  Include:
  <sys/stat.h>

> The mkdir module does not seem to export any header files.

It does not explicitly bring in any header file. But it gives you the guarantee
that you can use mkdir() with 2 arguments after including <sys/stat.h>.

> Oh wait - it will replace mkdir with a _function_ rpl_mkdir, right?

Function or inline function or macro - that is a detail. Recently we have
switched many things from macros to functions, because that allows gnulib
to be reasonably used in C++ programs.

> > That is, docs/posix-functions is intended to be a catch-all for _all_
> > portability problems, not just those fixed by gnulib, but tends to be
> > biased towards gnulib solutions.
> 
> I am sorry, I can parse this sentence just fine, but I cannot extract
> the meaning.  Remember, English is not my native language.

He means that in any doc/posix-functions/*.texi file we list all portability
problems that we know of - both fixed by gnulib and those we've considered
low priority -. But we certainly miss some problems that we've never
encountered.

Bruno
-- 
In memoriam Georges Darboy <http://en.wikipedia.org/wiki/Georges_Darboy>