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

[G. Branden Robinson]

At 2020-11-22T16:08:56+0100, Ingo Schwarze wrote:
[worthy backgrounder snipped]

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

Yes, I found this particularly startling.

>   2. The concept of encoding names and versions of all operating
>      systems is not sustainable in the long run.

This was probably a product of its times; there was BSD, only one BSD,
and then there was System V, and the importance of that conflict caused
people to adopt a kind of tunnel vision.

>   3. Cynthia was already unhappy with the chosen default behaviour
>      as early as 1991/08/05.

Does Cynthia ever pop up to reflect on mdoc's design?

[more snippage]

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

This looks sound to me, content-wise.

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

Agreed.

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

Good point.

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

Yes, I'm amenable to this.

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

Cool.  I prefer the form we're using for the groff man(7) pages:
        groff 1.22.4
but really this is a matter of the originating project's discretion.

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

Yes, I think the idea here to _encourage_ portable project developers to
start using .Os to say something, instead of as a stump.

> 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

    Configuration file '/etc/bash.bashrc'
     ==> Modified (by you or by a script) since installation.
     ==> Package distributor has shipped an updated version.
       What would you like to do about it?  Your options are:
        Y or I  : install the package maintainer's version
        N or O  : keep your currently-installed version
          D     : show the differences between the versions
          Z     : start a shell to examine the situation
     The default action is to keep your current version.
    *** bash.bashrc (Y/I/N/O/D/Z) [default=N]?

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

Colin, what do you think?

Regards,
Branden

signature.asc
Description: PGP signature