From: Paul Eggert <eggert@cs.ucla.edu>
Date: Mon, 30 Dec 2024 19:38:56 +0000 (-0800)
Subject: date: improve doc for ambiguous formats
X-Git-Tag: v9.6~42
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=a0c3e5648be9727d1e2e18f18f143c619f825706;p=thirdparty%2Fcoreutils.git

date: improve doc for ambiguous formats

Problem reported by Tim Connors <https://bugs.gnu.org/75208>.
* doc/coreutils.texi (Date conversion specifiers):
* src/date.c (usage):
Warn about ambiguous formats like %D.
---

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 11a51706b5..5a68ab5171 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -16656,7 +16656,9 @@ It is normally at least two characters, but it may be more.
 @item %d
 day of month (e.g., @samp{01})
 @item %D
-date; same as @samp{%m/%d/%y}
+date; same as @samp{%m/%d/%y}.
+Although commonly used in the US, this format is confusing elsewhere,
+and it is ambiguous for dates in different centuries.
 @item %e
 day of month, space padded; same as @samp{%_d}
 @item %F
@@ -16672,6 +16674,7 @@ year corresponding to the ISO week number, but without the century
 as @samp{%y}, except that if the ISO week number (see
 @samp{%V}) belongs
 to the previous or next year, that year is used instead.
+This format is ambiguous for dates in different centuries.
 @item %G
 year corresponding to the ISO week number.  This has the
 same format and value as @samp{%Y}, except that if the ISO
@@ -16710,9 +16713,11 @@ week number of year, with Monday as first day of week
 (@samp{00}@dots{}@samp{53}).
 Days in a new year preceding the first Monday are in week zero.
 @item %x
-locale's date representation (e.g., @samp{12/31/99})
+locale's date representation (e.g., @samp{12/31/99}).
+This format can be ambiguous for dates in different centuries.
 @item %y
-last two digits of year (@samp{00}@dots{}@samp{99})
+last two digits of year (@samp{00}@dots{}@samp{99}).
+This format is ambiguous for dates in different centuries.
 @item %Y
 year.  This is normally at least four characters, but it may be more.
 Year @samp{0000} precedes year @samp{0001}, and year @samp{-001}
diff --git a/src/date.c b/src/date.c
index ee32403ef2..2245136bcf 100644
--- a/src/date.c
+++ b/src/date.c
@@ -200,13 +200,13 @@ FORMAT controls the output.  Interpreted sequences are:\n\
       fputs (_("\
   %C   century; like %Y, except omit last two digits (e.g., 20)\n\
   %d   day of month (e.g., 01)\n\
-  %D   date; same as %m/%d/%y\n\
+  %D   date (ambiguous); same as %m/%d/%y\n\
   %e   day of month, space padded; same as %_d\n\
 "), stdout);
       fputs (_("\
   %F   full date; like %+4Y-%m-%d\n\
-  %g   last two digits of year of ISO week number (see %G)\n\
-  %G   year of ISO week number (see %V); normally useful only with %V\n\
+  %g   last two digits of year of ISO week number (ambiguous; 00-99); see %G\n\
+  %G   year of ISO week number; normally useful only with %V\n\
 "), stdout);
       fputs (_("\
   %h   same as %b\n\
@@ -243,9 +243,9 @@ FORMAT controls the output.  Interpreted sequences are:\n\
   %W   week number of year, with Monday as first day of week (00..53)\n\
 "), stdout);
       fputs (_("\
-  %x   locale's date representation (e.g., 12/31/99)\n\
+  %x   locale's date (can be ambiguous; e.g., 12/31/99)\n\
   %X   locale's time representation (e.g., 23:13:48)\n\
-  %y   last two digits of year (00..99)\n\
+  %y   last two digits of year (ambiguous; 00..99)\n\
   %Y   year\n\
 "), stdout);
       fputs (_("\