From nobody Sun Mar 23 04:58:16 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 4ZL3pw5nVhz5rk6T; Sun, 23 Mar 2025 04:58:16 +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 4ZL3pw4sL2z4FCq; Sun, 23 Mar 2025 04:58:16 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1742705896; 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=B5Maiercck5zoYGOTEz/pWcCMTPCRSZmqkvqrFDpHqM=; b=FLmh1zGLh1EY4A9RmuWQTsETBDN8zCOVNqRIfzgx819FgV6bjl+Hobj9dfRwlgs8trrldF j6JBlB4GfqyjQ+qz3DXNancl5a1KEWpgqRCAo/yVXhaqWWtcauHx8ZZp3+03ymWi5wlAem BSVYPSeZ2pOd2TTai4SbEeXyE60sU6YhRDSD4ZzzwVP7nBBS4msqiK7n5Nv749yLtjv1fS AoUU/90pjtStXnocw8sxZt1sb3kOx2BsjsfgRg5TnkWUPu28skAI9nkb0Fi7kHnWElwNbd nvbNedlvj5/9LZ+jCSD7k0dQyBD8aLHS+IeOR8Bknz+xd9coE3+wPEd6xGMT1w== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1742705896; a=rsa-sha256; cv=none; b=mhpWWhvRuhq+pVd+PomiKugTiEAzgpG1gTCqgYYIrjnL0TiBY2hzmdfkyVv+cyf514eRCv i2hnbWJDpXfT6BLWpmmmGBBi2i1/FWXNG4CB8SlahM1yuWEs5D2Oopuu7Y5f/3X1uttRX7 ybHNQpVtCCAZQ57/ndk2UrktlIQVG6xK8hkWjVZW3iyWmoCi41z9RoA6csHJRZBSduaxVu RG/j6k2BFtKnr/NL7QbhMJbhrzypI4R1baCNE/BPPA+lKk6+OP6aLVWlxtYvC4v5l3Whcg TvSUhZo3pWe7ArXgCWA5xsT6XSMoqPn9bee/QFDZQzb7OLuTzPu70annOigMpg== 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=1742705896; 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=B5Maiercck5zoYGOTEz/pWcCMTPCRSZmqkvqrFDpHqM=; b=ro3gb3vnu5bx9VrISv8essiX7F9jnrnPV35/vYt/tWa25pObt96aB/ISbzxkt843is0A9f r+5aSadi+Ca50v+D3wnFXzDOoZBPkl7n6H/wJDDt0PsruI7XmsxcMhKwgUqeFXpndG/bdW yhM3MKgRQdFizzYLW4txfHizZQD7PsO4NL2dDrRqj8TYWmLvAk4aRGcGnSjKsftqfv9ZP0 nvjtTa6/PnLswUvSAsmrgY9aM0yuXMgFGlcddG7Pnk1qYP5x0k1I9jkgvTll7uzZnt4f/V ZzVfzINFXvxx3uOGQD95k3Vyv3jwbaBLdTXv0dzfyGoEZpxgV70/VuIQ3VlWGQ== 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 4ZL3pw3FdNztH5; Sun, 23 Mar 2025 04:58:16 +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 52N4wGjt059374; Sun, 23 Mar 2025 04:58:16 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 52N4wGDD059371; Sun, 23 Mar 2025 04:58:16 GMT (envelope-from git) Date: Sun, 23 Mar 2025 04:58:16 GMT Message-Id: <202503230458.52N4wGDD059371@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Alexander Ziaee Subject: git: 29eb4de61a4c - main - 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/main X-Git-Reftype: branch X-Git-Commit: 29eb4de61a4c2ab1d940e10f3816db79e74d46b1 Auto-Submitted: auto-generated The branch main has been updated by ziaee: URL: https://cgit.FreeBSD.org/src/commit/?id=29eb4de61a4c2ab1d940e10f3816db79e74d46b1 commit 29eb4de61a4c2ab1d940e10f3816db79e74d46b1 Author: Alexander Ziaee AuthorDate: 2024-10-06 22:44:15 +0000 Commit: Alexander Ziaee CommitDate: 2025-03-23 04:54:21 +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 --- 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