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 April 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 item in the list, e.g.: 128.Bd -literal -offset indent 129\&.Bl -tag -width "-a address" 130\&.It Fl a Ar address 131Set the address. 132\&.It Fl v 133Print the version. 134\&.El 135.Ed 136.Pp 137In case the longest item is too long and hurts readability, 138the recommendation is to set 139the 140.Fl width 141argument 142to 143.Ql indent , 144e.g.: 145.Bd -literal -offset indent 146\&.Bl -tag -width "indent" 147\&.It Cm build 148Build the port. 149\&.It Cm install 150Install the port. 151\&.It Fl install-missing-packages 152Install the missing packages. 153\&.El 154.Ed 155.El 156.Ss Synopsis Formatting 157.Bl -dash -width "" 158.It 159Do not put whitespace between alternative parameters separated with a pipe 160.Pq Dq | , 161e.g.: 162.Bd -literal -offset indent 163\&.Cm compression Cm on Ns | Ns Cm off 164\&.Cm install Fl -all Ns | Ns Ar portname Ar ... 165.Ed 166.Pp 167which in the SYNOPSIS section is rendered as: 168.Bd -unfilled -offset indent 169.Cm compression Cm on Ns | Ns Cm off 170.Cm install Fl -all Ns | Ns Ar portname Ar ... 171.Ed 172.It 173Use 174.Sy \&Cm 175to stylize characters that are command modifiers 176.Po e.g., 177.Dq \&, , 178.Dq @ 179or 180.Dq "=" 181.Pc . 182For example: 183.Bd -literal -offset indent 184\&.Sm off 185\&.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where 186\&.Sm on 187.Ed 188.Pp 189which renders as: 190.Bd -filled -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 196instead of: 197.Bd -literal -offset indent 198\&.Sm off 199\&.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where 200\&.Sm on 201.Ed 202.Pp 203which would render as: 204.Bd -filled -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 210It is important to realize that in the correct example, 211.Dq \&, , 212.Dq @ 213and 214.Dq = 215are stylized with 216.Sy \&Cm . 217At the same time, the square brackets 218.Pq Dq "[]" 219are not stylized as they do not belong to the syntax of the 220.Fl -meet 221flag. 222.El 223.Ss Quoting 224.Bl -dash -width "" 225.It 226Use the 227.Sy \&Dq 228.Pq Do Dc 229macro 230for quoting. 231Use the 232.Sy \&Sq 233.Pq So Sc 234macro for quoting inside quotes. 235The use of the 236.Sy \&Qq 237.Pq Qo Qc 238macro is usually not necessary. 239.El 240.Ss Variables 241.Bl -dash -width "" 242.It 243Use 244.Sy \&Va 245instead of 246.Sy \&Dv 247for 248.Xr sysctl 8 249variables like 250.Va kdb.enter.panic . 251.It 252Use the angle brackets 253.Sy \&Aq 254.Pq Dq "<>" 255macro 256for arguments 257.Pq Sy \&Ar 258when they are mixed with similarly stylized macros like 259.Sy \&Pa 260or 261.Sy \&Va , 262e.g.: 263.Bd -literal -offset indent 264\&.Va critical_filesystems_ Ns Aq Ar type 265.Ed 266.Pp 267which renders as: 268.Bd -filled -offset indent 269.Va critical_filesystems_ Ns Aq Ar type 270.Ed 271.Pp 272instead of: 273.Bd -literal -offset indent 274\&.Va critical_filesystems_ Ns Ar type 275.Ed 276.Pp 277that would be rendered as: 278.Bd -filled -offset indent 279.Va critical_filesystems_ Ns Ar type 280.Ed 281.El 282.Sh SEE ALSO 283.Xr man 1 , 284.Xr mandoc 1 , 285.Xr mdoc 7 , 286.Xr roff 7 , 287.Xr style 9 288.Sh HISTORY 289This manual page first appeared in 290.Fx 13.0 . 291.Sh AUTHORS 292.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org 293