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