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

[Sam Steingold]

> * Eric Blake <address@hidden> [2011-05-24 11:37:40 -0600]:
> On 05/24/2011 11:26 AM, Sam Steingold wrote:
>> How do I find out where a module is documented?
>> E.g., when I discovered the getloadavg module, I had to do
>> find gnulib/ -name getload\*
>> to find gnulib/doc/glibc-functions/getloadavg.texi.
>
> If it is a POSIX function, it is documented in
> gnulib/doc/posix-functions.  If it is a glibc extension, it is
> documented in gnulib/doc/glibc-functions.  Otherwise, it is a gnulib
> invention, and we haven't been very consistent at where that
> documentation lives.

Yes, thanks, you (or someone else) already told me that at least once,
and I am using the advice, even though I usually cannot tell right away
whether a specific function is posix or glibc (e.g., I thought that
mkdtemp was not in posix) - which is why I am asking for the link.

>> It would be nice if there were a pointer in gnulib/modules/getloadavg,
>> preferably a URL with the up-to-date (updated nightly) doc generated from
>> the texi file.
>
> I would prefer not in the modules file itself (that seems like a
> maintenance burden to have to manually maintain an extra link), but
> perhaps in the generated web page that describes each module.

I guess I am using gnulib wrong.
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 and, if I see that it does not pull in
too many dependencies, I try to find the texi file to see if it solves
my portability problems. This is why I want a link in the modules/foo
file to foo.texi (or foo.html) so that I do not have to run a find.
What is the right way?

>> Also, mkdir.texi says:
>> -----------------
>> On Windows platforms (excluding Cygwin), this function is called 
>> @code{_mkdir}
>> and takes only one argument.  The fix (without Gnulib) is to define a macro
>> like this:
>> -----------------
>> what does this mean?
>> I need to use this macro if I am not using Gnulib?
>> I need to define the macro even if I am using Gnulib?
>
> It means that you either use the gnulib module (and don't worry about
> anything extra), or you can be lighter-weight and use that listed
> workaround instead of the gnulib module.  So only define that macro only
> if you are not using gnulib.

So, if I were using the mkdir module (which I won't because it pulls
dirname-lgpl which pulls a bunch of other modules), I can use mkdir with
2 arguments on mingw too?
But which header file will defined mkdir with 2 arguments?
The mkdir module does not seem to export any header files.
Oh wait - it will replace mkdir with a _function_ rpl_mkdir, right?

> 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.

--
Sam Steingold (http://sds.podval.org/) on CentOS release 5.6 (Final) X 
11.0.60900031
http://truepeace.org http://ffii.org http://openvotingconsortium.org
http://www.memritv.org http://honestreporting.com http://jihadwatch.org
As a computer, I find your faith in technology amusing.