upstream/opnsense-src
1
0
Fork 0
mirror of https://github.com/opnsense/src.git synced 2026-06-11 09:41:03 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

style.mdoc: HARDWARE generates Release Notes

Browse source 
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 29eb4de61a)
This commit is contained in:
Alexander Ziaee 2024-10-06 18:44:15 -04:00
parent 8d75a78b4d
commit b0d6aa07c1
No known key found for this signature in database
GPG key ID: 0A8F850BCDEF4511
1 changed files with 29 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

31
share/man/man5/style.mdoc.5
View file

@ -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