2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
4 .\" Copyright (c) 2018-2022 Mateusz Piotrowski <0mp@FreeBSD.org>
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
39 This file specifies the preferred style for manual pages in the
45 Use literal formatting for examples and literal shell commands, e.g.:
46 .Bd -literal -offset indent
48 \&.Ql make install clean .
52 .Bd -filled -offset indent
54 .Ql make install clean .
57 The incorrect way would be to use macros like
59 to stylize the command invocation:
60 .Bd -literal -offset indent
62 \&.Ql Nm make Cm install Cm clean .
66 .Bd -filled -offset indent
68 .Ql Nm make Cm install Cm clean .
73 macro is the preferred macro for formatting literal inline fragments.
76 was the preferred way before the deprecation of
84 section in the following way:
85 .Bd -literal -offset indent
87 \&.It Sy Example 1\\&: No Doing Something
89 The following command does something.
90 \&.Bd -literal -offset 2n
91 \&.Li # Ic make -VLEGAL
93 \&.It Sy Example 2\\&: No Doing Something Different
95 The following command does something different.
96 \&.Bd -literal -offset 2n
100 It is good to know this command.
105 .Bd -filled -offset indent
107 .It Sy Example 1\&: No Doing Something
109 The following command does something.
110 .Bd -literal -offset 2n
111 .Li # Ic make -VLEGAL
113 .It Sy Example 2\&: No Doing Something Different
115 The following command does something different.
116 .Bd -literal -offset 2n
120 It is good to know this command.
131 macro 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
141 In case the longest item is too long and hurts readability,
142 the recommendation is to set
149 .Bd -literal -offset indent
150 \&.Bl -tag -width "indent"
155 \&.It Fl install-missing-packages
156 Install the missing packages.
160 .Ss Synopsis Formatting
163 Do not put whitespace between alternative parameters separated with a pipe
166 .Bd -literal -offset indent
167 \&.Cm compression Cm on Ns | Ns Cm off
168 \&.Cm install Fl -all Ns | Ns Ar portname Ar ...
171 which 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 ...
179 to stylize characters that are command modifiers
187 .Bd -literal -offset indent
189 \&.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where
194 .Bd -filled -offset indent
196 .Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where
201 .Bd -literal -offset indent
203 \&.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where
207 which would render as:
208 .Bd -filled -offset indent
210 .Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where
214 It is important to realize that in the correct example,
221 At the same time, the square brackets
223 are not stylized as they do not belong to the syntax of the
238 macro for quoting inside quotes.
242 macro is usually not necessary.
254 .Va kdb.enter.panic .
256 Use the angle brackets
262 when they are mixed with similarly stylized macros like
267 .Bd -literal -offset indent
268 \&.Va critical_filesystems_ Ns Aq Ar type
272 .Bd -filled -offset indent
273 .Va critical_filesystems_ Ns Aq Ar type
277 .Bd -literal -offset indent
278 \&.Va critical_filesystems_ Ns Ar type
281 that would be rendered as:
282 .Bd -filled -offset indent
283 .Va critical_filesystems_ Ns Ar type
292 This manual page first appeared in
295 .An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org