Re: Bug#284002: [PATCH] mdoc: Update operating system release numbers

[Ingo Schwarze]

Hi Colin and Branden,

Colin Watson wrote on Sun, Nov 22, 2020 at 06:18:48PM +0000:
> On Mon, Nov 23, 2020 at 03:02:49AM +1100, G. Branden Robinson wrote:
>> At 2020-11-22T16:08:56+0100, Ingo Schwarze wrote:

>>> 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.

>> Hahaha. This is Debian...it's _both_ automatically updated during system
>> updates _and_ considered a user config file!
>> 
>>      https://www.debian.org/doc/debian-policy/ap-pkg-conffiles.html
>> 
>> "conffiles" have been a dpkg feature for something like 25 years now.
>> Every Debian sysadmin is familiar with the dpkg conffile prompt.  :D

Oh, that concept exists in OpenBSD, too, though not for quite as long.

> [...]
>> I suspect most people don't touch mdoc.local, so it will be
>> automatically updated for them.

In that case, i would still recommend using a string that is constant
over time or putting it somewhere else if that is possible with little
inconvenience.

Yes, automatically updating unchanged user configuration files
works very reliably, and even automatically merging changed user
configuration files often works.  But that doesn't mean that it
should be relied on when there is little benefit, and showing the
operating system version in manual page footers is little benefit
indeed.  I doubt that is worth risking merging inconveniences for
some users.

>> Colin, what do you think?
> 
> Putting this in mdoc.local would more or less work, but if I had to do
> this then I'd lean slightly towards just patching mdoc itself to say the
> right thing for the operating system.

FWIW, that's what i'm doing in the OpenBSD port.

FreeBSD appears to have

  .ds doc-volume-operating-system FreeBSD

in mdoc.local, see

  https://svnweb.freebsd.org/ports/head/textproc/groff/files/mdoc.local

which is *not* a user configuration file in FreeBSD but a constant,
system-owned file.

NetBSD still appears to use the default

  .ds doc-volume-operating-system BSD

in

  
http://cvsweb.netbsd.org/bsdweb.cgi/src/external/gpl2/groff/dist/tmac/doc-common

but it appears NetBSD still uses groff-1.19.2, so that isn't a
particularly useful data point i guess.  In pkgsrc, they have
groff-1.22.4 and they seem to set

  .ds volume-operating-system @@VOLUME_OPERATING_SYSTEM@@

though i'm unsure whether and how that actually works.

It seems Colin has a point that this way is encouraging inconsistency.

> However, if that were the recommendation for distributors then it would
> seem likely to result in a lack of consistency.  Maybe it's worth having
> a little bit of explicit support in upstream groff for what distributors
> are supposed to do?  I'd suggest that groff's configure could gain a
> --with-os-name option whose argument becomes the default value of .Os;
> it can carry on defaulting to "BSD", or the output of uname(3), or
> whatever else as you see fit.  That would (gently) encourage
> distributors to set this in a systematic way.

FWIW, that is essentially what (portable) mandoc does.
It supports a variable OSNAME in ./configure.local .

A few operating systems use that:

  OSNAME="Void Linux"
  OSNAME="Debian"

Examples:
https://github.com/void-linux/void-packages/blob/master/srcpkgs/mdocml/template
https://salsa.debian.org/debian/mdocml/-/blob/master/debian/patches/configure.local.patch

More operating systems do not bother and simply rely on the default
mechanism of using uname(3), which is just fine, too:

Examples:
https://git.alpinelinux.org/aports/tree/main/mandoc/APKBUILD
https://src.fedoraproject.org/rpms/mandoc/blob/master/f/mandoc.spec
https://gitweb.gentoo.org/repo/gentoo.git/tree/app-text/mandoc/mandoc-1.14.5.ebuild
https://aur.archlinux.org/cgit/aur.git/tree/configure.local?h=mandoc
https://github.com/Homebrew/homebrew-core/blob/master/Formula/mandoc.rb
https://github.com/macports/macports-ports/blob/master/textproc/mandoc/Portfile

Yours,
  Ingo