; Time Stamps doc: expand the explanation of the examples

* doc/emacs/files.texi (Time Stamps): Divide into three sections.
* doc/emacs/emacs.texi: Add new nodes to menu.
* lisp/time-stamp.el: Change reference to new node.

Author: Stephen Gildea

doc/emacs/emacs.texi

@@ -486,6 +486,11 @@ Backup Files
 * Backup Deletion::     Emacs deletes excess numbered backups.
 * Backup Copying::      Backups can be made by copying or renaming.
 
+Updating Time Stamps Automatically
+
+* Time Stamp Customization::   How to customize with time-stamp-pattern.
+* Time Stamps for One File::   Ensure automatic time-stamp of a specific file.
+
 @ifnottex
 Auto Reverting Non-File Buffers
 

doc/emacs/files.texi

@@ -1007,8 +1007,8 @@ was written will be preserved even if the file is copied or transformed
 in a way that loses the file system's modification time.
 
 There are two steps to setting up automatic time stamping.
-First, you need to have a time stamp template
-somewhere in the first eight lines of the file.
+First, the file needs a time stamp template
+somewhere in the first eight lines.
 The template looks like this:
 
 @example
@@ -1022,59 +1022,81 @@ or (your choice) like this:
 Time-stamp: " "
 @end example
 
-@noindent
-When time-stamping, Emacs will write the current time, date, and/or
-other info between the brackets or quotes.
-
 @findex time-stamp
-Second, add the function @code{time-stamp}
-to @code{before-save-hook} (@pxref{Hooks}).
-To do this, either customize the option @code{before-save-hook}
-(with @kbd{M-x customize-option}, @pxref{Specific Customization})
-or edit your init file adding this line:
+With that template in place, you can update the current buffer's time
+stamp once immediately with the command @kbd{M-x time-stamp}.
+Emacs will check for a template; if a template is found,
+Emacs will write the current date, time, author, and/or
+other info between the brackets or quotes.
+(If the buffer has no template, @code{time-stamp} does nothing.)
+After the first time stamp, the line might look like this:
 
 @example
-(add-hook 'before-save-hook 'time-stamp)
+Time-stamp: <1993-07-06 11:05:14 terryg>
 @end example
 
-To enable automatic time-stamping for only a specific file, add the
-following line to a local variables list
-(@pxref{Specifying File Variables}) near the end of the file:
+Second, configure Emacs to run @code{time-stamp} any time it saves a
+file, by adding @code{time-stamp}
+to @code{before-save-hook} (@pxref{Hooks}).
+You can either customize the option @code{before-save-hook}
+(with @kbd{M-x customize-option}, @pxref{Specific Customization}),
+or you can edit your init file adding this line:
 
 @example
-eval: (add-hook 'before-save-hook 'time-stamp nil t)
+(add-hook 'before-save-hook 'time-stamp)
 @end example
 
-To update the current buffer's time stamp once
-immediately, use the command @kbd{M-x time-stamp}.
+@menu
+* Time Stamp Customization::   How to customize with time-stamp-pattern.
+* Time Stamps for One File::   Ensure automatic time-stamp of a specific file.
+@end menu
+
+@node Time Stamp Customization
+@subsubsection Customizing the Time Stamp
 
 @vindex time-stamp-pattern
 To customize the time stamp in a particular file, set the
-variable @code{time-stamp-pattern} in that file's local variables list.
-You can change where the time stamp starts and ends and how the dynamic
-information is to be formatted; see the variable's built-in
-documentation for details.
+variable @code{time-stamp-pattern} in that file's local variables
+list (@pxref{Specifying File Variables}).
+You can change what pattern @code{time-stamp} will match against to
+identify a template and where in the file to look for the pattern using
+@code{time-stamp-pattern}; for details, see the variable's built-in
+documentation (with @kbd{C-h v}, @pxref{Name Help}).
+
 As a simple example, if this line occurs near the top of a file:
 
 @example
-\newcommand@{\yearpublished@}@{@}
+publishing_year_and_city = "Published nnnn in Boston, Mass.";
 @end example
 
 @noindent
-then the following at the end of the file tells @code{time-stamp} how to
-identify and update that custom template:
+then the following comment at the end of the same file tells
+@code{time-stamp} how to identify and update that custom template:
 
 @example
 @group
-%% Local variables:
-%% time-stamp-pattern: "@{.yearpublished@}@{%Y@}"
-%% End:
+// Local variables:
+// time-stamp-pattern: "Published %Y in Boston"
+// End:
 @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.
+This pattern says that the text before the start of the time stamp is
+``Published '', and the text after the end is `` in Boston''.
+If @code{time-stamp} finds both in one of the first eight lines,
+what is between will be replaced by the current year, as requested by
+the @code{%Y} format.
+
+After any change to file-local variables,
+type @kbd{M-x normal-mode} to re-read them.
+
+Here is another example, with the time stamp inserted into
+the last paragraph of an HTML document.
+Since this template is at the end of the document, not in the first
+eight lines, @code{time-stamp-format} starts with @code{-10/} to tell
+@code{time-stamp} to look at the last 10 lines.
+The @code{%%} asks for the default format
+(specified by @code{time-stamp-format}).
 
 @example
 @r{@dots{}}
@@ -1096,7 +1118,29 @@ Manual}).
 See the built-in documentation for the variable @code{time-stamp-format}
 for specifics and other variables that affect the formatting.
 
-For customizations, see the Custom group @code{time-stamp}.
+@node Time Stamps for One File
+@subsubsection Forcing Time Stamps for One File
+
+If you are working on a file with multiple authors, and you cannot
+be sure the other authors have enabled time-stamping globally in
+their Emacs init files, you can force it to be enabled for a
+particular file by adding @code{time-stamp} to that buffer's
+@code{before-save-hook} in that file's local variables list.
+To extend one of the previous examples:
+
+@example
+@group
+// Local variables:
+// eval: (add-hook 'before-save-hook 'time-stamp nil t)
+// time-stamp-pattern: "year_published = \"%Y\""
+// End:
+@end group
+@end example
+
+@noindent
+Although this example shows them both set together,
+you can use @code{eval} without also setting @code{time-stamp-pattern}
+if you like the default pattern.
 
 @node Reverting
 @section Reverting a Buffer

lisp/time-stamp.el

@@ -283,7 +283,7 @@ 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\".
+pattern includes newlines, which can be written as \"\\n\".
 
 These variables are best changed with file-local variables.
 If you were to change `time-stamp-pattern', `time-stamp-line-limit',
@@ -307,7 +307,8 @@ Examples:
 // 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 Info node `Time Stamp Customization' for more discussion and more
+in-depth examples.
 
 
 See also `time-stamp-count' and `time-stamp-inserts-lines'.")
@@ -318,8 +319,8 @@ See also `time-stamp-count' and `time-stamp-inserts-lines'.")
 ;;;###autoload
 (defun time-stamp ()
   "Update any time stamp strings (timestamps) in the buffer.
-Look for a time stamp template and update it with the current date,
-time, and/or other info.
+Look for a time stamp template and update it with the current
+date, time, author, and/or other info.
 
 The template, which you manually create on one of the first 8 lines
 of the file before running this function, by default can look like
@@ -526,6 +527,7 @@ time is used.  The time zone is determined by `time-stamp-time-zone'."
 ;;; five 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.