From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 115780 invoked by alias); 30 Nov 2016 12:38:18 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Received: (qmail 115754 invoked by uid 89); 30 Nov 2016 12:38:17 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.9 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,SPF_PASS,URIBL_RED autolearn=ham version=3.3.2 spammy=wanting, historical X-HELO: relay1.mentorg.com Date: Wed, 30 Nov 2016 12:38:00 -0000 From: Joseph Myers To: Rical Jasan CC: , Michael Kerrisk , Carlos O'Donell Subject: Re: [PATCH 3/3] manual: Add new header and standards annotations. In-Reply-To: <951c0013-8227-46c3-6d05-678bca61f2ce@pacific.net> Message-ID: References: <20161123063807.14845-1-ricaljasan@pacific.net> <20161123063807.14845-4-ricaljasan@pacific.net> <64fa1a5a-4af3-5e3f-b192-e79203c3e328@pacific.net> <951c0013-8227-46c3-6d05-678bca61f2ce@pacific.net> User-Agent: Alpine 2.20 (DEB 67 2015-01-07) MIME-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" X-ClientProxiedBy: svr-ies-mbx-01.mgc.mentorg.com (139.181.222.1) To svr-ies-mbx-01.mgc.mentorg.com (139.181.222.1) X-SW-Source: 2016-11/txt/msg01098.txt.bz2 On Wed, 30 Nov 2016, Rical Jasan wrote: > I don't think I'm completely following this. Is this a redundant test, > then: > > ./math/bits/math-finite.h:#if defined __USE_MISC && defined __USE_ISOC99 Formally it's redundant. The use of __USE_ISOC99 there is to mirror the conditions under which bits/mathcalls.h is included to declare float and long double functions at all (see my comments in commit 3bfee8beb8caa939020d942dfa405a3d98975749). Arguably bits/math-finite.h should be merged into bits/mathcalls.h (i.e. have a way for the macros there to map to the __*_finite functions when appropriate), though that's complicated by the separate ia64 version of bits/math-finite.h. > My practical question is, if MISC is nonstandard, what would we document > in @standards? Just MISC? I see it replaces deprecated feature test My suggestion was DEFAULT. > macros _BSD_SOURCE and _SVID_SOURCE (or rather _DEFAULT_SOURCE does, > which is the only thing that sets __USE_MISC). Would we not want to > document that something came from BSD, for example? (Also see comment > below about handling deprecation.) I'd say any such historical information about sources of functions should go in free text. Likewise if we say anything about a function that was BSD or SVID or GNU before it was adopted by POSIX, @standards would only mention (the relevant version of) POSIX, but free text could say more about the history. > What do you think about handling the common, "This function is a GNU > extension.", throughout the descriptions? Would you remove those in > lieu of "Standards: GNU (...)"? It's one of the few consistent and > widespread phrases throughout the manual. Yes, I think free text describing standards could be removed when it doesn't give any more information than the @standards text. Likewise free text saying what header has a declaration. > Also, what about deprecation? I saw the exceptional case of gets > mentioned recently. There are quite a few BSD things the manual warns > about being deprecated. Maybe anything that can't be coloured properly > in @standards just deserves a nice paragraph somewhere in the description. Indeed, something not handled by @standards needs free text. Eventually it would be good for all of the conform/ data, the header contents and the standards annotations to be cross-checked against each other by the glibc testsuite. (conform/ and headers are already checked against each other. conform/ should correspond closely to the manual for standards properly handled in both, if everything including structure elements gets annotations in the manual. Correspondence between the headers and the manual is necessarily weaker, because of symbols exposed by headers where the standards permit but don't require this and we don't want to define it to be a stable API for those headers, but checking such a correspondence is still useful and can cover more standards than conform/, including DEFAULT and GNU.) That includes automatically finding undocumented interfaces, for which bugs should then be filed if not already open (we have extremely out-of-date scripts/documented.sh for listing undocumented functions as well). When you're checking that the sets of implemented and documented interfaces match, you get into needing to document that an interface is only available in certain configurations of glibc (e.g. Linux-specific interfaces). Thus I can see us eventually wanting macros (whether or not variants of @standards) that will insert text indicating how an interface is system-specific, for use by such checks to avoid complaining that an interface is documented that doesn't actually exist. -- Joseph S. Myers joseph@codesourcery.com