bugGNU roff - Bugs: bug #57485, [PATCH] accept any number of...

 
 

bug #57485: [PATCH] accept any number of arguments for .Dd in the groff_mdoc(7) macros

Submitter:  Ingo Schwarze <schwarze>
Submitted:  Thu 26 Dec 2019 02:46:37 PM UTC
   
 
Category:  Macro mdoc Severity:  2 - Minor
Item Group:  Incorrect behaviour Status:  Fixed
Privacy:  Public Assigned to:  schwarze
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Sun 05 Feb 2023 07:14:51 AM UTC, comment #4: 

As noted in bug #57416, I would consider dropping the [PATCH] annotation from this ticket's summary since Ingo is (and has long been) a committing groff developer in good standing.

If one groff developer wants to solicit feedback on a patch in a Savannah ticket, I think setting the ticket status to "Need Info" might be a good means of signaling that.  But emailing the groff at gnu mailing list is probably the best approach--we can be a sleepy bunch.

G. Branden Robinson <gbranden>
Group administrator
Tue 19 Jan 2021 07:48:57 AM UTC, comment #3: 


commit 8545b5a6cc845a67547a393c6053c3b4ffc0d4ac
Author: Ingo Schwarze <schwarze@openbsd.org>
Date:   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 <jsg@openbsd.org>
    while he looked at 4.xBSD manual pages.

    Using feedback from cjwatson@ and Ralph Corderoy;
    OK bgarrigues@, and cjwatson@ agrees with the behaviour change.


G. Branden Robinson <gbranden>
Group administrator
Thu 26 Dec 2019 10:05:26 PM UTC, comment #2: 

Another clarification: In addition to improving the formatting of the
original 4.4BSD manuals, this patch does not cause a single regression
in any modern BSD system.  A manual page relying on the current weird
behaviour for != 3 arguments literally doesn't exist in any modern BSD
system:

Here is the complete list of manuals in FreeBSD 11.2
that call .Dd with != 3 arguments:

  man3/xo_attr_h.3   .Dd July, 2014
  man3/xo_attr_hv.3  .Dd July, 2014
  man3/xo_attr.3     .Dd July, 2014
  man7/ld.7          .Dd 2015-03-02
  man7/ldint.7       .Dd 2015-03-02
  man7/binutils.7    .Dd 2015-03-02
  man7/diff.7        .Dd 2015-03-02
  man7/as.7          .Dd 2015-03-02

Here is the same list for NetBSD 8.1, containing only a single page:

  man1/dns-sd.1      .Dd April 2004                    

In DragonFly BSD 5.6.1, there isn't a single instance.

In conclusion, while the main idea of the patch is to improve
formatting of the original 4.4BSD manuals, it also improves formatting
of modern manual pages.


Just because somebody raised the point that all mdoc documentation
authors are used to the syntax ".Dd Month day, year": that is clearly
true, but completely irrelvant.  I'm not proposing to change the
formatting for == 3 arguments.  This is only about improved
formatting in the rare case of != 3 arguments, with the side
benefit of simplifying the macro implementation.


Because someone doubted that the mdoc(7) manual page from the
mandoc(1) package already documents the proposed behaviour:
It says:

 "Other arguments are not portable; the mandoc(1) utility handles them
  as follows:
    -   To have the date automatically filled in by the OpenBSD
        version of cvs(1), the special string "$Mdocdate$" can be
        given as an argument.
    -   The traditional, purely numeric man(7) format year-month-day
        is accepted, too.
    -   If a date string cannot be parsed, it is used verbatim.
    -   If no date string is given, the current date is used."

Oh well, printing the current date is useless.  I'll remove that
from mandoc(1) when this patch gets pushed.  Right now, it happens
in mandoc(1) for different input than in groff, so removing it will
even improve compatibility...

Ingo Schwarze <schwarze>
Group Member
Thu 26 Dec 2019 05:22:01 PM UTC, comment #1: 

I'd like to stress that this patch indeed fixes a bug.  In 4.4BSD,
it was not documented that .Dd requires exactly three arguments
and prints the current date otherwise, but several manual pages
existed that gave a single quoted argument of the form "Month day,
year".  Documenting the weird behaviour of the groff_mdoc(7) macros
was done much later.  The mandoc(1) utility has been providing the
more useful behaviour proposed here for years, in a way that is in
particular compatible with the original 4.4BSD manual pages, and
it has been documenting the more useful behaviour for years, too.

So calling the current groff_mdoc(7) behaviour "documented behaviour"
is misleading.  At some point, a bug was documented instead of fixed
in groff, a bug that broke the formatting of even the original 4.4BSD
manuals, i.e. those of the system where these macros came from.


To clarify two minor details:

Losing unbreakable spaces is totally irrelevant.  For any sane
input, the footer line is always a single line only; no linebreaks
occur.

Of course this ticket only applies to the non-Mdocdate case,
nothing changes for Mdocdate.

Ingo Schwarze <schwarze>
Group Member
Thu 26 Dec 2019 02:46:37 PM UTC, original submission:  

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 <jsg@openbsd.org> while he looked at 4.xBSD manual pages.

Ingo Schwarze <schwarze>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #48120:  mdoc-Dd.patch added by schwarze (4KiB - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by schwarze (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 4 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-01-19 gbranden StatusNone Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2019-12-26 schwarze Attached File- Added mdoc-Dd.patch, #48120

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code