git: d383c870f7fe - main - mdoc: Standardize SYNOPISIS section for drivers

The branch main has been updated by ziaee:

URL: https://cgit.FreeBSD.org/src/commit/?id=d383c870f7fe20b67278184df54953a49189fca3

commit d383c870f7fe20b67278184df54953a49189fca3
Author:     Alexander Ziaee <[email protected]>
AuthorDate: 2026-08-17 16:07:54 +0000
Commit:     Alexander Ziaee <[email protected]>
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 [email protected] .
+.An Mike Pritchard Aq Mt [email protected]
+and
+.An Alexander Ziaee Aq Mt [email protected] .
 .Sh BUGS
 The actual code for this device driver is vaporware.