diff --git a/elisp/um.el b/elisp/um.el index b2bfa92..e53189a 100644 --- a/elisp/um.el +++ b/elisp/um.el @@ -1,19 +1,25 @@ -;;; uldb.el --- An ultralight database for composition. -*- lexical-binding: t -*- +;;; um.el --- An Ultralight database for Markdown composition. -*- lexical-binding: t -*- ;; by bth -;; An ultralight database for writing and project composition, using only unique -;; filenames, POSIX filesystem conventions, and the builtin `project' package. +;; Um is an ultralight database design and emacs toolkit for organizing writing +;; into larger compositions. It uses only unique filenames, POSIX filesystem +;; conventions, the builtin `project' package, and standard POSIX commandline +;; tools to build out the CLI. + +;; It consists of two parts: +;; 1. The elisp for functionality within emacs. +;; 2. Bash scripts for the commandline interface. ;; This is somewhat like org-roam, except without any database dependency. (And -;; it uses Markdown rather than org, which I don't care for.) +;; it assumes Markdown rather than org, which I don't care for.) ;; This depends on a few simple ideas: ;; 1. A numbered filename specification which serves as unique id. ;; 2. Placing that same id into the file header, so that concatenated files -;; have reference back to their source. See the `mdcat' utility. +;; have reference back to their source. See the `um cat` command. ;; 3. Using a source "journal/" directory, where source files should first be ;; composed and where we can assume a file exists if not elsewhere. @@ -24,38 +30,38 @@ ;; 5. (Optional) Use `embark' to visit files with a single keystroke. ;; features provided: -;; `uldb-journal-header' defines the standard header +;; `um-journal-header' defines the standard header -;; `uldb-project-find-meta' via `project-switch-project': open a file like +;; `um-project-find-meta' via `project-switch-project': open a file like ;; *meta.md in a given project. -;; `uldb-file-at-point-advice' via `embark-dwim': open file in known projects +;; `um-file-at-point-advice' via `embark-dwim': open file in known projects ;; with fallback to journal/ -;; `uldb-grep-tag': search files with same tag +;; `um-grep-tag': search files with same tag (require 'package) ;; Primary path glob for the journal. This allows various mountpoints. -(setq uldb-journal-path-glob ".*/writing/journal") +(setq um-journal-path-glob ".*/writing/journal") ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; journal header -(defun uldb-iso-8601 () +(defun um-iso-8601 () "Insert a date stamp in ISO 8601 order, but with periods in place of dashes." (format-time-string "%Y.%m.%d") ) -(defun uldb-journal-header () - "Create a uldb-journal-header composed of: +(defun um-journal-header () + "Create a um-journal-header composed of: # buffer-name minus the .md file type : date " (interactive) (insert - (format "# %s\n: %s\n\n" (substring (buffer-name) 0 -3) (uldb-iso-8601)) + (format "# %s\n: %s\n\n" (substring (buffer-name) 0 -3) (um-iso-8601)) ) ) @@ -64,7 +70,7 @@ ;; normally .git detection works fine. But for my journal/ I don't git. ;; https://michael.stapelberg.ch/posts/2021-04-02-emacs-project-override/ -(defun uldb-project-override (dir) +(defun um-project-override (dir) "Returns the parent directory containing a .project.el file, if any, to override the standard project.el detection logic when needed. @@ -74,16 +80,16 @@ (list 'vc nil override) nil))) ;; Cannot use :hook because 'project-find-functions does not end in -hook -(add-hook 'project-find-functions #'uldb-project-override) +(add-hook 'project-find-functions #'um-project-override) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; find-file-at-point ;; the journal/ serves as content origin, so it must be treated specially. -(setq uldb-journal-path (car (seq-filter +(setq um-journal-path (car (seq-filter (lambda (path) ;; this way I don't have to hardcode the full path: - (string-match uldb-journal-path-glob path)) + (string-match um-journal-path-glob path)) ;; stores all project roots in a list of strings: (project-known-project-roots)))) @@ -93,19 +99,19 @@ ;; run find-file at point, followed by M-n : ;; TODO: reuse same fallback logic as the embark advice if I keep this. -(defun uldb-journal-find-file () - (let ((default-directory uldb-journal-path) +(defun um-journal-find-file () + (let ((default-directory um-journal-path) (thing (thing-at-point 'filename)) ) (expand-file-name thing)) ) -(add-hook 'file-name-at-point-functions 'uldb-journal-find-file nil t) +(add-hook 'file-name-at-point-functions 'um-journal-find-file nil t) ;;;;;;;;;;;;;;;;;; ;; Embark solution (optional) ;; Load this with an advice: -;; (advice-add 'embark-target-file-at-point :around 'uldb-file-at-point-advice) +;; (advice-add 'embark-target-file-at-point :around 'um-file-at-point-advice) ;; `embark-target-file-at-point' uses `ffap-file-at-point', which uses ;; `default-directory' to expand the filename. @@ -114,7 +120,7 @@ ;; `embark-target-finders', since I'd have to remove the file finder and put my ;; function in the same place in the list anyway. -(defun uldb-file-at-point-advice (origfunc) +(defun um-file-at-point-advice (origfunc) "Like find-file-at-point, but checks all known project paths. In this order: @@ -136,7 +142,7 @@ in the root dir. (cl-loop for project-path in (seq-remove (lambda (path) - (or (string-match uldb-journal-path path) + (or (string-match um-journal-path path) (when (project-current) (string-match (caddr (project-current)) path)) )) @@ -148,14 +154,14 @@ in the root dir. )) ;; journal path - (let ((default-directory uldb-journal-path)) + (let ((default-directory um-journal-path)) (funcall origfunc)) )) ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; C-x p p -(defun uldb-project-find-meta () +(defun um-project-find-meta () (interactive) ;; this works because `project-switch-project' overrides the dir: (find-file (expand-file-name "*meta.md" (caddr (project-current))) t) @@ -164,7 +170,7 @@ in the root dir. ;; overwrite (setq project-switch-commands '( - (uldb-project-find-meta "open meta" "m") + (um-project-find-meta "open meta" "m") (project-dired "dired") (project-find-file "find file") (project-find-regexp "find regexp") @@ -174,7 +180,7 @@ in the root dir. ;; tags ;; TODO: do I want to search all projects? -(defun uldb-grep-tag () +(defun um-grep-tag () "Run project-find-regexp on the current identifer as a journal frontmatter tag. NOTE: this searches in the current project root only. @@ -190,4 +196,4 @@ NOTE: this searches in the current project root only. ;; Or, in dired, run `find-grep-dired'. -(provide 'uldb) +(provide 'um)