From 4eeb9252522d3e10a7e7069cc24ef0d78dec68f3 Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 20 May 2024 18:12:23 +0000 Subject: [PATCH] Rewrite the description of the .Os macro to match reality. While BSD releases from the CSRG did indeed put "BSD" and an operating system version number on .Os macro lines, that practice was discontinued in OpenBSD 25 years ago because it causes maintenance effort without providing any benefit. Other operating systems tend to agree that .Os is usually best left blank. For example, FreeBSD weeded out .Os arguments about two years after OpenBSD. --- share/man/man7/mdoc.7 | 33 +++++++++++++++------------------ 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/share/man/man7/mdoc.7 b/share/man/man7/mdoc.7 index 2ca9cc50fc2..b4b2b961aeb 100644 --- a/share/man/man7/mdoc.7 +++ b/share/man/man7/mdoc.7 @@ -1,4 +1,4 @@ -.\" $OpenBSD: mdoc.7,v 1.181 2022/01/13 08:39:24 schwarze Exp $ +.\" $OpenBSD: mdoc.7,v 1.182 2024/05/20 18:12:23 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze @@ -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 13 2022 $ +.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 @@ -2087,31 +2087,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 -- 2.20.1