Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-12.6 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI,SIGNED_OFF_BY, SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 13F64C4727C for ; Tue, 29 Sep 2020 14:23:33 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id AC373206DB for ; Tue, 29 Sep 2020 14:23:32 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="DoqF0YKa" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727659AbgI2OXc (ORCPT ); Tue, 29 Sep 2020 10:23:32 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:36116 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727543AbgI2OXc (ORCPT ); Tue, 29 Sep 2020 10:23:32 -0400 Received: from mail-wr1-x441.google.com (mail-wr1-x441.google.com [IPv6:2a00:1450:4864:20::441]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id CD7E4C061755 for ; Tue, 29 Sep 2020 07:23:31 -0700 (PDT) Received: by mail-wr1-x441.google.com with SMTP id c18so5606735wrm.9 for ; Tue, 29 Sep 2020 07:23:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Y1MneoyQBHC+g79bSjTct8l5JxM7muabsOdrTUPJsYk=; b=DoqF0YKaWB293+mjlc29QM/f42Fxc9bx6Ou9g+XismSrzvOwJ9+SbEK5ciips0mMQE iqsAQUXAewWngcpXh8EziF6NpBUSaEmZNEzcIkweUf6OkxT08kk8YPe6RE4VO0SVNg82 5g6ThrMNcHbHEzyvrQhc7G9XZ1w0thfhD3AYa1y+b//rLm77/mh0qpWnrHV7v3bmeaW0 VHoKcVQIAin62lsQqhfGGj2qnNo9TrjovWK2+zXqXbKqz9bM6dZ5vYpX5l0I7yigagat aEWhpR+GAdsWh4SWj4iTJA6ZLvQl0zKuK/Uo/kUWw1fjq++rptnqTwKkoEAvWx4orzuS /5GQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=Y1MneoyQBHC+g79bSjTct8l5JxM7muabsOdrTUPJsYk=; b=dEcqOlzcXaZTEmTDcLkfjbNP+28y6lSh3bGjJkT62mVJVLEc2jyiGlGbhOkpOIlCgj VIOb1OxFQpD8NtrIhdY2YhdnBzOehzFR06dC+Dqx7PfEbrcCxMyB/LJ+65fgwyTbZ6UY uc6QzgdDTXBWDlQzHSUX7nxVjjSN5tnn/UXl88DUfk1p3ewm4C1hxkN6CPGqSsQTVWvb jFACKUNuGU/TqQJAnaSK70QO1xM8eDSrgerJmUC9WoKq1y5ebNE1QywrAV788icwg5Er A0HKf6h7WaxHqKC4W8fMBbv8zkmkPnSUh+qSEIPpJ/Bn2v+mnZ7Y6eCpNC7FMJPBqscn +VGQ== X-Gm-Message-State: AOAM531r1rBbXvIqJYsJLKwLrzOmxBzi+VEWl7bzzCrwLYCr+DSg0suI MaeZdfUjIuDM9AaTr0dnodY= X-Google-Smtp-Source: ABdhPJy2Dlx4ndz62Fbkt5R/UEkZDGgVW1oPacFZyudAN0nJ5Mpt/geEIuTNZmM5LJmmu04kyMmMdA== X-Received: by 2002:a5d:4d48:: with SMTP id a8mr4612805wru.318.1601389410382; Tue, 29 Sep 2020 07:23:30 -0700 (PDT) Received: from localhost.localdomain ([170.253.60.68]) by smtp.googlemail.com with ESMTPSA id o4sm5986438wru.55.2020.09.29.07.23.29 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 29 Sep 2020 07:23:29 -0700 (PDT) From: Alejandro Colomar To: mtk.manpages@gmail.com Cc: Alejandro Colomar , linux-man@vger.kernel.org, libc-alpha@sourceware.org, g.branden.robinson@gmail.com, Dave.Martin@arm.com Subject: [PATCH v2] system_data_types.7: Improve "Include" wording and format, and explain it in NOTES Date: Tue, 29 Sep 2020 16:22:19 +0200 Message-Id: <20200929142219.72683-1-colomar.6.4.3@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Precedence: bulk List-ID: X-Mailing-List: linux-man@vger.kernel.org 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. .SH EXAMPLES The program shown below scans from a string and prints a value stored in a variable of an integer type that doesn't have a length modifier. -- 2.28.0