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

[Eric Blake]

On 05/24/2011 11:26 AM, Sam Steingold wrote:
> Hi,
> 
> 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.

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

> 
> Also, in the MODULES.html file:
> 1. the dependencies should be links

Patches to the generating script are welcome.

> 2. the links to files (e.g., argz.c et al) should specify the file type
> text/plain so that firefox does not ask me how to open it.

Don't know whether that is possible - that's more of a web server issue.

> say something like this:
> -----------------
> Portability problems fixed by Gnulib:
> @itemize
> @end itemize
> 
> Portability problems not fixed by Gnulib:
> @itemize
> @item
> This function is missing on some platforms: .......
> @end itemize
> -----------------
> if no "portability problems" are fixed, what does this module do?

That means we don't yet have a module that fixes the known portability
problems in that function.  Patches welcome.

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

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.

-- 
Eric Blake   address@hidden    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature