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
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{}}
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
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',
// 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'.")
;;;###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
;;; 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.
projects / emacs.git / commitdiff