; time-stamp: documentation, tests, NEWS

* lisp/time-stamp.el (time-stamp-pattern, time-stamp-count): Document
how to update different time stamps on multiple lines.
* doc/emacs/files.texi (Time stamps): Add an example showing a time
stamp at the end of a file.
* etc/NEWS: Announce time-stamp format additions.
* test/lisp/time-stamp-tests.el: More title-case tests.

(cherry picked from commit 7f10d2680be16219cbde78434836b0befce3a0b3)

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 36622037b8d526eab38442a631885f9262362943..d919e52c76dbd4cec096c4a89fb5459c2d13527c 100644 (file)
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1070,6 +1070,22 @@ identify and update that custom template:
 @end group
 @end example
 
+Here is another example, with the time stamp inserted into the last
+paragraph of an HTML document.  The @code{%%} in the pattern asks for
+the default format.
+
+@example
+@r{@dots{}}
+<p>Last modified: </p>
+</body>
+</html>
+<!--
+Local variables:
+time-stamp-pattern: "-10/Last modified: %%</p>$"
+End:
+-->
+@end example
+
 @vindex time-stamp-format
 By default the time stamp is
 formatted according to your locale setting (@pxref{Environment}) and

diff --git a/lisp/time-stamp.el b/lisp/time-stamp.el
index 8d40d7cd194cd8fdce245694b22335e8151ab3ba..7904b92184abd70a0d3de6d4e403a9aabd4972e3 100644 (file)
--- a/lisp/time-stamp.el
+++ b/lisp/time-stamp.el
@@ -248,7 +248,11 @@ your init file, you would be incompatible with other people's files.")
 
 (defvar time-stamp-count 1             ;Do not change!
   "How many templates \\[time-stamp] will look for in a buffer.
-The same time stamp will be written in each case.
+
+If the value is greater than 1, the same time stamp will be written in
+each case.  If you want to insert different text on different lines,
+then instead of changing this variable, include a newline (written as
+\"\\n\") in `time-stamp-format' or the format part of `time-stamp-pattern'.
 
 `time-stamp-count' is best changed with a file-local variable.
 If you were to change it in your init file, you would be incompatible
@@ -259,26 +263,27 @@ with other people's files.")
 (defvar time-stamp-pattern nil         ;Do not change!
   "Convenience variable setting all `time-stamp' location and format values.
 This string has four parts, each of which is optional.
-These four parts set `time-stamp-line-limit', `time-stamp-start',
-`time-stamp-format', and `time-stamp-end'.  See the documentation
-for each of these variables for details.
+These four parts override `time-stamp-line-limit', `time-stamp-start',
+`time-stamp-format' and `time-stamp-end', respectively.  See the
+documentation for each of these variables for details.
 
 The first part is a number followed by a slash; the number sets the number
 of lines at the beginning (negative counts from end) of the file searched
 for the time stamp.  The number and the slash may be omitted to use the
-normal value.
+value of `time-stamp-line-limit' as the number.
 
 The second part is a regexp identifying the pattern preceding the time stamp.
-This part may be omitted to use the normal pattern.
+This part may be omitted to use the value of `time-stamp-start'.
 
-The third part specifies the format of the time stamp inserted.  See
-the documentation for `time-stamp-format' for details.  Specify this
-part as \"%%\" to use the normal format.
+The third part specifies the format of the time stamp inserted.  Specify
+this part as \"%%\" to use the value of `time-stamp-format'.
 
 The fourth part is a regexp identifying the pattern following the time stamp.
-This part may be omitted to use the normal pattern.
+This part may be omitted to use the value of `time-stamp-end'.
 
 The pattern does not need to match the entire line of the time stamp.
+The pattern will update time stamp information on multiple lines if the
+pattern includes newlines, written as \"\\n\".
 
 These variables are best changed with file-local variables.
 If you were to change `time-stamp-pattern', `time-stamp-line-limit',
@@ -299,6 +304,11 @@ Examples:
 %% time-stamp-pattern: \"newcommand{\\\\\\\\timestamp}{%%}\"
     (sets `time-stamp-start' and `time-stamp-end')
 
+// time-stamp-pattern: \"10/Author %L\\nRevised %-d %b %Y$\"
+    (sets all four variables and updates text on two lines)
+
+See Info node `Time Stamps' for more examples.
+
 
 See also `time-stamp-count' and `time-stamp-inserts-lines'.")
 ;;;###autoload(put 'time-stamp-pattern 'safe-local-variable 'stringp)

diff --git a/test/lisp/time-stamp-tests.el b/test/lisp/time-stamp-tests.el
index 397e21f7bc71014cec5f71003c682638eaab0f99..4794051efd080209a74ea487353b2dc2bedb16d7 100644 (file)
--- a/test/lisp/time-stamp-tests.el
+++ b/test/lisp/time-stamp-tests.el
@@ -326,13 +326,12 @@
       ;; broken in 2019, changed in 2024
       (should (equal (time-stamp-string "%-A" ref-time1) Monday))
       (should (equal (time-stamp-string "%_A" ref-time1) Monday))
-      ;; allowed but not recommended since 2019 (warned 1997-2019)
-      (should (equal (time-stamp-string "%^A" ref-time1) MONDAY))
       ;; warned 1997-2019, changed in 2019, recommended (with caveat) since 2024
       (should (equal (time-stamp-string "%a" ref-time1) Mon))
       (should (equal (time-stamp-string "%4a" ref-time1) p4-Mon))
       (should (equal (time-stamp-string "%04a" ref-time1) p4-Mon))
       (should (equal (time-stamp-string "%A" ref-time1) Monday))
+      (should (equal (time-stamp-string "%^A" ref-time1) MONDAY))
       ;; warned 1997-2019, changed in 2019
       (should (equal (time-stamp-string "%^a" ref-time1) MON))
       (should (equal (time-stamp-string "%^4a" ref-time1) p4-MON))
@@ -383,13 +382,12 @@
       ;; broken in 2019, changed in 2024
       (should (equal (time-stamp-string "%-B" ref-time1) January))
       (should (equal (time-stamp-string "%_B" ref-time1) January))
-      ;; allowed but not recommended since 2019 (warned 1997-2019)
-      (should (equal (time-stamp-string "%^B" ref-time1) JANUARY))
       ;; warned 1997-2019, changed in 2019, recommended (with caveat) since 2024
       (should (equal (time-stamp-string "%b" ref-time1) Jan))
       (should (equal (time-stamp-string "%4b" ref-time1) p4-Jan))
       (should (equal (time-stamp-string "%04b" ref-time1) p4-Jan))
       (should (equal (time-stamp-string "%B" ref-time1) January))
+      (should (equal (time-stamp-string "%^B" ref-time1) JANUARY))
       ;; warned 1997-2019, changed in 2019
       (should (equal (time-stamp-string "%^b" ref-time1) JAN))
       (should (equal (time-stamp-string "%^4b" ref-time1) p4-JAN))
@@ -472,7 +470,7 @@
     (should (equal (time-stamp-string "%:I" ref-time1) "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, recommended since 2019
+    ;; implemented since 1997, recommended 2019-2024
     (should (equal (time-stamp-string "%1I" ref-time1) "3"))
     (should (equal (time-stamp-string "%1I" ref-time2) "12"))
     (should (equal (time-stamp-string "%1I" ref-time3) "6"))
@@ -499,7 +497,7 @@
     ;; recommended 1997-2019
     (should (equal (time-stamp-string "%:m" ref-time1) "1"))
     (should (equal (time-stamp-string "%:m" ref-time2) "11"))
-    ;; implemented since 1997, recommended since 2019
+    ;; implemented since 1997, recommended 2019-2024
     (should (equal (time-stamp-string "%1m" ref-time1) "1"))
     (should (equal (time-stamp-string "%1m" ref-time2) "11"))
     ;; warned 1997-2019, allowed 2019, recommended (with caveat) since 2024
@@ -522,7 +520,7 @@
     ;; recommended 1997-2019
     (should (equal (time-stamp-string "%:M" ref-time1) "4"))
     (should (equal (time-stamp-string "%:M" ref-time2) "14"))
-    ;; implemented since 1997, recommended since 2019
+    ;; implemented since 1997, recommended 2019-2024
     (should (equal (time-stamp-string "%1M" ref-time1) "4"))
     (should (equal (time-stamp-string "%1M" ref-time2) "14"))
     ;; warned 1997-2019, allowed 2019, recommended (with caveat) since 2024
@@ -545,7 +543,7 @@
     ;; recommended 1997-2019
     (should (equal (time-stamp-string "%:S" ref-time1) "5"))
     (should (equal (time-stamp-string "%:S" ref-time2) "15"))
-    ;; implemented since 1997, recommended since 2019
+    ;; implemented since 1997, recommended 2019-2024
     (should (equal (time-stamp-string "%1S" ref-time1) "5"))
     (should (equal (time-stamp-string "%1S" ref-time2) "15"))
     ;; warned 1997-2019, allowed 2019, recommended (with caveat) since 2024
@@ -568,10 +566,12 @@
      (should (equal (time-stamp-string "%:y" ref-time1) "2006")))
     (time-stamp-should-warn
      (should (equal (time-stamp-string "%:y" ref-time2) "2016")))
-    ;; warned 1997-2019, changed in 2019
-    ;; (We don't expect the %-y or %_y form to be useful,
-    ;; but we test both so that we can confidently state that
-    ;; `-' and `_' affect all 2-digit conversions identically.)
+    ;; %-y and %_y warned 1997-2019, changed in 2019
+    ;; (We don't expect these forms to be useful,
+    ;; but we test here so that we can confidently state that
+    ;; all 2-digit conversions behave identically.)
+    (should (equal (time-stamp-string "%1y" ref-time1) "6"))
+    (should (equal (time-stamp-string "%1y" ref-time2) "16"))
     (should (equal (time-stamp-string "%-y" ref-time1) "6"))
     (should (equal (time-stamp-string "%-y" ref-time2) "16"))
     (should (equal (time-stamp-string "%_y" ref-time1) " 6"))
@@ -601,6 +601,8 @@
           (am (format-time-string "%P" ref-time3 t))
           (Pm (format-time-string "%p" ref-time1 t))
           (Am (format-time-string "%p" ref-time3 t))
+          (Pm-tc (capitalize (format-time-string "%p" ref-time1 t)))
+          (Am-tc (capitalize (format-time-string "%p" ref-time3 t)))
           (PM (format-time-string "%^p" ref-time1 t))
           (AM (format-time-string "%^p" ref-time3 t)))
       ;; implemented and recommended since 1997
@@ -626,6 +628,11 @@
       (should (equal (time-stamp-string "%^#P" ref-time3) am))
       (should (equal (time-stamp-string "%^P" ref-time1) ""))
       (should (equal (time-stamp-string "%^P" ref-time3) ""))
+      ;; implemented since 2025
+      (should (equal (time-stamp-string "%*p" ref-time1) Pm-tc))
+      (should (equal (time-stamp-string "%*p" ref-time3) Am-tc))
+      (should (equal (time-stamp-string "%*P" ref-time1) Pm-tc))
+      (should (equal (time-stamp-string "%*P" ref-time3) Am-tc))
       ;; reserved for possible adding or removing periods (dots)
       (should (equal (time-stamp-string "%:p" ref-time1) Pm))
       (should (equal (time-stamp-string "%#:p" ref-time1) pm))
@@ -649,6 +656,7 @@
   "Test `time-stamp' format %Z."
   (with-time-stamp-test-env
     (let ((UTC-abbr (format-time-string "%Z" ref-time1 t))
+          (Utc-abbr (capitalize (format-time-string "%Z" ref-time1 t)))
           (utc-abbr (format-time-string "%#Z" ref-time1 t)))
       ;; implemented and recommended since 1995
       (should (equal (time-stamp-string "%Z" ref-time1) UTC-abbr))
@@ -656,7 +664,10 @@
       (should (equal (time-stamp-string "%#Z" ref-time1) utc-abbr))
       ;; ^ accepted and ignored since 1995/1997, test for consistency with %p
       (should (equal (time-stamp-string "%^Z" ref-time1) UTC-abbr))
-      (should (equal (time-stamp-string "%^#Z" ref-time1) utc-abbr)))))
+      (should (equal (time-stamp-string "%^#Z" ref-time1) utc-abbr))
+      ;; implemented since 2025
+      (should (equal (time-stamp-string "%*Z" ref-time1) Utc-abbr))
+      )))
 
 (ert-deftest time-stamp-format-time-zone-offset ()
   "Test `time-stamp' legacy format %z and spot-test new offset format %5z."