From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wr1-x441.google.com (mail-wr1-x441.google.com [IPv6:2a00:1450:4864:20::441]) by sourceware.org (Postfix) with ESMTPS id 0CEB0385E444 for ; Tue, 29 Sep 2020 11:34:55 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 0CEB0385E444 Received: by mail-wr1-x441.google.com with SMTP id m6so5019883wrn.0 for ; Tue, 29 Sep 2020 04:34:54 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:cc:subject:to:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=c5fXOtf7lkedRTbIqv+UVBPZkbQpmlhM92seLZS5gR0=; b=Xm8Z/41yVFPlIdvBbeaCwR1q9cNfmfr4SnAKCN8owTC5HtLLlq2idYM35Xa9j16Soc zyJa9cmLp3xDtk1YolcGh+slHE27+w87tsCUnAlZ1KjGxsHZ4gpZCOdwyX7JhIl7EGxP A7zOBdDNJlAutGoB3cEz+GyML6a4FaOht3D2K95S+26tGfo99l11zIgobioHyExdMnL1 loppiU4xJhgjmOIpiCjZSyKzg/PQk4x0B+26TsfVASYfsGKIf6aYXw7bUXcc7C67HdIs +iVJQD89QivVxtHhBO6M/qAHQQilScfnnRlJvLvK5ua6yyoNpMwrsw4yXc2+xYB3/zFL 8qTg== X-Gm-Message-State: AOAM530MIbL5e4+EWJ6LxSbBfqpBw0t8RIT9haiSWD/v48yhr9e/pN4V LZ0uT2+q2dFCNidx8aBvLZj5HFCTVrM= X-Google-Smtp-Source: ABdhPJyZIowNiDfn6Df9XN84ZYH7z5ZaFpF7/EGLEBoH3lt1k5x8uEZNv6ZxIREzax2RZfo+vRsGAw== X-Received: by 2002:adf:e80b:: with SMTP id o11mr4068513wrm.118.1601379293654; Tue, 29 Sep 2020 04:34:53 -0700 (PDT) Received: from ?IPv6:2001:a61:2479:6801:d8fe:4132:9f23:7e8f? ([2001:a61:2479:6801:d8fe:4132:9f23:7e8f]) by smtp.gmail.com with ESMTPSA id m3sm5807736wrs.83.2020.09.29.04.34.52 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Tue, 29 Sep 2020 04:34:53 -0700 (PDT) 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 To: Dave Martin , Alejandro Colomar References: <20200928151646.20271-1-colomar.6.4.3@gmail.com> <20200929103719.GJ6642@arm.com> From: "Michael Kerrisk (man-pages)" Message-ID: Date: Tue, 29 Sep 2020 13:34:52 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0 MIME-Version: 1.0 In-Reply-To: <20200929103719.GJ6642@arm.com> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-10.3 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, GIT_PATCH_0, KAM_SHORT, 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 11:34:56 -0000 Hi Alex, Dave, [Alex, just to note: this patch doesn't apply against current master.] On 9/29/20 12:37 PM, Dave Martin wrote: > 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. I do agree that we need to add some help for the reader. Alex, how about we start as follows. At the end of the NOTES Section, let's add a "Conventions used in this page" subsection (.SS). Some things to mention there: * In "Conforming to" we only concern ourselves with POSIX.2001 and later and C99 and later. The type may be specified in earlier versions of one of these standards, but in the interests of simplicity we omit details from earlier standards. * 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. And then I have a question. Alex, did you so far find a case of type where the C standard specified that a particular header shall define the type, but PPOSIX.1 either did not have that requirement or did not specify that header? I've been kind of expecting that the set of headers specified by POSIX be a proper superset of the the set of headers specified by C, but maybe you have found otherwise. >> 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. My question (to Alex) above is related. (And to repeat, the thing I most care about in the man pages is POSIX.1, rather than C.) >> .\" >> .\" * 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.) This feels too verbose to me. Again, I care more about POSIX than C here. This is Linux; it quacks like a UNIX; so POSIX is the most relevant thing. And I want to keep the discussion of these types reasonably brief. In particular, I think that people who care a lot about portability across C implementations need to be looking somewhere else than the Linux manual pages. Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/