RSS | Source | License

View Local HTML Manual in Helpful

Table of Contents

Wilfred’s helpful package (no pun intended) lets you view symbols in manual in Emacs by clicking the “View in Manual” button. However, I prefer the online HTML manual since it looks much nicer in terms of type setting.

Online HTML manuals comes with their problems, too. They are for the latest released version of Emacs, that’s 26.3 at the time of writing. I’ve been using Emacs 27 for it’s new features and, of course, the documentation for those changes are not in the online manual. So I need to view the local manual that comes with Emacs source code.

Local manual

Luckily both tasks are trivial. We first export our local Emacs Lisp Reference Manual. The TexInfo source is located under <emacs source>/doc/lispref. To export them to a HTML site, cd to that directory and run

make -e HTML_OPTS="--html --css-ref=./manual.css" elisp.html

By default HTML_OPTS includes a flag --no-split which exports everything into a single HTML file. Clearly we don’t want that. Also the exported HTML files doesn’t have the pretty CSS style we see in online versions. I didn’t bother to figure out why. Instead I pulled the CSS files down and made the exported manual pages use that. You can get it here. After export is done you will see a directory named elisp.html, put the CSS file under it. Record the path to this directory, we will use it later.

Hack helpful

Now we hack helpful to open our local manual rather than the builtin one. It’s relatively straight forward, we just need to hijack helpful--manual, which does the work of opening manual page for a symbol button.

(defvar helpful-html-manual-dir "/Users/yuan/emacs/doc/lispref/elisp.html"
  "Absolute path to the directory where HTML manuals are.")

(define-minor-mode helpful-html-manual-mode
  "View HTML manuals in helpful."
  :lighter ""
  :global t
  (if helpful-html-manual-mode
      (advice-add #'helpful--manual :override #'helpful--html-manual)
    (advice-remove #'helpful--manual #'helpful--html-manual)))

(defun helpful--html-manual (button)
  "Open the HTML manual for the symbol that this BUTTON represents."
  (let ((sym (symbol-name (button-get button 'symbol)))
        (index-file (expand-file-name "Index.html" helpful-html-manual-dir))
      (insert-file-contents index-file)
      (goto-char (point-min))
      (if (not (re-search-forward
                (format "<a href=\"\\(.*\\)\"><code>%s</code>" sym) nil t))
          (message "No manual index for %s" sym)
        (message "%s" (setq manual-page (expand-file-name
                                         (match-string 1) helpful-html-manual-dir)))
        (browse-url (format "file://%s" manual-page))))))

Change helpful-html-manual-dir to the directory we just recorded. Then just M-x helpful-html-manual-mode RET. Now clicking the “View in Manual” button opens the local manual page in a browser.

Written by Yuan Fu <casouri@gmail.com>

First Published on 2020-03-16 Mon 16:09

Last modified on 2020-06-21 Sun 18:50