clojure-essential-ref

Emacs packages providing commands to browse the Clojure documentation of a symbol in 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)

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.

Installation

To get only the web browsing mode:

(use-package clojure-essential-ref)

To also get the offline ebook browsing mode (depends on nov.el):

(use-package clojure-essential-ref-nov
  :init
  (setq clojure-essential-ref-nov-epub-path "~/Downloads/Clojure_The_Essential_Reference_v29_MEAP.epub"))

Configuration

ebook file

The offline ebook browing mode needs you to configure the path to the book (EPUB format):

(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:

(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:

(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 or page-break-lines makes them appear as intended.