org-dog

This package is barely useful right now. It is only public for technical reasons.

Org-dog is an extra workflow layer for Org mode. It aims to be a successor to my org-starter and (deprecated) org-multi-wiki packages but takes a different, unified approach. It lets you program Org workflow by user-defined conventions.

And this package is for those who don’t use org-roam. It should work the best if you have one Org file per subject/project/program, but not per topic or keyword (which is considered too many files).

Its primary goal is to help me organize my work and life in a better way, so it can be highly opinionated.

Features

The following is a short list of primary intended features, but there are more features to be planned:

• Let you easily manage dozens of Org files. You can organize files in directories. Add certain files to org-agenda-files.
• Files have a structure that follow certain conventions. Many files may have the same structure, but different files can have different structures. A file structure is defined by an eieio class.
• Hide files by context. Focus on relevant information.
• Integrate with consult and embark.

Example use case (WIP)

Assume if you have the following directory structure where each directory contains Org files:

• ~/org/ containing hacking.org, learning.org, etc.
  • languages/ containing Chinese.org, Korean.org, etc.
  • technology/ containing devops.org, web.org, emacs.org, etc.
  • archive/ containing many files you are no longer interested in

The following is an example configuration for this repository:

(setq org-dog-repository-alist
      `(("~/org/"
         :subdirs
         ,(apply-partially #'org-dog-subdirs-recursively
                           nil
                           (rx bol (or "archive" "lib") "/"))
         :routes
         (("hacking" org-dog-facade-datetree-file)
          ("learning" org-dog-facade-datetree-file)
          (nil org-dog-file)
          (t org-dog-facade-datetree-file)))))

(defcustom akirak/org-dog-agenda-file-pattern
  (rx bol (or "hacking"
              "learning"
              (and "languages/" "Chinese")
              (and "technology/" (or "devops"
                                     "web"
                                     "emacs"))))
  ""
  :type 'regexp)

(add-hook 'org-dog-file-registration-hook
          (defun akirak/org-dog-add-agenda-file (file-obj)
            (if (string-match-p akirak/org-dog-agenda-file-pattern
                                (oref file-obj relative))
                (add-to-list 'org-agenda-files (oref file-obj absolute))
              (cl-remove (oref file-obj absolute)
                         org-agenda-files
                         :test #'equal))))

org-dog-file-registration-hook is run on every file in the repository. Here are some descriptions of the configuration:

• You are supposed to continuously work on learning and hacking, so they are added to your agenda. They contain date trees.
• You once learned Korean, but you are currently focusing on Chinese, so the file for Chinese is added to the agenda. However, you can still recall information on Korean whenever you want.
• archive directory is ignored, because it only contains files that are no longer relevant. You won’t see files in the directory.

For details, see the info manual (which is work in progress).

What’s wrong with org-starter?

org-starter is a project I started in 2018, several months after I switched from Spacemacs to vanilla Emacs. It is the repository that has received the most stars of mine, but I have to admit that my Emacs Lisp skills were inferior at that time. With my current Emacs Lisp skills and insights from actual use of Org mode, I think I can take a better approach. Org Dog is an attempt to implement that.

Nonetheless, I created the package for my own needs, and I actually used it for years. There might be someone who hopes to continue using it, so I won’t immediately abandon it. I don’t plan on adding new features to the package, but I may react if there is a feature request.

Even though Org Dog does not aim to provide the same set of features as Org Starter does, hopefully it will become a substitution. Nonetheless, Org Dog can be quite opinionated and complex, so Org Starter may remain for basic Org configuration. (I also have to note that the package should have come with a better, more comprehensive documentation.)

About the name

At first, I considered naming this package org-cat because each Org file corresponds to one category by default, so having a bunch of Org files would mean having many categories (cats).

However, cats are independent-minded. This is not an offence to cat lovers, but cats can be troublesome, so I won’t allow them to live inside my computer.

I think dogs are more programmable, if you get it right. This is why I named this package org-dog.