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

[G. Branden Robinson]

At 2019-12-21T14:51:23+0100, Ingo Schwarze wrote:
> Colin Watson wrote on Tue, Dec 17, 2019 at 01:15:30PM +0000:
> > On Tue, Dec 17, 2019 at 01:14:06PM +0000, Colin Watson wrote:
> > Side note: I am not the biggest fan of this business of encoding a
> > bunch of other projects' release history in groff, so please don't
> > take me as an advocate of that.  However, I am generally an advocate
> > of the position that if one is going to encode this sort of thing
> > then it makes sense to keep it up to date.
> 
> I completely agree with all you are saying here.
[...]
> I do think that removing version verification and just printing
> whatever the manual page author requests in the same way as mandoc(1)
> is already doing it would be an improvement, but that should be
> discussed separately, not in this ticket.

There's another Debian bug report that impinges on this question.

https://bugs.debian.org/284002

How about we officially relax the semantics of ".Os" in mdoc(7) from
"operating system" to, say, "original source"?  Meaning whatever the
author/maintainer of the mdoc(7) document uses as a version control
identifier.  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, and with the current mnemonic and documenttion, a portable
GitHub project developer, for instance, has little reason to suspect
they should use this macro.

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?

Regards,
Branden

signature.asc
Description: PGP signature