X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/e654f4b02c4a0a288b6134c137d15dc57fefdaae..052ca4d1d2fffca52c6e69c4f8cd480ca547463e:/lisp/time-stamp.el

diff --git a/lisp/time-stamp.el b/lisp/time-stamp.el
index 85351d741f..b6e76ee539 100644
--- a/lisp/time-stamp.el
+++ b/lisp/time-stamp.el
@@ -1,17 +1,20 @@
 ;;; time-stamp.el --- Maintain last change time stamps in files edited by Emacs
 
-;; Copyright 1989, 1993, 1994, 1995 Free Software Foundation, Inc.
+;; Copyright 1989, 1993, 1994, 1995, 1997, 2000, 2001
+;;;	Free Software Foundation, Inc.
 
-;; Maintainer's Time-stamp: <1996-08-13 14:03:17 gildea>
-;; Maintainer: Stephen Gildea <gildea@lcs.mit.edu>
+;; This file is part of GNU Emacs.
+
+;; Maintainer's Time-stamp: <2003-02-01 09:26:25 gildea>
+;; Maintainer: Stephen Gildea <gildea@stop.mail-abuse.org>
 ;; Keywords: tools
 
-;; This file is free software; you can redistribute it and/or modify
+;; GNU Emacs is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
 ;; the Free Software Foundation; either version 2, or (at your option)
 ;; any later version.
 
-;; This file is distributed in the hope that it will be useful,
+;; GNU Emacs is distributed in the hope that it will be useful,
 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 ;; GNU General Public License for more details.
@@ -25,7 +28,7 @@
 
 ;; A template in a file can be updated with a new time stamp when
 ;; you save the file.  For example:
-;;     static char *ts = "sdmain.c Time-stamp: <1996-08-13 10:20:51 gildea>";
+;;     static char *ts = "sdmain.c Time-stamp: <2001-08-13 10:20:51 gildea>";
 ;; See the top of `time-stamp.el' for another example.
 
 ;; To use time-stamping, add this line to your .emacs file:
@@ -35,60 +38,110 @@
 ;; See the documentation for the functions `time-stamp'
 ;; and `time-stamp-toggle-active' for details.
 
-;;; Change Log:
-
-;; Originally based on the 19 Dec 88 version of
-;;   date.el by John Sturdy <mcvax!harlqn.co.uk!jcgs@uunet.uu.net>
-;; Version 2, January 1995: replaced functions with %-escapes
-;; $Id: time-stamp.el,v 1.23 1996/12/17 00:19:01 rms Exp rms $
-
 ;;; Code:
 
-(defvar time-stamp-active t
-  "*Non-nil to enable time-stamping of buffers by \\[time-stamp].
-Can be toggled by \\[time-stamp-toggle-active].
-See also the variable `time-stamp-warn-inactive'.")
-
-(defvar time-stamp-warn-inactive t
-  "Non-nil to have \\[time-stamp] warn if a buffer did not get time-stamped.
-A warning is printed if `time-stamp-active' is nil and the buffer contains
-a time stamp template that would otherwise have been updated.")
+(defgroup time-stamp nil
+  "Maintain last change time stamps in files edited by Emacs."
+  :group 'data
+  :group 'extensions)
 
-(defvar time-stamp-old-format-warn 'ask
-  "Action to take if `time-stamp-format' is an old-style list.
-If `error', the format is not used.  If `ask', the user is queried about
-using the time-stamp-format.  If `warn', a warning is displayed.
-If nil, no notification is given.")
-
-(defvar time-stamp-format "%Y-%m-%d %H:%M:%S %u"
+(defcustom time-stamp-format "%:y-%02m-%02d %02H:%02M:%02S %u"
   "*Format of the string inserted by \\[time-stamp].
 The value may be a string or a list.  Lists are supported only for
 backward compatibility; see variable `time-stamp-old-format-warn'.
 
-A string is used with `format-time-string'.
+A string is used verbatim except for character sequences beginning
+with %, as follows.  The values of non-numeric formatted items depend
+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'
+%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'
+%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'
+
+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
+%h   mail host name
+
+Decimal digits between the % and the type character specify the
+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 %H:%M:%S %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."
+  :type 'string
+  :group 'time-stamp
+  :version "20.1")
+
+(defcustom time-stamp-active t
+  "*Non-nil to enable time-stamping of buffers by \\[time-stamp].
+Can be toggled by \\[time-stamp-toggle-active].
+See also the variable `time-stamp-warn-inactive'."
+  :type 'boolean
+  :group 'time-stamp)
+
+(defcustom time-stamp-warn-inactive t
+  "Have \\[time-stamp] warn if a buffer did not get time-stamped.
+If non-nil, a warning is displayed if `time-stamp-active' has
+deactivated time stamping and the buffer contains a template that
+otherwise would have been updated."
+  :type 'boolean
+  :group 'time-stamp
+  :version "19.29")
+
+(defcustom time-stamp-old-format-warn 'ask
+  "Action if `time-stamp-format' is an old-style list.
+If `error', the format is not used.  If `ask', the user is queried about
+using the time-stamp-format.  If `warn', a warning is displayed.
+If nil, no notification is given."
+  :type '(choice (const :tag "Don't use the format" error)
+                 (const ask)
+                 (const warn)
+		 (const :tag "No notification" nil))
+  :group 'time-stamp)
 
-In addition to the features of `format-time-string',
-you can use the following %-constructs:
+(defcustom time-stamp-time-zone nil
+  "If non-nil, a string naming the timezone to be used by \\[time-stamp].
+Format is the same as that used by the environment variable TZ on your system."
+  :type '(choice (const nil) string)
+  :group 'time-stamp
+  :version "20.1")
 
-%f  file name without directory
-%F  full file name
-%h  mail host name
-%s  system name
-%u  user's login name")
 
-;;; Do not change time-stamp-line-limit, time-stamp-start, or
-;;; time-stamp-end in your .emacs or you will be incompatible
-;;; with other people's files!  If you must change them,
-;;; do so only in the local variables section of the file itself.
+;;; Do not change time-stamp-line-limit, time-stamp-start,
+;;; time-stamp-end, time-stamp-pattern, time-stamp-inserts-lines,
+;;; or time-stamp-count in your .emacs or you will be incompatible
+;;; with other people's files!  If you must change them, do so only
+;;; in the local variables section of the file itself.
 
 
 (defvar time-stamp-line-limit 8	    ;Do not change!
   "Lines of a file searched; positive counts from start, negative from end.
-The patterns `time-stamp-start' and `time-stamp-end' must be found on one
-of the first (last) `time-stamp-line-limit' lines of the file for the
-file to be time-stamped by \\[time-stamp].
+The patterns `time-stamp-start' and `time-stamp-end' must be found in
+the first (last) `time-stamp-line-limit' lines of the file for the
+file to be time-stamped by \\[time-stamp].  A value of 0 searches the
+entire buffer (use with care).
 
 Do not change `time-stamp-line-limit', `time-stamp-start', or
 `time-stamp-end' for yourself or you will be incompatible
@@ -109,19 +162,84 @@ do so in the local variables section of the time-stamped file itself.")
 (defvar time-stamp-end "\\\\?[\">]"    ;Do not change!
   "Regexp marking the text after the time stamp.
 \\[time-stamp] deletes the text between the first match of `time-stamp-start'
-and the following match of `time-stamp-end' on the same line,
-then writes the time stamp specified by `time-stamp-format' between them.
+and the following match of `time-stamp-end', then writes the
+time stamp specified by `time-stamp-format' between them.
 
-Do not change `time-stamp-line-limit', `time-stamp-start', or
-`time-stamp-end' for yourself or you will be incompatible
+The end text normally starts on the same line as the start text ends,
+but if there are any newlines in `time-stamp-format', the same number
+of newlines must separate the start and end.  \\[time-stamp] tries
+to not change the number of lines in the buffer.  `time-stamp-inserts-lines'
+controls this behavior.
+
+Do not change `time-stamp-line-limit', `time-stamp-start', `time-stamp-end',
+or `time-stamp-inserts-lines' for yourself or you will be incompatible
 with other people's files!  If you must change them for some application,
 do so in the local variables section of the time-stamped file itself.")
 
 
+(defvar time-stamp-inserts-lines nil    ;Do not change!
+  "Whether \\[time-stamp] can change the number of lines in a file.
+If nil, \\[time-stamp] skips as many lines as there are newlines in
+`time-stamp-format' before looking for the `time-stamp-end' pattern,
+thus it tries not to change the number of lines in the buffer.
+If non-nil, \\[time-stamp] starts looking for the end pattern
+immediately after the start pattern.  This behavior can cause
+unexpected changes in the buffer if used carelessly, but it is useful
+for generating repeated time stamps.
+
+Do not change `time-stamp-end' or `time-stamp-inserts-lines' for
+yourself or you will be incompatible with other people's files!
+If you must change them for some application, do so in the local
+variables section of the time-stamped file itself.")
+
+
+(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.
+
+Do not change `time-stamp-count' for yourself or you will be
+incompatible with other people's files!  If you must change it for
+some application, do so in the local variables section of the
+time-stamped file itself.")
+
+
+(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.
+
+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.
+
+The second part is a regexp identifying the pattern preceding the time stamp.
+This part may be omitted to use the normal pattern.
+
+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 fourth part is a regexp identifying the pattern following the time stamp.
+This part may be omitted to use the normal pattern.
+
+Examples:
+\"-10/\"
+\"-9/^Last modified: %%$\"
+\"@set Time-stamp: %:b %:d, %:y$\"
+\"newcommand{\\\\\\\\timestamp}{%%}\"
+
+Do not change `time-stamp-pattern' for yourself or you will be incompatible
+with other people's files!  Set it only in the local variables section
+of the time-stamped file itself.")
+
+
 
 ;;;###autoload
 (defun time-stamp ()
-  "Update the time stamp string in the buffer.
+  "Update the time stamp string(s) in the buffer.
 A template in a file can be automatically updated with a new time stamp
 every time you save the file.  Add this line to your .emacs file:
     (add-hook 'write-file-hooks 'time-stamp)
@@ -130,112 +248,174 @@ look like one of the following:
       Time-stamp: <>
       Time-stamp: \" \"
 The time stamp is written between the brackets or quotes:
-      Time-stamp: <1996-07-18 10:20:51 gildea>
-Only updates the time stamp if the variable `time-stamp-active' is non-nil.
+      Time-stamp: <2001-02-18 10:20:51 gildea>
+The time stamp is updated only if the variable `time-stamp-active' is non-nil.
 The format of the time stamp is set by the variable `time-stamp-format'.
-The variables `time-stamp-line-limit', `time-stamp-start',
-and `time-stamp-end' control finding the template."
+The variables `time-stamp-line-limit', `time-stamp-start', `time-stamp-end',
+`time-stamp-count', and `time-stamp-inserts-lines' control finding the
+template."
   (interactive)
-  (let ((case-fold-search nil)
+  (let ((line-limit time-stamp-line-limit)
+	(ts-start time-stamp-start)
+	(ts-format time-stamp-format)
+	(ts-end time-stamp-end)
+	(ts-count time-stamp-count)
+	(format-lines 0)
+	(end-lines 1)
 	(start nil)
-	(end nil)
 	search-limit)
-	(save-excursion
-	  (save-restriction
-	    (widen)
-	    (cond ((> time-stamp-line-limit 0)
-		   (goto-char (setq start (point-min)))
-		   (forward-line time-stamp-line-limit)
-		   (setq search-limit (point)))
-		  (t
-		   (goto-char (setq search-limit (point-max)))
-		   (forward-line time-stamp-line-limit)
-		   (setq start (point))))
-	    (goto-char start)
-	    (while (and (< (point) search-limit)
-			(not end)
-			(re-search-forward time-stamp-start search-limit 'move))
-	      (setq start (point))
-	      (end-of-line)
-	      (let ((line-end (point)))
-		(goto-char start)
-		(if (re-search-forward time-stamp-end line-end 'move)
-		    (setq end (match-beginning 0)))))))
-	(if end
-	    (progn
-	      ;; do all warnings outside save-excursion
-	      (cond
-	       ((not time-stamp-active)
-		(if time-stamp-warn-inactive
-		    ;; don't signal an error in a write-file-hook
-		    (progn
-		      (message "Warning: time-stamp-active is off; did not time-stamp buffer.")
-		      (sit-for 1))))
-	       ((not (and (stringp time-stamp-start)
-			  (stringp time-stamp-end)))
-		(message "time-stamp-start or time-stamp-end is not a string")
-		(sit-for 1))
-	       (t
-		(let ((new-time-stamp (time-stamp-string)))
-		  (if (stringp new-time-stamp)
-		      (save-excursion
-			(save-restriction
-			  (widen)
-			  (delete-region start end)
-			  (goto-char start)
-			  (insert new-time-stamp)
-			  (setq end (point))
-			  ;; remove any tabs used to format time stamp
-			  (goto-char start)
-			  (if (search-forward "\t" end t)
-			      (untabify start end)))))))))))
+    (if (stringp time-stamp-pattern)
+	(progn
+	  (string-match "\\`\\(\\(-?[0-9]+\\)/\\)?\\([^%]+\\)?\\(\\(%[-.,:@+_ #^()0-9]*[A-Za-z%][^%]*\\)*%[-.,:@+_ #^()0-9]*[A-Za-z%]\\)?\\([^%]+\\)?\\'" time-stamp-pattern)
+	  (and (match-beginning 2)
+	       (setq line-limit
+		     (string-to-int (match-string 2 time-stamp-pattern))))
+	  (and (match-beginning 3)
+	       (setq ts-start (match-string 3 time-stamp-pattern)))
+	  (and (match-beginning 4)
+	       (not (string-equal (match-string 4 time-stamp-pattern) "%%"))
+	       (setq ts-format (match-string 4 time-stamp-pattern)))
+	  (and (match-beginning 6)
+	       (setq ts-end (match-string 6 time-stamp-pattern)))))
+    (cond ((not (integerp line-limit))
+	   (setq line-limit 8)
+	   (message "time-stamp-line-limit is not an integer")
+	   (sit-for 1)))
+    (cond ((not (integerp ts-count))
+	   (setq ts-count 1)
+	   (message "time-stamp-count is not an integer")
+	   (sit-for 1))
+	  ((< ts-count 1)
+	   ;; We need to call time-stamp-once at least once
+	   ;; to output any warnings about time-stamp not being active.
+	   (setq ts-count 1)))
+    ;; Figure out what lines the end should be on.
+    (if (stringp ts-format)
+	(let ((nl-start 0))
+	  (while (string-match "\n" ts-format nl-start)
+	    (setq format-lines (1+ format-lines) nl-start (match-end 0)))))
+    (let ((nl-start 0))
+      (while (string-match "\n" ts-end nl-start)
+	(setq end-lines (1+ end-lines) nl-start (match-end 0))))
+    ;; Find overall what lines to look at
+    (save-excursion
+      (save-restriction
+	(widen)
+	(cond ((> line-limit 0)
+	       (goto-char (setq start (point-min)))
+	       (forward-line line-limit)
+	       (setq search-limit (point)))
+	      ((< line-limit 0)
+	       (goto-char (setq search-limit (point-max)))
+	       (forward-line line-limit)
+	       (setq start (point)))
+	      (t			;0 => no limit (use with care!)
+	       (setq start (point-min))
+	       (setq search-limit (point-max))))))
+    (while (and start
+		(< start search-limit)
+		(> ts-count 0))
+      (setq start (time-stamp-once start search-limit ts-start ts-end
+				   ts-format format-lines end-lines))
+      (setq ts-count (1- ts-count))))
   ;; be sure to return nil so can be used on write-file-hooks
   nil)
 
+(defun time-stamp-once (start search-limit ts-start ts-end
+			ts-format format-lines end-lines)
+  "Update one time stamp.  Internal routine called by \\[time-stamp].
+Returns the end point, which is where `time-stamp' begins the next search."
+  (let ((case-fold-search nil)
+	(end nil)
+	end-search-start
+	(end-length nil))
+    (save-excursion
+      (save-restriction
+	(widen)
+	;; Find the location of the time stamp.
+	(while (and (< (goto-char start) search-limit)
+		    (not end)
+		    (re-search-forward ts-start search-limit 'move))
+	  (setq start (point))
+	  (if (not time-stamp-inserts-lines)
+	      (forward-line format-lines))
+	  (setq end-search-start (max start (point)))
+	  (if (= (forward-line end-lines) 0)
+	      (progn
+	       (and (bolp) (backward-char))
+	       (let ((line-end (min (point) search-limit)))
+		 (if (>= line-end end-search-start)
+		     (progn
+		      (goto-char end-search-start)
+		      (if (re-search-forward ts-end line-end t)
+			  (progn
+			    (setq end (match-beginning 0))
+			    (setq end-length (- (match-end 0) end))))))))))))
+    (if end
+	(progn
+	  ;; do all warnings outside save-excursion
+	  (cond
+	   ((not time-stamp-active)
+	    (if time-stamp-warn-inactive
+		;; don't signal an error in a write-file-hook
+		(progn
+		  (message "Warning: time-stamp-active is off; did not time-stamp buffer.")
+		  (sit-for 1))))
+	   ((not (and (stringp ts-start)
+		      (stringp ts-end)))
+	    (message "time-stamp-start or time-stamp-end is not a string")
+	    (sit-for 1))
+	   (t
+	    (let ((new-time-stamp (time-stamp-string ts-format)))
+	      (if (and (stringp new-time-stamp)
+		       (not (string-equal (buffer-substring start end)
+					  new-time-stamp)))
+		  (save-excursion
+		    (save-restriction
+		      (widen)
+		      (delete-region start end)
+		      (goto-char start)
+		      (insert-and-inherit new-time-stamp)
+		      (setq end (point))
+		      ;; remove any tabs used to format time stamp
+		      (if (search-backward "\t" start t)
+			  (progn
+			    (untabify start end)
+			    (setq end (point))))))))))))
+    ;; return the location after this time stamp, if there was one
+    (and end end-length
+	 (+ end end-length))))
+
+
 ;;;###autoload
 (defun time-stamp-toggle-active (&optional arg)
   "Toggle `time-stamp-active', setting whether \\[time-stamp] updates a buffer.
-With arg, turn time stamping on if and only if arg is positive."
+With ARG, turn time stamping on if and only if arg is positive."
   (interactive "P")
   (setq time-stamp-active
 	(if (null arg)
 	    (not time-stamp-active)
 	  (> (prefix-numeric-value arg) 0)))
-    (message "time-stamp is now %s." (if time-stamp-active "active" "off")))
-
-(defconst time-stamp-no-file "(no file)"
-  "String to use when the buffer is not associated with a file.")
-
-(defun time-stamp-string-preprocess (format)
-  "Process occurrences in FORMAT of %f, %F, %h, %s and %u.
-These are replaced with the file name (nondirectory part),
-full file name, host name for mail, system name, and user name.
-Do not alter other %-combinations, and do detect %%."
-  (let ((result "") (pos 0) (case-fold-search nil)
-	(file (or buffer-file-name "(no file)")))
-    (while (string-match "%[%uhfFs]" format pos)
-      (setq result (concat result (substring format pos (match-beginning 0))))
-      (let ((char (aref format (1+ (match-beginning 0)))))
-	(cond ((= char ?%)
-	       (setq result (concat result "%%")))
-	      ((= char ?u)
-	       (setq result (concat result (user-login-name))))
-	      ((= char ?f)
-	       (setq result (concat result (file-name-nondirectory file))))
-	      ((= char ?f)
-	       (setq result (concat result file)))
-	      ((= char ?s)
-	       (setq result (concat result (system-name))))
-	      ((= char ?h)
-	       (setq result (concat result (time-stamp-mail-host-name))))))
-      (setq pos (match-end 0)))
-    (concat result (substring format pos))))
-
-(defun time-stamp-string ()
-  "Generate the new string to be inserted by \\[time-stamp]."
-  (if (stringp time-stamp-format)
-      (format-time-string (time-stamp-string-preprocess time-stamp-format)
-			  (current-time))
+  (message "time-stamp is now %s." (if time-stamp-active "active" "off")))
+
+
+(defun time-stamp-string (&optional ts-format)
+  "Generate the new string to be inserted by \\[time-stamp].
+Optionally use format TS-FORMAT instead of `time-stamp-format' to
+format the string."
+  (or ts-format
+      (setq ts-format time-stamp-format))
+  (if (stringp ts-format)
+      (if (stringp time-stamp-time-zone)
+	  (let ((ts-real-time-zone (getenv "TZ")))
+	    (unwind-protect
+		(progn
+		  (set-time-zone-rule time-stamp-time-zone)
+		  (format-time-string
+		   (time-stamp-string-preprocess ts-format)))
+	      (set-time-zone-rule ts-real-time-zone)))
+	(format-time-string
+	 (time-stamp-string-preprocess ts-format)))
     ;; handle version 1 compatibility
     (cond ((or (eq time-stamp-old-format-warn 'error)
 	       (and (eq time-stamp-old-format-warn 'ask)
@@ -247,15 +427,236 @@ Do not alter other %-combinations, and do detect %%."
 	   (cond ((eq time-stamp-old-format-warn 'warn)
 		  (message "Obsolescent time-stamp-format type; should be string")
 		  (sit-for 1)))
-	   (time-stamp-fconcat time-stamp-format " ")))))
+	   (time-stamp-fconcat ts-format " ")))))
 
 (defconst time-stamp-no-file "(no file)"
   "String to use when the buffer is not associated with a file.")
 
+;;; time-stamp is transitioning to using the new, expanded capabilities
+;;; of format-time-string.  During the process, this function implements
+;;; intermediate, compatible formats and complains about old, soon to
+;;; be unsupported, formats.  This function will get a lot (a LOT) shorter
+;;; when the transition is complete and we can just pass most things
+;;; straight through to format-time-string.
+;;;      At all times, all the formats recommended in the doc string
+;;; of time-stamp-format will work not only in the current version of
+;;; Emacs, but in all versions that have been released within the past
+;;; two years.
+;;;      The : modifier is a temporary conversion feature used to resolve
+;;; ambiguous formats--formats that are changing (over time) incompatibly.
+(defun time-stamp-string-preprocess (format &optional time)
+  "Use a FORMAT to format date, time, file, and user information.
+Optional second argument TIME is only for testing.
+Implements non-time extensions to `format-time-string'
+and all `time-stamp-format' compatibility."
+  (let ((fmt-len (length format))
+	(ind 0)
+	cur-char
+	(prev-char nil)
+	(result "")
+	field-width
+	field-result
+	alt-form change-case require-padding
+	(paren-level 0))
+    (while (< ind fmt-len)
+      (setq cur-char (aref format ind))
+      (setq
+       result
+       (concat result
+      (cond
+       ((eq cur-char ?%)
+	;; eat any additional args to allow for future expansion
+	(setq alt-form nil change-case nil require-padding nil field-width "")
+	(while (progn
+		 (setq ind (1+ ind))
+		 (setq cur-char (if (< ind fmt-len)
+				    (aref format ind)
+				  ?\0))
+		 (or (eq ?. cur-char)
+		     (eq ?, cur-char) (eq ?: cur-char) (eq ?@ cur-char)
+		     (eq ?- cur-char) (eq ?+ cur-char) (eq ?_ cur-char)
+		     (eq ?\  cur-char) (eq ?# cur-char) (eq ?^ cur-char)
+		     (and (eq ?\( cur-char)
+			  (not (eq prev-char ?\\))
+			  (setq paren-level (1+ paren-level)))
+		     (if (and (eq ?\) cur-char)
+			      (not (eq prev-char ?\\))
+			      (> paren-level 0))
+			 (setq paren-level (1- paren-level))
+		       (and (> paren-level 0)
+			    (< ind fmt-len)))
+		     (if (and (<= ?0 cur-char) (>= ?9 cur-char))
+			 ;; get format width
+			 (let ((field-index ind))
+			   (while (progn
+				    (setq ind (1+ ind))
+				    (setq cur-char (if (< ind fmt-len)
+						       (aref format ind)
+						     ?\0))
+				    (and (<= ?0 cur-char) (>= ?9 cur-char))))
+			   (setq field-width (substring format field-index ind))
+			   (setq ind (1- ind))
+			   t))))
+	  (setq prev-char cur-char)
+	  ;; some characters we actually use
+	  (cond ((eq cur-char ?:)
+		 (setq alt-form t))
+		((eq cur-char ?#)
+		 (setq change-case t))))
+	(setq field-result
+	(cond
+	 ((eq cur-char ?%)
+	  "%%")
+	 ((eq cur-char ?a)		;day of week
+	  (if change-case
+	      (format-time-string "%#a" time)
+	    (or alt-form (not (string-equal field-width ""))
+		(time-stamp-conv-warn "%a" "%:a"))
+	    (if (and alt-form (not (string-equal field-width "")))
+		""			;discourage "%:3a"
+	      (format-time-string "%A" time))))
+	 ((eq cur-char ?A)
+	  (if alt-form
+	      (format-time-string "%A" time)
+	    (or change-case (not (string-equal field-width ""))
+		(time-stamp-conv-warn "%A" "%#A"))
+	    (format-time-string "%#A" time)))
+	 ((eq cur-char ?b)		;month name
+	  (if change-case
+	      (format-time-string "%#b" time)
+	    (or alt-form (not (string-equal field-width ""))
+		(time-stamp-conv-warn "%b" "%:b"))
+	    (if (and alt-form (not (string-equal field-width "")))
+		""			;discourage "%:3b"
+	    (format-time-string "%B" time))))
+	 ((eq cur-char ?B)
+	  (if alt-form
+	      (format-time-string "%B" time)
+	    (or change-case (not (string-equal field-width ""))
+		(time-stamp-conv-warn "%B" "%#B"))
+	    (format-time-string "%#B" time)))
+	 ((eq cur-char ?d)		;day of month, 1-31
+	  (time-stamp-do-number cur-char alt-form field-width time))
+	 ((eq cur-char ?H)		;hour, 0-23
+	  (time-stamp-do-number cur-char alt-form field-width time))
+	 ((eq cur-char ?I)		;hour, 1-12
+	  (time-stamp-do-number cur-char alt-form field-width time))
+	 ((eq cur-char ?m)		;month number, 1-12
+	  (time-stamp-do-number cur-char alt-form field-width time))
+	 ((eq cur-char ?M)		;minute, 0-59
+	  (time-stamp-do-number cur-char alt-form field-width time))
+	 ((eq cur-char ?p)		;am or pm
+	  (or change-case
+	      (time-stamp-conv-warn "%p" "%#p"))
+	  (format-time-string "%#p" time))
+	 ((eq cur-char ?P)		;AM or PM
+	  (format-time-string "%p" time))
+	 ((eq cur-char ?S)		;seconds, 00-60
+	  (time-stamp-do-number cur-char alt-form field-width time))
+	 ((eq cur-char ?w)		;weekday number, Sunday is 0
+	  (format-time-string "%w" time))
+	 ((eq cur-char ?y)		;year
+	  (or alt-form (not (string-equal field-width ""))
+	      (time-stamp-conv-warn "%y" "%:y"))
+	  (string-to-int (format-time-string "%Y" time)))
+	 ((eq cur-char ?Y)		;4-digit year, new style
+	  (string-to-int (format-time-string "%Y" time)))
+	 ((eq cur-char ?z)		;time zone lower case
+	  (if change-case
+	      ""			;discourage %z variations
+	    (format-time-string "%#Z" time)))
+	 ((eq cur-char ?Z)
+	  (if change-case
+	      (format-time-string "%#Z" time)
+	    (format-time-string "%Z" time)))
+	 ((eq cur-char ?f)		;buffer-file-name, base name only
+	  (if buffer-file-name
+	      (file-name-nondirectory buffer-file-name)
+	    time-stamp-no-file))
+	 ((eq cur-char ?F)		;buffer-file-name, full path
+	  (or buffer-file-name
+	      time-stamp-no-file))
+	 ((eq cur-char ?s)		;system name
+	  (system-name))
+	 ((eq cur-char ?u)		;user name
+	  (user-login-name))
+	 ((eq cur-char ?U)		;user full name
+	  (user-full-name))
+	 ((eq cur-char ?l)		;logname (undocumented user name alt)
+	  (user-login-name))
+	 ((eq cur-char ?L)		;(undocumented alt user full name)
+	  (user-full-name))
+	 ((eq cur-char ?h)		;mail host name
+	  (time-stamp-mail-host-name))
+	 ))
+	(let ((padded-result
+	       (format (format "%%%s%c"
+			       field-width
+			       (if (numberp field-result) ?d ?s))
+		       (or field-result ""))))
+	  (let* ((initial-length (length padded-result))
+		 (desired-length (if (string-equal field-width "")
+				     initial-length
+				   (string-to-int field-width))))
+	    (if (> initial-length desired-length)
+		;; truncate strings on right, years on left
+		(if (stringp field-result)
+		    (substring padded-result 0 desired-length)
+		  (if (eq cur-char ?y)
+		      (substring padded-result (- desired-length))
+		    padded-result))	;non-year numbers don't truncate
+	      padded-result))))
+       (t
+	(char-to-string cur-char)))))
+      (setq ind (1+ ind)))
+    result))
+
+(defun time-stamp-do-number (format-char alt-form field-width time)
+  "Handle compatible FORMAT-CHAR where only default width/padding will change.
+ALT-FORM is whether `#' specified.  FIELD-WIDTH is the string
+width specification or \"\".  TIME is the time to convert."
+  (let ((format-string (concat "%" (char-to-string format-char))))
+    (and (not alt-form) (string-equal field-width "")
+	 (time-stamp-conv-warn format-string
+			       (format "%%:%c" format-char)))
+    (if (and alt-form (not (string-equal field-width "")))
+	""				;discourage "%:2d" and the like
+      (string-to-int (format-time-string format-string time)))))
+
+(defvar time-stamp-conversion-warn t
+  "Warn about soon-to-be-unsupported forms in `time-stamp-format'.
+If nil, these warnings are disabled, which would be a bad idea!
+You really need to update your files instead.
+
+The new formats will work with old versions of Emacs.
+New formats are being recommended now to allow `time-stamp-format'
+to change in the future to be compatible with `format-time-string'.
+The new forms being recommended now will continue to work then.")
+
+
+(defun time-stamp-conv-warn (old-form new-form)
+  "Display a warning about a soon-to-be-obsolete format.
+Suggests replacing OLD-FORM with NEW-FORM."
+  (cond
+   (time-stamp-conversion-warn
+    (save-excursion
+      (set-buffer (get-buffer-create "*Time-stamp-compatibility*"))
+      (goto-char (point-max))
+      (if (bobp)
+	  (progn
+	    (insert
+	     "The formats recognized in time-stamp-format will change in a future release\n"
+	     "to be compatible with the new, expanded format-time-string function.\n\n"
+	     "The following obsolescent time-stamp-format construct(s) were found:\n\n")))
+      (insert "\"" old-form "\" -- use " new-form "\n"))
+    (display-buffer "*Time-stamp-compatibility*"))))
+
+
+
 (defun time-stamp-mail-host-name ()
   "Return the name of the host where the user receives mail.
 This is the value of `mail-host-address' if bound and a string,
-otherwise the value of the function system-name."
+otherwise the value of the function `system-name'."
   (or (and (boundp 'mail-host-address)
 	   (stringp mail-host-address)
 	   mail-host-address)
@@ -285,8 +686,24 @@ around literals."
 
 ;;; Some functions used in time-stamp-format
 
-;;; Could generate most of a message-id with
-;;; '(time-stamp-yymmdd "" time-stamp-hhmm "@" time-stamp-mail-host-name)
+;;; These functions have been obsolete since 1995
+;;; and will be removed in Emacs 22.
+;;; Meanwhile, discourage other packages from using them.
+(let ((obsolete-functions '(time-stamp-month-dd-yyyy
+			    time-stamp-dd/mm/yyyy
+			    time-stamp-mon-dd-yyyy
+			    time-stamp-dd-mon-yy
+			    time-stamp-yy/mm/dd
+			    time-stamp-yyyy/mm/dd
+			    time-stamp-yyyy-mm-dd
+			    time-stamp-yymmdd
+			    time-stamp-hh:mm:ss
+			    time-stamp-hhmm)))
+  (while obsolete-functions
+    (make-obsolete (car obsolete-functions)
+		   "use time-stamp-string or format-time-string instead."
+		   "20.1")
+    (setq obsolete-functions (cdr obsolete-functions))))
 
 ;;; pretty form, suitable for a title page
 
@@ -343,4 +760,5 @@ The first character of DD is space if the value is less than 10."
 
 (provide 'time-stamp)
 
+;;; arch-tag: 8a12c5c3-25d6-4a71-adc5-24b0e025a1e7
 ;;; time-stamp.el ends here