From nobody Mon Aug 17 16:11:08 2026 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 4hNyW56gqdz6p0V1 for ; Mon, 17 Aug 2026 16:11:13 +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 "YR2" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 4hNyW55HMsz41fl for ; Mon, 17 Aug 2026 16:11:13 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1786983073; 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=ju66Fb+R9CCpUJOzRVBkGMPvaURej/r0n+oE/D7E6Hw=; b=Y8DlXXMBXa/WWOiY4qkaIpSH2kqIKtiSFQNpbTMVI7ZLrAnjyXowkEwMRYBaqdJ6mHlxMS SpKMMb/XAdiXIQkhhsoAPmfeF+dneFeipnh0NN+JDxbySzRg/U7oQ7rziFYG5Ais362ooT vYtZ/+xrT/4w5hREt53GJonUxcl68UD3VR8mi5SMGpt5OyCfiROKt0Ml4Qn5r2IzJrHoaZ Mb2xU3tBMvzRvk4PCF+SUKVX46o1qgVmKYhcV6M5dmFiJgxXu3nVzclbaNyjWM3kb1MS2j joHYFyzI+DBmiZY8d3kVNr659xb5ceHLEz7kuavm0rJaT4Wh8c4P18OmhZNw2g== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1786983073; a=rsa-sha256; cv=none; b=xUn9WXnlYmhJ5/Rkwvpzkdk4hCEorJnkkIeADMiyPlDuReKUbgmQWsKkLedN40jjmaR0kU tjmB2l67wMkP/ng2qhMtLUZBnQcOjuEfH044LAsT7SykTjX0KOYK3yhPN0HMcWA/qQVbKZ 52Xmrw6sn24y+vUGCxBX5/2r+nSAbqFUK68xnGS+8+keoH7akStoI8o2ScLa1lP8xNJj7C U2nnxf8s0uafX3VIcu+QkNuuB+m3qDJ1MdtqrL02pnrS+0ZZj1D8B1xWb2T5mAXAdEBXWT 9HBdGdHEt8h2IGUBw3r3QoRCvo4aVS2ebgyzQ+XRL69bR0Tk+cp8PM41DpiDhw== 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=1786983073; 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=ju66Fb+R9CCpUJOzRVBkGMPvaURej/r0n+oE/D7E6Hw=; b=XBgGdZcVs6dlVG8QZ1R4SDhHXBYLqPgrR2WhSzvxu4vrI5EuSGJyMRDZj0RZuFmmIEE+v0 sHohbBjnxDIcOml1R2GjNDEspPAxYXlMpMvKVnBbwNOFMEd8l24keJAr+7FLy3NSz4CIOC yyhJ1W5bleRzE4AxH4iHeat3YeKC4tkfkaXBKABwMSZIera4mQg3j6/jnvjAzb73yCiHcC 9FrIOh9ClhLpnOEh/c+LKXtDLQPFZKF9ZXlgWJ4Hf/UfFZ/SyoatV5+wXRbzX+x7YV0wZW biN470Pq83OkzYwdVOynFVb5h/H1LzWVW5nbAeKXQQQFEtnneXREqtj1oC69pw== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) by mxrelay.nyi.freebsd.org (Postfix) with ESMTP id 4hNyW54LR8z1KrW for ; Mon, 17 Aug 2026 16:11:13 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from git (uid 1279) (envelope-from git@FreeBSD.org) id 2652c by gitrepo.freebsd.org (DragonFly Mail Agent v0.13+ on gitrepo.freebsd.org); Mon, 17 Aug 2026 16:11:08 +0000 To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Alexander Ziaee Subject: git: d383c870f7fe - main - mdoc: Standardize SYNOPISIS section for drivers 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 List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list 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: d383c870f7fe20b67278184df54953a49189fca3 Auto-Submitted: auto-generated Date: Mon, 17 Aug 2026 16:11:08 +0000 Message-Id: <6a83329c.2652c.7967d297@gitrepo.freebsd.org> The branch main has been updated by ziaee: URL: https://cgit.FreeBSD.org/src/commit/?id=d383c870f7fe20b67278184df54953a49189fca3 commit d383c870f7fe20b67278184df54953a49189fca3 Author: Alexander Ziaee AuthorDate: 2026-08-17 16:07:54 +0000 Commit: Alexander Ziaee CommitDate: 2026-08-17 16:07:58 +0000 mdoc: Standardize SYNOPISIS section for drivers Standardize driver manuals on the style used for 12 years in vt(4). This brings SYNOPSIS across all FreeBSD manual sections into harmony of meaning where where SYNOPSIS lists available options, and does not contain prose. Adjust mdoc(7) to reflect the established convention. Reviewed by: jhb Discussed with: arch@ (marc.info/?l=freebsd-arch&m=176782215606871) Differential Revision: https://reviews.freebsd.org/D54586 --- contrib/mandoc/mdoc.7 | 9 ++++++++- share/examples/mdoc/example.4 | 46 +++++++++++++++++++++++++------------------ 2 files changed, 35 insertions(+), 20 deletions(-) diff --git a/contrib/mandoc/mdoc.7 b/contrib/mandoc/mdoc.7 index 7346cf25da65..8510764a21fc 100644 --- a/contrib/mandoc/mdoc.7 +++ b/contrib/mandoc/mdoc.7 @@ -1189,11 +1189,18 @@ and .It Ic \&Cd Ar line Kernel configuration declaration. This denotes strings accepted by -.Xr config 8 . +.Xr config 8 +or, on +.Fx , +device hints, +loader tunables, +and sysctl nodes in +.Em SYNOPSIS. It is most often used in section 4 manual pages. .Pp Examples: .Dl \&.Cd device le0 at scode? +.Dl \&.Cd kern.vty=vt .Pp .Em Remarks : this macro is commonly abused by using quoted literals to retain diff --git a/share/examples/mdoc/example.4 b/share/examples/mdoc/example.4 index 534444b05abf..c81632982c6c 100644 --- a/share/examples/mdoc/example.4 +++ b/share/examples/mdoc/example.4 @@ -5,27 +5,33 @@ .\" .\" Note: The date here should be updated whenever a non-trivial .\" change is made to the manual page. -.Dd July 31, 2015 -.Dt EXAMPLE 4 i386 +.Dd June 19, 2026 +.Dt EXAMPLE 4 amd64 .Os .Sh NAME .Nm example .Nd example device driver manual page .Sh SYNOPSIS -To compile the driver into the kernel, -place the following lines in the -kernel configuration file: -.Bd -ragged -offset indent -.Cd "device example" -.Cd "options EXAMPLE_DEBUG" -.Ed +.Cd device example +.Cd options EXAMPLE_DEBUG .Pp -Alternatively, to load the driver as a -module at boot time, place the following line in +In +.Xr device.hints 5 : +.Cd here.is.a.example.device.hint Ns Ao Ns = Ns Ar optional_value Ac +.Pp +In +.Xr rc.conf 5 : +.Cd kld_list="kernel_module_name" +.Pp +In .Xr loader.conf 5 : -.Bd -literal -offset indent -example_load="YES" -.Ed +.Cd here.is.a.example.tunable Ns Ao Ns = Ns Ar optional_value Ac +.Pp +In +.Xr loader.conf 5 +or +.Xr sysctl.conf 5 : +.Cd here.is.a.example.sysctl Ns Ao Ns = Ns Ar optional_value Ac .Sh DEPRECATION NOTICE This driver is scheduled for removal prior to the release of .Fx 17.0 . @@ -36,6 +42,10 @@ driver. It is intended that this example can be used as a template when writing a new manual page. .Pp +If the kernel is compiled with the +.Dv EXAMPLE_DEBUG +option, then additional debugging messages will be displayed. +.Pp The .Nm driver supports the following ioctls: @@ -45,10 +55,6 @@ Example ioctl. .It Dv EIOCNULL Example ioctl. .El -.Pp -If the kernel is compiled with the -.Dv EXAMPLE_DEBUG -option, then additional debugging messages will be displayed. .Sh HARDWARE The .Nm @@ -100,6 +106,8 @@ manual page example first appeared in .At v6 . .Sh AUTHORS This manual page was written by -.An Mike Pritchard Aq Mt mpp@FreeBSD.org . +.An Mike Pritchard Aq Mt mpp@FreeBSD.org +and +.An Alexander Ziaee Aq Mt ziaee@FreeBSD.org . .Sh BUGS The actual code for this device driver is vaporware.