Re: [PATCH] mdoc: Update operating system release numbers

[Ingo Schwarze]

Hi Branden,

i have to admit that .Os is among the worst-designed parts of the mdoc(7)
language.  First, it was't designed consistently to start with.  The first
major release it was widely used in was 4.4BSD.  Already in that release,
it was documented in the mdoc(7) manual as

  "OPERATING_SYSTEM [version/release]   Operating system (BSD)"

which is not particularly clear and also overly specific, explicitly
refering to one specific system, "BSD".  Besides, the very idea of
an "operating system" macro obviously caters to the specific notion
of a "base system" that is central to BSD systems and applies much
less to other operating systems like GNU/Linux which tend to be
composed of individual packages.  The longer mdoc.samples(7) manual
page added further confusion rather than clarification, saying:

  .Os operating_system release#
    The name of the operating system should be the common acronym,
    e.g. BSD or ATT.  The release should be the standard release
    nomenclature for the system specified, e.g. 4.3, 4.3+Tahoe, V.3,
    V.4.  Unrecognized arguments are displayed as given in the page
    footer.  For instance, a typical footer might be:

      .Os BSD 4.3

    or for a locally produced set

      .Os CS Department

    The Berkeley default, ".Os" without an argument, has been defined
    as BSD Experimental in the site specific file
    /usr/src/share/tmac/doc-common.  It really should default to LOCAL.

There are many obvious problems in the design:

  1. The syntax is not really consistent: both coded references
     like "BSD" "4.4" and free text strings are supported.
  2. The concept of encoding names and versions of all operating
     systems is not sustainable in the long run.
  3. Cynthia was already unhappy with the chosen default behaviour
     as early as 1991/08/05.

All that said, even in this first release where the macro was widely
used, it was already becoming obsolete for the intended purpose:

   $ grep -Rh '^\.Os' /co/BSD/4.4/ | sort | uniq -c | sort -nr
  362 .Os
  207 .Os BSD 4
  187 .Os BSD 4.2
   65 .Os BSD 4.3
   36 .Os BSD 4.4
   22 .Os BSD 3
  [...]

So, most manual pages already used .Os without arguments even at that
time and only smaller numbers referred to older releases, with the
numbers of pages refering to old releases further decreasing over time.

Nowadays, all BSD systems almost exclusively use .Os without an argument:

   $ grep -Rh '^\.Os' /co/FreeBSD/git/doc/ | sort | uniq -c | sort -nr
  1403 .Os
    80 .Os FreeBSD
    14 .Os BSD 4
  [...]

   $ grep -Rh '^\.Os' /co/NetBSD/ | sort | uniq -c | sort -nr
  4040 .Os
    22 .Os BSD 4
     8 .Os SunOS 5.10
  [...]

   $ grep -Rh '^\.Os' /usr/src | sort | uniq -c | sort -nr  # OenBSD
  4555 .Os
     4 .Os OpenBSD
     2 .Os NetBSD
  [...]

Consequently, i would suggest to say something like the following:

  .Os [operating system or software package name and version]

    This is the mandatory third macro of every mdoc(7) document.
    In manual pages that are part of the base system of an operating
    system, do not provide an argument.
    In manual pages that are part of a portable software package,
    the name of the software package can optionally be provided
    as an argument, optionally followed by a version number.

I would leave the decision about the default behaviour to the
formatter and to the operating system the formatter is running on.
For example, mandoc(1) uses uname(3) by default.  But using a
fixed string provided by the operating system or just leaving
the field in the page footer blank seem fine as alternatives.

To summarize, i agree with almost all you propose.
Minor nits below.

> How about we officially relax the semantics of ".Os" in mdoc(7) from
> "operating system" to, say, "original source"?

I tend to dislike backronyms, in particular when they are not very
descriptive or even misleading.  It doesn't matter at all in this
case whether the source is "original" or not.  For example, if
somebody forks a software project, applies some improvements to the
code and to the manual page and published the fork, then the argument
of the .Os macro (if any) should be updated or removed, *not* left
to point to the "original source".

So i think documenting it as "operating system or software package"
or something like that is better than saying "original source".

> Meaning whatever the author/maintainer of the mdoc(7) document
> uses as a version control identifier.

Yes.  And i would consider all forms

  .Os
  .Os groff
  .Os GNU troff
  .Os groff-1.23.0
  .Os GNU troff 1.23.0

valid, treating all information as optional, provided at the
discretion of the author.

> This would increase parallelism with man(7)'s fourth .TH
> argument, and give projects an easy place to hang an identifier
> for the page release.
> 
> Debian #284002 proposes overriding the "BSD" default with a
> distribution-specific string in the mdoc.local file, and that seems a
> resonable thing to do to me _as a fallback_ when there is no .Os in the
> first place,

Sure, that is one among the resonable options that operating systems have.

> and with the current mnemonic and documenttion, a portable
> GitHub project developer, for instance, has little reason to suspect
> they should use this macro.

Well, groff_mdoc(7) is already quite clear that the .Os macro itself
is mandatory, but the developer of some portable project would
probably see little reason to provide an argument.  That's not a
huge problem because providing arguments is optional, but nothing
is wrong to with providing arguments if desired.

> As far as I can tell, this is already designed for with the string
> "doc-default-operating-system".
> 
> So my proposal is twofold:
> 
> 1. Update groff_mdoc(7) as described above, to encourage mdoc(7) page
>    authors to use this to record a package/project name and release.
> 2. Encourage Colin to add the following to mdoc.local:
> 
>       .ds doc-default-operating-system Debian 11 (bullseye)\"
> 
>    or similar.
> 
> Thoughts?

Sure.  I dislike the concept of mdoc.local for more than one reason,
but probably it is good enough for this purposes if there is no
better way in Debian.  If mdoc.local gets automatically updated
during system updates, the proposed string also seems fine.  If it
is considered a user config file and does *not* get updated
automatically, then something like just "Debian GNU/Linux" might
be even better.

Yours,
  Ingo

-- 
Ingo Schwarze             <schwarze@usta.de>
http://www.openbsd.org/   <schwarze@openbsd.org>
http://mandoc.bsd.lv/     <schwarze@mandoc.bsd.lv>