From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 79009 invoked by alias); 22 May 2017 09:03:57 -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 78996 invoked by uid 89); 22 May 2017 09:03:56 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.5 required=5.0 tests=AWL,BAYES_00,RP_MATCHES_RCVD,SPF_PASS autolearn=ham version=3.3.2 spammy= X-HELO: smtp.pacific.net Subject: Re: [PATCH v4 0/5] manual: Header & Standards Cleanup To: Zack Weinberg , libc-alpha@sourceware.org References: <20170519093353.6158-1-ricaljasan@pacific.net> Cc: Joseph Myers , Carlos O'Donell , Michael Kerrisk From: Rical Jasan Message-ID: Date: Mon, 22 May 2017 09:03:00 -0000 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.8.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-SW-Source: 2017-05/txt/msg00644.txt.bz2 On 05/19/2017 02:05 PM, Zack Weinberg wrote: > On 05/19/2017 05:33 AM, Rical Jasan wrote: >> There exists a convention for annotating which headers and standards a >> given function, variable, etc., provided by the glibc come from, >> guaranteeing their automatic inclusion in the Summary of Library >> Facilities, where they are indexed along with their headers and >> standards. The convention is based upon expectations present in >> summary.awk, though that script does not do any enforcing, merely >> indexing what it can find. It is roughly: >> >> @comment HEADER(S) >> @comment STANDARD(S) >> @(def|item|vindex) >> >> It would be nice to use something other than ad-hoc @comments for such >> annotations, and also provide a framework for ensuring annotations >> exist and are correctly formatted. To that end, a new set of macros >> are proposed: @standards and @standardsx. >> >> Examples of intended use are: >> >> @item FOO >> @standards{STD, HDR} >> >> @defvar BAR >> @standards{STD1, HDR1} >> @standards{STD2, HDR2} >> >> @deftypefun foo >> @deftypefunx fool >> @standardsx{foo, STD, HDR} >> @standardsx{fool, STD, HDR} > > Very high-level question: why can't this third case be > > @deftypefun foo > @deftypefunx fool > @standards{STD, HDR} > > or, when foo was in C89 but foof/fool were added in C99 (for instance) > > @deftypefun foo > @deftypefunx foof > @deftypefunx fool > @standards{STD1, HDR} > @standardsx{foof, STD2, HDR} > @standardsx{fool, STD2, HDR} > > That is, @standards sets the default for the entire @deftypefun{x} > group, and then @standardsx can override specific cases if necessary. > This should make at least some @deftypefun{x} groups less repetitive. There is no technical reason we can't or shouldn't do that. After exploring this and examining my process a bit, I think it stemmed from the initial step of getting the conversion script working (needing to put all discovered annotations somewhere), but I can adjust it accordingly. The conversion script will need to be a little smarter, and summary.pl's checks will need to be changed, but the above approach will avoid wasting a lot of rendered space (e.g., fromfp, et al.), so I'm in favour. >> This patchset uses a script to convert existing @comment-based >> annotations to @standards. First, the script is submitted for review, >> then the @standards* macros are added to macros.texi. Next, a number >> of fixes are applied to various syntax issues and then the conversion >> takes place. Lastly, summary.awk is replaced by summary.pl, in order >> to generate summary.texi from the new @standards. > > I appreciate your providing the conversion script, but I'm not sure it > should be checked in. Are we ever going to use it again after this > process is complete? No. It isn't intended to be committed; it's supplied purely for review of the conversion patch. Instead of manually sending an auxiliary patch I just included it in the `git send-email' patches, since I track it locally too. I have commit access, and since I'll presumably be the one to push, I know not to include it. I thought I said "this is not intended to be committed" in its "commit message", but it looks like that got lost along the way. Rical