From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 51834 invoked by alias); 5 Apr 2017 03:08:39 -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 51793 invoked by uid 89); 5 Apr 2017 03:08:34 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.0 required=5.0 tests=AWL,BAYES_00,RP_MATCHES_RCVD,SPF_PASS autolearn=ham version=3.3.2 spammy=correlation, eventual, essentially X-HELO: smtp.pacific.net Subject: Re: [PATCH v2 3/5] manual: Add new header and standards annotations. To: Joseph Myers References: <20161206105525.21117-1-ricaljasan@pacific.net> <20161206105525.21117-4-ricaljasan@pacific.net> <665e49d4-dfa0-e14d-a793-d4acdca8e617@pacific.net> <7dd6da88-601f-e6f2-1f16-c24d7fdf84e2@pacific.net> <8c01ffc4-fcee-d584-bfab-d74a0b552b77@pacific.net> <8e8b0d56-b001-1870-1b5c-9895a1301c07@pacific.net> <0d5758f3-52bb-31cb-21e2-d218ace98065@pacific.net> <0aef1730-9021-ebe1-71d8-bf9f7e66c3e9@pacific.net> Cc: libc-alpha@sourceware.org, mtk.manpages@gmail.com, carlos@redhat.com From: Rical Jasan Message-ID: Date: Wed, 05 Apr 2017 03:08:00 -0000 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.7.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 8bit X-SW-Source: 2017-04/txt/msg00061.txt.bz2 On 04/04/2017 04:26 AM, Joseph Myers wrote: > On Tue, 4 Apr 2017, Rical Jasan wrote: >> the files are parsed and entries stored. Note that the locale is >> respected, so different users may have differently-ordered Summary >> chapters, but summary.awk appears to have done this as well. > > Respecting the locale is a simple bug; LC_ALL=C should be used in the > makefile when running anything that does sorting etc. as part of the build > process (as it already is in many places). But I like case insensitive sorting and expect exit, _Exit, and _exit to all be together in my manual. :P Anyway, "fixed" locally. Wrt. the patchset outline, how much of that would you like to see in v3? If I don't also supply the completion patches, I'll leave out the checking/enforcing bits in summary.pl to avoid breaking the build. There would then be significantly less to review, and the new content for completing the @standards can be a follow-up in a separate patchset. If you think the proposed syntax is acceptable, I'll also need to make a few tweaks to what I currently have, mostly so the conversion script doesn't use @comma{} for multiple standards or headers. I didn't begin addressing special cases until the bulk of the conversion was already in place, to see how it all panned out. The syntax I'm proposing at this point looks like: @item FOO @standards{STD, HDR} @deftypefun foo @deftypefunx fool @standardsx{foo, STD, HDR} @standardsx{fool, STD, HDR} @item BAR @standards{STD1, HDR1} @standards{STD2, HDR2} I believe that cleanly addresses both the generation of summary.texi and the eventual rendering we'd like to have. It does not address canonicalization of standards names (which could be enforced later in summary.pl), or whether or how to combine standards, those issues being in a different scope. Since the conversion creates the @standards from the @comments used by summary.awk and @standards aren't rendered yet, the status quo is maintained in that regard. The headers and standards are essentially rendered as-is in the Summary, with headers being wrapped in @file{}. The Summary entries are as-is as well, whether macros, variables, function prototypes, or what-have-you. The entries are all @items in a @table that uses @code. If we use the proposed syntax, there is also a choice of whether to change the Summary accordingly, or do any extra work to keep it the same. Consider the following entry: @comment crypt @item char * crypt (const char *@var{key}, const char *@var{salt}) @file{crypt.h} (BSD, SVID): @ref{crypt}. If we have in the manual: @item char * crypt (const char *@var{key}, const char *@var{salt}) @standards{BSD, crypt.h} @standards{SVID, crypt.h} The entry in summary.texi could become: @comment crypt @item char * crypt (const char *@var{key}, const char *@var{salt}) @file{crypt.h} (BSD): @ref{crypt}. @file{crypt.h} (SVID): @ref{crypt}. Currently, there is only a single line for every entry, so that also changes the status quo for summary.texi, similar to ignoring locale. This change is probably desirable, since it represents the same issue of correlation we're trying to solve by allowing multiple @standards to annotate a single element. I suppose the downside is that it's a little more verbose, but this is a reference manual. Rical