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