===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.287
retrieving revision 1.291
diff -u -p -r1.287 -r1.291
--- mandoc/mdoc.7	2021/07/29 17:32:01	1.287
+++ mandoc/mdoc.7	2024/05/20 18:44:34	1.291
@@ -1,4 +1,4 @@
-.\"	$Id: mdoc.7,v 1.287 2021/07/29 17:32:01 schwarze Exp $
+.\" $Id: mdoc.7,v 1.291 2024/05/20 18:44:34 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: July 29 2021 $
+.Dd $Mdocdate: May 20 2024 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -439,7 +439,7 @@ in the alphabetical
 .Bl -column "Brq, Bro, Brc" description
 .It Ic \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year
 .It Ic \&Dt Ta document title: Ar TITLE section Op Ar arch
-.It Ic \&Os Ta operating system version: Op Ar system Op Ar version
+.It Ic \&Os Ta operating system footer: Op Ar footer text
 .It Ic \&Nm Ta document name (one argument)
 .It Ic \&Nd Ta document description (one line)
 .El
@@ -1015,7 +1015,7 @@ A numbered list.
 No item heads can be specified.
 Formatted like
 .Fl bullet ,
-except that cardinal numbers are used in place of bullets,
+except that ordinal numbers are used in place of bullets,
 starting at 1.
 .It Fl hang
 Like
@@ -1614,7 +1614,7 @@ Examples:
 .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
+For GNU-style 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.
@@ -2074,31 +2074,28 @@ Examples:
 See also
 .Ic \&Oo .
 .Tg Os
-.It Ic \&Os Op Ar system Op Ar version
-Operating system version for display in the page footer.
-This is the mandatory third macro of
-any
+.It Ic \&Os Op Ar footer text
+The mandatory third macro of every
 .Nm
 file.
+Usually, do not specify any arguments,
+in particular not the operating system name and/or version.
 .Pp
-The optional
-.Ar system
-parameter specifies the relevant operating system or environment.
-It is suggested to leave it unspecified, in which case
+If no argument is given,
 .Xr mandoc 1
-uses its
+prints its
 .Fl Ios
-argument or, if that isn't specified either,
+argument in the page footer, or
 .Fa sysname
 and
 .Fa release
 as returned by
-.Xr uname 3 .
+.Xr uname 3
+by default.
 .Pp
-Examples:
-.Dl \&.Os
-.Dl \&.Os KTH/CSC/TCS
-.Dl \&.Os BSD 4.3
+Manual pages that are part of a portable software project can override
+the default by giving the project name and version number as arguments,
+but leaving it blank is never a bad choice.
 .Pp
 See also
 .Ic \&Dd
@@ -2486,10 +2483,7 @@ Based on POSIX.1 and POSIX.2, published in 1992.
 .br
 This standard was published in 1994.
 It was used as the basis for UNIX 95 certification.
-The following three refer to parts of it.
-.Pp
-.It \-xsh4.2
-.St -xsh4.2
+The following two refer to parts of it.
 .Pp
 .It \-xcurses4.2
 .St -xcurses4.2