On 17-Apr-08, at 12:29 PM, Alan Barrett wrote:
On Thu, 17 Apr 2008, Greg A. Woods; Planix, Inc. wrote:Just as sadly Joerg's advice to read about the value in the CAVEATS sectiondoesn't help, at least not on NetBSD-4.0 or earlier.The ctype(3) man page had a much better CAVEATS section than that of the individual to* and is* functions. I have now expanded it even further,and added references to it in all the to* and is* man pages.
I didn't even know there was a ctype(3) manual page! Argh. It's not referenced in any of the is* or to* manual pages on any existing release I have access to, nor is it mentioned in intro(3) or stdio(3).
Unfortunately the ctype(3) in all the available releases has neither CAVEATS nor EXAMPLES sections.
Can you please issue pullup requests for all these documentation fixes to all the currently maintained release branches?
In fact I would say that _all_ documentation fixes should be pulled up to all maintained releases just as soon as they've been verified and scrutinized by an "editor" (someone other than the author). In fact hasn't this already been agreed to by core, at least in principle.
Perhaps what's missing is an easier way of migrating such fixes to the maintained release branches. FreeBSD's long-standing "MFC" policy is sadly lacking in NetBSD. (In FreeBSD all changes which are fixes or sufficiently stable and self-contained features are tagged as "Merge From Current" to the stable branch(es), and less experienced developers are charged with doing these merges along with the necessary testing. See section 4.1 in <URL:http://www.freebsd.org/doc/en_US.ISO8859-1/books/dev-model/book.html#DEVELOPMENT-MODEL >)
Neither the SUSv2 docs online, nor any variant of the NetBSD manual pages, contain any good examples.The NetBSD ctype(3) man page has an example, but it may not be good.
Why are there separate is* and to* manual pages if the one ctype(3) page documents them all, as it now seems to do? Why not just links to the individual function/macro names as is done with other closely related family APIs?
--
Greg A. Woods; Planix, Inc.
<woods%planix.ca@localhost>