From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 63872 invoked by alias); 19 Dec 2016 10:37:43 -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 63857 invoked by uid 89); 19 Dec 2016 10:37:41 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-4.9 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,RP_MATCHES_RCVD,SPF_PASS autolearn=ham version=3.3.2 spammy=Facilities, adjusting, STANDARD, ITEM X-HELO: mail.pacific.net Subject: Re: [PATCH v2 1/5] manual: Refactor header and standards annotations. To: Joseph Myers References: <20161206105525.21117-1-ricaljasan@pacific.net> <20161206105525.21117-2-ricaljasan@pacific.net> Cc: libc-alpha@sourceware.org, mtk.manpages@gmail.com, carlos@redhat.com From: Rical Jasan Message-ID: <7b601dd6-09b5-c9e9-01b2-7b54e8c4eb55@pacific.net> Date: Mon, 19 Dec 2016 10:37:00 -0000 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.5.1 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 8bit X-Null-Tag: 42ffb294ac0f7f8d78d83e1337b92cee X-SW-Source: 2016-12/txt/msg00680.txt.bz2 On 12/06/2016 07:33 AM, Joseph Myers wrote: > On Tue, 6 Dec 2016, Rical Jasan wrote: > >> This commit handles some initial cleanup, making sure any >> existing header and standards annotations conform to the >> expected syntax. >> >> * manual/filesys.texi: Refactor code in preparation for future >> work on header and standards annotations. >> * manual/llio.texi: Likewise. >> * manual/locale.texi: Likewise. >> * manual/time.texi: Likewise. >> * manual/users.texi: Likewise. > > OK. Having had to take some time away from this, and coming back now ready to push this set in piecemeal fashion, I think this commit message can be improved, to give better context for itself: manual: Refactor header and standards annotations. This commit cleans up header and standards @comments, ensuring the standard and header lines immediately precede the item they are annotating (in that order). Doing so causes summary.awk to correctly pick up the annotations, fixing 1 entry in the Summary of Library Facilities and improving 2 others. And now would probably be a better time to update the syntax comment in summary.awk, which may not show up for a while otherwise (in [v2 4/5]; presently unreviewed). I was also thinking of adjusting it a bit: # This script recognizes sequences that look like: -# @comment HEADER.h +# @comment HEADER.h[ ...] # @comment STANDARD # @def... ITEM | @item ITEM | @vindex ITEM +# where multiple headers must be space-separated and STANDARD is +# essentially free-form. Should I submit a v3 for this, stick to v2, or go ahead and commit with the suggested updates? Rical