From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wr1-x443.google.com (mail-wr1-x443.google.com [IPv6:2a00:1450:4864:20::443]) by sourceware.org (Postfix) with ESMTPS id D857C3857C7F for ; Tue, 29 Sep 2020 14:52:20 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org D857C3857C7F Received: by mail-wr1-x443.google.com with SMTP id e16so5776157wrm.2 for ; Tue, 29 Sep 2020 07:52:20 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:cc:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=m962ENYoc7HdESPO6YQ+GpKTVMMPAzdMKUusB3TmfkY=; b=WmbJyApKjYqu9ARWM/9REQCuYM03SvXJgq7su2N8f8fBCCY1S4pvZvwUA5/6gDljl/ 45tmcshdJUKDGei6Uzaq502Rr1pjI48l6NmuSo8Ia21oQ3OWyZomgJEn95Kqf51ESnLj Zcez1Nqp5PUYc4BMb4jfZgeVJqKzIATpGxmqvZrDTWb/hL2FlJmz1oqTwewypdbqg2tx TgKPIHjGYRt1z5RvphBLXAQhVou5xfv+GMh9aKp8w1gJayo4FpucLrT3FfzpiNjtoiIm FOqo4ALcGRVK9TXfpTTmKk9wibUBGABlxAPB755UWsY8AEBaKl532vXg35jOSNA0E3oy WHrw== X-Gm-Message-State: AOAM530ZNp4XMft2DhknbHVdTPGpBB6U0SbRnOOhCwasukAjwfgXmIkz I5NYKEhNwKVPNULjd9MgbnE= X-Google-Smtp-Source: ABdhPJxJG5zy3dkIpKlOKW+EHBUUAlcYfOhAJbIJFf4yi+5LqpBWiHWuIOGQPCm9Chb3kiQHwNp7AA== X-Received: by 2002:a5d:444b:: with SMTP id x11mr4758891wrr.402.1601391139717; Tue, 29 Sep 2020 07:52:19 -0700 (PDT) Received: from [192.168.1.143] ([170.253.60.68]) by smtp.gmail.com with ESMTPSA id 18sm5816625wmj.28.2020.09.29.07.52.18 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Tue, 29 Sep 2020 07:52:19 -0700 (PDT) Subject: Re: [PATCH v2] system_data_types.7: Improve "Include" wording and format, and explain it in NOTES To: Dave Martin Cc: mtk.manpages@gmail.com, linux-man@vger.kernel.org, libc-alpha@sourceware.org, g.branden.robinson@gmail.com References: <20200929142219.72683-1-colomar.6.4.3@gmail.com> <20200929144324.GM6642@arm.com> From: Alejandro Colomar Message-ID: <3dae4d7f-3c08-4f1c-47ce-8815255ca24c@gmail.com> Date: Tue, 29 Sep 2020 16:52:18 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.12.0 MIME-Version: 1.0 In-Reply-To: <20200929144324.GM6642@arm.com> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-10.0 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_ENVFROM_END_DIGIT, FREEMAIL_FROM, GIT_PATCH_0, NICE_REPLY_A, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 29 Sep 2020 14:52:23 -0000 Hi Dave, On 2020-09-29 16:43, Dave Martin wrote: > On Tue, Sep 29, 2020 at 04:22:19PM +0200, Alejandro Colomar wrote: >> The previous format/wording for the includes wasn't very clear. >> Improve it a bit following Branden's proposal. >> It also helps reduce lines of code. >> >> Add a subsection in NOTES explaining the conventions used. >> >> Remove the comment for helping maintain the page, >> as the NOTES section is now clear enough. >> >> Reported-by: G. Branden Robinson >> Reported-by: Dave Martin >> Reported-by: Michael Kerrisk >> Signed-off-by: Alejandro Colomar >> --- >> >> Hi Michael, >> >> After this patch, we're at a sync-point: no more pending patches from me. >> >> Tomorrow I'll go to the mountain, so you can have a small break from me :p >> >> Cheers, >> >> Alex >> >> >> man7/system_data_types.7 | 302 +++++++++++++++------------------------ >> 1 file changed, 119 insertions(+), 183 deletions(-) >> >> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 >> index af0c55c65..9cf67ee6f 100644 >> --- a/man7/system_data_types.7 >> +++ b/man7/system_data_types.7 >> @@ -31,22 +31,7 @@ system_data_types \- overview of system data types >> .\" Layout: >> .\" A list of type names (the struct/union keyword will be omitted). >> .\" Each entry will have the following parts: >> -.\" * Include >> -.\" The headers will be in the following order: >> -.\" 1) The main header that shall define the type >> -.\" according to the C Standard, >> -.\" and >> -.\" the main header that shall define the type >> -.\" according to POSIX, >> -.\" in alphabetical order. >> -.\" ; >> -.\" 2) All other headers that shall define the type >> -.\" as described in the previous header(s) >> -.\" according to the C Standard or POSIX, >> -.\" in alphabetical order. >> -.\" *) All headers that define the type >> -.\" *if* the type is not defined by C nor POSIX, >> -.\" in alphabetical order. >> +.\" * Include (see NOTES) >> .\" >> .\" * Definition (no "Definition" header) >> .\" Only struct/union types will have definition; >> @@ -55,9 +40,10 @@ system_data_types \- overview of system data types >> .\" * Description (no "Description" header) >> .\" A few lines describing the type. >> .\" >> -.\" * Conforming to >> +.\" * Bugs (if any) >> +.\" >> +.\" * Conforming to (see NOTES) >> .\" Format: CXY and later; POSIX.1-XXXX and later. >> -.\" Forget about pre-C99 C standards (i.e., C89/C90) >> .\" >> .\" * Notes (optional) >> .\" >> @@ -203,8 +189,8 @@ See also: >> .RS >> .br >> Include: >> -.IR ; >> -or >> +.IR . >> +Alternatively, >> .IR . >> .PP >> An object type used for streams. >> @@ -269,19 +255,14 @@ type in this page. >> .RS >> .br >> Include: >> -.IR ; >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> +.IR . >> +Alternatively, >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> or >> .IR . >> .PP >> @@ -306,8 +287,8 @@ See also: >> .RS >> .br >> Include: >> -.IR ; >> -or >> +.IR . >> +Alternatively, >> .IR . >> .PP >> A type used to hold a general identifier. >> @@ -586,29 +567,19 @@ See also: >> .RS >> .br >> Include >> -.IR ; >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> +.IR . >> +Alternatively, >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> or >> .IR . >> .PP >> @@ -738,11 +709,10 @@ types in this page. >> .RS >> .br >> Include: >> -.IR ; >> -or >> -.I >> -or >> -.I >> +.IR . >> +Alternatively, >> +.IR , >> +.IR , >> or >> .IR . >> .PP >> @@ -787,8 +757,8 @@ structure in this page. >> .RS >> .br >> Include: >> -.IR ; >> -or >> +.IR . >> +Alternatively, >> .IR . >> .PP >> .EX >> @@ -823,9 +793,9 @@ See also: >> .RS >> .br >> Include: >> -.IR ; >> -or >> -.I >> +.IR . >> +Alternatively, >> +.IR , >> or >> .IR . >> .PP >> @@ -886,55 +856,32 @@ in this page. >> Include: >> .I >> or >> -.IR ; >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> +.IR . >> +Alternatively, >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> or >> .IR . >> .PP >> @@ -1007,21 +954,15 @@ types in this page. >> .RS >> .br >> Include: >> -.IR ; >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> +.IR . >> +Alternatively, >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> or >> .IR . >> .PP >> @@ -1083,9 +1024,9 @@ types in this page. >> .RS >> .br >> Include: >> -.IR ; >> -or >> -.I >> +.IR . >> +Alternatively, >> +.IR , >> or >> .IR . >> .PP >> @@ -1110,23 +1051,17 @@ structure in this page. >> .RS >> .br >> Include: >> -.I >> -or >> -.IR ; >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> +.I >> or >> -.I >> +.IR . >> +Alternatively, >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> or >> .IR . >> .PP >> @@ -1153,8 +1088,8 @@ See also: >> .RS >> .br >> Include: >> -.IR ; >> -or >> +.IR . >> +Alternatively, >> .IR . >> .PP >> Used for timer ID returned by >> @@ -1176,17 +1111,13 @@ See also: >> .RS >> .br >> Include: >> -.IR ; >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> +.IR . >> +Alternatively, >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> or >> .IR . >> .PP >> @@ -1214,11 +1145,10 @@ See also: >> .RS >> .br >> Include: >> -.IR ; >> -or >> -.I >> -or >> -.I >> +.IR . >> +Alternatively, >> +.IR , >> +.IR , >> or >> .IR . >> .PP >> @@ -1247,17 +1177,13 @@ See also: >> .RS >> .br >> Include: >> -.IR ; >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> -or >> -.I >> +.IR . >> +Alternatively, >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> +.IR , >> or >> .IR . >> .PP >> @@ -1418,9 +1344,9 @@ types in this page. >> .RS >> .br >> Include: >> -.IR ; >> -or >> -.I >> +.IR . >> +Alternatively, >> +.IR , >> or >> .IR . >> .PP >> @@ -1473,6 +1399,16 @@ If the type has upper and lower limits, >> the user should check that the value is within those limits, >> before actually copying the value. >> The example below shows how these conversions should be done. >> +.SS Conventions used in this page >> +In "Conforming to" we only concern ourselves with >> +C99 and later and POSIX.1-2001 and later. >> +Some types may be specified in earlier versions of one of these standards, >> +but in the interests of simplicity we omit details from earlier standards. >> +.PP >> +In "Include", we first note the "primary" header(s) that >> +define the type according to either the C or POSIX.1 standards. >> +Under "Alternatively", we note additional headers that >> +the standards specify shall define the type. > > While this is more informative, it still doesn't help the programmer > know which header(s) to use in a given situation. I'd worry that people > may not read as far as the NOTES, or may not remember what's in there > when referring to the header lists. I hope they do :) And if not, I hope that people will take the first one they see (and not go through some obscure alternative headers). > > Can we not just annotate each header listed with the originating > standard, say: > > (C) > > (POSIX) > ... (POSIX) > ... That may be a good idea; I've thought about doing that in the past; but also thought that it's still too much noise. Let's see what others think about it. The downside is that it adds a lot of lines, being harder to read for types with too many headers (e.g., size_t). It could also be done in the same line, but maybe it adds too much noise for the eyes to actually parse the headers. > > while this is a bit more effort in the man page, it should make things > clear for the reader. > > (the annotations can be terse, with a more complete citation of the > applicable standard in the NOTES or elsewhere). > > I'm not trying to be awkard here -- actually having man pages defining > key types and the relevant headers to include is a really good idea. No problem. I've already thought about this many times: how to be as informative as possible, without distracting from the main information. > > > Can we please alias all the actual type names to point to this page, > so that e.g., "man size_t" works? We already have that :) > > (This might be considered overkill, so if others shoot the suggestion > down, fair enough -- in any case the alises could be added by a later > patch.) > > Cheers > ---Dave > Cheers, Alex