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
