#+title: 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 [[https://en.wikipedia.org/wiki/Literate_programming][Literate Programming]] (sort of) paradigm (well sort of) proposed by [[https://en.wikipedia.org/wiki/Donald_Knuth][Donald Knuth]] in 1984, and uses Hlissner's awesome [[https://github.com/doomemacs/doomemacs][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 [[https://github.com/doomemacs/doomemacs][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 [[https://github.com/doomemacs/doomemacs/blob/master/docs/faq.org][FAQs]] & [[https://github.com/doomemacs/doomemacs/blob/master/docs/index.org][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 [[https://orgmode.org/manual/Extracting-Source-Code.html][tangles]]. By default Doom's literate config mode adds any ~#+begin_src~ blocks into the =config.el= file[fn:1]. If you want to tangle to a specific file you pass in a file name. #+begin_src orgmode :tangle no #+begin_src emacs-lisp :tangle "example.el" #+end_src or to disable it tangling for a codeblock set the =:tangle= property in code block header to =no=. #+begin_src orgmode :tangle no #+begin_src orgmode :tangle no #+end_src *** Noweb Reference This document uses [[https://orgmode.org/manual/Noweb-Reference-Syntax.html][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: #+begin_example :tangle no #+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 #+end_example will produce #+begin_example #+BEGIN_SRC emacs-lisp :noweb yes (setq sentence "Never a foot too far, even.") (reverse sentence) #+END_SRC #+end_example 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 [[https://nullprogram.com/blog/2016/12/22/][minor but non-zero start time benefits]] for using Lexical Bindings comments. All files created should start with #+BEGIN_SRC emacs-lisp ;;; config.el -*- lexical-binding: t; -*- #+END_SRC 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 [[https://github.com/doomemacs/doomemacs/blob/e96624926d724aff98e862221422cd7124a99c19/templates/init.example.el][e966249]]. #+name: init.el #+attr_html: :collapsed t #+begin_src emacs-lisp :tangle "init.el" :noweb no-export :comments no ;;; 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 <> :ui <> :editor <> :emacs <> :term <> :checkers <> :tools <> :os (:if IS-MAC macos) ; improve compatibility with macOS :lang <> :email <> :app <> :config <> ) #+end_src The code of these can be found in the [[https://github.com/doomemacs/doomemacs/tree/master/modules][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 #+begin_src emacs-lisp :tangle no 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 #+end_src =+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 #+begin_src emacs-lisp :tangle no ;;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 writing #+end_src *** Editor https://github.com/doomemacs/doomemacs/tree/master/modules/editor #+name:doom-editor #+begin_src emacs-lisp :tangle no (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 indent #+end_src *** Emacs https://github.com/doomemacs/doomemacs/tree/master/modules/emacs #+name:doom-emacs #+begin_src emacs-lisp :tangle no 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 tree #+end_src *** Term https://github.com/doomemacs/doomemacs/tree/master/modules/term #+name:doom-term #+begin_src emacs-lisp :tangle no ;;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 Emacs #+end_src *** Checker https://github.com/doomemacs/doomemacs/tree/master/modules/checker #+name:doom-checker #+begin_src emacs-lisp :tangle no syntax ; tasing you for every semicolon you forget ;;(spell +flyspell) ; tasing you for misspelling mispelling ;;grammar ; tasing grammar mistake every you make #+end_src *** Tools https://github.com/doomemacs/doomemacs/tree/master/modules/tools #+name:doom-tools #+begin_src emacs-lisp :tangle no ;;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/ftp #+end_src *** Language https://github.com/doomemacs/doomemacs/tree/master/modules/lang #+name:doom-lang #+begin_src emacs-lisp :tangle no ;;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 simpler #+end_src *** Emails https://github.com/doomemacs/doomemacs/tree/master/modules/email #+name:doom-email #+begin_src emacs-lisp :tangle no ;;(mu4e +org +gmail) ;;notmuch ;;(wanderlust +gmail) #+end_src *** App https://github.com/doomemacs/doomemacs/tree/master/modules/app #+name:doom-app #+begin_src emacs-lisp :tangle no ;;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/vnought #+end_src *** Config https://github.com/doomemacs/doomemacs/tree/master/modules/config #+name:doom-config #+begin_src emacs-lisp :tangle no ;literate (default +bindings +smartparens) #+end_src * Content Stolen From A large amount of the details listed here have been lifted from [[https://tecosaur.github.io/emacs-config/][tecosaur's literate configuration]]. * Footnotes [fn:1] See [[https://github.com/doomemacs/doomemacs/tree/master/modules/config/literate#change-where-src-blocks-are-tangled-or-prevent-it-entirely][Doom FAQ on this for more.]]