From d12215324bb201d5f8c9e2b52c9b8d2abf30b1f4 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 21 Jul 2018 19:11:32 +0300 Subject: [PATCH] Minor rewording of last change * lisp/vc/add-log.el (add-log-dont-create-changelog-file) (add-log--pseudo-changelog-buffer-name) (add-log--changelog-buffer-p, add-change-log-entry): Doc fixes. * etc/NEWS: Improve wording of last change. * doc/emacs/maintaining.texi (Change Log Commands): Improve wording of last change. --- doc/emacs/maintaining.texi | 10 +++-- etc/NEWS | 12 ++++-- lisp/vc/add-log.el | 78 +++++++++++++++++++------------------- 3 files changed, 54 insertions(+), 46 deletions(-) diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index c59978ebbe2..b31cacf998a 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1657,14 +1657,16 @@ ordering of entries. @vindex add-log-dont-create-changelog-file Version control systems are another way to keep track of changes in -your program and keep a change log. In these situations, you may not -want to keep a separate versioned change log file. If +your program and keep a change log. Many projects that use a VCS don't +keep a separate versioned change log file nowadays, so you may wish to +avoid having such a file in the repository. If the value of @code{add-log-dont-create-changelog-file} is non-@code{nil}, commands like @kbd{C-x 4 a} (@code{add-change-log-entry-other-window}) will record changes in a suitably named temporary buffer instead of a file, -unless such a file already exists. +if such a file does not already exist. -In either case, you can type @kbd{C-c C-a} +Whether you have a change log file or use a temporary buffer for +change logs, you can type @kbd{C-c C-a} (@code{log-edit-insert-changelog}) in the VC Log buffer to insert the relevant change log entries, if they exist. @xref{Log Buffer}. diff --git a/etc/NEWS b/etc/NEWS index 72e35f93e19..c2b6b500eeb 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -219,10 +219,14 @@ navigation and editing of large files. ** Change Logs and VC -*** Recording ChangeLog entries doesn't require an actual file -An existing file will be used if it already exists. This is -controlled by the defcustom 'add-log-dont-create-changelog-file', -which defaults to t. +*** Recording ChangeLog entries doesn't require an actual file. +If a ChangeLog file doesn't exist, and if the new variable +'add-log-dont-create-changelog-file' is non-nil (which is the +default), commands such as 'C-x 4 a' will add log entries to a +suitable named temporary buffer. (An existing ChangeLog file will +still be used if it exists.) Set the variable to nil to get the +previous behavior of always creating a buffer that visits a ChangeLog +file. ** diff-mode *** Hunks are now automatically refined by default diff --git a/lisp/vc/add-log.el b/lisp/vc/add-log.el index 5ed43e8c8c4..d6e85408608 100644 --- a/lisp/vc/add-log.el +++ b/lisp/vc/add-log.el @@ -744,7 +744,7 @@ Optional arg BUFFER-FILE overrides `buffer-file-name'." file-name) (defun add-log-file-name (buffer-file log-file) - "Compute file-name of BUFFER-FILE as displayed in LOG-FILE." + "Compute file-name of BUFFER-FILE to be used in entries in LOG-FILE." ;; Never want to add a change log entry for the ChangeLog file itself. (unless (or (null buffer-file) (string= buffer-file log-file)) (if add-log-file-name-function @@ -770,22 +770,23 @@ Optional arg BUFFER-FILE overrides `buffer-file-name'." (defcustom add-log-dont-create-changelog-file t "If non-nil, don't create ChangeLog files for log entries. -This applies only if no pre-existing ChangeLog is found." +If a ChangeLog file does not already exist, a non-nil value +means to put log entries in a suitably named buffer." :type :boolean :version "27.1") (put 'add-log-dont-create-changelog-file 'safe-local-variable 'booleanp) (defun add-log--pseudo-changelog-buffer-name (changelog-file-name) - "Compute suitable name for a non-file ChangeLog buffer. - CHANGELOG-FILE-NAME is the file name of the actual ChangeLog file - if it were to exist." + "Compute a suitable name for a non-file visiting ChangeLog buffer. +CHANGELOG-FILE-NAME is the file name of the actual ChangeLog file +if it were to exist." (format "*changes to %s*" (abbreviate-file-name (file-name-directory changelog-file-name)))) (defun add-log--changelog-buffer-p (changelog-file-name buffer) - "Tell if BUFFER holds a ChangeLog for CHANGELOG-FILE-NAME." + "Return non-nil if BUFFER holds a change log for CHANGELOG-FILE-NAME." (with-current-buffer buffer (if buffer-file-name (equal buffer-file-name changelog-file-name) @@ -794,7 +795,7 @@ This applies only if no pre-existing ChangeLog is found." (defun add-log-find-changelog-buffer (changelog-file-name) "Find a ChangeLog buffer for CHANGELOG-FILE-NAME. - Respect `add-log-use-pseudo-changelog', which see." +Respect `add-log-use-pseudo-changelog', which see." (if (or (file-exists-p changelog-file-name) (not add-log-dont-create-changelog-file)) (find-file-noselect changelog-file-name) @@ -807,37 +808,38 @@ This applies only if no pre-existing ChangeLog is found." other-window new-entry put-new-entry-on-new-line) "Find ChangeLog buffer, add an entry for today and an item for this file. - Optional arg WHOAMI (interactive prefix) non-nil means prompt for - user name and email (stored in `add-log-full-name' and - `add-log-mailing-address'). - - Second arg CHANGELOG-FILE-NAME is file name of the change log. - If nil, use the value of `change-log-default-name'. If the file - thus named exists, it's used for the new entry. If it doesn't - exist, it is created, unless `add-log-dont-create-changelog-file' is t, - in which case a suitably named file-less buffer is used for - keeping entries pertaining to CHANGELOG-FILE-NAME's directory. - - Third arg OTHER-WINDOW non-nil means visit in other window. - - Fourth arg NEW-ENTRY non-nil means always create a new entry at the front; - never append to an existing entry. Option `add-log-keep-changes-together' - otherwise affects whether a new entry is created. - - Fifth arg PUT-NEW-ENTRY-ON-NEW-LINE non-nil means that if a new - entry is created, put it on a new line by itself, do not put it - after a comma on an existing line. - - Option `add-log-always-start-new-record' non-nil means always create a - new record, even when the last record was made on the same date and by - the same person. - - The change log file can start with a copyright notice and a copying - permission notice. The first blank line indicates the end of these - notices. - - Today's date is calculated according to `add-log-time-zone-rule' if - non-nil, otherwise in local time." +Optional arg WHOAMI (interactive prefix) non-nil means prompt for +user name and email (stored in `add-log-full-name' +and `add-log-mailing-address'). + +Second arg CHANGELOG-FILE-NAME is the file name of the change log. +If nil, use the value of `change-log-default-name'. If the file +thus named exists, it is used for the new entry. If it doesn't +exist, it is created, unless `add-log-dont-create-changelog-file' is t, +in which case a suitably named buffer that doesn't visit any file +is used for keeping entries pertaining to CHANGELOG-FILE-NAME's +directory. + +Third arg OTHER-WINDOW non-nil means visit in other window. + +Fourth arg NEW-ENTRY non-nil means always create a new entry at the front; +never append to an existing entry. Option `add-log-keep-changes-together' +otherwise affects whether a new entry is created. + +Fifth arg PUT-NEW-ENTRY-ON-NEW-LINE non-nil means that if a new +entry is created, put it on a new line by itself, do not put it +after a comma on an existing line. + +Option `add-log-always-start-new-record' non-nil means always create a +new record, even when the last record was made on the same date and by +the same person. + +The change log file can start with a copyright notice and a copying +permission notice. The first blank line indicates the end of these +notices. + +Today's date is calculated according to `add-log-time-zone-rule' if +non-nil, otherwise in local time." (interactive (list current-prefix-arg (prompt-for-change-log-name))) (let* ((defun (add-log-current-defun)) -- 2.39.2