Clarify %g and %G time format specs

* src/timefns.c (Fformat_time_string):
* doc/lispref/os.texi (Time Parsing): Clarify %g/%G.  (Bug#52934)

2 files changed, 13 insertions, 5 deletions

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index a08af898789..b1c19e384be 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1793,9 +1793,16 @@ This stands for the ISO 8601 date format, which is like
 @samp{%+4Y-%m-%d} except that any flags or field width override the
 @samp{+} and (after subtracting 6) the @samp{4}.
 @item %g
-This stands for the year corresponding to the ISO week within the century.
+@cindex ISO week, in time formatting
+This stands for the year without century (00--99) corresponding to the
+current @dfn{ISO week} number.  ISO weeks start on Monday and end on
+Sunday.  If an ISO week begins in one year and ends in another, the
+rules regarding which year @samp{%g} will produce are complex and will
+not be described here; however, in general, if most of the week's days
+are in the ending year, @samp{%g} will produce that year.
 @item %G
-This stands for the year corresponding to the ISO week.
+This stands for the year with century corresponding to the current ISO
+week number.
 @item %h
 This is a synonym for @samp{%b}.
 @item %H
diff --git a/src/timefns.c b/src/timefns.c
index 809ffafea4f..3e533ca51dc 100644
--- a/src/timefns.c
+++ b/src/timefns.c
@@ -1422,8 +1422,9 @@ without consideration for daylight saving time.
 The value is a copy of FORMAT-STRING, but with certain constructs replaced
 by text that describes the specified date and time in TIME:
 
-%Y is the year, %y within the century, %C the century.
-%G is the year corresponding to the ISO week, %g within the century.
+%Y is the year, %y year without century, %C the century.
+%G is the year corresponding to the ISO week, %g year corresponding
+ to the ISO week, without century.
 %m is the numeric month.
 %b and %h are the locale's abbreviated month name, %B the full name.
  (%h is not supported on MS-Windows.)
@@ -1431,7 +1432,7 @@ by text that describes the specified date and time in TIME:
 %u is the numeric day of week from 1 (Monday) to 7, %w from 0 (Sunday) to 6.
 %a is the locale's abbreviated name of the day of week, %A the full name.
 %U is the week number starting on Sunday, %W starting on Monday,
- %V according to ISO 8601.
+ %V the week number according to ISO 8601.
 %j is the day of the year.
 
 %H is the hour on a 24-hour clock, %I is on a 12-hour clock, %k is like %H