Re: [PATCH] iswblank.3: ATTRIBUTES: Note function that is thread safe with exceptions

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

On 02/13/2014 05:48 AM, Carlos O'Donell wrote:
> On Wed, Feb 12, 2014 at 11:07 PM, Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org> 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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html