time-stamp doc: recommend formats closer to format-time-string

* time-stamp.el (time-stamp-format, time-stamp-pattern): Update
recommended (documented) formats.  No code changes, just documentation.
All recommended formats are compatible at least as far back as Emacs
22.1 (released in 2007) and are now closer to compatibility with
format-time-string.

* time-stamp-tests.el: Update test comments to match.

diff --git a/etc/NEWS b/etc/NEWS
index cb8b6fcac189660447fd2fd66449a010c45c3bdc..9a9e25bea9075e36c593457f8a3ee676237dcbd3 100644 (file)
--- 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.
+
 \f
 * New Modes and Packages in Emacs 27.1
 

diff --git a/lisp/time-stamp.el b/lisp/time-stamp.el
index 284d4501552b7bf9ad927c7277f530efce4f80b5..f6b00185793fe818a28014245782657f1fd16f59 100644 (file)
--- 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 452d83ddba9ceaa68b1206c71283922ae9d3a7db..f13fee76f0eb9596887d5fcc5f1967ec654d41fe 100644 (file)
--- 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