1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 3.\" 4.\" Copyright (c) 2018-2021 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.\" $FreeBSD$ 28.\" 29.Dd December 3, 2021 30.Dt STYLE.MDOC 5 31.Os 32.Sh NAME 33.Nm style.mdoc 34.Nd 35.Fx 36.Xr mdoc 7 37file style guide 38.Sh DESCRIPTION 39This file specifies the preferred style for manual pages in the 40.Fx 41source tree. 42.Ss Code Examples 43.Bl -dash -width "" 44.It 45Use literal formatting for examples and literal shell commands, e.g.: 46.Bd -literal -offset indent 47Then run 48\&.Ql make install clean . 49.Ed 50.Pp 51which renders as: 52.Bd -filled -offset indent 53Then run 54.Ql make install clean . 55.Ed 56.Pp 57The incorrect way would be to use macros like 58.Sy \&Nm 59to stylize the command invocation: 60.Bd -literal -offset indent 61Then run 62\&.Ql Nm make Cm install Cm clean . 63.Ed 64.Pp 65which renders as: 66.Bd -filled -offset indent 67Then run 68.Ql Nm make Cm install Cm clean . 69.Ed 70.It 71The 72.Sy \&Ql 73macro is the preferred macro for formatting literal inline fragments. 74Historically, 75.Sy \&Dq \&Li 76was the preferred way before the deprecation of 77.Sy \&Li . 78.El 79.Ss EXAMPLES Section 80.Bl -dash -width "" 81.It 82Format the 83.Sx EXAMPLES 84section in the following way: 85.Bd -literal -offset indent 86\&.Bl -tag -width 0n 87\&.It Sy Example 1\\&: No Doing Something 88\&.Pp 89The following command does something. 90\&.Bd -literal -offset 2n 91\&.Li # Ic make -VLEGAL 92\&.Ed 93\&.It Sy Example 2\\&: No Doing Something Different 94\&.Pp 95The following command does something different. 96\&.Bd -literal -offset 2n 97\&.Li # Ic bectl list 98\&.Ed 99\&.Pp 100It is good to know this command. 101\&.El 102.Ed 103.Pp 104which renders as: 105.Bd -filled -offset indent 106.Bl -tag -width 0n 107.It Sy Example 1\&: No Doing Something 108.Pp 109The following command does something. 110.Bd -literal -offset 2n 111.Li # Ic make -VLEGAL 112.Ed 113.It Sy Example 2\&: No Doing Something Different 114.Pp 115The following command does something different. 116.Bd -literal -offset 2n 117.Li # Ic bectl list 118.Ed 119.Pp 120It is good to know this command. 121.El 122.Ed 123.El 124.Ss Synopsis Formatting 125.Bl -dash -width "" 126.It 127Do not put whitespace between alternative parameters separated with a pipe 128.Pq Dq | , 129e.g.: 130.Bd -literal -offset indent 131\&.Cm compression Cm on Ns | Ns Cm off 132\&.Cm install Fl -all Ns | Ns Ar portname Ar ... 133.Ed 134.Pp 135which in the SYNOPSIS section is rendered as: 136.Bd -unfilled -offset indent 137.Cm compression Cm on Ns | Ns Cm off 138.Cm install Fl -all Ns | Ns Ar portname Ar ... 139.Ed 140.It 141Use 142.Sy \&Cm 143to stylize characters that are command modifiers 144.Po e.g., 145.Dq \&, , 146.Dq @ 147or 148.Dq "=" 149.Pc . 150For example: 151.Bd -literal -offset indent 152\&.Sm off 153\&.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where 154\&.Sm on 155.Ed 156.Pp 157which renders as: 158.Bd -filled -offset indent 159.Sm off 160.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where 161.Sm on 162.Ed 163.Pp 164instead of: 165.Bd -literal -offset indent 166\&.Sm off 167\&.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where 168\&.Sm on 169.Ed 170.Pp 171which would render as: 172.Bd -filled -offset indent 173.Sm off 174.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where 175.Sm on 176.Ed 177.Pp 178It is important to realize that in the correct example, 179.Dq \&, , 180.Dq @ 181and 182.Dq = 183are stylized with 184.Sy \&Cm . 185At the same time, the square brackets 186.Pq Dq "[]" 187are not stylized as they do not belong to the syntax of the 188.Fl -meet 189flag. 190.El 191.Ss Quoting 192.Bl -dash -width "" 193.It 194Use the 195.Sy \&Dq 196.Pq Do Dc 197macro 198for quoting. 199Use the 200.Sy \&Sq 201.Pq So Sc 202macro for quoting inside quotes. 203The use of the 204.Sy \&Qq 205.Pq Qo Qc 206macro is usually not necessary. 207.El 208.Ss Variables 209.Bl -dash -width "" 210.It 211Use 212.Sy \&Va 213instead of 214.Sy \&Dv 215for 216.Xr sysctl 8 217variables like 218.Va kdb.enter.panic . 219.It 220Use the angle brackets 221.Sy \&Aq 222.Pq Dq "<>" 223macro 224for arguments 225.Pq Sy \&Ar 226when they are mixed with similarly stylized macros like 227.Sy \&Pa 228or 229.Sy \&Va , 230e.g.: 231.Bd -literal -offset indent 232\&.Va critical_filesystems_ Ns Aq Ar type 233.Ed 234.Pp 235which renders as: 236.Bd -filled -offset indent 237.Va critical_filesystems_ Ns Aq Ar type 238.Ed 239.Pp 240instead of: 241.Bd -literal -offset indent 242\&.Va critical_filesystems_ Ns Ar type 243.Ed 244.Pp 245that would be rendered as: 246.Bd -filled -offset indent 247.Va critical_filesystems_ Ns Ar type 248.Ed 249.El 250.Sh SEE ALSO 251.Xr man 1 , 252.Xr mandoc 1 , 253.Xr mdoc 7 , 254.Xr style 9 255.Sh HISTORY 256This manual page first appeared in 257.Fx 13.0 . 258.Sh AUTHORS 259.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org 260