Adapt doc for man.el

* etc/NEWS: Rephrase 'Man-support-remote-systems' entry.
Fix typos.

* lisp/man.el (Man-header-file-path, man): Adapt docstrings.

2 files changed, 13 insertions, 15 deletions

diff --git a/etc/NEWS b/etc/NEWS
index 00df004fd70..54360e43322 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -688,16 +688,15 @@ bound to 'C-c C-d' in 'go-ts-mode'.
 
 +++
 *** New user option 'Man-prefer-synchronous-call'.
-When this is non-nil, call the 'man' program synchronously rather than
+When this is non-nil, run the 'man' command synchronously rather than
 asynchronously (which is the default behavior).
 
 +++
 *** New user option 'Man-support-remote-systems'.
-If the user option 'Man-support-remote-systems' is non-nil, and
-'default-directory' indicates a remote system, the man page is taken
-from the remote system.  Calling the 'man' command with a prefix like
-'C-u M-x man' reverts the value of 'Man-support-remote-systems' for
-that call.
+This option controls whether the man page is taken from the remote
+system when the current buffer is remote.  You can invoke the 'man'
+command with a prefix argument to reverse the value of this option
+only for the current invocation.
 
 ** DocView
 
@@ -1011,7 +1010,7 @@ A major mode based on the tree-sitter library for editing Lua files.
 
 *** New commands 'previous-line-completion' and 'next-line-completion'.
 Bound to '<UP>' and '<DOWN>' arrow keys, respectively, they navigate
-the *Completions* buffer vertically by lines, wrapping at the
+the "*Completions*" buffer vertically by lines, wrapping at the
 top/bottom when 'completion-auto-wrap' is non-nil.
 
 +++
diff --git a/lisp/man.el b/lisp/man.el
index d64a355e3d8..28c71ba1e06 100644
--- a/lisp/man.el
+++ b/lisp/man.el
@@ -583,9 +583,10 @@ Otherwise, the value is whatever the function
       "/bin/sh"))
 
 (defun Man-header-file-path ()
-  "C Header file search path used in Man.
-In the local case, it is the value of `Man-header-file-path'.
-Otherwise, it will be checked on the remote system."
+  "Return the C header file search path that Man uses.
+Normally, this is the value of the user option `Man-header-file-path',
+but when the man page is retrieved from a remote system this
+function tries to find the C header path on that system."
   (let ((remote-id (file-remote-p default-directory)))
     (if (null remote-id)
         ;; The local case.
@@ -1088,11 +1089,9 @@ SPC character in the above examples, because this command attempts
 to auto-complete your input based on the installed manual pages.
 
 If `default-directory' is remote, and `Man-support-remote-systems'
-is non-nil, the man page will be formatted on the corresponding
-remote system.
-
-If `man' is called interactively with a prefix argument, the
-value of `Man-support-remote-systems' is reverted."
+is non-nil, this command formats the man page on the remote system.
+A prefix argument reverses the value of `Man-support-remote-systems'
+for the current call."
 
   (interactive
    (list (let* ((default-entry (Man-default-man-entry))