diff --git a/etc/NEWS b/etc/NEWS index cb8b6fcac18..9a9e25bea90 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1995,6 +1995,27 @@ and 'gravatar-force-default'. *** The built-in ada-mode is now deleted. The GNU ELPA package is a good replacement, even in very large source files. +** Some conversions recommended for 'time-stamp-format' have changed. +The new documented/recommended %-conversions are closer to those +used by 'format-time-string' and are compatible at least as far back +as Emacs 22.1 (released in 2007). + +Uppercase abbreviated day name of week: was %3A, now %#a +Full day name of week: was %:a, now %:A +Uppercase abbreviated month name: was %3B, now %#b +Full month name: was %:b, now %:B +Four-digit year: was %:y, now %Y +Lowercase timezone name: was %z, now %#Z +Fully-qualified host name: was %s, now %Q +Unqualified host name: (was none), now %q +Login name: was %u, now %l +User's full name: was %U, now %L + +Merely having (add-hook 'before-save-hook 'time-stamp) in your +Emacs init file does not expose you to this change. However, +if you set 'time-stamp-format' or 'time-stamp-pattern' with a +file-local variable, you may need to update the value. + * New Modes and Packages in Emacs 27.1 diff --git a/lisp/time-stamp.el b/lisp/time-stamp.el index 284d4501552..f6b00185793 100644 --- a/lisp/time-stamp.el +++ b/lisp/time-stamp.el @@ -41,7 +41,7 @@ :group 'data :group 'extensions) -(defcustom time-stamp-format "%:y-%02m-%02d %02H:%02M:%02S %u" +(defcustom time-stamp-format "%Y-%02m-%02d %02H:%02M:%02S %l" "Format of the string inserted by \\[time-stamp]. This is a string, used verbatim except for character sequences beginning with %, as follows. The values of non-numeric formatted items depend @@ -49,26 +49,26 @@ on the locale setting recorded in `system-time-locale' and `locale-coding-system'. The examples here are for the default \(`C') locale. -%:a weekday name: `Monday'. %#A gives uppercase: `MONDAY' -%3a abbreviated weekday: `Mon'. %3A gives uppercase: `MON' -%:b month name: `January'. %#B gives uppercase: `JANUARY' -%3b abbreviated month: `Jan'. %3B gives uppercase: `JAN' +%:A weekday name: `Monday' %#A gives uppercase: `MONDAY' +%3a abbreviated weekday: `Mon' %#a gives uppercase: `MON' +%:B month name: `January' %#B gives uppercase: `JANUARY' +%3b abbreviated month: `Jan' %#b gives uppercase: `JAN' %02d day of month %02H 24-hour clock hour %02I 12-hour clock hour %02m month number %02M minute -%#p `am' or `pm'. %P gives uppercase: `AM' or `PM' +%#p `am' or `pm' %P gives uppercase: `AM' or `PM' %02S seconds %w day number of week, Sunday is 0 -%02y 2-digit year: `03' %:y 4-digit year: `2003' -%z time zone name: `est'. %Z gives uppercase: `EST' +%02y 2-digit year: `03' %Y 4-digit year: `2003' +%#Z lowercase time zone name: `est' %Z gives uppercase: `EST' Non-date items: %% a literal percent character: `%' %f file name without directory %F gives absolute pathname -%s system name -%u user's login name %U user's full name +%l login name %L full name of logged-in user +%q unqualified host name %Q fully-qualified host name %h mail host name Decimal digits between the % and the type character specify the @@ -76,16 +76,15 @@ field width. Strings are truncated on the right; years on the left. A leading zero in the field width zero-fills a number. For example, to get the format used by the `date' command, -use \"%3a %3b %2d %02H:%02M:%02S %Z %:y\". +use \"%3a %3b %2d %02H:%02M:%02S %Z %Y\". -In the future these formats will be aligned more with `format-time-string'. -Because of this transition, the default padding for numeric formats will -change in a future version. Therefore either a padding width should be -specified, or the : modifier should be used to explicitly request the -historical default." +The default padding of some formats has changed to be more compatible +with format-time-string. To be compatible with older versions of Emacs, +specify a padding width (as shown) or use the : modifier to request the +transitional behavior (again, as shown)." :type 'string :group 'time-stamp - :version "20.1") + :version "27.1") ;;;###autoload(put 'time-stamp-format 'safe-local-variable 'stringp) (defcustom time-stamp-active t @@ -227,13 +226,13 @@ Examples: \"-10/\" (sets only `time-stamp-line-limit') \"-9/^Last modified: %%$\" (sets `time-stamp-line-limit', -`time-stamp-start', `time-stamp-end' and `time-stamp-format') +`time-stamp-start' and `time-stamp-end') -\"@set Time-stamp: %:b %:d, %:y$\" (sets `time-stamp-start', -`time-stamp-end' and `time-stamp-format') +\"@set Time-stamp: %:B %1d, %Y$\" (sets `time-stamp-start', +`time-stamp-format' and `time-stamp-end') -\"newcommand{\\\\\\\\timestamp}{%%}\" (sets `time-stamp-start', -`time-stamp-end' and `time-stamp-format') +\"newcommand{\\\\\\\\timestamp}{%%}\" (sets `time-stamp-start' +and `time-stamp-end') Do not change `time-stamp-pattern' `time-stamp-line-limit', `time-stamp-start', or `time-stamp-end' for yourself or you will be diff --git a/test/lisp/time-stamp-tests.el b/test/lisp/time-stamp-tests.el index 452d83ddba9..f13fee76f0e 100644 --- a/test/lisp/time-stamp-tests.el +++ b/test/lisp/time-stamp-tests.el @@ -63,9 +63,10 @@ ;; implemented and documented since 1997 (should (equal (time-stamp-string "%3a" ref-time) "Mon")) (should (equal (time-stamp-string "%#A" ref-time) "MONDAY")) + ;; documented 1997-2019 (should (equal (time-stamp-string "%3A" ref-time) "MON")) (should (equal (time-stamp-string "%:a" ref-time) "Monday")) - ;; implemented since 2001, undocumented future formats + ;; implemented since 2001, documented since 2019 (should (equal (time-stamp-string "%#a" ref-time) "MON")) (should (equal (time-stamp-string "%:A" ref-time) "Monday")) ;; warned since 1997, will change @@ -82,9 +83,10 @@ ;; implemented and documented since 1997 (should (equal (time-stamp-string "%3b" ref-time) "Jan")) (should (equal (time-stamp-string "%#B" ref-time) "JANUARY")) + ;; documented 1997-2019 (should (equal (time-stamp-string "%3B" ref-time) "JAN")) (should (equal (time-stamp-string "%:b" ref-time) "January")) - ;; implemented since 2001, undocumented future formats + ;; implemented since 2001, documented since 2019 (should (equal (time-stamp-string "%#b" ref-time) "JAN")) (should (equal (time-stamp-string "%:B" ref-time) "January")) ;; warned since 1997, will change @@ -103,10 +105,10 @@ (should (equal (time-stamp-string "%2d" ref-time2) "18")) (should (equal (time-stamp-string "%02d" ref-time) "02")) (should (equal (time-stamp-string "%02d" ref-time2) "18")) - ;; implemented and documented since 1997 + ;; documented 1997-2019 (should (equal (time-stamp-string "%:d" ref-time) "2")) (should (equal (time-stamp-string "%:d" ref-time2) "18")) - ;; implemented since 1997, undocumented future format + ;; implemented since 1997, documented since 2019 (should (equal (time-stamp-string "%1d" ref-time) "2")) (should (equal (time-stamp-string "%1d" ref-time2) "18")) ;; warned since 1997, will change @@ -125,11 +127,11 @@ (should (equal (time-stamp-string "%02H" ref-time) "15")) (should (equal (time-stamp-string "%02H" ref-time2) "12")) (should (equal (time-stamp-string "%02H" ref-time3) "06")) - ;; implemented and documented since 1997 + ;; documented 1997-2019 (should (equal (time-stamp-string "%:H" ref-time) "15")) (should (equal (time-stamp-string "%:H" ref-time2) "12")) (should (equal (time-stamp-string "%:H" ref-time3) "6")) - ;; implemented since 1997, undocumented future format + ;; implemented since 1997, documented since 2019 (should (equal (time-stamp-string "%1H" ref-time) "15")) (should (equal (time-stamp-string "%1H" ref-time2) "12")) (should (equal (time-stamp-string "%1H" ref-time3) "6")) @@ -151,11 +153,11 @@ (should (equal (time-stamp-string "%02I" ref-time) "03")) (should (equal (time-stamp-string "%02I" ref-time2) "12")) (should (equal (time-stamp-string "%02I" ref-time3) "06")) - ;; implemented and documented since 1997 + ;; documented 1997-2019 (should (equal (time-stamp-string "%:I" ref-time) "3")) ;PM (should (equal (time-stamp-string "%:I" ref-time2) "12")) ;PM (should (equal (time-stamp-string "%:I" ref-time3) "6")) ;AM - ;; implemented since 1997, undocumented future format + ;; implemented since 1997, documented since 2019 (should (equal (time-stamp-string "%1I" ref-time) "3")) (should (equal (time-stamp-string "%1I" ref-time2) "12")) (should (equal (time-stamp-string "%1I" ref-time3) "6")) @@ -175,10 +177,10 @@ (should (equal (time-stamp-string "%2m" ref-time2) "11")) (should (equal (time-stamp-string "%02m" ref-time) "01")) (should (equal (time-stamp-string "%02m" ref-time2) "11")) - ;; implemented and documented since 1997 + ;; documented 1997-2019 (should (equal (time-stamp-string "%:m" ref-time) "1")) (should (equal (time-stamp-string "%:m" ref-time2) "11")) - ;; implemented since 1997, undocumented future format + ;; implemented since 1997, documented since 2019 (should (equal (time-stamp-string "%1m" ref-time) "1")) (should (equal (time-stamp-string "%1m" ref-time2) "11")) ;; warned since 1997, will change @@ -195,10 +197,10 @@ (should (equal (time-stamp-string "%2M" ref-time2) "14")) (should (equal (time-stamp-string "%02M" ref-time) "04")) (should (equal (time-stamp-string "%02M" ref-time2) "14")) - ;; implemented and documented since 1997 + ;; documented 1997-2019 (should (equal (time-stamp-string "%:M" ref-time) "4")) (should (equal (time-stamp-string "%:M" ref-time2) "14")) - ;; implemented since 1997, undocumented future format + ;; implemented since 1997, documented since 2019 (should (equal (time-stamp-string "%1M" ref-time) "4")) (should (equal (time-stamp-string "%1M" ref-time2) "14")) ;; warned since 1997, will change @@ -215,10 +217,10 @@ (should (equal (time-stamp-string "%2S" ref-time2) "15")) (should (equal (time-stamp-string "%02S" ref-time) "05")) (should (equal (time-stamp-string "%02S" ref-time2) "15")) - ;; implemented and documented since 1997 + ;; documented 1997-2019 (should (equal (time-stamp-string "%:S" ref-time) "5")) (should (equal (time-stamp-string "%:S" ref-time2) "15")) - ;; implemented since 1997, undocumented future format + ;; implemented since 1997, documented since 2019 (should (equal (time-stamp-string "%1S" ref-time) "5")) (should (equal (time-stamp-string "%1S" ref-time2) "15")) ;; warned since 1997, will change @@ -251,9 +253,9 @@ (with-time-stamp-test-env ;; implemented and documented since 1995 (should (equal (time-stamp-string "%02y" ref-time) "06")) - ;; implemented and documented since 1997 + ;; documented 1997-2019 (should (equal (time-stamp-string "%:y" ref-time) "2006")) - ;; implemented since 1997, undocumented future format + ;; implemented since 1997, documented since 2019 (should (equal (time-stamp-string "%Y" ref-time) "2006")) ;; warned since 1997, will change (time-stamp-should-warn (equal (time-stamp-string "%y" ref-time) "2006")))) @@ -263,8 +265,9 @@ (with-time-stamp-test-env ;; implemented and documented since 1995 (should (equal (time-stamp-string "%Z" ref-time) "GMT")) + ;; documented 1995-2019 (should (equal (time-stamp-string "%z" ref-time) "gmt")) - ;; implemented since 1997, undocumented future format + ;; implemented since 1997, documented since 2019 (should (equal (time-stamp-string "%#Z" ref-time) "gmt")))) (ert-deftest time-stamp-test-non-date-conversions () @@ -277,14 +280,15 @@ (should (equal (time-stamp-string "%F" ref-time) "/emacs/test/time-stamped-file")) (should (equal (time-stamp-string "%h" ref-time) "test-mail-host-name")) + ;; documented 1995-2019 (should (equal (time-stamp-string "%s" ref-time) "test-system-name.example.org")) (should (equal (time-stamp-string "%U" ref-time) "Time Stamp Tester")) (should (equal (time-stamp-string "%u" ref-time) "test-logname")) - ;; implemented since 2001, undocumented future formats + ;; implemented since 2001, documented since 2019 (should (equal (time-stamp-string "%L" ref-time) "Time Stamp Tester")) (should (equal (time-stamp-string "%l" ref-time) "test-logname")) - ;; implemented since 2007, undocumented future formats + ;; implemented since 2007, documented since 2019 (should (equal (time-stamp-string "%Q" ref-time) "test-system-name.example.org")) (should (equal