===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.282
retrieving revision 1.286
diff -u -p -r1.282 -r1.286
--- mandoc/mdoc.7	2020/06/25 20:45:09	1.282
+++ mandoc/mdoc.7	2021/07/29 16:25:20	1.286
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.282 2020/06/25 20:45:09 schwarze Exp $
+.\"	$Id: mdoc.7,v 1.286 2021/07/29 16:25:20 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: June 25 2020 $
+.Dd $Mdocdate: July 29 2021 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -297,7 +297,7 @@ utility does this, that, and the other.
 It usually follows with a breakdown of the options (if documenting a
 command), such as:
 .Bd -literal -offset indent
-The arguments are as follows:
+The options are as follows:
 \&.Bl \-tag \-width Ds
 \&.It Fl v
 Print verbose information.
@@ -1568,20 +1568,26 @@ and
 .It Ic \&Fl Op Ar word ...
 Command-line flag or option.
 Used when listing arguments to command-line utilities.
-Prints a fixed-width hyphen
-.Sq \-
-directly followed by each argument.
-If no arguments are provided, a hyphen is printed followed by a space.
-If the argument is a macro, a hyphen is prefixed to the subsequent macro
-output.
+For each argument, prints an ASCII hyphen-minus character
+.Sq \- ,
+immediately followed by the argument.
+If no arguments are provided, a hyphen-minus is printed followed by a space.
+If the argument is a macro, a hyphen-minus is prefixed
+to the subsequent macro output.
 .Pp
 Examples:
-.Dl ".Fl R Op Fl H | L | P"
-.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
-.Dl ".Fl type Cm d Fl name Pa CVS"
-.Dl ".Fl Ar signal_number"
-.Dl ".Fl o Fl"
+.Dl ".Nm du Op Fl H | L | P"
+.Dl ".Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
+.Dl ".Nm route Cm add Fl inet Ar destination gateway"
+.Dl ".Nm locate.updatedb Op Fl \e-fcodes Ns = Ns Ar dbfile"
+.Dl ".Nm aucat Fl o Fl"
+.Dl ".Nm kill Fl Ar signal_number"
 .Pp
+For GNU-sytle long options, escaping the additional hyphen-minus is not
+strictly required, but may be safer with future versions of GNU troff; see
+.Xr mandoc_char 7
+for details.
+.Pp
 See also
 .Ic \&Cm .
 .It Ic \&Fn Ar funcname Op Ar argument ...
@@ -2726,7 +2732,7 @@ column, if applicable, describes closure rules.
 .Ss Block full-explicit
 Multi-line scope closed by an explicit closing macro.
 All macros contains bodies; only
-.Ic \s&Bf
+.Ic \&Bf
 and
 .Pq optionally
 .Ic \&Bl
@@ -3150,7 +3156,7 @@ The manual page
 .Lk https://man.voidlinux.org/groff_mdoc "groff_mdoc(7)"
 contained in the
 .Dq groff
-package documents exactly the same language in a somehwat different style.
+package documents exactly the same language in a somewhat different style.
 .Sh HISTORY
 The
 .Nm