[groff] 13/13: groff_mdoc(7): Tweak mandatory macro explanations.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 8e09f1b914f75db13d099cb0fec2b8b8ae97a632
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: 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>.
---
 ChangeLog             | 13 +++++++++++
 tmac/groff_mdoc.7.man | 61 ++++++++++++++++++++++++++++++++++-----------------
 2 files changed, 54 insertions(+), 20 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 0e03a30..d95c06c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2020-12-05  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       * tmac/groff_mdoc.7.man: Tweak mandatory macro explanations.
+
+       Update descriptions and template of .Dd, .Dt, .Os usage to
+       reflect recent changes and recommended conventions.
+
+       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>.
+
 2020-12-01  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * src/utils/xtotroff/xtotroff.c (MapFont): Avoid writing past
diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index 0b8202e..e383fe3 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -47,9 +47,9 @@
 .\" extremely slow package.
 .\"
 .
-.Dd November 2, 2010
+.Dd @MDATE@
 .Dt groff_mdoc 7
-.Os
+.Os groff @VERSION@
 .
 .
 .Sh Name
@@ -566,9 +566,9 @@ The body of a man page is easily constructed from a basic 
template:
 .
 .Bd -literal -offset indent
 \&.\e" The following commands are required for all man pages.
-\&.Dd Month day, year
-\&.Dt DOCUMENT_TITLE [section number] [architecture/volume]
-\&.Os [OPERATING_SYSTEM] [version/release]
+\&.Dd date
+\&.Dt document-title [section number] [architecture/volume]
+\&.Os [package or operating system] [version/release]
 \&.Sh Name
 \&.Nm name
 \&.Nd one line description of name
@@ -610,12 +610,15 @@ The first items in the template are the commands
 .Ql .Dt ,
 and
 .Ql .Os ;
-the document date, the operating system the man page or subject source is
-developed or modified for, and the man page title (in
-.Em upper case )
-along with the section of the manual the page belongs in.
+the document date,
+the document title and section of the manual the page belongs in,
+and either the project or package supplying the page or the operating
+system it is developed or modified for.
+.
 These commands identify the page and are discussed below in
 .Sx Title macros .
+.
+.
 .Pp
 The remaining items in the template are section headers
 .Pf ( Li .Sh ) ;
@@ -731,8 +734,7 @@ If it is specified, and no volume name is given, a default 
volume name is
 used.
 .
 .Pp
-Under
-.Tn \*[doc-operating-system] ,
+In this implementation,
 the following sections are defined:
 .Pp
 .TS
@@ -840,29 +842,48 @@ look for strings named
 then denotes the keyword to be used with the
 .Ql .Dt
 macro.
+.
+.
 .Pp
 This macro is neither callable nor parsed.
 .
+.
 .It Li .Os Xo
-.Op Aq operating system
-.Op Aq release
+.Op Aq operating system or package name
+.Op Aq version or release
 .Xc
+This is the mandatory third macro of every
+.Xr mdoc 7
+document.
+.
+In man pages supplied by the base installation of an operating system,
+do not provide an argument.
+.
+A portable software package maintaining its own man pages can supply
+its name and version number or release identifier as optional arguments.
+.
 If the first parameter is empty,
 the default
-.Sq Tn "\*[doc-operating-system]"
+.Sq Tn "\*[doc-default-operating-system]"
 is used.
-This may be overridden in the local configuration file,
+.
+This default may be overridden in the local configuration file,
 .Pa mdoc.local .
-In general, the name of the operating system should be the common acronym,
-e.g.\&
+.
+Historically,
+the name of the operating system was one of the common initialisms
 .Tn BSD
 or
 .Tn ATT .
+.
 The release should be the standard release nomenclature for the system
 specified.
-In the following table, the possible second arguments for some predefined
-operating systems are listed.
-Similar to
+.
+In the following table,
+possible second arguments for some predefined operating systems are
+listed.
+.
+Similarly to
 .Ql .Dt ,
 local additions might be defined in
 .Pa mdoc.local ;