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 994E33860C39 for ; Tue, 29 Sep 2020 10:37:25 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 994E33860C39 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 6695E31B; Tue, 29 Sep 2020 03:37:25 -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 9C1023F6CF; Tue, 29 Sep 2020 03:37:24 -0700 (PDT) Date: Tue, 29 Sep 2020 11:37:21 +0100 From: Dave Martin To: Alejandro Colomar Cc: mtk.manpages@gmail.com, g.branden.robinson@gmail.com, linux-man@vger.kernel.org, libc-alpha@sourceware.org Subject: Re: [RFC] system_data_types.7: wfix + ffix Message-ID: <20200929103719.GJ6642@arm.com> References: <20200928151646.20271-1-colomar.6.4.3@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20200928151646.20271-1-colomar.6.4.3@gmail.com> User-Agent: Mutt/1.5.23 (2014-03-12) X-Spam-Status: No, score=-11.6 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 10:37:27 -0000 On Mon, Sep 28, 2020 at 05:16:47PM +0200, Alejandro Colomar wrote: > The previous format/wording for the includes wasn't very clear. > Improve it a bit following Branden's proposal. > > Reported-by: G. Branden Robinson > Signed-off-by: Alejandro Colomar > --- > > Hi, > > What do you think about this? > > Would you change something? Why should the user of a man page have to go look at the comments in the page source in order to find an explanation of what the notation in the page means? That seems very strange. > > Thanks, > > Alex > > > man7/system_data_types.7 | 285 ++++++++++++++++----------------------- > 1 file changed, 113 insertions(+), 172 deletions(-) > > diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 > index 16930985e..dc4a3bae4 100644 > --- a/man7/system_data_types.7 > +++ b/man7/system_data_types.7 > @@ -33,20 +33,21 @@ system_data_types \- overview of system data types > .\" Each entry will have the following parts: > .\" * Include > .\" The headers will be in the following order: > +.\" "Include:" > .\" 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 > +.\" according to the C Standard. > +.\" ["or"] > +.\" 2) The main header that shall define the type > +.\" according to POSIX. > +.\" [". Alternatively,"] > +.\" 3) 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. > +.\" "." It is fine to have notes about page maintenance here -- i.e., which headers should be placed where in the list, and what order to sort them in. However, I think that statements about which header(s) provide the type under which standard need to be in the actual page text. Programmers need this information. > .\" > .\" * Definition (no "Definition" header) > .\" Only struct/union types will have definition; > @@ -203,8 +204,8 @@ See also: > .RS > .br > Include: > -.IR ; > -or > +.IR . > +Alternatively, > .IR . > .PP > An object type used for streams. > @@ -268,19 +269,14 @@ type in this page. > .RS > .br > Include: > -.IR ; > -or > -.I > -or > -.I > -or > -.I > -or > -.i > -or > -.I > -or > -.I > +.IR . > +Alternatively, How does the reader of the page know that "alternatively" here has a specific and different meaning from "or"? Can we describe this somehow along the lines of: The C standards specify this type in the following header: In POSIX environments, it is sufficient instead to include any of the following headers, but the resulting program may not be portable to other C implementations unless is also included: [etc.] (I'm not sure this is 100% true, but it seems a safe recommendation. I'm also being lazy by writing "the C standards" and "POSIX environments" here -- it would be better to be specific.) [...] Cheers ---Dave