Tuesday, August 5, 2008

man-pages-3.06 is released

I've uploaded man-pages-3.06 into the release directory (or view the online pages). The main changes in man-pages-3.06 are updates to around 65 math pages. The changes are broadly as follows:
  • RETURN VALUE: in many cases, the math pages lacked descriptions of the return value when the function arguments are special cases such as +0, -0, NaN (not-a-number), +infinity, -infinity, etc. This has been fixed. I carried out tests on glibc 2.8 to ensure that the behavior of all of these functions matches the RETURN VALUE descriptions (and the POSIX.1-2001 requirements).
  • BUGS: a BUGS sections was added to a few pages to document deviations from from expected behavior.
  • ERRORS: many pages lacked a clear (or indeed any) description of how errno is set on error and what exception is raised for each error. This has been fixed. The ERRORS sections are now generally headed up as per the POSIX.1 way of doing things, describing Pole, Range, and Domain errors, as applicable. I carried out tests on glibc 2.8 to ensure that all of these functions match the ERRORS descriptions. Deviations from POSIX.1-2001 requirements have been filed as glibc bug reports, and noted in the man pages. (The pages now describe the situation for ERRORS as at glibc 2.8. I may eventually try and extend the text with descriptions of changes in older versions of glibc; watch for a post on that subject in the next days, when I'll describe my test scripts.)
  • Fixed feature test macros (FTMs). Often, the FTM requirements for the float and long double versions of a math function are different from the requirements for the double version. Each math page now shows the correct FTM requirements for all three versions of the function(s) it describes. This may have required either a change to the existing FTM text (if the requirements for the double function were already described), or the addition of an FTM description to a SYNOPSIS where one was not previously present (typically because the double version of the function does not require any FTMs to be defined). A few outright errors in the documentation of FTM requirements were also fixed.
  • CONFORMING TO: in many cases, POSIX.1-2001 was not mentioned. Where a function is specified in POSIX.1-2001, this is now noted. Also, statements about what other standards a function conforms to were generally clarified. (The wording about which functions conformed to C99 was previously often done as an add-on sentence; now it is made part of the first sentence of the CONFORMING TO section, along with mention of POSIX.1-2001.)
While making all of the above changes, I split out some logically separate material from existing pages to create three new pages: erfc(3) (formerly part of erf(3)), scalbln(3) (formerly part of scalb(3)), and y0(3) (formerly part of j0(3)).

P.S. One point that is still not covered in any page is the circumstances that generate inexact (FE_INEXACT) floating-point exceptions. (The details for these exceptions are not specified in POSIX.1-2001, and I haven't gone looking for the standards that describe the details.) If anyone has thoughts on what needs to be done about this, I'm open to ideas.


No comments: