From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 119559 invoked by alias); 19 May 2017 21:05:36 -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 119547 invoked by uid 89); 19 May 2017 21:05:35 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.7 required=5.0 tests=AWL,BAYES_00,FREEMAIL_FROM,RCVD_IN_DNSWL_NONE,RCVD_IN_SORBS_SPAM,SPF_PASS autolearn=no version=3.3.2 spammy= X-HELO: mail-qk0-f179.google.com X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:references:cc:from:message-id:date :user-agent:mime-version:in-reply-to:content-transfer-encoding; bh=L5pHOJxtLH90cGrOCi2GIwgVLTg4b2q3sy9BCTc/7OY=; b=AmmXBEp8scxvniZp2zOkvwpDwd4wgJqhotu3Qfvowc6m9ehXlzcsZdT9UVW3pzLyWs Yz1y8AgYRAR7oKLAoDKQ9cTOBI7xRiQj225XFzwMV3+q6JLnaQzo2BtSvRKINZUcv2lK IqYJ7UZR+WoofLNcRHuY+7eGxfpA5GxACSN94k0mAilcqbdHyQUv+++dlKPK2ojtM5ER ftr/5gKvbbB3me0f5qOdYjoIZnh/dVIZtW9/AXCnsq/CSV8vamwEPUukr4CnLRP5qOs0 ERUbXmO4hvEQOoIXrOZHX7xLIGX57MQbHE8gLcK5lCmEw1XEGN0MJt94d/WMxaxq1z0R PWrA== X-Gm-Message-State: AODbwcDGPyp+ENwc8wXO45l32uEvLW9F5BaZQ0IUnd2nWhJ3g+vpEXIK xpmcmv6gyIrCSw== X-Received: by 10.55.138.193 with SMTP id m184mr10098310qkd.192.1495227936112; Fri, 19 May 2017 14:05:36 -0700 (PDT) Subject: Re: [PATCH v4 0/5] manual: Header & Standards Cleanup To: Rical Jasan , libc-alpha@sourceware.org References: <20170519093353.6158-1-ricaljasan@pacific.net> Cc: Joseph Myers , Carlos O'Donell , Michael Kerrisk From: Zack Weinberg Message-ID: Date: Fri, 19 May 2017 21:05: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: <20170519093353.6158-1-ricaljasan@pacific.net> Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-SW-Source: 2017-05/txt/msg00614.txt.bz2 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. > 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? I do not feel qualified to review Perl code; I haven't used the language for anything nontrivial in many years. Because of this I am not going to review your patch 1 or 5. > In order to provide insight on the differences between summary.awk and > summary.pl, and how @standards will differ from the @comment-based > annotations, some analysis of the immediate and expected long-term > differences follows. I also appreciate your providing this analysis and I think temporary omission of certain entries from the summary files is fine. I'd like an answer to the above very high-level question before we proceed with the conversion, though. zw