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

[Peng Haitao <penght-BthXqXjhjHXQFUHtdCDX3A@public.gmane.org>]

Hi Michael,

What is the status of this thread now?

> If need be Alex can repost the text for the linux kenrel man pages
> project to reuse it under an alternate license.

Maybe we need Alex can repost "Safety Concepts" section for the man-pages?

Thanks.


-- 
Best Regards,
Peng

On 02/26/2014 01:28 AM, Carlos O'Donell wrote:
> On Sun, Feb 23, 2014 at 5:16 AM, Michael Kerrisk (man-pages)
> <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
>>> 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.
> 
> My pleasure.
> 
>> 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?)
> 
> No automation. Manual inspection. It took Alexandre roughly a year to
> get through ~1000+ functions. After a while though the previous safety
> notes help you out immensely as you don't need to recurse deeply in a
> function when you know the properties of the functions you are
> calling.
> 
>> 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?
> 
> The noes are preliminary so we make no promises.
> 
> We document the actual state (not perfectly true, but it's the
> statement we want to make).
> 
> We do not presently indicate what is the desired state.
> 
> Some interfaces deviate from the standards, and in some cases we have
> started marking that e.g. !posix.
> 
> However, we need to do a second pass to ensure that:
> 
> (a) We transition from preliminary to full guarantees about the API.
> 
> -- When we do this transition we will look at what the desired
> guarantee is for each function.
> 
> For example we may *never* guarantee setlocale is MT-safe, simply
> because the consequence of making it safe slows down every other
> function that uses locales.
> 
> (b) We document the standard requirement for reference.
> 
> (c) We add texinfo comments when we have notes to describe why we
> deviate from the standard.
> 
>> 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 glibc manual changes were generated manually.
> 
> However, the notes per function are not text, but instead texinfo macros.
> 
> The macros are then turned into the text you see.
> 
> Therefore we have a meta-language in texinfo macros to describe the
> safety notes for each function.
> 
> We have a regression test to ensure these notes follow the rules we
> set out for them e.g. if you mark something unsafe you note why using
> a valid marker for that safety note.
> 
> Markup has not been added to the source to generate a summary of
> information about MT-safety.
> 
> This is actually a GSoC project for glibc:
> https://sourceware.org/glibc/wiki/GSoC
> 
> See "Dynamic Documentation"
> 
> Fundamentally we can't move source code documentation into the manual
> because of the licensing barrier between GFDL and LGPLv2, *however*
> since gcc has the same problem with C++ we do have a known process for
> doing this easily (FSF maintainer given the right to relicense the
> generated docs and check them in).
> 
> I also question the validity of copyrighting some of this information.
> For example I consider that the safety note information isn't
> copyrightable because it's a property of the function. Descriptive
> text about why we don't follow the standard would be copyrightable
> though.
> 
>> 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.
> 
> We considered this initially and we want to go in that direction, but
> for this initial pass we determined it would complicate the project
> and decided to do a manual pass.
> 
> If you can suggest any technology we might wish to use, we could
> refine our GSoC project?
> 
> 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