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@xxxxxxxxx> 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
