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