1.\" 2.\" Copyright (c) 2018-2025 Mateusz Piotrowski <0mp@FreeBSD.org> 3.\" 4.\" SPDX-License-Identifier: BSD-2-Clause 5.\" 6.Dd February 16, 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.Pp 45This pollutes the 46.Xr whatis 1 47database, causing 48.Ql whatis clean 49to incorrectly show the page it was written in. 50.El 51.Ss Copyright Header 52Refer to 53.Xr style 9 . 54.Ss HARDWARE Section 55Driver manuals in section four should have a 56.Sx HARDWARE 57section describing hardware known to work with the driver. 58This section is drawn verbatim into the Release Hardware Notes, 59therefore there are several things to note: 60.Bl -dash -width "" 61.It 62The introductory sentence should be in the form: 63.Bd -literal -offset indent 64The 65\&.Nm 66driver supports the following $device_class: 67.Ed 68.Pp 69Followed by the list of supported hardware. 70.Pp 71This defines what driver the subsection is referring to, 72and allows the reader to search through the Hardware Notes 73not only for the device models they have, 74but also for the device type they are looking to acquire. 75.It 76The supported hardware should be listed as a bullet list, 77or if complexity requires, a column list. 78These two list types create very neat subsections 79with clean starting and stopping points. 80.El 81.Ss EXAMPLES Section 82.Bl -dash -width "" 83.It 84Format the 85.Sx EXAMPLES 86section in the following way: 87.Bd -literal -offset indent 88\&.Bl -tag -width 0n 89\&.It Sy Example 1\\&: Doing Something 90\&.Pp 91The following command does something. 92\&.Bd -literal -offset 2n 93\&.Ic # make -VLEGAL 94\&.Ed 95\&.It Sy Example 2\\&: Doing Something Different 96\&.Pp 97The following command does something different. 98\&.Bd -literal -offset 2n 99\&.Ic # bectl list 100\&.Ed 101\&.Pp 102It is good to know this command. 103\&.El 104.Ed 105.Pp 106which renders as: 107.Bl -tag -width 0n 108.It Sy Example 1\&: Doing Something 109.Pp 110The following command does something. 111.Bd -literal -offset 2n 112.Ic # make -VLEGAL 113.Ed 114.It Sy Example 2\&: Doing Something Different 115.Pp 116The following command does something different. 117.Bd -literal -offset 2n 118.Ic # bectl list 119.Ed 120.Pp 121It is good to know this command. 122.El 123.El 124.Ss Lists 125.Bl -dash -width "" 126.It 127The 128.Fl width 129argument to the 130.Sy \&.Bl 131macro should match the length of the longest rendered item in the list, 132e.g.: 133.Bd -literal -offset indent 134\&.Bl -tag -width "-a address" 135\&.It Fl a Ar address 136Set the address. 137\&.It Fl v 138Print the version. 139\&.El 140.Ed 141.Pp 142In case the longest item is too long and hurts readability, 143the recommendation is to set 144the 145.Fl width 146argument 147to 148.Ql indent , 149e.g.: 150.Bd -literal -offset indent 151\&.Bl -tag -width "indent" 152\&.It Cm build 153Build the port. 154\&.It Cm install 155Install the port. 156\&.It Fl install-missing-packages 157Install the missing packages. 158\&.El 159.Ed 160.El 161.Ss Quoting 162.Bl -dash -width "" 163.It 164Use the 165.Sy \&Dq 166.Pq Do Dc 167macro 168for quoting. 169Use the 170.Sy \&Sq 171.Pq So Sc 172macro for quoting inside quotes. 173The use of the 174.Sy \&Qq 175.Pq Qo Qc 176macro is usually not necessary. 177.El 178.Ss Variables 179.Bl -dash -width "" 180.It 181Use 182.Sy \&Va 183instead of 184.Sy \&Dv 185for 186.Xr sysctl 8 187variables like 188.Va kdb.enter.panic . 189.It 190Use the angle brackets 191.Sy \&Aq 192.Pq Dq Ao Ac 193macro 194for arguments 195.Pq Sy \&Ar 196when they are mixed with similarly stylized macros like 197.Sy \&Pa 198or 199.Sy \&Va , 200e.g.: 201.Bd -literal -offset indent 202\&.Va critical_filesystems_ Ns Aq Ar type 203.Ed 204.Pp 205which renders as: 206.Bd -filled -offset indent 207.Va critical_filesystems_ Ns Aq Ar type 208.Ed 209.Pp 210instead of: 211.Bd -literal -offset indent 212\&.Va critical_filesystems_ Ns Ar type 213.Ed 214.Pp 215that would be rendered as: 216.Bd -filled -offset indent 217.Va critical_filesystems_ Ns Ar type 218.Ed 219.El 220.Sh FILES 221.Bl -tag -width "/usr/share/examples/mdoc/tab" 222.It /usr/share/examples/mdoc/ 223Examples for writing manual pages. 224.El 225.Sh SEE ALSO 226.Xr man 1 , 227.Xr mandoc 1 , 228.Xr mdoc 7 , 229.Xr roff 7 , 230.Xr style 9 231.Sh HISTORY 232This manual page first appeared in 233.Fx 13.0 . 234.Sh AUTHORS 235.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org 236