[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: G. Branden Robinson
Subject: Re: [PATCH] mdoc: Update operating system release numbers
Date: Mon, 23 Nov 2020 03:02:49 +1100
User-agent: NeoMutt/20180716

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.


> > 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's _both_ automatically updated during system
updates _and_ considered a user config file!

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


Attachment: signature.asc
Description: PGP signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]