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