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