bugGNU roff - Bugs: bug #66903, [man,mdoc] recommend ISO 8601 date...

 
 

bug #66903: [man,mdoc] recommend ISO 8601 date format

Submitter:  Alejandro Colomar <alx>
Submitted:  Wed 12 Mar 2025 04:38:33 PM UTC
   
 
Category:  Macro package - others/general Severity:  1 - Wish
Item Group:  Documentation Status:  Confirmed
Privacy:  Public Assigned to:  None
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Wed 12 Mar 2025 09:56:10 PM UTC, comment #2: 

original submission:

> The groff_man(7) manual page doesn't specify which format should be used for the date.  Would you mind recommending ISO 8601?
>
> This format is the only format recognized by ISO (apart from the basic variant, YYYYMMDD), and is what the Linux man-pages project already uses.


Hi Alex,

Yes, thanks.  groff's man pages are already set to ship using ISO 8601
date format in the forthcoming 1.24 release.

Expanding scope to include groff mdoc.

Homework for self: make this ticket a dependency of bug #65099.

Per emails on which I was CCed by I acknowledge that the FreeBSD and
mandoc(1) communities are not interested in following this change.



Date: Wed, 12 Mar 2025 00:40:48 +0000 (UTC)
From: Alexander Ziaee <ziaee@FreeBSD.org>
To: alx <alx@kernel.org>
CC: branden <branden@debian.org>, tech <tech@mandoc.bsd.lv>
Message-Id: <E1tsA9Q-0004Aw-Ox@rmmprod06.runbox>
Subject: Re: Date format
X-Mailer: RMM6

Hi Alex,

On 2025-03-11 18:49 -04:00 EDT, "Alejandro Colomar" <alx@kernel.org>
wrote:
> If you're going to change the titles to
> lowercase, maybe you could take that opportunity to automate the
> change.
> Since all pages will be touched at once, you could flip the date
> format
> at once?

I spoke with some of the other FreeBSD maintainers, we have a
consensus that neither of these changes is an acceptable
churn to us. We remain interested in productive ways to collaborate
on improving the quality  and predictability of information in
system reference manuals.


Oh, and I don't need to to quote Ingo because he's already commented to
this ticket...which means Savannah is going to spit at me and tell me to
reload it.  Better save this pending comment, then.

G. Branden Robinson <gbranden>
Group administrator
Wed 12 Mar 2025 05:18:18 PM UTC, comment #1: 

For context,

  • AT&T Version 1 to AT&T Version 6 UNIX used mm/dd/yy
  • AT&T Version 7 UNIX used mm/dd/yy in nroff output and Month dd, year in troff output
  • 2BSD used mm/dd/yyyy
  • 3BSD to 4.1BSD were inconsistent
  • 4.2BSD used dd Month yyyy (no comma)
  • Since 4.3BSD-Tahoe (June 1988), BSD has been using Month dd, yyyy (as introduced in v7 troff) consistently for more than 35 years, and this is documented in mdoc(7).
  • The ISO 8601 variant yyyy-mm-dd is common in older GNU manuals, though i don't know where it first appeared in manuals.  It certainly has no tradition in UNIX, neither in the AT&T nor in the BSD branch.


I think using yyyy-mm-dd is a bad idea.  Even though endorsed by ISO, purely numerical mm-dd and dd-mm are notorious for being easily confused with each other.  The traditional AT&T UNIX and BSD format Month dd, yyyy is preferable because it is unambiguous and reads well for human beings, which is the audience of manual pages.  Being easy to parse for a computer, on the other hand, is not a goal for manual page output.

There recebtly was some discussion on the tech at mandoc mailing list, for example https://marc.info/?l=mandoc-tech&m=174172793214691

Existing mdoc(7) manuals tend to be highly consistent in this respect, so attempting to change the recommendation for mdoc(7) is likely to make matters worse even though causing huge effort in at least four major projects.  Changing the recommendation for man(7) would have less adverse impact because man(7) manuals tend to be less consistent in this respect.  Adjusting the recommendation for man(7) to match the firmly established one for mdoc(7) seems like the best option to me in the long run.

Ingo Schwarze <schwarze>
Group Member
Wed 12 Mar 2025 04:38:33 PM UTC, original submission:  

The groff_man(7) manual page doesn't specify which format should be used for the date.  Would you mind recommending ISO 8601?

This format is the only format recognized by ISO (apart from the basic variant, YYYYMMDD), and is what the Linux man-pages project already uses.

Alejandro Colomar <alx>

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one

Digest:
   bug dependencies.

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by alx (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 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2025-03-12 gbranden Dependencies- bugs #65099 is dependent
    2025-03-12 gbranden CategoryMacro package man Macro package - others/general
        StatusNone Confirmed
        SummaryPlease recommend a date format in groff_man(7) [man,mdoc] recommend ISO 8601 date format
    2025-03-12 barx Carbon-CopyRemoved 93119 -
    2025-03-12 barx Severity3 - Normal 1 - Wish

    Back to the top

    Powered by Savane 3.15-e6e5.
    Corresponding source code