[groff] 01/01: Accept any number of arguments for .Dd in the groff_mdoc(7) macros.

[Ingo Schwarze]

schwarze pushed a commit to branch master
in repository groff.

commit 8545b5a6cc845a67547a393c6053c3b4ffc0d4ac
Author: Ingo Schwarze <address@hidden>
AuthorDate: Sat Jan 18 17:38:49 2020 +0100

    Accept any number of arguments for .Dd in the groff_mdoc(7) macros.
    
    * tmac/doc-common-u:
    The .Dd macro behaved in a weird way:
    Without arguments, it printed the string "Epoch".
    With one, two, four, or more arguments, it ignored all arguments
    and used the current date instead.
    Only for exactly three arguments, it printed the arguments.
    None of this made sense.  Giving the date as "Epoch" is
    absurd, and printing the current date is just misleading:
    why should a document be considered up-to-date when the author
    did not even bother to state the date of the last change?
    Admittedly, the behaviour for 0 and 4 or more arguments
    already appeared 4.3BSD-Reno, and the behaviour for 2 or 3
    arguments in 4.4BSD.  But it was already wrong even in those
    days: several manual pages in 4.4BSD gave .Dd a single, quoted
    argument, e.g. .Dd "June 9, 1993": cap_mkdb(1), id(1), sed(1),
    err(3), getcap(3), sysctl(3), amd(8), disklabel(8), and others.
    Consequently, simply print all the arguments, no matter how
    many there are.
    
    This bug was found by Jonathan Gray <address@hidden>
    while he looked at 4.xBSD manual pages.
    
    Using feedback from cjwatson@ and Ralph Corderoy;
    OK bgarrigues@, and cjwatson@ agrees with the behaviour change.
---
 ChangeLog             | 25 +++++++++++++++++++++++++
 tmac/doc-common-u     | 31 ++-----------------------------
 tmac/groff_mdoc.7.man | 32 +++++++++++++++++---------------
 3 files changed, 44 insertions(+), 44 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 1efc014..ee16c7b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,28 @@
+2020-01-18  Ingo Schwarze  <address@hidden>
+
+       Accept any number of arguments for .Dd in the groff_mdoc(7) macros.
+
+       * tmac/doc-common-u: The .Dd macro behaved in a weird way:
+       Without arguments, it printed the string "Epoch".
+       With one, two, four, or more arguments, it ignored all arguments
+       and used the current date instead.
+       Only for exactly three arguments, it printed the arguments.
+       None of this made sense.  Giving the date as "Epoch" is
+       absurd, and printing the current date is just misleading:
+       why should a document be considered up-to-date when the author
+       did not even bother to state the date of the last change?
+       Admittedly, the behaviour for 0 and 4 or more arguments
+       already appeared 4.3BSD-Reno, and the behaviour for 2 or 3
+       arguments in 4.4BSD.  But it was already wrong even in those
+       days: several manual pages in 4.4BSD gave .Dd a single, quoted
+       argument, e.g. .Dd "June 9, 1993": cap_mkdb(1), id(1), sed(1),
+       err(3), getcap(3), sysctl(3), amd(8), disklabel(8), and others.
+       Consequently, simply print all the arguments, no matter how
+       many there are.
+
+       This bug was found by Jonathan Gray <address@hidden>
+       while he looked at 4.xBSD manual pages.
+
 2020-01-18  G. Branden Robinson <address@hidden>
 
        * doc/groff.texi: Document initial empty set membership of
diff --git a/tmac/doc-common-u b/tmac/doc-common-u
index 648926c..dc20552 100644
--- a/tmac/doc-common-u
+++ b/tmac/doc-common-u
@@ -900,39 +900,12 @@
 .\" NS   doc-date-string
 .\" NS   doc-command-name
 .\" NS
-.\" NS local variables:
-.\" NS   doc-date-XXX
-.\" NS
 .\" NS width register 'Dd' set above
 .
-.ds doc-date-1  January
-.ds doc-date-2  February
-.ds doc-date-3  March
-.ds doc-date-4  April
-.ds doc-date-5  May
-.ds doc-date-6  June
-.ds doc-date-7  July
-.ds doc-date-8  August
-.ds doc-date-9  September
-.ds doc-date-10 October
-.ds doc-date-11 November
-.ds doc-date-12 December
-.
 .de Dd
 .  ds doc-command-name
-.
-.  ie \n[.$] \{\
-.    ie "\$1"$Mdocdate:" \
-.      ds doc-date-string \$2\~\$3, \$4
-.    el \{ .ie (\n[.$] == 3) \
-.      ds doc-date-string \$1\~\$2 \$3
-.    el \{\
-.      ds doc-date-string "\*[doc-date-\n[mo]]
-.      as doc-date-string \~\n[dy], \n[year]
-.    \}\}
-.  \}
-.  el \
-.    ds doc-date-string Epoch
+.  ie "\$1"$Mdocdate:"  .ds doc-date-string \$2\~\$3, \$4
+.  el                   .ds doc-date-string \$*
 ..
 .
 .
diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index 05f895f..5e76495 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -944,30 +944,32 @@ ugly.
 .Pp
 This macro is neither callable nor parsed.
 .
-.It Li .Dd Oo
-.Aq month
+.It Li .Dd Xo
+.Aq Month
 .Aq day ,
 .Aq year
-.Oc
-If
-.Ql Dd
-has no arguments,
-.Ql Epoch
-is used for the date string.
-If it has exactly three arguments, they are concatenated, separated with
-unbreakable space:
+.Xc
+The document date for display in the page footer.
+This is the mandatory first macro of any
+.Nm \-mdoc
+manual.
+The
+.Aq Month
+is the full English month name, the
+.Aq day
+is an integer number without a leading zero, and the
+.Aq year
+is the full four-digit year, for example:
 .Pp
 .Dl .Dd January 25, 2001
 .Pp
-The month's name shall not be abbreviated.
-.Pp
-With any other number of arguments, the current date is used, ignoring
-the parameters.
+The arguments are concatenated, separated with space characters,
+even if they do not match the recommended format.
 .Pp
 As a special exception, the format
 .Bd -filled -offset indent
 .Li .Dd $Mdocdate:
-.Aq month
+.Aq Month
 .Aq day
 .Aq year
 .Li $