2 .\" SPDX-License-Identifier: BSD-2-Clause
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
37 This file specifies the preferred style for manual pages in the
43 Use literal formatting for examples and literal shell commands, e.g.:
44 .Bd -literal -offset indent
46 \&.Ql make install clean .
50 .Bd -filled -offset indent
52 .Ql make install clean .
55 The incorrect way would be to use macros like
57 to stylize the command invocation:
58 .Bd -literal -offset indent
60 \&.Ql Nm make Cm install Cm clean .
64 .Bd -filled -offset indent
66 .Ql Nm make Cm install Cm clean .
71 macro is the preferred macro for formatting literal inline fragments.
74 was the preferred way before the deprecation of
82 section in the following way:
83 .Bd -literal -offset indent
85 \&.It Sy Example 1\\&: No Doing Something
87 The following command does something.
88 \&.Bd -literal -offset 2n
89 \&.Li # Ic make -VLEGAL
91 \&.It Sy Example 2\\&: No Doing Something Different
93 The following command does something different.
94 \&.Bd -literal -offset 2n
98 It is good to know this command.
103 .Bd -filled -offset indent
105 .It Sy Example 1\&: No Doing Something
107 The following command does something.
108 .Bd -literal -offset 2n
109 .Li # Ic make -VLEGAL
111 .It Sy Example 2\&: No Doing Something Different
113 The following command does something different.
114 .Bd -literal -offset 2n
118 It is good to know this command.
129 macro should match the length of the longest item in the list, e.g.:
130 .Bd -literal -offset indent
131 \&.Bl -tag -width "-a address"
132 \&.It Fl a Ar address
139 In case the longest item is too long and hurts readability,
140 the recommendation is to set
147 .Bd -literal -offset indent
148 \&.Bl -tag -width "indent"
153 \&.It Fl install-missing-packages
154 Install the missing packages.
158 .Ss Synopsis Formatting
161 Do not put whitespace between alternative parameters separated with a pipe
164 .Bd -literal -offset indent
165 \&.Cm compression Cm on Ns | Ns Cm off
166 \&.Cm install Fl -all Ns | Ns Ar portname Ar ...
169 which in the SYNOPSIS section is rendered as:
170 .Bd -unfilled -offset indent
171 .Cm compression Cm on Ns | Ns Cm off
172 .Cm install Fl -all Ns | Ns Ar portname Ar ...
177 to stylize characters that are command modifiers
185 .Bd -literal -offset indent
187 \&.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where
192 .Bd -filled -offset indent
194 .Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where
199 .Bd -literal -offset indent
201 \&.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where
205 which would render as:
206 .Bd -filled -offset indent
208 .Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where
212 It is important to realize that in the correct example,
219 At the same time, the square brackets
221 are not stylized as they do not belong to the syntax of the
236 macro for quoting inside quotes.
240 macro is usually not necessary.
252 .Va kdb.enter.panic .
254 Use the angle brackets
260 when they are mixed with similarly stylized macros like
265 .Bd -literal -offset indent
266 \&.Va critical_filesystems_ Ns Aq Ar type
270 .Bd -filled -offset indent
271 .Va critical_filesystems_ Ns Aq Ar type
275 .Bd -literal -offset indent
276 \&.Va critical_filesystems_ Ns Ar type
279 that would be rendered as:
280 .Bd -filled -offset indent
281 .Va critical_filesystems_ Ns Ar type
290 This manual page first appeared in
293 .An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org