master b70a00d9bf 2/2: Gently discourage use of `lsh` (bug#56641)

[Mattias Engdegård]

branch: master
commit b70a00d9bf119b6bc5c1f7c3397d04b7d8892fb7
Author: Mattias Engdegård <mattiase@acm.org>
Commit: Mattias Engdegård <mattiase@acm.org>

    Gently discourage use of `lsh` (bug#56641)
    
    * lisp/subr.el (lsh): Note the general preference for `ash`.
    * lisp/emacs-lisp/shortdoc.el (number): Remove entry for `lsh`.
    It was identical to that for `ash` which is misleading.
    Shortdoc is very helpful for finding the right function to use,
    and `lsh` is just for compatibility at this point.
---
 lisp/emacs-lisp/shortdoc.el | 3 ---
 lisp/subr.el                | 5 ++++-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 1514ece6d1..05b3361cb3 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -1183,9 +1183,6 @@ A FUNC form can have any number of `:no-eval' (or 
`:no-value'),
   (ash
    :eval (ash 1 4)
    :eval (ash 16 -1))
-  (lsh
-   :eval (lsh 1 4)
-   :eval (lsh 16 -1))
   (logand
    :no-eval "(logand #b10 #b111)"
    :result-string "#b10")
diff --git a/lisp/subr.el b/lisp/subr.el
index ef6cc41f3b..510a77dbc8 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -524,7 +524,10 @@ was called."
   "Return VALUE with its bits shifted left by COUNT.
 If COUNT is negative, shifting is actually to the right.
 In this case, if VALUE is a negative fixnum treat it as unsigned,
-i.e., subtract 2 * `most-negative-fixnum' from VALUE before shifting it."
+i.e., subtract 2 * `most-negative-fixnum' from VALUE before shifting it.
+
+This function is provided for compatibility.  In new code, use `ash'
+instead."
   (when (and (< value 0) (< count 0))
     (when (< value most-negative-fixnum)
       (signal 'args-out-of-range (list value count)))