Theurgy

• Dependencies
• Running as a Server
• Opinionated Stuff
  • Org-Mode
• Workflow
  • Working With Tabs
  • Navigation
    • The Mouse
    • Keybindings
    • Line Number Jumping
  • Extension

Theurgy is an Emacs distribution or configuration base. More specifically, it is my day-to-day configuration.

Development is guided by these principles (but probably is not strictly adherent to them, feel free to submit PRs):

1. Keep it portable, keep it consistent: this configuration must run on multiple systems with vastly different environments. I want to be able to use the same configuration on my Windows/Mac work laptops, as well as my own Linux devices.
2. Don't reinvent the wheel: if some functionality exists in vanilla Emacs, prefer it unless there's a good reason not to. This does not mean we are a minimal config - install packages when you need some functionality that is tedious to self-implement.
3. UX first: Theurgy should be an efficient tool first and foremost.

Dependencies

Some packages or flows within Theurgy have external dependencies. Typically, in this case we check if the dependency exists (or we hope that the downstream package does that for us). The complete list of packages with external dependencies is here for your perusal.

• pdf-tools: requires epdfinfo. This is disabled on Windows systems by default, customize theurgy-enable-pdf-tools-windows.
• ready-player: requires mpv and ffmpeg. This is disabled on Windows systems by default, customize theurgy-enable-ready-player-windows.
• vterm: requires libvterm. This is disabled on Windows systems by default, customize theurgy-enable-vterm-windows. If vterm is not available, theurgy will fall back to the standard Emacs shell for terminal emulation.

Here is the complete list of other optional dependencies:

• Hunspell: if Hunspell is installed, Theurgy will use it and a dictionary file in the user-emacs-directory to provide completions with both flyspell and ispell. The theurgy-hunspell-dict variable can be customized to select a different dictionary than the en_AU.dict used by default. Additionally, the ispell-dictionary and ispell-local-dictionary-alist variables should be customised accordingly to get rid of the en_AU locale.
• all-the-icons: all-the-icons requires icons to be manually installed with all-the-icons-install-fonts at least once.
• Ouroboros Emacs Themes: Ouroboros themes depend on 3 fonts to properly display. These themes are not automatically loaded, so you may choose to load any other theme.
• gomuks: I've tried to provide some basic integration with Gomuks, as it is more usable for me than ement at the moment due to Pantalaimon not working properly.

In addition, git is a hard dependency that must be installed for Theurgy to work.

Running as a Server

I make no claims of startup speed, and I recommend running Emacs as a server and connecting to it with the client. You can do this by running emacs --daemon in any terminal.

If using bspwm and sxhkd, I suggest the following keyinds to make use of everything Theurgy has to offer:

  super + Return
        emacsclient --create-frame --eval "(progn (set-frame-parameter nil 'tab-bar-lines 0) (theurgy-main-shell))"
        
  super + alt + e
        bspc rule -a '*' -o state=floating; emacsclient --eval "(emacs-everywhere)"

  super + e
        emacsclient --create-frame

  super + ctrl + e
        bspc rule -a '*' -o state=floating; emacsclient --create-frame -e '(progn (select-frame-set-input-focus (selected-frame)) (org-capture))'

Opinionated Stuff

This is a list of files/flows that are very opinionated and you may wish to delete from the configuration, or heavily modify.

Org-Mode

My org-mode workflow is VERY opinionated, and at the time of writing a lot of values are hard-coded.

The whole workflows/org-custom.el file assumes a directory tree like this in ~/.org:

  .
  ├── documents
  ├── latex-templates
  ├── lore
  │   ├── assets
  │   ├── raw
  │   └── refined
  │       ├── essay
  │       ├── journal
  │       ├── lightning
  │       └── wiki
  └── tasks
      ├── maintenance
      └── projects
          └── career

You can read more about this configuration here, but you may wish to M-% ~/.org to your own org directory, or simply get rid of all irrelevant code.

Workflow

Working With Tabs

Theurgy is focused on a tab and project based workflow, with each tab generally corresponding to a single project. New tabs can be created with C-t 2 and deleted with C-t 0 (this prefix is different from vanilla to avoid conflicts with some modes). You can navigate between tabs with C-<tab> and C-S-<tab>.

When creating a new tab, Theurgy will open the dashboard. Pressing p at the dashboard will allow you to select any whaler project, the list of which can be customized with whaler-directories-alist and whaler-oneoff-directories-alist. You can also customize the theurgy-project-default-file-alist to select which file should open by default when visiting a project.

Each tab stores the directory of the current project in the tab group name, and this allows other buffers (such as neotree) to reliably get the project directory when the tab changes. If you want to add other functions to run on tab change, Theurgy provides a tab-bar-select-tab-hook to do so, and you can fetch the project directory with theurgy-get-tab-project-dir.

Navigation

The Mouse

By default, Theurgy enforces mouse-less navigation by unbinding every mouse button. You can turn mouse clicking back on by customizing theurgy-mouse-disabled.

Keybindings

Theurgy does not use Evil, but it doesn't strictly adhere to Emacs binding conventions either. You may not like this.

Line Number Jumping

M-g g and M-g r allow you to jump to absolute and relative line numbers respectively. When used, the current buffer will temporarily have the desired line number type enabled. Pressing C-g before jumping to a line number will cause the displayed line number type to change permanently for that buffer.

Extension

Theurgy can be extended by placing any arbitrary Emacs Lisp files in ./workflows (to use for specific mode customisations), ./userland (to use for application replacements), and ./screens (to use for specific GUIs and layouts).