refactor!: move helpful from :core to :lang emacs-lisp

BREAKING CHANGE: This moves helpful.el out of core into :lang
emacs-lisp. Since most (all) people have this module enabled, this
shouldn't make a difference for most people, but if you're one of the
few that don't have :lang emacs-lisp enabled, Doom will revert to using
Emacs' built-in help.el and describe-* commands.

Others can also disable helpful with (package! helpful :disable t) if
they prefer Emacs' built-in help system, which wasn't possible before,
because it was a core package.

This was done as part of an ongoing effort to slim down Doom's core in
preparation for v3.

modules/lang/emacs-lisp/autoload.el

@@ -116,8 +116,14 @@ if it's callable, `apropos' otherwise."
                            '(outline org-fold-outline))
                  (org-show-hidden-entry))))
            'deferred))
-        (thing (helpful-symbol (intern thing)))
-        ((call-interactively #'helpful-at-point))))
+        (thing
+         (funcall (or (command-remapping #'describe-symbol)
+                      #'describe-symbol)
+                  (intern thing)))
+        ((call-interactively
+          (if (fboundp #'helpful-at-point)
+              #'helpful-at-point
+            #'describe-symbol)))))
 
 ;; DEPRECATED Remove when 28 support is dropped.
 (unless (fboundp 'lisp--local-defform-body-p)

modules/lang/emacs-lisp/config.el

@@ -261,6 +261,77 @@ See `+emacs-lisp-non-package-mode' for details.")
         "s" #'buttercup-run-at-point))
 
 
+(use-package! helpful
+  ;; a better *help* buffer
+  :commands helpful--read-symbol
+  :hook (helpful-mode . visual-line-mode)
+  :init
+  ;; Make `apropos' et co search more extensively. They're more useful this way.
+  (setq apropos-do-all t)
+
+  (global-set-key [remap describe-function] #'helpful-callable)
+  (global-set-key [remap describe-command]  #'helpful-command)
+  (global-set-key [remap describe-variable] #'helpful-variable)
+  (global-set-key [remap describe-key]      #'helpful-key)
+  (global-set-key [remap describe-symbol]   #'helpful-symbol)
+
+  (defun doom-use-helpful-a (fn &rest args)
+    "Force FN to use helpful instead of the old describe-* commands."
+    (letf! ((#'describe-function #'helpful-function)
+            (#'describe-variable #'helpful-variable))
+      (apply fn args)))
+
+  (after! apropos
+    ;; patch apropos buttons to call helpful instead of help
+    (dolist (fun-bt '(apropos-function apropos-macro apropos-command))
+      (button-type-put
+       fun-bt 'action
+       (lambda (button)
+         (helpful-callable (button-get button 'apropos-symbol)))))
+    (dolist (var-bt '(apropos-variable apropos-user-option))
+      (button-type-put
+       var-bt 'action
+       (lambda (button)
+         (helpful-variable (button-get button 'apropos-symbol))))))
+
+  ;; DEPRECATED: Remove when support for 29 is dropped.
+  (when (= emacs-major-version 29)
+    (defadvice! doom--find-function-search-for-symbol-save-excursion-a (fn &rest args)
+      "Suppress cursor movement by `find-function-search-for-symbol'.
+
+Addresses an unwanted side-effect in `find-function-search-for-symbol' on Emacs
+29 where the cursor is moved to a variable's definition if it's defined in the
+current buffer."
+      :around #'find-function-search-for-symbol
+      (let (buf pos)
+        (letf! (defun find-library-name (library)
+                 (let ((filename (funcall find-library-name library)))
+                   (with-current-buffer (find-file-noselect filename)
+                     (setq buf (current-buffer)
+                           pos (point)))
+                   filename))
+          (prog1 (apply fn args)
+            (when (buffer-live-p buf)
+              (with-current-buffer buf (goto-char pos))))))))
+  :config
+  (setq helpful-set-variable-function #'setq!)
+
+  (cond ((modulep! :completion ivy)
+         (setq counsel-describe-function-function #'helpful-callable
+               counsel-describe-variable-function #'helpful-variable
+               counsel-descbinds-function #'helpful-callable))
+        ((modulep! :completion helm)
+         (dolist (fn '(helm-describe-variable helm-describe-function))
+           (advice-add fn :around #'doom-use-helpful-a))))
+
+  ;; Open help:* links with helpful-* instead of describe-*
+  (advice-add #'org-link--open-help :around #'doom-use-helpful-a)
+
+  (map! :map helpful-mode-map
+        :ng "o"  #'link-hint-open-link
+        :n  "gr" #'helpful-update))
+
+
 ;;
 ;;; Project modes
 

modules/lang/emacs-lisp/packages.el

@@ -7,6 +7,7 @@
 (package! highlight-quoted :pin "24103478158cd19fbcfb4339a3f1fa1f054f1469")
 
 ;; Tools
+(package! helpful :pin "4ba24cac9fb14d5fdc32582cd947572040e82b2c")
 (package! macrostep :pin "4939d88779761e8b5461b4cf73f86600172987db")
 (package! overseer :pin "7fdcf1a6fba6b1569a09c1666b4e51bcde266ed9")
 (package! elisp-def :pin "1ad4baccbf3d0d13e7607d332ae6bc60a5dd7360")

modules/lang/org/config.el

@@ -540,9 +540,9 @@ relative to `org-directory', unless it is an absolute path."
   ;; documentation -- especially Doom's!
   (letf! ((defun -call-interactively (fn)
             (lambda (path _prefixarg)
-              (funcall
-               fn (or (intern-soft path)
-                      (user-error "Can't find documentation for %S" path))))))
+              (funcall (or (command-remapping fn) fn)
+                       (or (intern-soft path)
+                           (user-error "Can't find documentation for %S" path))))))
     (org-link-set-parameters
      "kbd"
      :follow (lambda (ev)
@@ -553,12 +553,12 @@ relative to `org-directory', unless it is an absolute path."
      :face 'help-key-binding)
     (org-link-set-parameters
      "var"
-     :follow (-call-interactively #'helpful-variable)
+     :follow (-call-interactively #'describe-variable)
      :activate-func #'+org-link--var-link-activate-fn
      :face '(font-lock-variable-name-face underline))
     (org-link-set-parameters
      "fn"
-     :follow (-call-interactively #'helpful-callable)
+     :follow (-call-interactively #'describe-function)
      :activate-func #'+org-link--fn-link-activate-fn
      :face '(font-lock-function-name-face underline))
     (org-link-set-parameters
@@ -739,9 +739,6 @@ mutating hooks on exported output, like formatters."
   (add-to-list 'org-file-apps '(directory . emacs))
   (add-to-list 'org-file-apps '(remote . emacs))
 
-  ;; Open help:* links with helpful-* instead of describe-*
-  (advice-add #'org-link--open-help :around #'doom-use-helpful-a)
-
   ;; Some uses of `org-fix-tags-on-the-fly' occur without a check on
   ;; `org-auto-align-tags', such as in `org-self-insert-command' and
   ;; `org-delete-backward-char'.