Skip to content

Wilfred/helpful

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

Prior to this commit, setting attribute :extend of the face
helpful--heading to t did not take any effect. This is fixed by this
commit by propertizing the newline right after the heading as well.
32cb28b

Git stats

Files

Permalink
Failed to load latest commit information.

Helpful Coverage Status MELPA

Helpful is an alternative to the built-in Emacs help that provides much more contextual information.

screenshot

Usage

Install from MELPA, then call one of the following commands:

  • helpful-callable
  • helpful-function
  • helpful-macro
  • helpful-command
  • helpful-key
  • helpful-variable
  • helpful-at-point

If you want to replace the default Emacs help keybindings, you can do so:

;; Note that the built-in `describe-function' includes both functions
;; and macros. `helpful-function' is functions only, so we provide
;; `helpful-callable' as a drop-in replacement.
(global-set-key (kbd "C-h f") #'helpful-callable)

(global-set-key (kbd "C-h v") #'helpful-variable)
(global-set-key (kbd "C-h k") #'helpful-key)
(global-set-key (kbd "C-h x") #'helpful-command)

I also recommend the following keybindings to get the most out of helpful:

;; Lookup the current symbol at point. C-c C-d is a common keybinding
;; for this in lisp modes.
(global-set-key (kbd "C-c C-d") #'helpful-at-point)

;; Look up *F*unctions (excludes macros).
;;
;; By default, C-h F is bound to `Info-goto-emacs-command-node'. Helpful
;; already links to the manual, if a function is referenced there.
(global-set-key (kbd "C-h F") #'helpful-function)

Ivy users can use Helpful with counsel commands:

(setq counsel-describe-function-function #'helpful-callable)
(setq counsel-describe-variable-function #'helpful-variable)

Features

Source code

screenshot

Helpful will try really hard to show the source code. It shows the source code for interactively defined functions (unlike the built-in Help) and falls back to the raw sexp if no source is available.

View Callers

screenshot

Helpful will show you where a function is being called!

Prettier Docstrings

screenshot

Docstrings in helpful:

  • Highlight the summary (the first sentence)
  • Include cross-references to other functions/variables
  • Linkify references to Info nodes
  • Hide superfluous punctuation

screenshot

If a symbol is also documented in the Info manual, helpful will provide a link to the relevant section too.

Symbol Properties

screenshot

Helpful will show you the properties that have been applied to the current symbol. This provides visibility of features like edebug or byte-code optimisation.

Helpful will also highlight any symbol aliases.

Describe Commands

Helpful provides a separate helpful-command function, for when you just want to view interactive functions.

View Keymaps

screenshot

Helpful displays any keybindings that apply to interactive functions.

Integrated Tooling

screenshot

You can trace, debug or disassemble functions from inside Helpful. This is discoverable and doesn't require memorisation of commands.

Aliases

screenshot

If a function has multiple aliases in Emacs, Helpful will show all of the aliases defined.

Inspirations

This project has been heavily influenced by:

License

GPLv3+.

I am providing code in the repository to you under an open source license. Because this is my personal repository, the license you receive to my code is from me and not my employer.