source@mandoc.bsd.lv
 help / color / mirror / Atom feed
* mandoc: Rewrite the description of the .Os macro to match reality.
@ 2024-05-20 18:16 schwarze
  0 siblings, 0 replies; only message in thread
From: schwarze @ 2024-05-20 18:16 UTC (permalink / raw)
  To: source

Log Message:
-----------
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.

Modified Files:
--------------
    mandoc:
        mdoc.7

Revision Data
-------------
Index: mdoc.7
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc.7,v
diff -Lmdoc.7 -Lmdoc.7 -u -p -r1.289 -r1.290
--- mdoc.7
+++ mdoc.7
@@ -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
@@ -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
--
 To unsubscribe send an email to source+unsubscribe@mandoc.bsd.lv


^ permalink raw reply	[flat|nested] only message in thread

only message in thread, other threads:[~2024-05-20 18:16 UTC | newest]

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-05-20 18:16 mandoc: Rewrite the description of the .Os macro to match reality schwarze

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).