; 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.

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 06f44a88aabca1723923ebb24daf020902f3092c..246e335cfe7ecd7d641cdedb876de94b1a6d59b1 100644 (file)
--- 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 b559a776c0985fe814fe8d966d475f93f4ce74f1..00a7659209e11c58cf8c49fb7645821021e2142c 100644 (file)
--- 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 ba981545085e3e509f0a9dccfc1bba2fdd58612c..1144a23f317e8afa294472f0dddbdb4b48e182aa 100644 (file)
--- 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)))