1.\" 2.\" Copyright (c) 2018-2025 Mateusz Piotrowski <0mp@FreeBSD.org> 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd October 24, 2025 7.Dt STYLE.MDOC 5 8.Os 9.Sh NAME 10.Nm style.mdoc 11.Nd FreeBSD manual page style guide 12.Sh DESCRIPTION 13This file specifies the preferred style for manual pages in the 14.Fx 15source tree. 16.Ss Code Examples 17.Bl -dash -width "" 18.It 19Use literal formatting for examples and literal shell commands, e.g.: 20.Bd -literal -offset indent 21Then run 22\&.Ql make install clean . 23.Ed 24.Pp 25which renders as: 26.Bd -filled -offset indent 27Then run 28.Ql make install clean . 29.Ed 30.Pp 31The incorrect way would be to use macros like 32.Sy \&Nm 33to stylize the command invocation: 34.Bd -literal -offset indent 35Then run 36\&.Ql Nm make Cm install Cm clean . 37.Ed 38.Pp 39which renders as: 40.Bd -filled -offset indent 41Then run 42.Ql Nm make Cm install Cm clean . 43.Ed 44.It 45The 46.Sy \&Ql 47macro is the preferred macro for formatting literal inline fragments. 48Historically, 49.Sy \&Dq \&Li 50was the preferred way before the deprecation of 51.Sy \&Li . 52.El 53.Ss Copyright Header 54Refer to 55.Xr style 9 . 56.Ss HARDWARE Section 57Driver manuals in section four should have a 58.Sx HARDWARE 59section describing hardware known to work with the driver. 60This section is drawn verbatim into the Release Hardware Notes, 61therefore there are several things to note: 62.Bl -dash -width "" 63.It 64The introductory sentence should be in the form: 65.Bd -literal -offset indent 66The 67\&.Nm 68driver supports the following $device_class: 69.Ed 70.Pp 71Followed by the list of supported hardware. 72.Pp 73This defines what driver the subsection is referring to, 74and allows the reader to search through the Hardware Notes 75not only for the device models they have, 76but also for the device type they are looking to acquire. 77.It 78The supported hardware should be listed as a bullet list, 79or if complexity requires, a column list. 80These two list types create very neat subsections 81with clean starting and stopping points. 82.El 83.Ss EXAMPLES Section 84.Bl -dash -width "" 85.It 86Format the 87.Sx EXAMPLES 88section in the following way: 89.Bd -literal -offset indent 90\&.Bl -tag -width 0n 91\&.It Sy Example 1\\&: Doing Something 92\&.Pp 93The following command does something. 94\&.Bd -literal -offset 2n 95\&.Ic # make -VLEGAL 96\&.Ed 97\&.It Sy Example 2\\&: Doing Something Different 98\&.Pp 99The following command does something different. 100\&.Bd -literal -offset 2n 101\&.Ic # bectl list 102\&.Ed 103\&.Pp 104It is good to know this command. 105\&.El 106.Ed 107.Pp 108which renders as: 109.Bl -tag -width 0n 110.It Sy Example 1\&: Doing Something 111.Pp 112The following command does something. 113.Bd -literal -offset 2n 114.Ic # make -VLEGAL 115.Ed 116.It Sy Example 2\&: Doing Something Different 117.Pp 118The following command does something different. 119.Bd -literal -offset 2n 120.Ic # bectl list 121.Ed 122.Pp 123It is good to know this command. 124.El 125.El 126.Ss Lists 127.Bl -dash -width "" 128.It 129The 130.Fl width 131argument to the 132.Sy \&.Bl 133macro should match the length of the longest rendered item in the list, 134e.g.: 135.Bd -literal -offset indent 136\&.Bl -tag -width "-a address" 137\&.It Fl a Ar address 138Set the address. 139\&.It Fl v 140Print the version. 141\&.El 142.Ed 143.Pp 144In case the longest item is too long and hurts readability, 145the recommendation is to set 146the 147.Fl width 148argument 149to 150.Ql indent , 151e.g.: 152.Bd -literal -offset indent 153\&.Bl -tag -width "indent" 154\&.It Cm build 155Build the port. 156\&.It Cm install 157Install the port. 158\&.It Fl install-missing-packages 159Install the missing packages. 160\&.El 161.Ed 162.El 163.Ss Synopsis Formatting 164.Bl -dash -width "" 165.It 166Do not put whitespace between alternative parameters separated with a pipe 167.Pq Dq | , 168e.g.: 169.Bd -literal -offset indent 170\&.Cm compression Cm on Ns | Ns Cm off 171\&.Cm install Fl -all Ns | Ns Ar portname Ar ... 172.Ed 173.Pp 174which in the SYNOPSIS section is rendered as: 175.Bd -unfilled -offset indent 176.Cm compression Cm on Ns | Ns Cm off 177.Cm install Fl -all Ns | Ns Ar portname Ar ... 178.Ed 179.It 180Use 181.Sy \&Cm 182to stylize characters that are command modifiers 183.Po e.g., 184.Dq \&, , 185.Dq @ 186or 187.Dq "=" 188.Pc . 189For example: 190.Bd -literal -offset indent 191\&.Sm off 192\&.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where 193\&.Sm on 194.Ed 195.Pp 196which renders as: 197.Bd -filled -offset indent 198.Sm off 199.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where 200.Sm on 201.Ed 202.Pp 203instead of: 204.Bd -literal -offset indent 205\&.Sm off 206\&.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where 207\&.Sm on 208.Ed 209.Pp 210which would render as: 211.Bd -filled -offset indent 212.Sm off 213.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where 214.Sm on 215.Ed 216.Pp 217It is important to realize that in the correct example, 218.Dq \&, , 219.Dq @ 220and 221.Dq = 222are stylized with 223.Sy \&Cm . 224At the same time, the square brackets 225.Pq Dq "[]" 226are not stylized as they do not belong to the syntax of the 227.Fl -meet 228flag. 229.El 230.Ss Quoting 231.Bl -dash -width "" 232.It 233Use the 234.Sy \&Dq 235.Pq Do Dc 236macro 237for quoting. 238Use the 239.Sy \&Sq 240.Pq So Sc 241macro for quoting inside quotes. 242The use of the 243.Sy \&Qq 244.Pq Qo Qc 245macro is usually not necessary. 246.El 247.Ss Variables 248.Bl -dash -width "" 249.It 250Use 251.Sy \&Va 252instead of 253.Sy \&Dv 254for 255.Xr sysctl 8 256variables like 257.Va kdb.enter.panic . 258.It 259Use the angle brackets 260.Sy \&Aq 261.Pq Dq "<>" 262macro 263for arguments 264.Pq Sy \&Ar 265when they are mixed with similarly stylized macros like 266.Sy \&Pa 267or 268.Sy \&Va , 269e.g.: 270.Bd -literal -offset indent 271\&.Va critical_filesystems_ Ns Aq Ar type 272.Ed 273.Pp 274which renders as: 275.Bd -filled -offset indent 276.Va critical_filesystems_ Ns Aq Ar type 277.Ed 278.Pp 279instead of: 280.Bd -literal -offset indent 281\&.Va critical_filesystems_ Ns Ar type 282.Ed 283.Pp 284that would be rendered as: 285.Bd -filled -offset indent 286.Va critical_filesystems_ Ns Ar type 287.Ed 288.El 289.Sh SEE ALSO 290.Xr man 1 , 291.Xr mandoc 1 , 292.Xr mdoc 7 , 293.Xr roff 7 , 294.Xr style 9 295.Sh HISTORY 296This manual page first appeared in 297.Fx 13.0 . 298.Sh AUTHORS 299.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org 300