15 KiB
Doom Emacs Configuration
I'll fill out the how and why of this all as I figure out what the hell I'm doing. My current Emacs Configuration is a mess of copy and pasted snippet loosely grouped together. There's a fair number of work around, to transient configuration issues that now no longer exist, and more of stuff cribbed off StackOverflow & held together with string & bubble gum. While not yet calling Configuration Bankrupty, I am going to try to see if I can restructure this technical debt.
This Emacs configuration is written using the Literate Programming (sort of) paradigm (well sort of) proposed by Donald Knuth in 1984, and uses Hlissner's awesome Doom Emacs configuration framework.
While I like Literate Programming, I kind of think that literate configuration is largely a mixed bag. Literate Programming produces often more words then code. For even medium size configurations discoveribility & readability of what is happening can be bogged down in the weight of prose explaining the backstory, current thought, moral ponderings, pros & cons, and deciding thoughts. This extra cruft potentially makes understanding more through, but at cost of readiblity & readability is king. As a compromise I'm going to version both to the verbose config.org file and all of the produced configuration files. As an example about that verbosity mentioned prior this entire paragram could have been skipped.
Document Structure
This section will be the what & how of things. There will no directly tangled code in this section.
Doom Emacs
This is built on top of Hlissner's awesome Doom Emacs configuration frameworks. Configuraiton is divided into 150 modules, & fair number of convience functions. Rather than detailing stuff about I'll say to go read FAQs & Index.
Configuration is located in the DOOMDIR directory. This is default value is located is the $HOME/.doom.d directory. Typically this directory contains:
-
init.el - Enabled Doom Modules
-
config.el - General Emacs configuration
-
package.el - Packages to fetch from MELPA, Github, etc.
Additional configuration for scoped functionality will be named as +name.el.
Tangle
This org-mode document works by using tangles. By default Doom's literate config mode adds any #+begin_src blocks into the config.el file1. If you want to tangle to a specific file you pass in a file name.
#+begin_src emacs-lisp :tangle "example.el"
or to disable it tangling for a codeblock set the :tangle property in code block header to no.
#+begin_src orgmode :tangle noNoweb Reference
This document uses noweb reference syntax. This allows us to extract bits of configuration into named codeblocks, which can be interpulated into another code block's variable. For example:
#+NAME: initialization #+BEGIN_SRC emacs-lisp (setq sentence "Never a foot too far, even.") #+END_SRC #+BEGIN_SRC emacs-lisp :noweb yes (reverse sentence) #+END_SRC
will produce
#+BEGIN_SRC emacs-lisp :noweb yes (setq sentence "Never a foot too far, even.") (reverse sentence) #+END_SRC
NOTE: unless you explicitly turn off the named code block will be tangled into config.el. Use the no tangle option if you want to disable this.
Doom Configuration
Misc
Lexical Bindings.
There minor but non-zero start time benefits for using Lexical Bindings comments. All files created should start with
;;; config.el -*- lexical-binding: t; -*-
replace config.el with the filename being loaded.
Modules
The configuration is below is pulled from the template init.example.el provided by doom. This one is based off commit e966249.
;;; init.el -*- lexical-binding: t; -*-
;; This file controls what Doom modules are enabled and what order they load
;; in. Remember to run 'doom sync' after modifying it!
;; NOTE Press 'SPC h d h' (or 'C-h d h' for non-vim users) to access Doom's
;; documentation. There you'll find a link to Doom's Module Index where all
;; of our modules are listed, including what flags they support.
;; NOTE Move your cursor over a module's name (or its flags) and press 'K' (or
;; 'C-c c k' for non-vim users) to view its documentation. This works on
;; flags as well (those symbols that start with a plus).
;;
;; Alternatively, press 'gd' (or 'C-c c d') on a module to browse its
;; directory (for easy access to its source code).
(doom! :completion
<<doom-completion>>
:ui
<<doom-ui>>
:editor
<<doom-editor>>
:emacs
<<doom-emacs>>
:term
<<doom-term>>
:checkers
<<doom-checker>>
:tools
<<doom-tools>>
:os
(:if IS-MAC macos) ; improve compatibility with macOS
:lang
<<doom-lang>>
:email
<<doom-email>>
:app
<<doom-app>>
:config
<<doom-config>>
)The code of these can be found in the modeules directory, the readme for each module will list any additional configuration options.
Completion
https://github.com/doomemacs/doomemacs/tree/master/modules/completion
#+name:doom-completion
company ; the ultimate code completion backend
;;helm ; the *other* search engine for love and life
;;ido ; the other *other* search engine...
;;ivy ; a search engine for love and life
vertico ; the search engine of the future
+childframe exist for both company & vertico, ux is a bit jarring to use with vertico so I'm not using that.
UI
https://github.com/doomemacs/doomemacs/tree/master/modules/ui
#+name:doom-ui
;;deft ; notational velocity for Emacs
doom ; what makes DOOM look the way it does
doom-dashboard ; a nifty splash screen for Emacs
;;doom-quit ; DOOM quit-message prompts when you quit Emacs
;;(emoji +unicode) ; 🙂
hl-todo ; highlight TODO/FIXME/NOTE/DEPRECATED/HACK/REVIEW
;;hydra
;;indent-guides ; highlighted indent columns
;;ligatures ; ligatures and symbols to make your code pretty again
;;minimap ; show a map of the code on the side
modeline ; snazzy, Atom-inspired modeline, plus API
;;nav-flash ; blink cursor line after big motions
;;neotree ; a project drawer, like NERDTree for vim
ophints ; highlight the region an operation acts on
(popup +defaults) ; tame sudden yet inevitable temporary windows
;;tabs ; a tab bar for Emacs
;;treemacs ; a project drawer, like neotree but cooler
;;unicode ; extended unicode support for various languages
(vc-gutter +pretty) ; vcs diff in the fringe
vi-tilde-fringe ; fringe tildes to mark beyond EOB
;;window-select ; visually switch windows
workspaces ; tab emulation, persistence & separate workspaces
;;zen ; distraction-free coding or writingEditor
https://github.com/doomemacs/doomemacs/tree/master/modules/editor
#+name:doom-editor
(evil +everywhere); come to the dark side, we have cookies
file-templates ; auto-snippets for empty files
fold ; (nigh) universal code folding
;;(format +onsave) ; automated prettiness
;;god ; run Emacs commands without modifier keys
;;lispy ; vim for lisp, for people who don't like vim
;;multiple-cursors ; editing in many places at once
;;objed ; text object editing for the innocent
;;parinfer ; turn lisp into python, sort of
;;rotate-text ; cycle region at point between text candidates
snippets ; my elves. They type so I don't have to
;;word-wrap ; soft wrapping with language-aware indentEmacs
https://github.com/doomemacs/doomemacs/tree/master/modules/emacs
#+name:doom-emacs
dired ; making dired pretty [functional]
electric ; smarter, keyword-based electric-indent
;;ibuffer ; interactive buffer management
undo ; persistent, smarter undo for your inevitable mistakes
vc ; version-control and Emacs, sitting in a treeTerm
https://github.com/doomemacs/doomemacs/tree/master/modules/term
#+name:doom-term
;;eshell ; the elisp shell that works everywhere
;;shell ; simple shell REPL for Emacs
;;term ; basic terminal emulator for Emacs
;;vterm ; the best terminal emulation in EmacsChecker
https://github.com/doomemacs/doomemacs/tree/master/modules/checker
#+name:doom-checker
syntax ; tasing you for every semicolon you forget
;;(spell +flyspell) ; tasing you for misspelling mispelling
;;grammar ; tasing grammar mistake every you makeTools
https://github.com/doomemacs/doomemacs/tree/master/modules/tools
#+name:doom-tools
;;ansible
;;biblio ; Writes a PhD for you (citation needed)
;;debugger ; FIXME stepping through code, to help you add bugs
;;direnv
;;docker
;;editorconfig ; let someone else argue about tabs vs spaces
;;ein ; tame Jupyter notebooks with emacs
(eval +overlay) ; run code, run (also, repls)
;;gist ; interacting with github gists
lookup ; navigate your code and its documentation
;;lsp ; M-x vscode
magit ; a git porcelain for Emacs
;;make ; run make tasks from Emacs
;;pass ; password manager for nerds
;;pdf ; pdf enhancements
;;prodigy ; FIXME managing external services & code builders
;;rgb ; creating color strings
;;taskrunner ; taskrunner for all your projects
;;terraform ; infrastructure as code
;;tmux ; an API for interacting with tmux
;;tree-sitter ; syntax and parsing, sitting in a tree...
;;upload ; map local to remote projects via ssh/ftpLanguage
https://github.com/doomemacs/doomemacs/tree/master/modules/lang
#+name:doom-lang
;;agda ; types of types of types of types...
;;beancount ; mind the GAAP
;;(cc +lsp) ; C > C++ == 1
;;clojure ; java with a lisp
;;common-lisp ; if you've seen one lisp, you've seen them all
;;coq ; proofs-as-programs
;;crystal ; ruby at the speed of c
;;csharp ; unity, .NET, and mono shenanigans
;;data ; config/data formats
;;(dart +flutter) ; paint ui and not much else
;;dhall
;;elixir ; erlang done right
;;elm ; care for a cup of TEA?
emacs-lisp ; drown in parentheses
;;erlang ; an elegant language for a more civilized age
;;ess ; emacs speaks statistics
;;factor
;;faust ; dsp, but you get to keep your soul
;;fortran ; in FORTRAN, GOD is REAL (unless declared INTEGER)
;;fsharp ; ML stands for Microsoft's Language
;;fstar ; (dependent) types and (monadic) effects and Z3
;;gdscript ; the language you waited for
;;(go +lsp) ; the hipster dialect
;;(graphql +lsp) ; Give queries a REST
;;(haskell +lsp) ; a language that's lazier than I am
;;hy ; readability of scheme w/ speed of python
;;idris ; a language you can depend on
;;json ; At least it ain't XML
;;(java +lsp) ; the poster child for carpal tunnel syndrome
;;javascript ; all(hope(abandon(ye(who(enter(here))))))
;;julia ; a better, faster MATLAB
;;kotlin ; a better, slicker Java(Script)
;;latex ; writing papers in Emacs has never been so fun
;;lean ; for folks with too much to prove
;;ledger ; be audit you can be
;;lua ; one-based indices? one-based indices
markdown ; writing docs for people to ignore
;;nim ; python + lisp at the speed of c
;;nix ; I hereby declare "nix geht mehr!"
;;ocaml ; an objective camel
org ; organize your plain life in plain text
;;php ; perl's insecure younger brother
;;plantuml ; diagrams for confusing people more
;;purescript ; javascript, but functional
;;python ; beautiful is better than ugly
;;qt ; the 'cutest' gui framework ever
;;racket ; a DSL for DSLs
;;raku ; the artist formerly known as perl6
;;rest ; Emacs as a REST client
;;rst ; ReST in peace
;;(ruby +rails) ; 1.step {|i| p "Ruby is #{i.even? ? 'love' : 'life'}"}
;;(rust +lsp) ; Fe2O3.unwrap().unwrap().unwrap().unwrap()
;;scala ; java, but good
;;(scheme +guile) ; a fully conniving family of lisps
sh ; she sells {ba,z,fi}sh shells on the C xor
;;sml
;;solidity ; do you need a blockchain? No.
;;swift ; who asked for emoji variables?
;;terra ; Earth and Moon in alignment for performance.
;;web ; the tubes
;;yaml ; JSON, but readable
;;zig ; C, but simplerEmails
https://github.com/doomemacs/doomemacs/tree/master/modules/email
#+name:doom-email
;;(mu4e +org +gmail)
;;notmuch
;;(wanderlust +gmail)App
https://github.com/doomemacs/doomemacs/tree/master/modules/app
#+name:doom-app
;;calendar
;;emms
;;everywhere ; *leave* Emacs!? You must be joking
;;irc ; how neckbeards socialize
;;(rss +org) ; emacs as an RSS reader
;;twitter ; twitter client https://twitter.com/vnoughtConfig
https://github.com/doomemacs/doomemacs/tree/master/modules/config
#+name:doom-config
;literate
(default +bindings +smartparens)Content Stolen From
A large amount of the details listed here have been lifted from tecosaur's literate configuration.