From 455a6d62b4a4aa17f205c81bdbcbc7e3c4a06549 Mon Sep 17 00:00:00 2001 From: Stephen Gildea Date: Fri, 28 Mar 2025 07:04:03 -0700 Subject: [PATCH] ; 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. (cherry picked from commit 7527e395499e7ef24249b286dda87d7feb04fb8e) --- doc/emacs/emacs.texi | 5 ++ doc/emacs/files.texi | 108 ++++++++++++++++++++++++++++++------------- lisp/time-stamp.el | 10 ++-- 3 files changed, 87 insertions(+), 36 deletions(-) diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 47b6be189aa..7850740dcb0 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -483,6 +483,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 diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 7f62603ae41..5aaaff18fc7 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1005,8 +1005,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 @@ -1020,59 +1020,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{}} @@ -1094,7 +1116,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 diff --git a/lisp/time-stamp.el b/lisp/time-stamp.el index 43b9f1a0c5d..3d3886660d9 100644 --- a/lisp/time-stamp.el +++ b/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. -- 2.39.5