113bf4d9eSMateusz Piotrowski.\" 213bf4d9eSMateusz Piotrowski.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 313bf4d9eSMateusz Piotrowski.\" 4ca588aedSMateusz Piotrowski.\" Copyright (c) 2018-2019 Mateusz Piotrowski <0mp@FreeBSD.org> 513bf4d9eSMateusz Piotrowski.\" 613bf4d9eSMateusz Piotrowski.\" Redistribution and use in source and binary forms, with or without 713bf4d9eSMateusz Piotrowski.\" modification, are permitted provided that the following conditions 813bf4d9eSMateusz Piotrowski.\" are met: 913bf4d9eSMateusz Piotrowski.\" 1. Redistributions of source code must retain the above copyright 1013bf4d9eSMateusz Piotrowski.\" notice, this list of conditions and the following disclaimer. 1113bf4d9eSMateusz Piotrowski.\" 2. Redistributions in binary form must reproduce the above copyright 1213bf4d9eSMateusz Piotrowski.\" notice, this list of conditions and the following disclaimer in the 1313bf4d9eSMateusz Piotrowski.\" documentation and/or other materials provided with the distribution. 1413bf4d9eSMateusz Piotrowski.\" 1513bf4d9eSMateusz Piotrowski.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 1613bf4d9eSMateusz Piotrowski.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 1713bf4d9eSMateusz Piotrowski.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 1813bf4d9eSMateusz Piotrowski.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 1913bf4d9eSMateusz Piotrowski.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 2013bf4d9eSMateusz Piotrowski.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 2113bf4d9eSMateusz Piotrowski.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 2213bf4d9eSMateusz Piotrowski.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 2313bf4d9eSMateusz Piotrowski.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 2413bf4d9eSMateusz Piotrowski.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 2513bf4d9eSMateusz Piotrowski.\" SUCH DAMAGE. 2613bf4d9eSMateusz Piotrowski.\" 2713bf4d9eSMateusz Piotrowski.\" $FreeBSD$ 2813bf4d9eSMateusz Piotrowski.\" 29*6d33315dSMateusz Piotrowski.Dd June 30, 2020 3013bf4d9eSMateusz Piotrowski.Dt STYLE.MDOC 5 3113bf4d9eSMateusz Piotrowski.Os 3213bf4d9eSMateusz Piotrowski.Sh NAME 3313bf4d9eSMateusz Piotrowski.Nm style.mdoc 3413bf4d9eSMateusz Piotrowski.Nd 3513bf4d9eSMateusz Piotrowski.Fx 3613bf4d9eSMateusz Piotrowski.Xr mdoc 7 3713bf4d9eSMateusz Piotrowskifile style guide 3813bf4d9eSMateusz Piotrowski.Sh DESCRIPTION 3913bf4d9eSMateusz PiotrowskiThis file specifies the preferred style for manual pages in the 4013bf4d9eSMateusz Piotrowski.Fx 4113bf4d9eSMateusz Piotrowskisource tree. 42e84f6455SMateusz Piotrowski.Ss Code Examples 4313bf4d9eSMateusz Piotrowski.Bl -dash -width "" 4413bf4d9eSMateusz Piotrowski.It 4513bf4d9eSMateusz PiotrowskiUse literal formatting for examples and literal shell commands, e.g.: 4613bf4d9eSMateusz Piotrowski.Bd -literal -offset indent 4713bf4d9eSMateusz PiotrowskiThen run 4813bf4d9eSMateusz Piotrowski\&.Dq Li make install clean . 4913bf4d9eSMateusz Piotrowski.Ed 5013bf4d9eSMateusz Piotrowski.Pp 5113bf4d9eSMateusz Piotrowskiwhich renders as: 5213bf4d9eSMateusz Piotrowski.Bd -filled -offset indent 5313bf4d9eSMateusz PiotrowskiThen run 5413bf4d9eSMateusz Piotrowski.Dq Li make install clean . 5513bf4d9eSMateusz Piotrowski.Ed 5613bf4d9eSMateusz Piotrowski.Pp 5713bf4d9eSMateusz PiotrowskiThe incorrect way would be to use macros like 5813bf4d9eSMateusz Piotrowski.Sy \&Nm 5913bf4d9eSMateusz Piotrowskito stylize the command invocation: 6013bf4d9eSMateusz Piotrowski.Bd -literal -offset indent 6113bf4d9eSMateusz PiotrowskiThen run 6213bf4d9eSMateusz Piotrowski\&.Dq Nm make Cm install Cm clean . 6313bf4d9eSMateusz Piotrowski.Ed 6413bf4d9eSMateusz Piotrowski.Pp 6513bf4d9eSMateusz Piotrowskiwhich renders as: 6613bf4d9eSMateusz Piotrowski.Bd -filled -offset indent 6713bf4d9eSMateusz PiotrowskiThen run 6813bf4d9eSMateusz Piotrowski.Dq Nm make Cm install Cm clean . 6913bf4d9eSMateusz Piotrowski.Ed 7013bf4d9eSMateusz Piotrowski.El 71e84f6455SMateusz Piotrowski.Ss EXAMPLES Section 72e84f6455SMateusz Piotrowski.Bl -dash -width "" 73e84f6455SMateusz Piotrowski.It 74e84f6455SMateusz PiotrowskiFormat the 75e84f6455SMateusz Piotrowski.Sx EXAMPLES 76e84f6455SMateusz Piotrowskisection in the following way: 77e84f6455SMateusz Piotrowski.Bd -literal -offset indent 78e84f6455SMateusz Piotrowski\&.Bl -tag -width 0n 79ca588aedSMateusz Piotrowski\&.It Sy Example 1\\&: No Doing Something 80e84f6455SMateusz Piotrowski\&.Pp 81e84f6455SMateusz PiotrowskiThe following command does something. 82e84f6455SMateusz Piotrowski\&.Bd -literal -offset 2n 83e84f6455SMateusz Piotrowski\&.Li # Ic make -VLEGAL 84e84f6455SMateusz Piotrowski\&.Ed 85ca588aedSMateusz Piotrowski\&.It Sy Example 2\\&: No Doing Something Different 86e84f6455SMateusz Piotrowski\&.Pp 87e84f6455SMateusz PiotrowskiThe following command does something different. 88e84f6455SMateusz Piotrowski\&.Bd -literal -offset 2n 89e84f6455SMateusz Piotrowski\&.Li # Ic bectl list 90e84f6455SMateusz Piotrowski\&.Ed 91e84f6455SMateusz Piotrowski\&.Pp 92e84f6455SMateusz PiotrowskiIt is good to know this command. 93e84f6455SMateusz Piotrowski\&.El 94e84f6455SMateusz Piotrowski.Ed 95e84f6455SMateusz Piotrowski.Pp 96e84f6455SMateusz Piotrowskiwhich renders as: 97e84f6455SMateusz Piotrowski.Bd -filled -offset indent 98e84f6455SMateusz Piotrowski.Bl -tag -width 0n 99e84f6455SMateusz Piotrowski.It Sy Example 1\&: No Doing Something 100e84f6455SMateusz Piotrowski.Pp 101e84f6455SMateusz PiotrowskiThe following command does something. 102e84f6455SMateusz Piotrowski.Bd -literal -offset 2n 103e84f6455SMateusz Piotrowski.Li # Ic make -VLEGAL 104e84f6455SMateusz Piotrowski.Ed 105e84f6455SMateusz Piotrowski.It Sy Example 2\&: No Doing Something Different 106e84f6455SMateusz Piotrowski.Pp 107e84f6455SMateusz PiotrowskiThe following command does something different. 108e84f6455SMateusz Piotrowski.Bd -literal -offset 2n 109e84f6455SMateusz Piotrowski.Li # Ic bectl list 110e84f6455SMateusz Piotrowski.Ed 111e84f6455SMateusz Piotrowski.Pp 112e84f6455SMateusz PiotrowskiIt is good to know this command. 113e84f6455SMateusz Piotrowski.El 114e84f6455SMateusz Piotrowski.Ed 115e84f6455SMateusz Piotrowski.El 116e84f6455SMateusz Piotrowski.Ss Synopsis Formatting 11713bf4d9eSMateusz Piotrowski.Bl -dash -width "" 11813bf4d9eSMateusz Piotrowski.It 11913bf4d9eSMateusz PiotrowskiDo not put whitespace between alternative parameters separated with a pipe 12013bf4d9eSMateusz Piotrowski.Pq Dq | , 12113bf4d9eSMateusz Piotrowskie.g.: 12213bf4d9eSMateusz Piotrowski.Bd -literal -offset indent 12313bf4d9eSMateusz Piotrowski\&.Cm compression Cm on Ns | Ns Cm off 12413bf4d9eSMateusz Piotrowski\&.Cm install Fl -all Ns | Ns Ar portname Ar ... 12513bf4d9eSMateusz Piotrowski.Ed 12613bf4d9eSMateusz Piotrowski.Pp 12713bf4d9eSMateusz Piotrowskiwhich in the SYNOPSIS section is rendered as: 12813bf4d9eSMateusz Piotrowski.Bd -unfilled -offset indent 12913bf4d9eSMateusz Piotrowski.Cm compression Cm on Ns | Ns Cm off 13013bf4d9eSMateusz Piotrowski.Cm install Fl -all Ns | Ns Ar portname Ar ... 13113bf4d9eSMateusz Piotrowski.Ed 13213bf4d9eSMateusz Piotrowski.It 13313bf4d9eSMateusz PiotrowskiUse 13413bf4d9eSMateusz Piotrowski.Sy \&Cm 13513bf4d9eSMateusz Piotrowskito stylize characters that are command modifiers 13613bf4d9eSMateusz Piotrowski.Po e.g., 13713bf4d9eSMateusz Piotrowski.Dq \&, , 13813bf4d9eSMateusz Piotrowski.Dq @ 13913bf4d9eSMateusz Piotrowskior 14013bf4d9eSMateusz Piotrowski.Dq "=" 14113bf4d9eSMateusz Piotrowski.Pc . 14213bf4d9eSMateusz PiotrowskiFor example: 14313bf4d9eSMateusz Piotrowski.Bd -literal -offset indent 14413bf4d9eSMateusz Piotrowski\&.Sm off 14513bf4d9eSMateusz Piotrowski\&.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where 14613bf4d9eSMateusz Piotrowski\&.Sm on 14713bf4d9eSMateusz Piotrowski.Ed 14813bf4d9eSMateusz Piotrowski.Pp 14913bf4d9eSMateusz Piotrowskiwhich renders as: 15013bf4d9eSMateusz Piotrowski.Bd -filled -offset indent 15113bf4d9eSMateusz Piotrowski.Sm off 15213bf4d9eSMateusz Piotrowski.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where 15313bf4d9eSMateusz Piotrowski.Sm on 15413bf4d9eSMateusz Piotrowski.Ed 15513bf4d9eSMateusz Piotrowski.Pp 15613bf4d9eSMateusz Piotrowskiinstead of: 15713bf4d9eSMateusz Piotrowski.Bd -literal -offset indent 15813bf4d9eSMateusz Piotrowski\&.Sm off 15913bf4d9eSMateusz Piotrowski\&.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where 16013bf4d9eSMateusz Piotrowski\&.Sm on 16113bf4d9eSMateusz Piotrowski.Ed 16213bf4d9eSMateusz Piotrowski.Pp 16313bf4d9eSMateusz Piotrowskiwhich would render as: 16413bf4d9eSMateusz Piotrowski.Bd -filled -offset indent 16513bf4d9eSMateusz Piotrowski.Sm off 16613bf4d9eSMateusz Piotrowski.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where 16713bf4d9eSMateusz Piotrowski.Sm on 16813bf4d9eSMateusz Piotrowski.Ed 16913bf4d9eSMateusz Piotrowski.Pp 17013bf4d9eSMateusz PiotrowskiIt is important to realize that in the correct example, 17113bf4d9eSMateusz Piotrowski.Dq \&, , 17213bf4d9eSMateusz Piotrowski.Dq @ 17313bf4d9eSMateusz Piotrowskiand 17413bf4d9eSMateusz Piotrowski.Dq = 17513bf4d9eSMateusz Piotrowskiare stylized with 17613bf4d9eSMateusz Piotrowski.Sy \&Cm . 17713bf4d9eSMateusz PiotrowskiAt the same time, the square brackets 17813bf4d9eSMateusz Piotrowski.Pq Dq "[]" 17913bf4d9eSMateusz Piotrowskiare not stylized as they do not belong to the syntax of the 18013bf4d9eSMateusz Piotrowski.Fl -meet 18113bf4d9eSMateusz Piotrowskiflag. 18213bf4d9eSMateusz Piotrowski.El 18313bf4d9eSMateusz Piotrowski.Ss Quoting 18413bf4d9eSMateusz Piotrowski.Bl -dash -width "" 18513bf4d9eSMateusz Piotrowski.It 18613bf4d9eSMateusz PiotrowskiUse the 18713bf4d9eSMateusz Piotrowski.Sy \&Dq 18813bf4d9eSMateusz Piotrowski.Pq Do Dc 18913bf4d9eSMateusz Piotrowskimacro 19013bf4d9eSMateusz Piotrowskifor quoting. 19113bf4d9eSMateusz PiotrowskiUse the 19213bf4d9eSMateusz Piotrowski.Sy \&Sq 19313bf4d9eSMateusz Piotrowski.Pq So Sc 19413bf4d9eSMateusz Piotrowskimacro for quoting inside quotes. 19513bf4d9eSMateusz PiotrowskiThe use of the 19613bf4d9eSMateusz Piotrowski.Sy \&Qq 19713bf4d9eSMateusz Piotrowski.Pq Qo Qc 19813bf4d9eSMateusz Piotrowskimacro is usually not necessary. 19913bf4d9eSMateusz Piotrowski.El 20013bf4d9eSMateusz Piotrowski.Ss Variables 20113bf4d9eSMateusz Piotrowski.Bl -dash -width "" 20213bf4d9eSMateusz Piotrowski.It 20313bf4d9eSMateusz PiotrowskiUse 20413bf4d9eSMateusz Piotrowski.Sy \&Va 2056e33d37fSMateusz Piotrowskiinstead of 20613bf4d9eSMateusz Piotrowski.Sy \&Dv 20713bf4d9eSMateusz Piotrowskifor 20813bf4d9eSMateusz Piotrowski.Xr sysctl 8 20913bf4d9eSMateusz Piotrowskivariables like 21013bf4d9eSMateusz Piotrowski.Va kdb.enter.panic . 21113bf4d9eSMateusz Piotrowski.It 21213bf4d9eSMateusz PiotrowskiUse the angle brackets 21313bf4d9eSMateusz Piotrowski.Sy \&Aq 21413bf4d9eSMateusz Piotrowski.Pq Dq "<>" 21513bf4d9eSMateusz Piotrowskimacro 21613bf4d9eSMateusz Piotrowskifor arguments 21713bf4d9eSMateusz Piotrowski.Pq Sy \&Ar 21813bf4d9eSMateusz Piotrowskiwhen they are mixed with similarly stylized macros like 21913bf4d9eSMateusz Piotrowski.Sy \&Pa 22013bf4d9eSMateusz Piotrowskior 22113bf4d9eSMateusz Piotrowski.Sy \&Va , 22213bf4d9eSMateusz Piotrowskie.g.: 22313bf4d9eSMateusz Piotrowski.Bd -literal -offset indent 22413bf4d9eSMateusz Piotrowski\&.Va critical_filesystems_ Ns Aq Ar type 22513bf4d9eSMateusz Piotrowski.Ed 22613bf4d9eSMateusz Piotrowski.Pp 22713bf4d9eSMateusz Piotrowskiwhich renders as: 22813bf4d9eSMateusz Piotrowski.Bd -filled -offset indent 22913bf4d9eSMateusz Piotrowski.Va critical_filesystems_ Ns Aq Ar type 23013bf4d9eSMateusz Piotrowski.Ed 23113bf4d9eSMateusz Piotrowski.Pp 23213bf4d9eSMateusz Piotrowskiinstead of: 23313bf4d9eSMateusz Piotrowski.Bd -literal -offset indent 23413bf4d9eSMateusz Piotrowski\&.Va critical_filesystems_ Ns Ar type 23513bf4d9eSMateusz Piotrowski.Ed 23613bf4d9eSMateusz Piotrowski.Pp 23713bf4d9eSMateusz Piotrowskithat would be rendered as: 23813bf4d9eSMateusz Piotrowski.Bd -filled -offset indent 23913bf4d9eSMateusz Piotrowski.Va critical_filesystems_ Ns Ar type 24013bf4d9eSMateusz Piotrowski.Ed 24113bf4d9eSMateusz Piotrowski.El 24213bf4d9eSMateusz Piotrowski.Sh SEE ALSO 24313bf4d9eSMateusz Piotrowski.Xr man 1 , 24413bf4d9eSMateusz Piotrowski.Xr mandoc 1 , 245*6d33315dSMateusz Piotrowski.Xr mdoc 7 , 246*6d33315dSMateusz Piotrowski.Xr style 9 24713bf4d9eSMateusz Piotrowski.Sh HISTORY 24813bf4d9eSMateusz PiotrowskiThis manual page first appeared in 24913bf4d9eSMateusz Piotrowski.Fx 13.0 . 25013bf4d9eSMateusz Piotrowski.Sh AUTHORS 25113bf4d9eSMateusz Piotrowski.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org 252