share/man/man5/style.mdoc.5

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