On 02/13/2014 05:48 AM, Carlos O'Donell wrote: > On Wed, Feb 12, 2014 at 11:07 PM, Peng Haitao <penght@xxxxxxxxxxxxxx> wrote: >>> My suggestion is: >>> >>> "The function iswblank() is thread safe with exceptions (locale). See >>> "Safety Concepts" for more information." >>> >>> Then describe the locale issue once in the "Safety Concepts" section. >>> >>> This reduces duplicated text and simplifies each man page. >>> >>> Users that know what "locale" means can scroll quickly, users that >>> don't can look it up and learn. >>> >>> Does that make sense? >>> >> >> Your suggestion can simplify each man page, but our description make each man page clearer. > > There is a natural tension here between being descriptive and being succinct. (Yup.) >> In Oracle Solaris's manpages and POSIX, when the function has exceptions, >> exceptions are described in this function. > > We should strive to be better than that. (Yup ;-).) >> In POSIX, when the function has exceptions, exceptions are described in this function as follows: >> The wcrtomb() function need not be thread-safe if called with a NULL ps argument. >> >> The tmpnam() function need not be thread-safe if called with a NULL parameter. >> >> I don't have strong preference. If Michael and other members prefer >> your suggestion, I can modify my patches. > > I have a strong preference for harmonizing this information across the > man pages and the glibc manual. Sorry for being late to this thread. Carlos, I agree with you. I will take a bit of time now to look more closely at the glibc markings, and follow up. Thanks for raising this. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
