https://github.com/p3r7/clojure-essential-ref
🔖 cider-doc to "Clojure, The Essential Reference"
https://github.com/p3r7/clojure-essential-ref
cider clojure documentation emacs
Last synced: 6 months ago
JSON representation
🔖 cider-doc to "Clojure, The Essential Reference"
- Host: GitHub
- URL: https://github.com/p3r7/clojure-essential-ref
- Owner: p3r7
- License: mit
- Created: 2020-06-04T09:35:55.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2022-12-15T14:27:51.000Z (about 3 years ago)
- Last Synced: 2025-08-16T03:51:07.864Z (6 months ago)
- Topics: cider, clojure, documentation, emacs
- Language: Emacs Lisp
- Homepage:
- Size: 80.1 KB
- Stars: 47
- Watchers: 5
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# clojure-essential-ref
Emacs packages providing commands to browse the Clojure documentation of a symbol in book [Clojure, The Essential Reference](https://livebook.manning.com/book/clojure-the-essential-reference/):
- `clojure-essential-ref`: browse the default way (see _Configuration_)
- `clojure-essential-ref-web`: browse online in the web version of the book (_liveBook_)
- `clojure-essential-ref-nov`: browse offline in a local ebook (provided by optional sibling package `clojure-essential-ref-nov`, depends on [nov.el](https://depp.brause.cc/nov.el/))
They require a CIDER session to be launched to perform fully-qualified symbol resolution. Likewise, the source file must be known to CIDER. So, when adding a new source file during interactive development your might need to re-evaluate a `require` of this source file or even `cider-eval-buffer` it.
They behave similarly to `cider-clojuredocs-web`, including the default proposal of _symbol-at-point_. They are a nice companion to the latter (alongside `cider-doc`).
For more context, read the [accompanying blog post](https://www.eigenbahn.com/2020/06/04/emacs-clojure-essential-ref).
## Installation
To get only the web browsing mode:
```el
(use-package clojure-essential-ref)
```
[](https://melpa.org/#/clojure-essential-ref)
[](https://stable.melpa.org/#/clojure-essential-ref)
To also get the offline ebook browsing mode (depends on [nov.el](https://depp.brause.cc/nov.el/)):
```el
(use-package clojure-essential-ref-nov
:init
(setq clojure-essential-ref-nov-epub-path "~/Downloads/Clojure_The_Essential_Reference_v29_MEAP.epub"))
```
[](https://melpa.org/#/clojure-essential-ref-nov)
[](https://stable.melpa.org/#/clojure-essential-ref-nov)
## Configuration
#### ebook file
The offline ebook browing mode needs you to configure the path to the book (EPUB format):
```el
(use-package clojure-essential-ref-nov
;; ...
:init
(setq clojure-essential-ref-nov-epub-path "~/Downloads/Clojure_The_Essential_Reference_v29_MEAP.epub")
```
#### Default browsing mode
The default browing mode (command `clojure-essential-ref`) is the online _liveBook_.
To use the offline ebook browing mode instead:
```el
(use-package clojure-essential-ref-nov
;; ...
:init
(setq clojure-essential-ref-default-browse-fn #'clojure-essential-ref-nov-browse)
```
## Usage
Under a CIDER session, just call the command:
M-x clojure-essential-ref
For convenience sake, you can bind it to a keyboard shortcut:
```el
(use-package clojure-essential-ref
;; ...
:bind (
:map cider-mode-map
("C-h F" . clojure-essential-ref)
:map cider-repl-mode-map
("C-h F" . clojure-essential-ref)))
```
## Legibility
This code uses form feeds (`^L` character) as separators.
Either package [form-feed](https://github.com/wasamasa/form-feed) or [page-break-lines](https://github.com/purcell/page-break-lines) makes them appear as intended.