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