Better, more user-oriented doc strings.

(time-stamp-mail-host): Now a user option.
(time-stamp-current-year, time-stamp-hh:mm): Removed.
(time-stamp-mm/dd/yy, time-stamp-dd/mm/yy): Removed.
(time-stamp-yyyy-mm-dd): New function, ISO 8601 format.

1 files changed, 61 insertions, 57 deletions

diff --git a/lisp/time-stamp.el b/lisp/time-stamp.el
index af529c93cee..b7e9b022238 100644
--- a/lisp/time-stamp.el
+++ b/lisp/time-stamp.el
@@ -2,7 +2,7 @@
 ;;; Copyright 1989, 1993 Free Software Foundation, Inc.
 
 ;; Maintainer: Stephen Gildea <gildea@lcs.mit.edu>
-;; Time-stamp: <93/12/07 07:38:54 gildea>
+;; Time-stamp: <93/12/19 14:50:59 gildea>
 ;; Keywords: tools
 
 ;; This file is free software; you can redistribute it and/or modify
@@ -62,37 +62,55 @@ which are included verbatim.  Spaces are not inserted around literal strings.")
 ;;; 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!  See comment above.
+(defvar time-stamp-line-limit 8     ;Do not change!
   "Number of lines at the beginning of a file that are searched.
-The patterns time-stamp-start and time-stamp-end must be found on one
-of the first time-stamp-line-limit lines of the file for the file to
-be time-stamped.")
+The patterns `time-stamp-start' and `time-stamp-end' must be found on one
+of the first `time-stamp-line-limit' lines of the file for the file to
+be time-stamped by \\[time-stamp].
+
+Do not change `time-stamp-line-limit', `time-stamp-start', or
+`time-stamp-end' 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-start "Time-stamp: \\\\?[\"<]+"    ;Do not change!
   "Regexp after which the time stamp is written by \\[time-stamp].
-See also the variables  time-stamp-end  and  time-stamp-line-limit.
+See also the variables `time-stamp-end' and `time-stamp-line-limit'.
 
-Do not change time-stamp-line-limit, time-stamp-start, or
-time-stamp-end for yourself or you will be incompatible
+Do not change `time-stamp-line-limit', `time-stamp-start', or
+`time-stamp-end' 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-end "\\\\?[\">]"    ;Do not change!  See comment above.
+(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
-\(which see) and the following match of  time-stamp-end  on the same line,
-then writes the time stamp specified by  time-stamp-format  between them.")
+\\[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.
+
+Do not change `time-stamp-line-limit', `time-stamp-start', or
+`time-stamp-end' 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.")
+
 
 ;;;###autoload
 (defun time-stamp ()
   "Update the time stamp string in the buffer.
+If you put a time stamp template anywhere in the first 8 lines of a file,
+it can be updated every time you save the file.  See the top of
+`time-stamp.el' for a sample.  The template looks like one of the following:
+    Time-stamp: <>
+    Time-stamp: \" \"
+The time stamp is written between the brackets or quotes, resulting in
+    Time-stamp: <93/06/18 10:26:51 gildea>
 Only does its thing if the variable  time-stamp-active  is non-nil.
 Typically used on  write-file-hooks  for automatic time-stamping.
-The format of the time stamp is determined by the variable
-time-stamp-format.  The first  time-stamp-line-limit  lines of the
-buffer (normally 8) are searched for the time stamp template,
-and if it is found, a new time stamp is written into it."
+The format of the time stamp is determined by the variable  time-stamp-format.
+The variables time-stamp-line-limit, time-stamp-start, and time-stamp-end
+control finding the template."
   (interactive)
   (if time-stamp-active
        (let ((case-fold-search nil))
@@ -128,7 +146,7 @@ and if it is found, a new time stamp is written into it."
   (time-stamp-fconcat time-stamp-format " "))
 
 (defun time-stamp-fconcat (list sep)
-  "Similar to (mapconcat 'funcall LIST SEP) but LIST can have literals.
+  "Similar to (mapconcat 'funcall LIST SEP) but LIST allows literals.
 If an element of LIST is a symbol, it is funcalled to get the string to use;
 the separator SEP is used between two strings obtained by funcalling a
 symbol.  Otherwise the element itself is inserted; no separator is used
@@ -151,38 +169,35 @@ around literals."
 (defconst time-stamp-month-numbers
   '(("Jan" . 1) ("Feb" . 2) ("Mar" . 3) ("Apr" . 4) ("May" . 5) ("Jun" . 6)
     ("Jul" . 7) ("Aug" . 8) ("Sep" . 9) ("Oct" . 10) ("Nov" . 11) ("Dec" . 12))
-  "Assoc list of months and their number.")
+  "Alist of months and their number.")
 
 (defconst time-stamp-month-full-names
   ["(zero)" "January" "February" "March" "April" "May" "June"
    "July" "August" "September" "October" "November" "December"])
 
 (defvar time-stamp-mail-host nil
-  "Name of the host where the user receives mail.
-See the function time-stamp-mail-host-name.")
+  "*Name of the host where the user receives mail.
+See the function `time-stamp-mail-host-name'.")
 
 ;;; Some useful functions to use in time-stamp-format
 
 ;;; Could generate most of a message-id with
-;;; '(time-stamp-yymmdd "" time-stamp-hhmm "@" mail-host-name)
+;;; '(time-stamp-yymmdd "" time-stamp-hhmm "@" time-stamp-mail-host-name)
 
 (defun time-stamp-mail-host-name ()
   "Return the name of the host where the user receives mail.
-This is the value of time-stamp-mail-host if bound and a string,
-otherwise the value of the function system-name."
+This is the value of `time-stamp-mail-host' if bound and a string,
+otherwise the value of the function system-name.
+This function may be usefully referenced by `time-stamp-format'."
   (or (and (boundp 'time-stamp-mail-host)
            (stringp time-stamp-mail-host)
            time-stamp-mail-host)
       (system-name)))
 
-(defun time-stamp-current-year ()
-  "Return the current year as a four-character string."
-  (substring (current-time-string) -4))
-
 ;;; pretty form, suitable for a title page
 
 (defun time-stamp-month-dd-yyyy ()
-  "Return the current date as a string in \"Month dd, yyyy\" form."
+  "Return the current date as a string in \"Month DD, YYYY\" form."
   (let ((date (current-time-string)))
     (format "%s %d, %s"
             (aref time-stamp-month-full-names
@@ -193,8 +208,8 @@ otherwise the value of the function system-name."
 ;;; same as __DATE__ in ANSI C
 
 (defun time-stamp-mon-dd-yyyy ()
-  "Return the current date as a string in \"Mon dd yyyy\" form.
-The first character of dd is Space if the value is less than 10."
+  "Return the current date as a string in \"Mon DD YYYY\" form.
+The first character of DD is space if the value is less than 10."
   (let ((date (current-time-string)))
     (format "%s %2d %s"
             (substring date 4 7)
@@ -204,7 +219,7 @@ The first character of dd is Space if the value is less than 10."
 ;;; RFC 822 date
 
 (defun time-stamp-dd-mon-yy ()
-  "Return the current date as a string in \"dd Mon yy\" form."
+  "Return the current date as a string in \"DD Mon YY\" form."
   (let ((date (current-time-string)))
     (format "%02d %s %s"
             (string-to-int (substring date 8 10))
@@ -214,7 +229,7 @@ The first character of dd is Space if the value is less than 10."
 ;;; RCS 3 date
 
 (defun time-stamp-yy/mm/dd ()
-  "Return the current date as a string in \"yy/mm/dd\" form."
+  "Return the current date as a string in \"YY/MM/DD\" form."
   (let ((date (current-time-string)))
     (format "%s/%02d/%02d"
             (substring date -2)
@@ -224,47 +239,37 @@ The first character of dd is Space if the value is less than 10."
 ;;; RCS 5 date
 
 (defun time-stamp-yyyy/mm/dd ()
-  "Return the current date as a string in \"yyyy/mm/dd\" form."
+  "Return the current date as a string in \"YYYY/MM/DD\" form."
   (let ((date (current-time-string)))
     (format "%s/%02d/%02d"
             (substring date -4)
             (cdr (assoc (substring date 4 7) time-stamp-month-numbers))
             (string-to-int (substring date 8 10)))))
 
-(defun time-stamp-yymmdd ()
-  "Return the current date as a string in \"yymmdd\" form."
-  (let ((date (current-time-string)))
-    (format "%s%02d%02d"
-            (substring date -2)
-            (cdr (assoc (substring date 4 7) time-stamp-month-numbers))
-            (string-to-int (substring date 8 10)))))
+;;; ISO 8601 date
 
-(defun time-stamp-dd/mm/yy ()
-  "Return the current date as a string in \"dd/mm/yy\" form."
+(defun time-stamp-yyyy-mm-dd ()
+  "Return the current date as a string in \"YYYY-MM-DD\" form."
   (let ((date (current-time-string)))
-    (format "%02d/%02d/%s"
-            (string-to-int (substring date 8 10))
+    (format "%s-%02d-%02d"
+            (substring date -4)
             (cdr (assoc (substring date 4 7) time-stamp-month-numbers))
-            (substring date -2))))
+            (string-to-int (substring date 8 10)))))
 
-(defun time-stamp-mm/dd/yy ()
-  "Return the current date as a string in \"mm/dd/yy\" form."
+(defun time-stamp-yymmdd ()
+  "Return the current date as a string in \"YYMMDD\" form."
   (let ((date (current-time-string)))
-    (format "%02d/%02d/%s"
+    (format "%s%02d%02d"
+            (substring date -2)
             (cdr (assoc (substring date 4 7) time-stamp-month-numbers))
-            (string-to-int (substring date 8 10))
-            (substring date -2))))
+            (string-to-int (substring date 8 10)))))
 
 (defun time-stamp-hh:mm:ss ()
-  "Return the current time as a string in \"hh:mm:ss\" form."
+  "Return the current time as a string in \"HH:MM:SS\" form."
   (substring (current-time-string) 11 19))
 
-(defun time-stamp-hh:mm ()
-  "Return the current time as a string in \"hh:mm\" form."
-  (substring (current-time-string) 11 16))
-
 (defun time-stamp-hhmm ()
-  "Return the current time as a string in \"hhmm\" form."
+  "Return the current time as a string in \"HHMM\" form."
   (let ((date (current-time-string)))
     (concat (substring date 11 13)
             (substring date 14 16))))
@@ -272,4 +277,3 @@ The first character of dd is Space if the value is less than 10."
 (provide 'time-stamp)
 
 ;;; time-stamp.el ends here
-