Merge from origin/emacs-26

af1624f * lisp/net/shr.el (shr-browse-url): Doc fix.  (Bug#30957)
3a451bd ; * doc/emacs/msdos.texi: Fix wording of last change.
3bc1e2f Mention `key-description' as inverse of `kbd' (Bug#30942)
e50196e Document return value of pcase (Bug#30425)
8a2466f * doc/emacs/macos.texi: Tweak grammar and capitalization.
9db62bf Distinguish free from non-free OSes
ff49d86 * doc/emacs/misc.texi (Amusements): Avoid non-printing charac...
5bab671 Fix xrefs in pdf Emacs manual

3 files changed, 14 insertions, 5 deletions

diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el
index 6cfd074cf0b..ce148c9e1a9 100644
--- a/lisp/emacs-lisp/pcase.el
+++ b/lisp/emacs-lisp/pcase.el
@@ -118,7 +118,9 @@ two element list, binding its elements to symbols named `foo' and
 
 A significant difference from `cl-destructuring-bind' is that, if
 a pattern match fails, the next case is tried until either a
-successful match is found or there are no more cases.
+successful match is found or there are no more cases.  The CODE
+expression corresponding to the matching pattern determines the
+return value.  If there is no match the returned value is nil.
 
 Another difference is that pattern elements may be quoted,
 meaning they must match exactly: The pattern \\='(foo bar)
@@ -211,7 +213,8 @@ Emacs Lisp manual for more information and examples."
 
 ;;;###autoload
 (defmacro pcase-exhaustive (exp &rest cases)
-  "The exhaustive version of `pcase' (which see)."
+  "The exhaustive version of `pcase' (which see).
+If EXP fails to match any of the patterns in CASES, an error is signaled."
   (declare (indent 1) (debug pcase))
   (let* ((x (gensym "x"))
          (pcase--dontwarn-upats (cons x pcase--dontwarn-upats)))
diff --git a/lisp/net/shr.el b/lisp/net/shr.el
index 69063abf033..08aefd01d0d 100644
--- a/lisp/net/shr.el
+++ b/lisp/net/shr.el
@@ -934,8 +934,12 @@ size, and full-buffer size."
   (shr-browse-url))
 
 (defun shr-browse-url (&optional external mouse-event)
-  "Browse the URL under point.
-If EXTERNAL, browse the URL using `shr-external-browser'."
+  "Browse the URL at point using `browse-url'.
+If EXTERNAL is non-nil (interactively, the prefix argument), browse
+the URL using `shr-external-browser'.
+If this function is invoked by a mouse click, it will browse the URL
+at the position of the click.  Optional argument MOUSE-EVENT describes
+the mouse click event."
   (interactive (list current-prefix-arg last-nonmenu-event))
   (mouse-set-point mouse-event)
   (let ((url (get-text-property (point) 'shr-url)))
diff --git a/lisp/subr.el b/lisp/subr.el
index 113bd978b63..cfaa8aa4e54 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -768,7 +768,9 @@ side-effects, and the argument LIST is not modified."
 KEYS should be a string in the format returned by commands such
 as `C-h k' (`describe-key').
 This is the same format used for saving keyboard macros (see
-`edmacro-mode')."
+`edmacro-mode').
+
+For an approximate inverse of this, see `key-description'."
   ;; Don't use a defalias, since the `pure' property is only true for
   ;; the calling convention of `kbd'.
   (read-kbd-macro keys))