I want to organize the functions in my Emacs configuration so that they are easier for me to test and so that other people can load them from my repository. Instead of copying multiple code blogs from my blog posts or my exported Emacs configuration, it would be great if people could just include a file from the repository. I don't think people copy that much from my config, but it might still be worth making it easier for people to borrow interesting functions. It would be great to have libraries of functions that people can evaluate without worrying about side effects, and then they can copy or write a shorter piece of code to use those functions.
In Prot's configuration (The custom libraries of my configuration), he includes each library as in full, in a single code block, with the boilerplate description, keywords, and (provide '...) that make them more like other libraries in Emacs.
I'm not quite sure my little functions are at that point yet. For now, I like the way that the functions are embedded in the blog posts and notes that explain them, and the org-babel :comments argument can insert links back to the sections of my configuration that I can open with org-open-at-point-global or org-babel-tangle-jump-to-org.
Thinking through the options...
Org tangles blocks in order, so if I want boilerplate or if I want to add require statements, I need to have a section near the beginning of my config that sets those up for each file. Noweb references might help me with common text like the license. Likewise, if I want a (provide ...) line at the end of each file, I need a section near the end of the file.
If I want to specify things out of sequence, I could use Noweb. By setting :noweb-ref some-id :tangle no on the blocks I want to collect later, I can then tangle them in the middle of the boilerplate. Here's a brief demo:
#+begin_src emacs-lisp :noweb yes :tangle lisp/sacha-eshell.el :comments no
<<sacha-eshell>>
(provide 'sacha-eshell)
#+end_src
However, I'll lose the comment links that let me jump back to the part of the Org file with the original source block. This means that if I use find-function to jump to the definition of a function and then I want to find the outline section related to it, I have to use a function that checks if this might be my custom code and then looks in my config for "defun …". It's a little less generic.
I wonder if I can combine multiple targets with some code that knows what it's being tangled to, so it can write slightly different text. org-babel-tangle-single-block currently calculates the result once and then adds it to the list for each filename, so that doesn't seem likely.
Alternatively, maybe I can use noweb or my own tangling function and add the link comments from org-babel-tangle-comments.
Aha, I can fiddle with org-babel-post-tangle-hook to insert the boilerplate after the blocks have been written. Then I can add the lexical-binding: t cookie and the structure that makes it look more like the other libraries people define and use. It's always nice when I can get away with a small change that uses an existing hook. For good measure, let's even include a list of links to the sections of my config that affect that file.
(defvar sacha-dotemacs-url "https://sachachua.com/dotemacs/")
(defun sacha-dotemacs-link-for-section-at-point (&optional combined)
"Return the link for the current section."
(let* ((custom-id (org-entry-get-with-inheritance "CUSTOM_ID"))
(title (org-entry-get (point) "ITEM"))
(url (if custom-id
(concat "dotemacs:" custom-id)
(concat sacha-dotemacs-url ":-:text=" (url-hexify-string title)))))
(if combined
(org-link-make-string
url
title)
(cons url title))))
(eval-and-compile
(require 'org-core nil t)
(require 'org-macs nil t)
(require 'org-src nil t))
(declare-function 'org-babel-tangle--compute-targets "ob-tangle")
(defun sacha-org-collect-links-for-tangled-files ()
"Return a list of ((filename (link link link link)) ...)."
(let* ((file (buffer-file-name))
results)
(org-babel-map-src-blocks (buffer-file-name)
(let* ((info (org-babel-get-src-block-info))
(link (sacha-dotemacs-link-for-section-at-point)))
(mapc
(lambda (target)
(let ((list (assoc target results #'string=)))
(if list
(cl-pushnew link (cdr list) :test 'equal)
(push (list target link) results))))
(org-babel-tangle--compute-targets file info))))
(nreverse
(mapcar (lambda (o)
(cons (car o)
(nreverse (cdr o))))
results))))
(defvar sacha-emacs-config-module-links nil "Cache for links from tangled files.")
(defun sacha-emacs-config-update-module-info ()
"Update the list of links."
(interactive)
(setq sacha-emacs-config-module-links
(seq-filter
(lambda (o)
(string-match "sacha-" (car o)))
(sacha-org-collect-links-for-tangled-files)))
(setq sacha-emacs-config-modules-info
(mapcar (lambda (group)
`(,(file-name-base (car group))
(commentary
.
,(replace-regexp-in-string
"^"
";; "
(concat
"Related Emacs config sections:\n\n"
(org-export-string-as
(mapconcat
(lambda (link)
(concat "- " (cdr link) "\\\\\n " (org-link-make-string (car link)) "\n"))
(cdr group)
"\n")
'ascii
t))))))
sacha-emacs-config-module-links)))
(defun sacha-emacs-config-prepare-to-tangle ()
"Update module info if tangling my config."
(when (string-match "Sacha.org" (buffer-file-name))
(sacha-emacs-config-update-module-info)))
Let's set up the functions for tangling the boilerplate.
(defvar sacha-emacs-config-modules-dir "~/sync/emacs/lisp/")
(defvar sacha-emacs-config-modules-info nil "Alist of module info.")
(defvar sacha-emacs-config-url "https://sachachua.com/dotemacs")
(defun sacha-org-babel-post-tangle-insert-boilerplate-for-sacha-lisp ()
(when (file-in-directory-p (buffer-file-name) sacha-emacs-config-modules-dir)
(goto-char (point-min))
(let ((base (file-name-base (buffer-file-name))))
(insert (format ";;; %s.el --- %s -*- lexical-binding: t -*-
;; Author: %s <%s>
;; URL: %s
;;; License:
;;
;; This file is not part of GNU Emacs.
;;
;; This is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;;
;; This is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
;;; Commentary:
;;
%s
;;; Code:
\n\n"
base
(or
(assoc-default 'description
(assoc-default base sacha-emacs-config-modules-info #'string=))
"")
user-full-name
user-mail-address
sacha-emacs-config-url
(or
(assoc-default 'commentary
(assoc-default base sacha-emacs-config-modules-info #'string=))
"")))
(goto-char (point-max))
(insert (format "\n(provide '%s)\n;;; %s.el ends here\n"
base
base))
(save-buffer))))
(setq sacha-emacs-config-url "https://sachachua.com/dotemacs")
(with-eval-after-load 'org
(add-hook 'org-babel-pre-tangle-hook #'sacha-emacs-config-prepare-to-tangle)
(add-hook 'org-babel-post-tangle-hook #'sacha-org-babel-post-tangle-insert-boilerplate-for-sacha-lisp))
You can see the results at .emacs.d/lisp. For example, the function definitions in this post are at lisp/sacha-emacs.el.
