[Emacs-diffs] master 8ba1ca5: time-stamp doc: recommend formats closer to format-time-string

[Stephen Gildea]

branch: master
commit 8ba1ca54f31b556edcc24d497d132203cc0cb9c0
Author: Stephen Gildea <address@hidden>
Commit: Stephen Gildea <address@hidden>

    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.
---
 etc/NEWS                      | 21 +++++++++++++++++++++
 lisp/time-stamp.el            | 43 +++++++++++++++++++++----------------------
 test/lisp/time-stamp-tests.el | 42 +++++++++++++++++++++++-------------------
 3 files changed, 65 insertions(+), 41 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index cb8b6fc..9a9e25b 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 284d450..f6b0018 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 452d83d..f13fee7 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