From patchwork Tue Sep 29 14:22:19 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alejandro Colomar X-Patchwork-Id: 40545 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 44C22386F40E; Tue, 29 Sep 2020 14:23:35 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 44C22386F40E DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1601389415; bh=Y1MneoyQBHC+g79bSjTct8l5JxM7muabsOdrTUPJsYk=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=S0Sl93G5tVlVrWklzVf9E739hn+gfkyM/Q2HLq2gsAgUXO4+E/wBeIXQpkeSAR4Um soTp9hgC3w5HjdVE1pK6dFHLDguYygWhyQp59FLYd6YBbDwwgSsCM5tp1hkbG+9IeP CyiL55EUUOEa62mDESf6249TEpQQ/YKo55vknv9w= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org 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 6326D3857C7F for ; Tue, 29 Sep 2020 14:23:31 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 6326D3857C7F Received: by mail-wr1-x441.google.com with SMTP id x14so5600552wrl.12 for ; Tue, 29 Sep 2020 07:23:31 -0700 (PDT) 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=Cxodjw90qvxba+CGVknvmUH7UEFknx5I0s8W6Cxx0+vZCc5U1rsOV3jOX8NA1yHJBs GI54lTuYHY9OEzhQUx/wv51bLs/fuc55BAYq/S2KjKFzJA+sLg9WPSsykktpqSvkROYE kNXjGZqMgMMc7UucnaZykP5EVDpaNF3ue5IaIFXZ3yo3Dy2TdGgpDVcuspxrG1ettUmJ Ym3jd5RVDsVjHduA7+9LLKiX+a39YASQc1ob9bkTAIZEHnpN7XZ5Tj7Sk9N5y2ufUcPm F0kaCUwwnYTYJFx6c2jPCk5f1qGaI/KZh1Y+AWLK03edH7Z6HvzU/PlN4JdH7gG7tgk2 4G6Q== X-Gm-Message-State: AOAM531ltMQJcSBC0UM1J2Ef6yPAt/ohtDo388N6B281rUF9k+aN7SC9 hfXYNoT5IP97msNw93CQHDI= 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) To: mtk.manpages@gmail.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 X-Spam-Status: No, score=-9.9 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, 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-Patchwork-Original-From: Alejandro Colomar via Libc-alpha From: Alejandro Colomar Reply-To: Alejandro Colomar Cc: Alejandro Colomar , linux-man@vger.kernel.org, g.branden.robinson@gmail.com, libc-alpha@sourceware.org, Dave.Martin@arm.com Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" 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.