[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: function portability documentation
From: |
Bruno Haible |
Subject: |
Re: function portability documentation |
Date: |
Mon, 22 May 2006 20:29:43 +0200 |
User-agent: |
KMail/1.5 |
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