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 12, 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 EXAMPLES Section 78.Bl -dash -width "" 79.It 80Format the 81.Sx EXAMPLES 82section in the following way: 83.Bd -literal -offset indent 84\&.Bl -tag -width 0n 85\&.It Sy Example 1\\&: Doing Something 86\&.Pp 87The following command does something. 88\&.Bd -literal -offset 2n 89\&.Ic # make -VLEGAL 90\&.Ed 91\&.It Sy Example 2\\&: Doing Something Different 92\&.Pp 93The following command does something different. 94\&.Bd -literal -offset 2n 95\&.Ic # bectl list 96\&.Ed 97\&.Pp 98It is good to know this command. 99\&.El 100.Ed 101.Pp 102which renders as: 103.Bl -tag -width 0n 104.It Sy Example 1\&: Doing Something 105.Pp 106The following command does something. 107.Bd -literal -offset 2n 108.Ic # make -VLEGAL 109.Ed 110.It Sy Example 2\&: Doing Something Different 111.Pp 112The following command does something different. 113.Bd -literal -offset 2n 114.Ic # bectl list 115.Ed 116.Pp 117It is good to know this command. 118.El 119.El 120.Ss Lists 121.Bl -dash -width "" 122.It 123The 124.Fl width 125argument to the 126.Sy \&.Bl 127macro should match the length of the longest rendered item in the list, 128e.g.: 129.Bd -literal -offset indent 130\&.Bl -tag -width "-a address" 131\&.It Fl a Ar address 132Set the address. 133\&.It Fl v 134Print the version. 135\&.El 136.Ed 137.Pp 138In case the longest item is too long and hurts readability, 139the recommendation is to set 140the 141.Fl width 142argument 143to 144.Ql indent , 145e.g.: 146.Bd -literal -offset indent 147\&.Bl -tag -width "indent" 148\&.It Cm build 149Build the port. 150\&.It Cm install 151Install the port. 152\&.It Fl install-missing-packages 153Install the missing packages. 154\&.El 155.Ed 156.El 157.Ss Synopsis Formatting 158.Bl -dash -width "" 159.It 160Do not put whitespace between alternative parameters separated with a pipe 161.Pq Dq | , 162e.g.: 163.Bd -literal -offset indent 164\&.Cm compression Cm on Ns | Ns Cm off 165\&.Cm install Fl -all Ns | Ns Ar portname Ar ... 166.Ed 167.Pp 168which in the SYNOPSIS section is rendered as: 169.Bd -unfilled -offset indent 170.Cm compression Cm on Ns | Ns Cm off 171.Cm install Fl -all Ns | Ns Ar portname Ar ... 172.Ed 173.It 174Use 175.Sy \&Cm 176to stylize characters that are command modifiers 177.Po e.g., 178.Dq \&, , 179.Dq @ 180or 181.Dq "=" 182.Pc . 183For example: 184.Bd -literal -offset indent 185\&.Sm off 186\&.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where 187\&.Sm on 188.Ed 189.Pp 190which renders as: 191.Bd -filled -offset indent 192.Sm off 193.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where 194.Sm on 195.Ed 196.Pp 197instead of: 198.Bd -literal -offset indent 199\&.Sm off 200\&.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where 201\&.Sm on 202.Ed 203.Pp 204which would render as: 205.Bd -filled -offset indent 206.Sm off 207.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where 208.Sm on 209.Ed 210.Pp 211It is important to realize that in the correct example, 212.Dq \&, , 213.Dq @ 214and 215.Dq = 216are stylized with 217.Sy \&Cm . 218At the same time, the square brackets 219.Pq Dq "[]" 220are not stylized as they do not belong to the syntax of the 221.Fl -meet 222flag. 223.El 224.Ss Quoting 225.Bl -dash -width "" 226.It 227Use the 228.Sy \&Dq 229.Pq Do Dc 230macro 231for quoting. 232Use the 233.Sy \&Sq 234.Pq So Sc 235macro for quoting inside quotes. 236The use of the 237.Sy \&Qq 238.Pq Qo Qc 239macro is usually not necessary. 240.El 241.Ss Variables 242.Bl -dash -width "" 243.It 244Use 245.Sy \&Va 246instead of 247.Sy \&Dv 248for 249.Xr sysctl 8 250variables like 251.Va kdb.enter.panic . 252.It 253Use the angle brackets 254.Sy \&Aq 255.Pq Dq "<>" 256macro 257for arguments 258.Pq Sy \&Ar 259when they are mixed with similarly stylized macros like 260.Sy \&Pa 261or 262.Sy \&Va , 263e.g.: 264.Bd -literal -offset indent 265\&.Va critical_filesystems_ Ns Aq Ar type 266.Ed 267.Pp 268which renders as: 269.Bd -filled -offset indent 270.Va critical_filesystems_ Ns Aq Ar type 271.Ed 272.Pp 273instead of: 274.Bd -literal -offset indent 275\&.Va critical_filesystems_ Ns Ar type 276.Ed 277.Pp 278that would be rendered as: 279.Bd -filled -offset indent 280.Va critical_filesystems_ Ns Ar type 281.Ed 282.El 283.Sh SEE ALSO 284.Xr man 1 , 285.Xr mandoc 1 , 286.Xr mdoc 7 , 287.Xr roff 7 , 288.Xr style 9 289.Sh HISTORY 290This manual page first appeared in 291.Fx 13.0 . 292.Sh AUTHORS 293.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org 294