From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by sourceware.org (Postfix) with ESMTP id B58123857816 for ; Tue, 29 Sep 2020 15:10:52 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org B58123857816 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=arm.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=Dave.Martin@arm.com Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id D161412FC; Tue, 29 Sep 2020 08:10:51 -0700 (PDT) Received: from arm.com (usa-sjc-imap-foss1.foss.arm.com [10.121.207.14]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id E90013F6CF; Tue, 29 Sep 2020 08:10:50 -0700 (PDT) Date: Tue, 29 Sep 2020 16:10:48 +0100 From: Dave Martin To: Alejandro Colomar Cc: mtk.manpages@gmail.com, linux-man@vger.kernel.org, libc-alpha@sourceware.org, g.branden.robinson@gmail.com Subject: Re: [PATCH v2] system_data_types.7: Improve "Include" wording and format, and explain it in NOTES Message-ID: <20200929151047.GN6642@arm.com> References: <20200929142219.72683-1-colomar.6.4.3@gmail.com> <20200929144324.GM6642@arm.com> <3dae4d7f-3c08-4f1c-47ce-8815255ca24c@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <3dae4d7f-3c08-4f1c-47ce-8815255ca24c@gmail.com> User-Agent: Mutt/1.5.23 (2014-03-12) X-Spam-Status: No, score=-12.1 required=5.0 tests=BAYES_00, GIT_PATCH_0, KAM_DMARC_STATUS, 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 15:10:55 -0000 On Tue, Sep 29, 2020 at 04:52:18PM +0200, Alejandro Colomar wrote: > 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. OK > > 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 :) Great :) [...] Cheers ---Dave