254 lines
9.2 KiB
Org Mode
254 lines
9.2 KiB
Org Mode
#+title: :tools lookup
|
|
#+subtitle: Navigate your labyrinthine code and docs
|
|
#+created: January 04, 2018
|
|
#+since: 2.0.9
|
|
|
|
* Description :unfold:
|
|
This module adds code navigation and documentation lookup tools to help you
|
|
quickly look up definitions, references, documentation, dictionary definitions
|
|
or synonyms.
|
|
|
|
- Jump-to-definition and find-references implementations that just work.
|
|
- Powerful xref integration for languages that support it.
|
|
- Search online providers like [[https://devdocs.io][devdocs.io]], [[https://stackoverflow.com][stackoverflow]], [[https://google.com][google]], [[https://duckduckgo.com][duckduckgo]], or
|
|
[[https://youtube.com][youtube]] (duckduckgo and google have live suggestions).
|
|
- Integration with [[https://github.com/Kapeli/feeds][Dash.app docsets]].
|
|
- Support for online (and offline) dictionaries and thesauruses.
|
|
|
|
** Maintainers
|
|
- [[doom-user:][@hlissner]]
|
|
|
|
[[doom-contrib-maintainer:][Become a maintainer?]]
|
|
|
|
** Module flags
|
|
- +dictionary ::
|
|
Enable word definition and thesaurus lookup functionality.
|
|
- +docsets ::
|
|
Enable integration with Dash.app docsets.
|
|
- +offline ::
|
|
Install and prefer offline dictionary/thesaurus (with [[doom-module:+dictionary]]).
|
|
|
|
** Packages
|
|
- [[doom-package:dumb-jump]]
|
|
- [[doom-package:helm-xref]] if [[doom-module::completion helm]]
|
|
- [[doom-package:ivy-xref]] if [[doom-module::completion ivy]]
|
|
- [[doom-package:request]]
|
|
- if [[doom-module:+docsets]]
|
|
- [[doom-package:dash-docs]]
|
|
- [[doom-package:counsel-dash]] if [[doom-module::completion ivy]]
|
|
- [[doom-package:helm-dash]] if [[doom-module::completion helm]]
|
|
- if [[doom-module:+dictionary]]
|
|
- if macOS
|
|
- [[doom-package:osx-dictionary]]
|
|
- else
|
|
- [[doom-package:define-word]]
|
|
- [[doom-package:powerthesaurus]]
|
|
- if [[doom-module:+offline]]
|
|
- [[doom-package:wordnut]]
|
|
- [[doom-package:synosaurus]]
|
|
|
|
** Hacks
|
|
/No hacks documented for this module./
|
|
|
|
** TODO Changelog
|
|
# This section will be machine generated. Don't edit it by hand.
|
|
/This module does not have a changelog yet./
|
|
|
|
* Installation
|
|
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
|
|
|
|
This module has several optional dependencies:
|
|
|
|
- ~ripgrep~ as a last-resort fallback for jump-to-definition/find-references.
|
|
- ~sqlite3~ for Dash docset support (if you have [[doom-module:+docsets]] enabled)
|
|
- ~wordnet~ for offline dictionary and thesaurus support (if you have
|
|
[[doom-module:+dictionary]] and [[doom-module:+offline]] enabled).
|
|
|
|
** MacOS
|
|
#+begin_src sh
|
|
brew install ripgrep wordnet
|
|
|
|
# An older version of sqlite is included in MacOS. If it causes you problems (and
|
|
# folks have reported it will), install it through homebrew:
|
|
brew install sqlite
|
|
# Note that it's keg-only, meaning it isn't symlinked to /usr/local/bin. You'll
|
|
# have to add it to PATH yourself (or symlink it into your PATH somewhere). e.g.
|
|
export PATH="/usr/local/opt/sqlite/bin:$PATH"
|
|
#+end_src
|
|
|
|
** Arch Linux
|
|
#+begin_src sh
|
|
sudo pacman -S sqlite ripgrep
|
|
yay -S wordnet-cli
|
|
#+end_src
|
|
|
|
** NixOS
|
|
#+begin_src nix
|
|
environment.systemPackages = with pkgs; [
|
|
ripgrep
|
|
sqlite
|
|
wordnet
|
|
];
|
|
#+end_src
|
|
|
|
* Usage
|
|
** Jump to definition
|
|
Use ~+lookup/definition~ (bound to [[kbd:][gd]] in normal mode) to jump to the definition
|
|
of the symbol at point.
|
|
|
|
This module provides a goto-definition implementation that will try the
|
|
following sources before giving up:
|
|
|
|
1. Whatever ~:definition~ function is registered for the current buffer with the
|
|
~:lookup~ setting (see "Configuration" section).
|
|
2. Any available xref backends.
|
|
3. [[doom-package:dumb-jump]] (a text search with aides to reduce false positives).
|
|
3. An ordinary project-wide text search with =ripgrep=.
|
|
5. If ~evil-mode~ is active, use ~evil-goto-definition~, which preforms a simple
|
|
text search within the current buffer.
|
|
|
|
If there are multiple results, you will be prompted to select one.
|
|
|
|
** Find references
|
|
Use ~+lookup/references~ (bound to [[kbd:][gD]] in normal mode) to see a list of
|
|
references for the symbol at point from throughout your project.
|
|
|
|
Like ~+lookup/definition~, this tries a number of sources before giving up. It
|
|
will try:
|
|
|
|
1. Whatever ~:references~ function is registered for the current buffer with the
|
|
~:lookup~ setting (see [[*Configuration][Configuration]]).
|
|
2. Any available [[doom-package:xref]] backends.
|
|
3. An ordinary project-wide text search with ripgrep.
|
|
|
|
If there are multiple results, you will be prompted to select one.
|
|
|
|
** Look up documentation
|
|
~+lookup/documentation~ (bound to [[kbd:][K]] in normal mode) will open documentation for
|
|
the symbol at point.
|
|
|
|
Depending on your configuration, this will try a list of sources:
|
|
|
|
1. Whatever ~:documentation~ function is registered for the current buffer with
|
|
the ~:lookup~ setting (see "Configuration" section).
|
|
2. Any Dash.app docsets, if any are installed for the current major mode.
|
|
3. devdocs.io, if it has a docset for the current mode.
|
|
4. An online search; using the last engine used (it will prompt you the first
|
|
time, or if ~current-prefix-arg~ is non-nil).
|
|
|
|
** Search a specific documentation backend
|
|
You can perform a documentation lookup on any backends directly:
|
|
|
|
+ Dash Docsets: ~+lookup/in-docsets~, or ~:dash QUERY~ for evil users.
|
|
+ Online (generic): ~+lookup/online~ or ~+lookup/online-select~ (bound to [[kbd:][SPC /
|
|
o]]), or ~:lo[okup] QUERY~ for evil users.
|
|
|
|
** Dash.app Docset integration
|
|
You can install dash docsets with ~M-x dash-docs-install-docset~ and search
|
|
them offline with ~M-x +lookup/in-docsets~, or with ~+lookup/documentation~ in
|
|
modes that don't have a specialized :documentation lookup handler.
|
|
|
|
* Configuration
|
|
** Associating lookup handlers with major modes
|
|
~set-lookup-handlers! MODES &key DEFINITION REFERENCES DOCUMENTATION FILE
|
|
XREF-BACKEND ASYNC~
|
|
|
|
Use ~set-lookup-handlers!~ to register lookup targets for MODES (a major or
|
|
minor mode symbol or list thereof). PLIST accepts the following optional
|
|
properties:
|
|
|
|
- ~:definition FN~ ::
|
|
Run when jumping to a symbol's definition. Used by ~+lookup/definition~.
|
|
- ~:references FN~ ::
|
|
Run when looking for usage references of a symbol in the current project. Used
|
|
by ~+lookup/references~.
|
|
- ~:documentation FN~ ::
|
|
Run when looking up documentation for a symbol. Used by
|
|
~+lookup/documentation~.
|
|
- ~:file FN~ ::
|
|
Run when looking up the file for a symbol/string. Typically a file path. Used
|
|
by ~+lookup/file~.
|
|
- ~:xref-backend FN~ ::
|
|
Defines an [[doom-package:xref]] backend, which implicitly provides ~:definition~ and
|
|
~:references~ handlers. If you specify them anyway, they will take precedence
|
|
over the xref backend, however.
|
|
|
|
E.g.
|
|
#+begin_src emacs-lisp
|
|
;; For python-mode, anaconda-mode offers a backend for all three lookup
|
|
;; functions. We can register them like so:
|
|
(set-lookup-handlers! 'python-mode
|
|
:definition #'anaconda-mode-find-definitions
|
|
:references #'anaconda-mode-find-references
|
|
:documentation #'anaconda-mode-show-doc)
|
|
|
|
;; If a language or plugin provides a custom xref backend available for it, use
|
|
;; that instead. It will provide the best jump-to-definition and find-references
|
|
;; experience. You can specify custom xref backends with:
|
|
(set-lookup-handlers! 'js2-mode :xref-backend #'xref-js2-xref-backend)
|
|
;; NOTE: xref doesn't provide a :documentation backend.
|
|
#+end_src
|
|
|
|
** Associating Dash docsets with major modes
|
|
~set-docsets! MODES &rest DOCSETS...~
|
|
|
|
Use ~set-docsets!~ to register DOCSETS (one string or list of strings) for MODES
|
|
(one major mode symbol or a list of them). It is used by ~+lookup/in-docsets~
|
|
and ~+lookup/documentation~.
|
|
|
|
E.g.
|
|
#+begin_src emacs-lisp
|
|
(set-docsets! 'js2-mode "JavaScript" "JQuery")
|
|
;; Add docsets to minor modes by starting DOCSETS with :add
|
|
(set-docsets! 'rjsx-mode :add "React")
|
|
;; Or remove docsets from minor modes
|
|
(set-docsets! 'nodejs-mode :remove "JQuery")
|
|
#+end_src
|
|
|
|
This determines what docsets to implicitly search for when you use
|
|
~+lookup/documentation~ in a mode with no ~:documentation~ handler. Those
|
|
docsets must be installed with ~dash-docs-install-docset~.
|
|
|
|
** Open in eww instead of browser
|
|
~+lookup/online~ opens the search results with in ~+lookup-open-url-fn~
|
|
(default: ~#'browse-url~). Here is how to change this to EWW (so it opens inside
|
|
Emacs):
|
|
#+begin_src emacs-lisp
|
|
(setq +lookup-open-url-fn #'eww)
|
|
#+end_src
|
|
|
|
#+begin_quote
|
|
~+lookup/in-docsets~ consults ~dash-docs-browser-func~ instead, which is
|
|
already set to ~#'eww~ by default.
|
|
#+end_quote
|
|
|
|
** Open in Xwidget WebKit instead of browser
|
|
To open results from ~+lookup/online~ or ~+lookup/in-docsets~ in Xwidget WebKit
|
|
instead of your system browser, set ~+lookup-open-url-fn~ and/or
|
|
~dash-docs-browser-func~ to ~+lookup-xwidget-webkit-open-url-fn~ (needs Emacs
|
|
with Xwidgets support):
|
|
#+begin_src emacs-lisp
|
|
(setq +lookup-open-url-fn #'+lookup-xwidget-webkit-open-url-fn)
|
|
(after! dash-docs
|
|
(setq dash-docs-browser-func #'+lookup-xwidget-webkit-open-url-fn))
|
|
#+end_src
|
|
|
|
* Troubleshooting
|
|
/There are no known problems with this module./ [[doom-report:][Report one?]]
|
|
|
|
* Frequently asked questions
|
|
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
|
|
|
|
* TODO Appendix
|
|
#+begin_quote
|
|
/This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]]
|
|
#+end_quote
|
|
|
|
** Commands
|
|
- ~+lookup/definition~
|
|
- ~+lookup/references~
|
|
- ~+lookup/documentation~
|
|
- ~+lookup/online~
|
|
- ~+lookup/online-select~
|
|
- ~+lookup/in-devdocs~
|
|
- ~+lookup/in-docsets~
|