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.

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))