inserting links painlessly with abbrevs (part 1)

Whenever I mention an emacs variable or function for the first time I link it to an html page containing its documentation. The html page is generated from the actual documentation buffer I see in Emacs. That is so instead of just inferring what variables or functions I mention do based on how I use them or what I say about them, readers can actually see the official documentation for these functions in the exact way I can. The only problem is that the process of actually setting the link up on my end for me requires several steps. I need to look the symbol up with helpful-variable or, if it is a function or macro, helpful-function; then I need to convert the buffer to html using htmlize; and I need to save that htmlized buffer to a file in my documentation folder; and then I need to actually link my post to the documentation. That is quite the bit of work and something I am not too keen on doing for every variable or function I happen to reference. In this post I showcase how I leverage Emacs's abbrevs to automate this.

The idea is to write a function that jumps to a particular link, determines if it refer to a variable or function, takes an html "buffer snapshot" of its documentation, and saves it to a file in the appropriate place. In practice, this is what the workflow will look like: I type vlk (which stands for "variable link") followed by a space, Emacs prompts me for a variable to get the documentation from, then when I select the symbol, the abbrev will expand into a link pointing to the documentation of the symbol. Under the hood the function will check the documentation folder for documentation for the variable and make the link to that file. And if the documentation is not found it will open the documentation buffer for that variable, htmlize with htmlize-buffer, and write it to a file first. The result of all this is what I believe to be the most efficient documentation link possible. 

(defun oo-expand-variable-doc-link ()
  "Insert an org link to a helpful callable snapshot.
Find the appropriate documentation for the callable in the documentation
directory.  If it does not exist create it and add it."
  (let* ((doc-dir (expand-file-name "~/Documents/MyBlog/org/documentation/"))
         (helpful-switch-buffer-function #'identity)
         (symbol (helpful--read-symbol "Variable: " (helpful--variable-at-point) #'helpful--variable-p))
         (html-file (expand-file-name (format "%s-helpful-variable--%s.html" emacs-version symbol) doc-dir))
         (html-buffer nil))
    (unless (file-exists-p html-file)
      (setq help-buffer (helpful-variable symbol))
      (unless help-buffer (error "No help buffer."))
      (setq html-buffer (htmlize-buffer help-buffer))
      (unless html-buffer (error "No html buffer."))
      (with-current-buffer html-buffer
        (write-region (point-min) (point-max) html-file)
        (kill-buffer help-buffer)
        (kill-buffer)))
    (insert (format "[[file:%s][%s]]"  html-file symbol))))

For some added flair I name the file according to the Emacs version I am using so that if I upgrade my current Emacs version (29.4) to say Emacs 30, then.

To define the abbrev we specify the function as a hook. 

(define-abbrev global-abbrev-table "vlk" "" #'oo-expand-variable-doc-link :enable-function #'oo-in-blog-post-p)

This abbrev is specific to my blog posts. And I do not want it expanding anywhere but blog posts. Giving the abbrev vlk the :enable-property guarantees this. 

(defun oo-in-blog-post-p ()
  "Return non-nil if the current buffer is for one of my blog posts."
  (declare (pure t) (side-effect-free error-free))
  (and (derived-mode-p 'org-mode)
       (stringp default-directory)
       (string= (expand-file-name default-directory)
                (expand-file-name "~/Documents/MyBlog/org/posts/"))))

The process is similar to a function. 

(defun! oo-expand-callable-doc-link ()
  "Insert an org link to a helpful callable snapshot.
Find the appropriate documentation for the callable in the documentation
directory.  If it does not exist create it and add it."
  (set! doc-dir (expand-file-name "~/Documents/MyBlog/org/documentation/"))
  (set! helpful-switch-buffer-function #'identity)
  (set! symbol (helpful--read-symbol "Callable: " (helpful--callable-at-point) #'fboundp))
  (set! html-file (expand-file-name (format "%s-helpful-callable--%s.html" emacs-version symbol) doc-dir))
  (unless (file-exists-p html-file)
    (set! help-buffer (quiet! (helpful-callable symbol)))
    (quitif! (not help-buffer) "No help buffer.")
    (set! html-buffer (quiet! (htmlize-buffer help-buffer)))
    (quitif! (not html-buffer) "No html buffer.")
    (with-current-buffer html-buffer
      (quiet! (write-region (point-min) (point-max) html-file))
      (kill-buffer help-buffer)
      (kill-buffer)))
  (insert (format "[[file:%s][%s]]"  html-file symbol)))