share/man/man5/style.mdoc.5

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3 .\"
   4 .\" Copyright (c) 2018-2019 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 March 10, 2019
  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 \&.Dq Li make install clean .
  49 .Ed
  50 .Pp
  51 which renders as:
  52 .Bd -filled -offset indent
  53 Then run
  54 .Dq Li 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 \&.Dq Nm make Cm install Cm clean .
  63 .Ed
  64 .Pp
  65 which renders as:
  66 .Bd -filled -offset indent
  67 Then run
  68 .Dq Nm make Cm install Cm clean .
  69 .Ed
  70 .El
  71 .Ss EXAMPLES Section
  72 .Bl -dash -width ""
  73 .It
  74 Format the
  75 .Sx EXAMPLES
  76 section in the following way:
  77 .Bd -literal -offset indent
  78 \&.Bl -tag -width 0n
  79 \&.It Sy Example 1\\&: No Doing Something
  80 \&.Pp
  81 The following command does something.
  82 \&.Bd -literal -offset 2n
  83 \&.Li # Ic make -VLEGAL
  84 \&.Ed
  85 \&.It Sy Example 2\\&: No Doing Something Different
  86 \&.Pp
  87 The following command does something different.
  88 \&.Bd -literal -offset 2n
  89 \&.Li # Ic bectl list
  90 \&.Ed
  91 \&.Pp
  92 It is good to know this command.
  93 \&.El
  94 .Ed
  95 .Pp
  96 which renders as:
  97 .Bd -filled -offset indent
  98 .Bl -tag -width 0n
  99 .It Sy Example 1\&: No Doing Something
 100 .Pp
 101 The following command does something.
 102 .Bd -literal -offset 2n
 103 .Li # Ic make -VLEGAL
 104 .Ed
 105 .It Sy Example 2\&: No Doing Something Different
 106 .Pp
 107 The following command does something different.
 108 .Bd -literal -offset 2n
 109 .Li # Ic bectl list
 110 .Ed
 111 .Pp
 112 It is good to know this command.
 113 .El
 114 .Ed
 115 .El
 116 .Ss Synopsis Formatting
 117 .Bl -dash -width ""
 118 .It
 119 Do not put whitespace between alternative parameters separated with a pipe
 120 .Pq Dq | ,
 121 e.g.:
 122 .Bd -literal -offset indent
 123 \&.Cm compression Cm on Ns | Ns Cm off
 124 \&.Cm install Fl -all Ns | Ns Ar portname Ar ...
 125 .Ed
 126 .Pp
 127 which in the SYNOPSIS section is rendered as:
 128 .Bd -unfilled -offset indent
 129 .Cm compression Cm on Ns | Ns Cm off
 130 .Cm install Fl -all Ns | Ns Ar portname Ar ...
 131 .Ed
 132 .It
 133 Use
 134 .Sy \&Cm
 135 to stylize characters that are command modifiers
 136 .Po e.g.,
 137 .Dq \&, ,
 138 .Dq @
 139 or
 140 .Dq "="
 141 .Pc .
 142 For example:
 143 .Bd -literal -offset indent
 144 \&.Sm off
 145 \&.Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where
 146 \&.Sm on
 147 .Ed
 148 .Pp
 149 which renders as:
 150 .Bd -filled -offset indent
 151 .Sm off
 152 .Fl -meet Cm = Ar who Oo Cm \&, Ar who " " Ar "..." Oc Cm @ Ar where
 153 .Sm on
 154 .Ed
 155 .Pp
 156 instead of:
 157 .Bd -literal -offset indent
 158 \&.Sm off
 159 \&.Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where
 160 \&.Sm on
 161 .Ed
 162 .Pp
 163 which would render as:
 164 .Bd -filled -offset indent
 165 .Sm off
 166 .Fl -meet No = Ar who Oo , Ar who " " Ar "..." Oc @ Ar where
 167 .Sm on
 168 .Ed
 169 .Pp
 170 It is important to realize that in the correct example,
 171 .Dq \&, ,
 172 .Dq @
 173 and
 174 .Dq =
 175 are stylized with
 176 .Sy \&Cm .
 177 At the same time, the square brackets
 178 .Pq Dq "[]"
 179 are not stylized as they do not belong to the syntax of the
 180 .Fl -meet
 181 flag.
 182 .El
 183 .Ss Quoting
 184 .Bl -dash -width ""
 185 .It
 186 Use the
 187 .Sy \&Dq
 188 .Pq Do Dc
 189 macro
 190 for quoting.
 191 Use the
 192 .Sy \&Sq
 193 .Pq So Sc
 194 macro for quoting inside quotes.
 195 The use of the
 196 .Sy \&Qq
 197 .Pq Qo Qc
 198 macro is usually not necessary.
 199 .El
 200 .Ss Variables
 201 .Bl -dash -width ""
 202 .It
 203 Use
 204 .Sy \&Va
 205 instead of
 206 .Sy \&Dv
 207 for
 208 .Xr sysctl 8
 209 variables like
 210 .Va kdb.enter.panic .
 211 .It
 212 Use the angle brackets
 213 .Sy \&Aq
 214 .Pq Dq "<>"
 215 macro
 216 for arguments
 217 .Pq Sy \&Ar
 218 when they are mixed with similarly stylized macros like
 219 .Sy \&Pa
 220 or
 221 .Sy \&Va ,
 222 e.g.:
 223 .Bd -literal -offset indent
 224 \&.Va critical_filesystems_ Ns Aq Ar type
 225 .Ed
 226 .Pp
 227 which renders as:
 228 .Bd -filled -offset indent
 229 .Va critical_filesystems_ Ns Aq Ar type
 230 .Ed
 231 .Pp
 232 instead of:
 233 .Bd -literal -offset indent
 234 \&.Va critical_filesystems_ Ns Ar type
 235 .Ed
 236 .Pp
 237 that would be rendered as:
 238 .Bd -filled -offset indent
 239 .Va critical_filesystems_ Ns Ar type
 240 .Ed
 241 .El
 242 .Sh SEE ALSO
 243 .Xr man 1 ,
 244 .Xr mandoc 1 ,
 245 .Xr mdoc 7
 246 .Sh HISTORY
 247 This manual page first appeared in
 248 .Fx 13.0 .
 249 .Sh AUTHORS
 250 .An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org