helpful

a fork of Wilfred's helpful
git clone https://git.trogloxene.org/helpful.git
Log | Files | Refs | README

README.md (3965B)

      1 # Helpful [![Coverage Status](https://coveralls.io/repos/github/Wilfred/helpful/badge.svg?branch=master)](https://coveralls.io/github/Wilfred/helpful?branch=master) [![MELPA](http://melpa.org/packages/helpful-badge.svg)](http://melpa.org/#/helpful)
      2 
      3 Helpful is an alternative to the built-in Emacs help that provides
      4 much more contextual information.
      5 
      6 ![screenshot](screenshots/helpful.png)
      7 
      8 ## Usage
      9 
     10 Install from MELPA, then call one of the following commands:
     11 
     12 * `helpful-callable`
     13 * `helpful-function`
     14 * `helpful-macro`
     15 * `helpful-command`
     16 * `helpful-key`
     17 * `helpful-variable`
     18 * `helpful-at-point`
     19 
     20 If you want to replace the default Emacs help keybindings, you can do
     21 so:
     22 
     23 ``` emacs-lisp
     24 ;; Note that the built-in `describe-function' includes both functions
     25 ;; and macros. `helpful-function' is functions only, so we provide
     26 ;; `helpful-callable' as a drop-in replacement.
     27 (global-set-key (kbd "C-h f") #'helpful-callable)
     28 
     29 (global-set-key (kbd "C-h v") #'helpful-variable)
     30 (global-set-key (kbd "C-h k") #'helpful-key)
     31 (global-set-key (kbd "C-h x") #'helpful-command)
     32 ```
     33 
     34 I also recommend the following keybindings to get the most out of
     35 helpful:
     36 
     37 ``` emacs-lisp
     38 ;; Lookup the current symbol at point. C-c C-d is a common keybinding
     39 ;; for this in lisp modes.
     40 (global-set-key (kbd "C-c C-d") #'helpful-at-point)
     41 
     42 ;; Look up *F*unctions (excludes macros).
     43 ;;
     44 ;; By default, C-h F is bound to `Info-goto-emacs-command-node'. Helpful
     45 ;; already links to the manual, if a function is referenced there.
     46 (global-set-key (kbd "C-h F") #'helpful-function)
     47 ```
     48 
     49 [Ivy](https://github.com/abo-abo/swiper) users can use Helpful with
     50 counsel commands:
     51 
     52 ``` emacs-lisp
     53 (setq counsel-describe-function-function #'helpful-callable)
     54 (setq counsel-describe-variable-function #'helpful-variable)
     55 ```
     56 
     57 ## Features
     58 
     59 ### Source code
     60 
     61 ![screenshot](screenshots/helpful_source.png)
     62 
     63 Helpful will try really hard to show the source code. It shows the
     64 source code for interactively defined functions (unlike the built-in
     65 Help) and falls back to the raw sexp if no source is available.
     66 
     67 ### View Callers
     68 
     69 ![screenshot](screenshots/helpful_refs.png)
     70 
     71 Helpful will show you where a function is being called!
     72 
     73 ### Prettier Docstrings
     74 
     75 ![screenshot](screenshots/helpful_docstring.png)
     76 
     77 Docstrings in helpful:
     78 
     79 * Highlight the summary (the first sentence)
     80 * Include cross-references to other functions/variables
     81 * Linkify references to Info nodes
     82 * Hide superfluous punctuation
     83 
     84 ![screenshot](screenshots/helpful_view_in_manual.png)
     85 
     86 If a symbol is also documented in the Info manual, helpful will
     87 provide a link to the relevant section too.
     88 
     89 ### Symbol Properties
     90 
     91 ![screenshot](screenshots/helpful_props.png)
     92 
     93 Helpful will show you the properties that have been applied to the
     94 current symbol. This provides visibility of features
     95 like edebug or byte-code optimisation.
     96 
     97 Helpful will also highlight any symbol aliases.
     98 
     99 ### Describe Commands
    100 
    101 Helpful provides a separate `helpful-command` function, for when you
    102 just want to view interactive functions.
    103 
    104 ### View Keymaps
    105 
    106 ![screenshot](screenshots/helpful_bindings.png)
    107 
    108 Helpful displays any keybindings that apply to interactive functions.
    109 
    110 ### Integrated Tooling
    111 
    112 ![screenshot](screenshots/helpful_tools.png)
    113 
    114 You can trace, debug or disassemble functions from inside
    115 Helpful. This is discoverable and doesn't require memorisation of
    116 commands.
    117 
    118 ### Aliases
    119 
    120 ![screenshot](screenshots/helpful_aliases.png)
    121 
    122 If a function has multiple aliases in Emacs, Helpful will show all of
    123 the aliases defined.
    124 
    125 ## Inspirations
    126 
    127 This project has been heavily influenced by:
    128 
    129 * [help+.el](https://www.emacswiki.org/emacs/help+.el), help-fns+.el, help-mode+.el
    130 * [Dave Williams' demo of Lucid's Energize](https://www.youtube.com/watch?v=pQQTScuApWk)
    131 
    132 ## License
    133 
    134 GPLv3+.
    135 
    136 I am providing code in the repository to you under an open source
    137 license. Because this is my personal repository, the license you
    138 receive to my code is from me and not my employer.