dotfiles/emacs/config.org

#+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
       <<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>>
       )
#+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.]]