Re: [mdoc] .Os: What should the argument be?

[G. Branden Robinson]

Hi Alex,

...butting in here...

At 2022-09-06T19:08:37+0200, Alejandro Colomar wrote:
> The current man page for NGINX Unit uses an empty .Os call, probably
> because who wrote it didn't know what better to write there, and since
> it works with it empty, why not.
> 
> The current mdoc(7) documentation says this should be the operating
> system and release, but of course, portable programs don't have a
> "operating system", but rather multiple.  So if this is to be used for
> the OS version, it should be empty, and let the OS fill that with the
> default, but that would be useless, the same as Doug pointed out of
> the 5th arg to TH.  Then, the only useful thing that this can be used
> for is the project and release, as Branden told me recently for the
> 4th arg to TH; that does make sense.
> 
> Could we change the documentation to note that?

This was discussed back around December 2020,
leading to the following commit.

commit 8e09f1b914f75db13d099cb0fec2b8b8ae97a632
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Dec 5 15:48:38 2020 +1100

    groff_mdoc(7): Tweak mandatory macro explanations.

    Update descriptions and template of .Dd, .Dt, .Os usage to reflect
    recent changes and recommended conventions.

    * .Dd now accepts arbitrary arguments describing the date (see
      8545b5a6cc845a67547a393c6053c3b4ffc0d4ac, 18 January 2020).
    * In the example template, stop using full capitals for .Dt and .Os
      parameters; they are not used in the rest of the template.  Stop
      implying that the date should be in traditional U.S. format.  Broaden
      description of .Os parameters to accommodate package identifiers as
      arguments.
    * Resequence descriptions of mandatory mdoc(7) macro calls to follow
      their order of presentation.  This has the benefit of pushing the post
      complicated phrase (describing .Os) to the end of the sentence.

    * Use @MDATE@ in this page's own .Dd call for parallelism with other
      groff man pages.
    * Use "groff @VERSION@" as the arguments to this page's own .Os call for
      paralellism with other groff man pages.
    * Stop misleadingly using \*[doc-operating-system] string (which
      defaults to "BSD" but does not work well if package arguments are
      given to .Os) to introduce the list of predefined man section titles.
      Simply say "in this implementation" instead.
    * Recast description of .Os macro to accommodate packaged man pages,
      based on suggested wording from Ingo Schwarze.
    * Present \*[doc-default-operating-system] as the default operating
      system, not \*[doc-operating-system].
    * Recast sentence to characterize historical practice; vanilla BSD and
      ATT are no longer current systems.
    * Say "similarly to" instead of "similar to", as it is an adverbial
      phrase.

    Thanks to Ingo Schwarze, Colin Watson, and Alan D. Salewski for the
    discussion, and Florent Rougon and Robert Bihlmeyer (many years ago) for
    the original report.

    Fixes <https://bugs.debian.org/284002>.

Regards,
Branden

signature.asc
Description: PGP signature