Re: function portability documentation

[Bruno Haible]

Ralf Wildenhues wrote:
> so here we go, quickly:

Thanks, Ralf, for proofreading. I've integrated many of your remarks.

> - Should the entries be indexed?  I would prefer so.

Yes, certainly. Probably this is also a good occasion to split the
"program index" and the "function / header index". IMO they should be
separate, because they belong to two different worlds (shell vs. C).

> - It would probably add to the long-term maintainability if the *printf
> and similar families of functions would be treated in one place only.
> This isn't too important now, though.

The main ordering is alphabetically; I cannot see any other reasonable sort
criterion. But you are right, if we want to expand on the printf or on the
wchar_t topic, it's probably good to add a subsection for each of these
two topics, to which we can then refer in each function's notes.

> - Then, for uniformity with the rest of the manual, please
>    s/POSIX/Posix/

POSIX is an acronym (Portable Operating System Interface for UniX) and
should therefore IMO be written in upper case.

>    s/\(BSD\|GNU\|IRIX\)/@acronym{\1}/

I'm sorry, but have you seen how it looks in autoconf.dvi when @acronym
is used? Awful. No font change is better than this one.

> > The + search algorithm is system specific.
>
> I think it's system-specific.

Not sure. You find both writings frequently on the web.

> > code is + available through @code{WSAGetLastError()} instead.
>
> A recent change to GCS suggests not using the parentheses to denote
> a function; reserve that for actual function calls instead.

Here I mean the actual function call. errno needs to be conditionally replaced
with WSAGetLastError().

> > + @item fnmatch
> > + This function is broken in some version of Solaris or glibc.
>
> Shouldn't this be `and' instead of `or'?

I don't know. The gnulib macro wasn't clear enough to me. I hope Paul knows
more about it.

> > + this means that it translates '\n' to CR/LF by default.  Use the "b"
> > flag + if you need reliable binary I/O.
>
> Please use @samp{\n}, and @samp{"b"}; more generally, I'd put most
> double-quoted values in the section in @samp{}, or @code{} when they
> specify code literals, they look nicer that way in the DVI output.

I'll put them in @code.

> > + @file{<libintl.h>} from GNU gettext; it redefines this function so that
> > it is + POSIX compliant.
>
> Wouldn't @file{libintl.h}, or `The fix is to @samp{#include <libintl.h>}'
> look nicer?  Several instances.

Hmm, #include is not an English verb...

> it'd be nice to cross-reference AC_SYS_LARGEFILE.

Yes. How do I write a reference to a macro definition inside an info node
(_not_ to the info node that contains it)? The index apparently has such
references, but how to I write them in texinfo?

> It's be good to answer these questions before it goes in.

Yes. I hope Paul Eggert knows these.

> > + @item Integer types smaller than @samp{int}.
>
> Would `Integer types with a lower conversion rank than that of @samp{int}.'
> be better?  (As in: even if, on your system, short int and int have the
> same representation

Such systems are outside the scope of this section; they are not GNU porting
targets.

> > + @item mkdir
> > + When the argument ends in a slash, the function call fails on some
> > systems.
>
> Do we know which?

We need to add more details afterwards. This is just a beginning.

> Refer to AC_FUNC_MMAP?

AC_FUNC_MMAP is the answer only for a specific use case of mmap. There are
many others.

> > + @item nanosleep
>
> TODO?  :-)

Yes :-)

Bruno