368 lines
15 KiB
Org Mode
368 lines
15 KiB
Org Mode
|
#+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.]]
|