95 lines
6.5 KiB
Org Mode
95 lines
6.5 KiB
Org Mode
#+title: Theurgy
|
|
|
|
Theurgy is an [[https://www.gnu.org/software/emacs/][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.
|
|
|
|
- [[https://github.com/vedang/pdf-tools][pdf-tools]]: requires epdfinfo. This is disabled on Windows systems by default, customize =theurgy-enable-pdf-tools-windows=.
|
|
- [[https://github.com/xenodium/ready-player][ready-player]]: requires mpv and ffmpeg. This is disabled on Windows systems by default, customize =theurgy-enable-ready-player-windows=.
|
|
- [[https://github.com/akermu/emacs-libvterm][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:
|
|
- [[https://github.com/hunspell/hunspell][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.
|
|
- [[https://git.cyan.sh/BirDt/ouroboros-emacs-themes][Ouroboros Emacs Themes]]: Ouroboros themes depend on [[https://git.cyan.sh/BirDt/ouroboros-emacs-themes#headline-6][3 fonts]] to properly display. These themes are not automatically loaded, so you may choose to load any other theme.
|
|
|
|
|
|
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:
|
|
|
|
#+begin_src fundamental
|
|
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))'
|
|
|
|
#+end_src
|
|
|
|
* 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=:
|
|
|
|
#+begin_src fundamental
|
|
.
|
|
├── documents
|
|
├── latex-templates
|
|
├── lore
|
|
│ ├── assets
|
|
│ ├── raw
|
|
│ └── refined
|
|
│ ├── essay
|
|
│ ├── journal
|
|
│ ├── lightning
|
|
│ └── wiki
|
|
└── tasks
|
|
├── maintenance
|
|
└── projects
|
|
└── career
|
|
#+end_src
|
|
|
|
You can read more about this configuration [[https://www.cyan.sh/blog/posts/architecting-a-better-org-workflow.html][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 [[github.com/SalOrak/whaler.el][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).
|