From nobody Wed Mar 26 05:42:27 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4ZMwfX03RZz5rPbp; Wed, 26 Mar 2025 05:42:28 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4ZMwfW5nXmz3s6t; Wed, 26 Mar 2025 05:42:27 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1742967747; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=OSVH0vcgKLk6NLW52suqo9zNLxwdR3Ti+MXCT89yuE8=; b=OMWpcUYQ+j7YvvUhiLZEpnn64+SB7JiJb4pqiRKg160ImOzqxKzk92S4EeyBAddAUsGdeK 3rRQaigLICqPI8zncyYu5l0PJ58L/lk6Fn684LnQICbaDtkLJsWdW1IbjUlxZ8hZt87c8F vyC9qJ9DgDgaVe4vvA4So8fJQoqWH0UuEdJgmPdKRXE1d6XIpqJs3Q0wJpugaUjpAza6wm XNM/tn/Ewteti3W5vdtC4FyrOCzdBac37dx8tvm0HCsBXRDK4DPacxt+fa6xNrFZKV5qlw 4xhFNy+PXPxDbiI2915YO8tgYQOF55y5utujnO83DGPfQdBtX8gk7suQzCIKCA== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1742967747; a=rsa-sha256; cv=none; b=BCdQkaO+iVRPcSUcVHq8/iORpWfTg/Ff9AHXIddlBX5m5NEsJSGlaTlBmhTK3hg24J/LCp 8YpFHJVyDDIsAys1vp4VVf/KHezpHvIzkdiIvbC22R5sFeR0a8Udtoknz8wT6/SzAKqAcf tI8WQl1y7zJ50b2TgsrZsMLWqSTzt1+t50S3unAahT4XGPU47MAqhnYR5gT49jkfWx3wVg 5QSMVORd3I7cJhva285cNjgkeGwj+tSSIy6LNPCJIjpRF1cX+3kDhX+hpa6P6PsXU8Kv9y zLJHyjLGmSxzpx2c+BamGz576q9cgImRPoJzX2cvsgu3hB/vNxwQd/mzLxYtOQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1742967747; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=OSVH0vcgKLk6NLW52suqo9zNLxwdR3Ti+MXCT89yuE8=; b=eH4VbOorwR5mLuxbTSyuDjbv/26YNdupArnud3ecgcSd8W67sZd31zcONU7N9ACdptSY/p 27nlKzJfz6u6FId0/Bowg91UQ2nP8zQumUEWgLDEN0WWDVPx5Bjkumwce6ZgUThKDQurJs OXta8x9UfNLYLfywweRAUQ2GN8BiLDwfAq5rbH+c1xVBeaRalpmBqiPgVOAH1xpRi4YTl6 5m3+Y/BI0ecgG6NFGgsiUu4MDEQqghovifN+rUcLuKYotpgONApp2sQCWDsvTI14f7tO03 TbN6F8PX/cBDd5av7p2XG22pKUeltMzsNYkgPDIRXYZFZ4WR/xdgqGRi2WE6FA== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4ZMwfW4w3mz1CSC; Wed, 26 Mar 2025 05:42:27 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 52Q5gRe6030979; Wed, 26 Mar 2025 05:42:27 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 52Q5gREN030976; Wed, 26 Mar 2025 05:42:27 GMT (envelope-from git) Date: Wed, 26 Mar 2025 05:42:27 GMT Message-Id: <202503260542.52Q5gREN030976@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Alexander Ziaee Subject: git: b0d6aa07c193 - stable/14 - style.mdoc: HARDWARE generates Release Notes List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: ziaee X-Git-Repository: src X-Git-Refname: refs/heads/stable/14 X-Git-Reftype: branch X-Git-Commit: b0d6aa07c19370fd9c936f4ed28fe391b530bb9f Auto-Submitted: auto-generated The branch stable/14 has been updated by ziaee: URL: https://cgit.FreeBSD.org/src/commit/?id=b0d6aa07c19370fd9c936f4ed28fe391b530bb9f commit b0d6aa07c19370fd9c936f4ed28fe391b530bb9f Author: Alexander Ziaee AuthorDate: 2024-10-06 22:44:15 +0000 Commit: Alexander Ziaee CommitDate: 2025-03-26 05:40:59 +0000 style.mdoc: HARDWARE generates Release Notes FreeBSD Release Infrastructure has been building the Hardware Release Notes from these subsections in the Kernel Interfaces Manual. Standardize this behavior in the FreeBSD Manual page style guide with everything we learned in the 14.2-RELEASE. To me, this is an enormously exciting discovery, and I believe that over the next 5 years, this can transform the supported hardware UX, without reinventing the wheel, by doubling down on our ways instead of reinventing them. MFC after: 3 days Reported by: bz (special thanks) Reviewed by: imp, mhorne, pauamma, rpolaka Approved by: mhorne (mentor) Differential Revision: https://reviews.freebsd.org/D48343 (cherry picked from commit 29eb4de61a4c2ab1d940e10f3816db79e74d46b1) --- share/man/man5/style.mdoc.5 | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/share/man/man5/style.mdoc.5 b/share/man/man5/style.mdoc.5 index dd4d8a1f5fdf..d96c9ff08bbb 100644 --- a/share/man/man5/style.mdoc.5 +++ b/share/man/man5/style.mdoc.5 @@ -1,4 +1,4 @@ -.\"- +.\" .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2018-2022 Mateusz Piotrowski <0mp@FreeBSD.org> @@ -24,7 +24,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd December 12, 2024 +.Dd December 21, 2024 .Dt STYLE.MDOC 5 .Os .Sh NAME @@ -74,6 +74,33 @@ Historically, was the preferred way before the deprecation of .Sy \&Li . .El +.Ss HARDWARE Section +Driver manuals in section four should have a +.Sx HARDWARE +section describing hardware known to work with the driver. +This section is drawn verbatim into the Release Hardware Notes, +therefore there are several things to note: +.Bl -dash -width "" +.It +The introductory sentence should be in the form: +.Bd -literal -offset indent +The +\&.Nm +driver supports the following $device_class: +.Ed +.Pp +Followed by the list of supported hardware. +.Pp +This defines what driver the subsection is referring to, +and allows the reader to search through the Hardware Notes +not only for the device models they have, +but also for the device type they are looking to acquire. +.It +The supported hardware should be listed as a bullet list, +or if complexity requires, a column list. +These two list types create very neat subsections +with clean starting and stopping points. +.El .Ss EXAMPLES Section .Bl -dash -width "" .It