emacs-29 40a758f5ceb 1/3: ; Minor fixes in documentation of recently-changed VC commands

[Eli Zaretskii]

branch: emacs-29
commit 40a758f5ceb3d46fa3669e2471db1a45a08f3a23
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Minor fixes in documentation of recently-changed VC commands
    
    * lisp/vc/vc.el (vc-print-branch-log, vc-create-branch)
    (vc-create-tag, vc-retrieve-tag, vc-switch-branch): Doc fixes.
    * lisp/vc/vc-hooks.el (vc-menu-map): Minor wording change in :help
    text.
    
    * doc/emacs/maintaining.texi (VC Change Log, Creating Branches):
    Minor wording and markup changes.
---
 doc/emacs/maintaining.texi |  7 ++++---
 lisp/vc/vc-hooks.el        |  2 +-
 lisp/vc/vc.el              | 49 ++++++++++++++++++++++++++++++++++------------
 3 files changed, 41 insertions(+), 17 deletions(-)

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 06f44a88aab..246e335cfe7 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1071,8 +1071,9 @@ revision at point.  A second @key{RET} hides it again.
 @findex vc-print-branch-log
   @kbd{C-x v b l @var{branch-name} @key{RET}} (@code{vc-print-branch-log})
 displays a @file{*vc-change-log*} buffer showing the history of the
-version-controlled directory tree like @code{vc-print-root-log} does,
-but in another branch provided as an argument.
+version-controlled directory tree, like @code{vc-print-root-log} does,
+but it shows the history of a branch other than the current one; it
+prompts for the branch whose history to display.
 
 @kindex C-x v I
 @kindex C-x v O
@@ -1690,7 +1691,7 @@ and so on, depending on the number of existing branches 
at that point.
 @findex vc-create-branch
   This procedure will not work for distributed version control systems
 like git or Mercurial.  For those systems you should use the command
-@code{vc-create-branch} (@kbd{C-x v b c @var{branch-name} @key{RET}})
+@code{vc-create-branch} (@w{@kbd{C-x v b c @var{branch-name} @key{RET}}})
 instead.
 
   To create a new branch at an older revision (one that is no longer
diff --git a/lisp/vc/vc-hooks.el b/lisp/vc/vc-hooks.el
index b559a776c09..00a7659209e 100644
--- a/lisp/vc/vc-hooks.el
+++ b/lisp/vc/vc-hooks.el
@@ -899,7 +899,7 @@ In the latter case, VC mode is deactivated for this buffer."
                  :help "Create version tag"))
     (bindings--define-key map [vc-print-branch-log]
       '(menu-item "Show Branch History..." vc-print-branch-log
-                 :help "List the change log for a branch"))
+                 :help "List the change log for another branch"))
     (bindings--define-key map [vc-switch-branch]
       '(menu-item "Switch Branch..." vc-switch-branch
                  :help "Switch to another branch"))
diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
index ba981545085..1144a23f317 100644
--- a/lisp/vc/vc.el
+++ b/lisp/vc/vc.el
@@ -2504,9 +2504,13 @@ Otherwise, return nil."
 (defun vc-create-tag (dir name branchp)
   "Descending recursively from DIR, make a tag called NAME.
 For each registered file, the working revision becomes part of
-the named configuration.  If the prefix argument BRANCHP is
-given, the tag is made as a new branch and the files are
-checked out in that new branch."
+the configuration identified by the tag.
+If BRANCHP is non-nil (interactively, the prefix argument), the
+tag NAME is a new branch, and the files are checked out and
+updated to reflect their revisions on that branch.
+In interactive use, DIR is `default-directory' for repository-granular
+VCSes (all the modern decentralized VCSes belong to this group),
+otherwise the command will prompt for DIR."
   (interactive
    (let ((granularity
          (vc-call-backend (vc-responsible-backend default-directory)
@@ -2529,9 +2533,23 @@ checked out in that new branch."
 
 ;;;###autoload
 (defun vc-create-branch (dir name)
-  "Descending recursively from DIR, make a branch called NAME.
-After a new branch is made, the files are checked out in that new branch.
-Uses `vc-create-tag' with the non-nil arg `branchp'."
+  "Make a branch called NAME in directory DIR.
+After making the new branch, check out the branch, i.e. update the
+files in the tree to their revisions on the branch.
+
+Interactively, prompt for the NAME of the branch.
+
+With VCSes that maintain version information per file, this command also
+prompts for the directory DIR whose files, recursively, will be tagged
+with the NAME of new branch.  For VCSes that maintain version
+information for the entire repository (all the modern decentralized
+VCSes belong to this group), DIR is always the `default-directory'.
+
+Finally, this command might prompt for the branch or tag from which to
+start (\"fork\") the new branch, with completion candidates including
+all the known branches and tags in the repository.
+
+This command invokes `vc-create-tag' with the non-nil BRANCHP argument."
   (interactive
    (let ((granularity
           (vc-call-backend (vc-responsible-backend default-directory)
@@ -2545,17 +2563,17 @@ Uses `vc-create-tag' with the non-nil arg `branchp'."
 
 ;;;###autoload
 (defun vc-retrieve-tag (dir name &optional branchp)
-  "For each file in or below DIR, retrieve their tagged version NAME.
+  "For each file in or below DIR, retrieve their version identified by tag 
NAME.
 NAME can name a branch, in which case this command will switch to the
 named branch in the directory DIR.
 Interactively, prompt for DIR only for VCS that works at file level;
-otherwise use the repository root of the current buffer.
+otherwise use the root directory of the current buffer's VC tree.
 If NAME is empty, it refers to the latest revisions of the current branch.
 If locking is used for the files in DIR, then there must not be any
 locked files at or below DIR (but if NAME is empty, locked files are
 allowed and simply skipped).
-If the prefix argument BRANCHP is given, switch the branch
-and check out the files in that branch.
+If BRANCHP is non-nil (interactively, the prefix argument), switch to the
+branch and check out and update the files to their version on that branch.
 This function runs the hook `vc-retrieve-tag-hook' when finished."
   (interactive
    (let* ((granularity
@@ -2596,7 +2614,12 @@ This function runs the hook `vc-retrieve-tag-hook' when 
finished."
 ;;;###autoload
 (defun vc-switch-branch (dir name)
   "Switch to the branch NAME in the directory DIR.
-If NAME is empty, it refers to the latest revisions of the current branch.
+If NAME is empty, it refers to the latest revision of the current branch.
+Interactively, prompt for DIR only for VCS that works at file level;
+otherwise use the root directory of the current buffer's VC tree.
+Interactively, prompt for the NAME of the branch.
+After switching to the branch, check out and update the files to their
+version on that branch.
 Uses `vc-retrieve-tag' with the non-nil arg `branchp'."
   (interactive
    (let* ((granularity
@@ -2851,8 +2874,8 @@ with its diffs (if the underlying VCS backend supports 
that)."
 
 ;;;###autoload
 (defun vc-print-branch-log (branch)
-  "Show the change log for BRANCH in a window.
-The command prompts for the branch to log."
+  "Show the change log for BRANCH in another window.
+The command prompts for the branch whose change log to show."
   (interactive
    (let* ((backend (vc-responsible-backend default-directory))
           (rootdir (vc-call-backend backend 'root default-directory)))