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

["Carlos O'Donell" <carlos-v2tUB8YBRSi3e3T8WW9gsA@public.gmane.org>]

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.

> 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.

> 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.

Cheers,
Carlos.
--
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