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