===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.280
retrieving revision 1.286
diff -u -p -r1.280 -r1.286
--- mandoc/mdoc.7	2020/01/19 18:02:00	1.280
+++ mandoc/mdoc.7	2021/07/29 16:25:20	1.286
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.280 2020/01/19 18:02:00 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: January 19 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.
@@ -1203,7 +1203,8 @@ Close a
 block.
 Does not have any tail arguments.
 .It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year
-Document date for display in the page footer.
+Document date for display in the page footer,
+by convention the date of the last change.
 This is the mandatory first macro of any
 .Nm
 manual.
@@ -1567,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 ...
@@ -1848,8 +1855,8 @@ instead.
 Format a hyperlink.
 .Pp
 Examples:
-.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
-.Dl \&.Lk http://bsd.lv
+.Dl \&.Lk https://bsd.lv \(dqThe BSD.lv Project\(dq
+.Dl \&.Lk https://bsd.lv
 .Pp
 See also
 .Ic \&Mt .
@@ -2725,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
@@ -3084,17 +3091,6 @@ The following problematic behaviour is found in groff:
 .Pp
 .Bl -dash -compact
 .It
-.Ic \&Dd
-with non-standard arguments behaves very strangely.
-When there are three arguments, they are printed verbatim.
-Any other number of arguments is replaced by the current date,
-but without any arguments the string
-.Dq Epoch
-is printed.
-.It
-.Ic \&Lk
-only accepts a single link-name argument; the remainder is misformatted.
-.It
 .Ic \&Pa
 does not format its arguments when used in the FILES section under
 certain list types.
@@ -3102,9 +3098,6 @@ certain list types.
 .Ic \&Ta
 can only be called by other macros, but not at the beginning of a line.
 .It
-.Ic \&%C
-is not implemented (up to and including groff-1.22.2).
-.It
 .Sq \ef
 .Pq font face
 and
@@ -3154,10 +3147,16 @@ but produces large indentations.
 .Xr tbl 7
 .Pp
 The web page
-.Lk http://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language"
+.Lk https://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language"
 provides a few tutorial-style pages for beginners, an extensive style
 guide for advanced authors, and an alphabetic index helping to choose
 the best macros for various kinds of content.
+.Pp
+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 somewhat different style.
 .Sh HISTORY
 The
 .Nm