xref: /freebsd/share/man/man5/style.mdoc.5 (revision 6d33315d2f7bd38c923f7a1db277348fad767a42)
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