Alexandre, Carlos, On Wed, Feb 12, 2014 at 4:31 PM, Carlos O'Donell <carlos@xxxxxxxxxxxxxxxx> wrote: > On Tue, Feb 11, 2014 at 8:34 PM, Peng Haitao <penght@xxxxxxxxxxxxxx> wrote: >> >> On 02/11/2014 12:03 AM, Carlos O'Donell wrote: >>> On Mon, Feb 10, 2014 at 1:20 AM, Peng Haitao <penght@xxxxxxxxxxxxxx> wrote: >>>> The function iswblank() is thread safe with exceptions. >>>> +.SH ATTRIBUTES >>>> +.SS Multithreading (see pthreads(7)) >>>> +The >>>> +.BR iswblank () >>>> +function is thread-safe with exceptions. >>>> +It can be safely used in multithreaded applications, as long as >>>> +.BR setlocale (3) >>>> +is not called to change the locale during its execution. >>> >>> Now that glibc 2.19 is out the door and using a standard set of >>> "exception" markers should we try to standardize the same markers? >>> >> >> Yes, maybe it is better. >> But in Oracle Solaris's manpages, iswblank is marked "MT-Safe with exceptions". >> I also think "MT-Safe with exceptions" is OK. > > 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? > > My further suggestion is to use the same ~20 exception notes as glibc e.g. > race, const, locale, env, hostid, sigintr, init, lock, corrupt, heap, > dlopen, plugin, i18ln, fd, mem, sig, term, and cwd (we also have > !posix to indicate it is known not to conform with posix). > > The glibc manual is marked with them now, you can see iswblank here: > http://www.gnu.org/software/libc/manual/html_mono/libc.html#index-iswblank-486 I realize I could did through a lot of archived mail and answer these questions, but I hope you can save me some time. 1. How was the information about MT-Safety etc derived. I'm assuming a lot of arduous manual inspection, right? (Or was there some automation involved?) 2. Does the glibc manual document the actual or the desired state of the functions wrt to MT-Safety? Where these differ, does the manual document that? 3. Were the glibc manual changes generated manually, or was there some degree of automation involved? I.e., has some markup been added to the source that allows one to generate a summary of information about MT-safety? As far as I can tell, that is not the case, but I wanted to check. The motivation of the above questions is of course that I wonder what degree of automation might be achievable in making changes to the documentation in man-pages. 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
