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.

diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 1514ece6d1f9028eea65a50170998aa42c9c8c5e..05b3361cb3d265cf7c8c5603540818c18caf3c8d 100644 (file)
--- 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 ef6cc41f3b9c6ccfaedb3c39e83f8f5b87e27972..510a77dbc8d1e52534a2d1e020210c26bd1af908 100644 (file)
--- 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)))