dotfiles/emacs/config.org

368 lines
15 KiB
Org Mode
Raw Normal View History

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