]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - share/man/man5/style.mdoc.5
tarfs.5: Document the importance of zstd framing
[FreeBSD/FreeBSD.git] / share / man / man5 / style.mdoc.5
1 .\"
2 .\" SPDX-License-Identifier: BSD-2-Clause
3 .\"
4 .\" Copyright (c) 2018-2022 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 .Dd January 29, 2022
28 .Dt STYLE.MDOC 5
29 .Os
30 .Sh NAME
31 .Nm style.mdoc
32 .Nd
33 .Fx
34 .Xr mdoc 7
35 file style guide
36 .Sh DESCRIPTION
37 This file specifies the preferred style for manual pages in the
38 .Fx
39 source tree.
40 .Ss Code Examples
41 .Bl -dash -width ""
42 .It
43 Use literal formatting for examples and literal shell commands, e.g.:
44 .Bd -literal -offset indent
45 Then run
46 \&.Ql make install clean .
47 .Ed
48 .Pp
49 which renders as:
50 .Bd -filled -offset indent
51 Then run
52 .Ql make install clean .
53 .Ed
54 .Pp
55 The incorrect way would be to use macros like
56 .Sy \&Nm
57 to stylize the command invocation:
58 .Bd -literal -offset indent
59 Then run
60 \&.Ql Nm make Cm install Cm clean .
61 .Ed
62 .Pp
63 which renders as:
64 .Bd -filled -offset indent
65 Then run
66 .Ql Nm make Cm install Cm clean .
67 .Ed
68 .It
69 The
70 .Sy \&Ql
71 macro is the preferred macro for formatting literal inline fragments.
72 Historically,
73 .Sy \&Dq \&Li
74 was the preferred way before the deprecation of
75 .Sy \&Li .
76 .El
77 .Ss EXAMPLES Section
78 .Bl -dash -width ""
79 .It
80 Format the
81 .Sx EXAMPLES
82 section in the following way:
83 .Bd -literal -offset indent
84 \&.Bl -tag -width 0n
85 \&.It Sy Example 1\\&: No Doing Something
86 \&.Pp
87 The following command does something.
88 \&.Bd -literal -offset 2n
89 \&.Li # Ic make -VLEGAL
90 \&.Ed
91 \&.It Sy Example 2\\&: No Doing Something Different
92 \&.Pp
93 The following command does something different.
94 \&.Bd -literal -offset 2n
95 \&.Li # Ic bectl list
96 \&.Ed
97 \&.Pp
98 It is good to know this command.
99 \&.El
100 .Ed
101 .Pp
102 which renders as:
103 .Bd -filled -offset indent
104 .Bl -tag -width 0n
105 .It Sy Example 1\&: No Doing Something
106 .Pp
107 The following command does something.
108 .Bd -literal -offset 2n
109 .Li # Ic make -VLEGAL
110 .Ed
111 .It Sy Example 2\&: No Doing Something Different
112 .Pp
113 The following command does something different.
114 .Bd -literal -offset 2n
115 .Li # Ic bectl list
116 .Ed
117 .Pp
118 It is good to know this command.
119 .El
120 .Ed
121 .El
122 .Ss Lists
123 .Bl -dash -width ""
124 .It
125 The
126 .Fl width
127 argument to the
128 .Sy \&.Bl
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
133 Set the address.
134 \&.It Fl v
135 Print the version.
136 \&.El
137 .Ed
138 .Pp
139 In case the longest item is too long and hurts readability,
140 the recommendation is to set
141 the
142 .Fl width
143 argument
144 to
145 .Ql indent ,
146 e.g.:
147 .Bd -literal -offset indent
148 \&.Bl -tag -width "indent"
149 \&.It Cm build
150 Build the port.
151 \&.It Cm install
152 Install the port.
153 \&.It Fl install-missing-packages
154 Install the missing packages.
155 \&.El
156 .Ed
157 .El
158 .Ss Synopsis Formatting
159 .Bl -dash -width ""
160 .It
161 Do not put whitespace between alternative parameters separated with a pipe
162 .Pq Dq | ,
163 e.g.:
164 .Bd -literal -offset indent
165 \&.Cm compression Cm on Ns | Ns Cm off
166 \&.Cm install Fl -all Ns | Ns Ar portname Ar ...
167 .Ed
168 .Pp
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 ...
173 .Ed
174 .It
175 Use
176 .Sy \&Cm
177 to stylize characters that are command modifiers
178 .Po e.g.,
179 .Dq \&, ,
180 .Dq @
181 or
182 .Dq "="
183 .Pc .
184 For example:
185 .Bd -literal -offset indent
186 \&.Sm off
187 \&.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where
188 \&.Sm on
189 .Ed
190 .Pp
191 which renders as:
192 .Bd -filled -offset indent
193 .Sm off
194 .Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where
195 .Sm on
196 .Ed
197 .Pp
198 instead of:
199 .Bd -literal -offset indent
200 \&.Sm off
201 \&.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where
202 \&.Sm on
203 .Ed
204 .Pp
205 which would render as:
206 .Bd -filled -offset indent
207 .Sm off
208 .Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where
209 .Sm on
210 .Ed
211 .Pp
212 It is important to realize that in the correct example,
213 .Dq \&, ,
214 .Dq @
215 and
216 .Dq =
217 are stylized with
218 .Sy \&Cm .
219 At the same time, the square brackets
220 .Pq Dq "[]"
221 are not stylized as they do not belong to the syntax of the
222 .Fl -meet
223 flag.
224 .El
225 .Ss Quoting
226 .Bl -dash -width ""
227 .It
228 Use the
229 .Sy \&Dq
230 .Pq Do Dc
231 macro
232 for quoting.
233 Use the
234 .Sy \&Sq
235 .Pq So Sc
236 macro for quoting inside quotes.
237 The use of the
238 .Sy \&Qq
239 .Pq Qo Qc
240 macro is usually not necessary.
241 .El
242 .Ss Variables
243 .Bl -dash -width ""
244 .It
245 Use
246 .Sy \&Va
247 instead of
248 .Sy \&Dv
249 for
250 .Xr sysctl 8
251 variables like
252 .Va kdb.enter.panic .
253 .It
254 Use the angle brackets
255 .Sy \&Aq
256 .Pq Dq "<>"
257 macro
258 for arguments
259 .Pq Sy \&Ar
260 when they are mixed with similarly stylized macros like
261 .Sy \&Pa
262 or
263 .Sy \&Va ,
264 e.g.:
265 .Bd -literal -offset indent
266 \&.Va critical_filesystems_ Ns Aq Ar type
267 .Ed
268 .Pp
269 which renders as:
270 .Bd -filled -offset indent
271 .Va critical_filesystems_ Ns Aq Ar type
272 .Ed
273 .Pp
274 instead of:
275 .Bd -literal -offset indent
276 \&.Va critical_filesystems_ Ns Ar type
277 .Ed
278 .Pp
279 that would be rendered as:
280 .Bd -filled -offset indent
281 .Va critical_filesystems_ Ns Ar type
282 .Ed
283 .El
284 .Sh SEE ALSO
285 .Xr man 1 ,
286 .Xr mandoc 1 ,
287 .Xr mdoc 7 ,
288 .Xr style 9
289 .Sh HISTORY
290 This manual page first appeared in
291 .Fx 13.0 .
292 .Sh AUTHORS
293 .An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org