From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wr1-x442.google.com (mail-wr1-x442.google.com [IPv6:2a00:1450:4864:20::442]) by sourceware.org (Postfix) with ESMTPS id 8D6DB3857800 for ; Tue, 29 Sep 2020 11:57:30 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 8D6DB3857800 Received: by mail-wr1-x442.google.com with SMTP id j2so5057115wrx.7 for ; Tue, 29 Sep 2020 04:57:30 -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=6bNzq/ebHUet/XdT0FFen+pWdPLwre8g3CY0488K2Vk=; b=Jv8u/Dd1SVtfEfebdmOMICn9Vjm61YGethBAMhOIPb92+uwGv7SDwO5mu4mcJbbmON VyMY8rYJq083Uxi9mMlFpXp7suVbmICn29ut2UXwfcFfq4vWRtVsBK3qBfOciqD5lnbC aJMfHeVTIT8RMZd3tmGYASjze2/WYaGjZD60aVBUbvhqNTF2eEvLIXLW+O5gvpQhv5e+ x/zysqA47E/ZbthbO0ESorr5Lci/EkLixtQMP8p1sbKac02AFbH94ukIc71R0DzbpTTS YTEJ1RQ65ho7mFohGPJk0bF8Ltb5Z+UN9jyNETgklLJ8Nxxpl5f60XloNhYodgapL8Mb 7j2w== X-Gm-Message-State: AOAM532/B2N4I/t9TibaY1fHGiFo3Y9K3FzjOZa0fGLevCdfJhzy2nwp R9B5IyG4jdaaFUlsxGOgJLqDpVCIdYTDig== X-Google-Smtp-Source: ABdhPJwYF4VmLYg811O83aMn45HOLZXW9B11oZEA4yJt5W1xAyBSIjXszVBB8aYI1SNLn7fM4eEwhA== X-Received: by 2002:a5d:6cb1:: with SMTP id a17mr4060458wra.386.1601380649338; Tue, 29 Sep 2020 04:57:29 -0700 (PDT) Received: from [192.168.1.143] ([170.253.60.68]) by smtp.gmail.com with ESMTPSA id t10sm4922739wmi.1.2020.09.29.04.57.28 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Tue, 29 Sep 2020 04:57:28 -0700 (PDT) Subject: Re: [RFC] system_data_types.7: wfix + ffix To: Dave Martin Cc: mtk.manpages@gmail.com, g.branden.robinson@gmail.com, linux-man@vger.kernel.org, libc-alpha@sourceware.org References: <20200928151646.20271-1-colomar.6.4.3@gmail.com> <20200929103719.GJ6642@arm.com> From: Alejandro Colomar Message-ID: Date: Tue, 29 Sep 2020 13:57:27 +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: <20200929103719.GJ6642@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 11:57:32 -0000 Hi Dave, On 2020-09-29 12:37, 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 think I'll add a paragraph in the NOTES section at the bottom of the page. > >> >> 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. I hope a paragraph in the NOTES section will be explicit enough, as said above. > >> .\" >> .\" * 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"? Well, it remarks a bit that those are something like 2nd class headers for that definition. But that together with a paragraph in NOTES will be better. > > 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.) > > [...] I wanted to avoid that because that would add a lot of noise lines. Do you think the note in NOTES would be enough? Thanks, Alex > > Cheers > ---Dave >