View on GitHub
View on GitHub
#+end_export
#+begin_export latex
\newpage % because the contents are multi-page, this looks better
#+end_export
#+begin_quote
Let us change our traditional attitude to the construction of programs:
Instead of imagining that our main task is to instruct a computer what to do,
let us concentrate rather on explaining to human beings what we want a
computer to do. --- Donald Knuth
#+end_quote
* Intro
Customising an editor can be very rewarding ... until you have to leave it.
For years I have been looking for ways to avoid this pain.
Then I discovered [[https://github.com/cknadler/vim-anywhere][vim-anywhere]], and found that it had an Emacs companion,
[[https://github.com/zachcurry/emacs-anywhere][emacs-anywhere]]. To me, this looked most attractive.
Separately, online I have seen the following statement enough times I think it's a catchphrase
#+begin_quote
Redditor1: I just discovered this thing, isn't it cool. \\
Redditor2: Oh, there's an Emacs mode for that.
#+end_quote
I tried out the =spacemacs= distribution a bit, but it wasn't quite to my liking.
Then I heard about =doom emacs= and thought I may as well give that a try.
TLDR; it's great.
Now I've discovered the wonders of literate programming, and am becoming more
settled by the day. This is my config, and also a cautionary tale (just replace
"Linux" with "Emacs" in the comic below).
[[xkcd:456]]
** Why Emacs?
# https://github.com/esac-io/eos
# https://github.com/remacs/remacs
# https://www.eigenbahn.com/2020/01/12/emacs-is-no-editor
Emacs is not a text editor, this is a common misnomer. It is far more apt to
describe Emacs as Lisp machine providing a generic user-centric text
manipulation environment.
In simpler terms one can think of Emacs as a platform for text-related
applications. It's a vague and generic definition because Emacs itself is
generic.
Good with text. How far does that go? A lot further than one initially thinks:
+ [[https://orgmode.org/][Task planning]]
+ [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Dired.html][File management]]
+ [[https://github.com/akermu/emacs-libvterm][Terminal emulation]]
+ [[https://www.djcbsoftware.nl/code/mu/mu4e.html][Email client]]
+ [[https://www.gnu.org/software/tramp/][Remote server tool]]
+ [[https://magit.vc/][Git frontend]]
+ Web [[https://github.com/pashky/restclient.el][client]]/[[https://github.com/skeeto/emacs-web-server][server]]
+ and more...
Ideally, one may use Emacs as /the/ interface to perform =input → transform →
output= cycles, i.e. form a bridge between the human mind and information
manipulation.
*** The enveloping editor
Emacs allows one to do more in one place than any other application. Why is this
good?
+ Enables one to complete tasks with a consistent, standard set of keybindings,
GUI and editing methods --- learn once, use everywhere
+ Reduced context-switching
+ Compressing the stages of a project --- a more centralised workflow can progress
with greater ease
+ Integration between tasks previously relegated to different applications, but
with a common subject --- e.g. linking to an email in a to-do list
*** Some notably unique features
+ Recursive editing
+ Completely introspectable, with pervasive docstrings
+ Mutable environment, which can be incrementally modified
+ Functionality without applications
+ Client-server seperation allows for a daemon, giving near-instant perceived
startup time.
*** Issues
+ Emacs has irritating quirks
+ Some aspects are showing their age (naming conventions, APIs)
+ Emacs is ([[https://www.gnu.org/software/emacs/manual/html_node/elisp/Threads.html][mostly]]) single-threaded, meaning that when something holds that
thread up the whole application freezes
+ A few other nuisances
*** Teach a man to fish...
#+begin_quote
Give a man a fish, and you feed him for a day. Teach a man to fish, and you feed
him for a lifetime. --- Anne Isabella
#+end_quote
Most popular editors have a simple and pretty [[https://code.visualstudio.com/docs/getstarted/settings][settings interface]], filled with
check-boxes, selects, and the occasional text-box. This makes it easy for the
user to pick between common desirable behaviours. To me this is now like /giving
a man a fish/.
What if you want one of those 'check-box' settings to be only on in certain
conditions? Some editors have workspace settings, but that requires you to
manually set the value for /every single instance/. Urgh, [[https://github.com/microsoft/vscode/issues/93153][what]] [[https://github.com/microsoft/vscode/issues/93628][a]] [[https://github.com/microsoft/vscode/issues/5595][pain]].
What if you could set the value of that 'check-box' setting to be the result of
an arbitrary expression evaluated for each file? This is where an editor like
Emacs comes in.
Configuration for Emacs isn't a list of settings in JSON etc. it's *an executable
program which modifies the behaviour of the editor to suit your liking*.
This is 'teaching a man to fish'.
Emacs is built in the same language you configure it in (Emacs [[https://en.wikipedia.org/wiki/Lisp_(programming_language)][Lisp]], or [[https://www.gnu.org/software/emacs/manual/html_node/eintr/][elisp]]).
It comes with a broad array of useful functions for text-editing, and Doom adds
a few handy little convenience functions.
Want to add a keybinding to delete the previous line? It's as easy as
#+name: Keybinding to delete the previous line
#+begin_src emacs-lisp :tangle no
(map! "C-d"
(cmd! (previous-line)
(kill-line)
(forward-line)))
#+end_src
How about another example, say you want to be presented with a list of currently
open /buffers/ (think files, almost) when you split the window. It's as simple as
#+name: Prompt for buffer after split
#+begin_src emacs-lisp :tangle no
(defadvice! prompt-for-buffer (&rest _)
:after 'window-split (switch-to-buffer))
#+end_src
Want to test it out? You don't need to save and restart, you can just /evaluate
the expression/ within your current Emacs instance and try it immediately! This
editor is, after all, a Lisp interpreter.
Want to tweak the behaviour? Just re-evaluate your new version --- it's a
super-tight iteration loop.
** Editor comparison
[[xkcd:378]]
Over the years I have tried out (spent at least a year using as my primary
editor) the following applications
- Python IDLE
- Komodo Edit
- Brackets
- ;VSCode
- and now, Emacs
I have attempted to quantify aspects of my impressions of them below.
#+plot: transpose:yes type:radar min:0 max:4 ticks:4 file:"misc/editor-comparison.png"
| Editor | Extensibility | Ecosystem | Ease of Use | Comfort | Completion | Performance |
|-------------+---------------+-----------+-------------+---------+------------+-------------|
| IDLE | 1 | 1 | 3 | 1 | 1 | 2 |
| ;VSCode | 3 | 3 | 4 | 3.5 | 4 | 3 |
| Brackets | 2.5 | 2 | 3 | 3 | 2.5 | 2 |
| Emacs | 4 | 4 | 2 | 4 | 3.5 | 3 |
| Komodo Edit | 2 | 1 | 3 | 2 | 2 | 2 |
#+attr_html: :class invertible :alt Radar chart comparing my thoughts on a few editors.
[[https://tecosaur.com/lfs/emacs-config/editor-comparison.png]]
** Notes for the unwary adventurer
If you like the look of this, that's marvellous, and I'm really happy that I've
made something which you may find interesting, however:
#+begin_warning
This config is /insidious/. Copying the whole thing blindly can easily lead to
undesired effects. I recommend copying chunks instead.
#+end_warning
If you are so bold as to wish to steal bits of my config (or if I upgrade and
wonder why things aren't working), here's a list of sections which rely on
external setup (i.e. outside of this config).
+ libvterm :: I rely on my distro-provided =libvterm.so=, [[*VTerm][vterm]] sets a compile flag.
If this causes issues, just delete the ~(setq term-module-cmake-args ...)~ bit.
+ dictionary :: I've downloaded a custom [[http://app.aspell.com/create][SCOWL]] dictionary, which I use in [[*Ispell][ispell]].
If this causes issues, just delete the ~(setq ispell-dictionary ...)~ bit.
+ uni-units file :: I've got a file in =~/.org/.uni-units= which I use in ~org-capture~
If this causes issues, just remove the reference to that file in [[*Capture][Capture]] and
instances of ~unit-prompt~ used in ~(doct ...)~
Oh, did I mention that I started this config when I didn't know any =elisp=, and
this whole thing is a hack job? If you can suggest any improvements, please do
so, no matter how much criticism you include I'll appreciate it :)
[[xkcd:1513]]
*** Extra Requirements
The lovely ~doom doctor~ is good at diagnosing most missing things, but here are a
few extras.
+ A [[https://www.tug.org/texlive/][LaTeX Compiler]] is required for the mathematics rendering performed in [[#org][Org]],
and by [[*CalcTeX][CalcTeX]].
+ I use the [[https://overpassfont.org/][Overpass]] font as a go-to sans serif.
It's used as my ~doom-variable-pitch-font~ and in the graph generated by [[*Roam][Roam]].
I have chosen it because it possesses a few characteristics I consider
desirable, namely:
- A clean, and legible style. Highway-style fonts tend to be designed to be
clear at a glance, and work well with a thicker weight, and this is inspired
by /Highway Gothic/.
- It's slightly quirky. Look at the diagonal cut on stems for example.
Helvetica is a masterful design, but I like a bit more pizzazz now and then.
+ A few LSP servers. Take a look at [[file:init.el][init.el]] to see which modules have the ~+lsp~ flag.
+ The =cargo-script= rust crate is required for evaluation of rust blocks by babel.
As described in the README for [[https://github.com/micanzhang/ob-rust][ob-rust]]. Like ~delta~, this can just be installed
using cargo.
#+begin_src shell :eval no :tangle (if (executable-find "cargo-script") "no" "setup.sh")
cargo install cargo-script
#+end_src
+ The [[https://github.com/dandavison/delta/][Delta]] binary. It's packaged for some distributions but I installed it with
#+begin_src shell :eval no :tangle (if (executable-find "delta") "no" "setup.sh")
cargo install git-delta
#+end_src
+ The =theme-magic= package requires the ~wal~ (=pywal=) executable. If this is
packaged for you, great! If not, it's just a quick ~pip install~ away.
#+begin_src shell :eval no :tangle (if (executable-find "wal") "no" "setup.sh")
sudo python3 -m pip install pywal
#+end_src
** Current Issues
*** Magit push in daemon
Quite often trying to push to a remote in the Emacs daemon produces as error like this:
#+begin_src fundamental
128 git … push -v origin refs/heads/master\:refs/heads/master
Pushing to git@github.com:tecosaur/emacs-config.git
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
#+end_src
*** CalcTeX brings up compilation buffer
With my [[*Calc][Calc]] hook, the first call of =M-x calc= brings up a compilation buffer
from CalcTeX. I'm guessing this is from the compilation of the preamble / ~.fmt~ file.
*** Unread emails doesn't work across Emacs instances
It would be nice if it did, so that I could have the Emacs-daemon hold the
active mu4e session, but still get that information. In this case I'd want to
change the action to open the Emacs daemon, but it should be possible.
This would probably involve hooking into the daemon's modeline update function
to write to a temporary file, and having a file watcher started in other Emacs
instances, in a similar manner to [[*Rebuild mail index while using mu4e][Rebuild mail index while using mu4e]].
* Rudimentary configuration
Make this file run (slightly) faster with lexical binding (see [[https://nullprogram.com/blog/2016/12/22/][this blog post]]
for more info).
#+begin_src emacs-lisp :comments no
;;; config.el -*- lexical-binding: t; -*-
#+end_src
** Personal Information
It's useful to have some basic personal information
#+begin_src emacs-lisp
(setq user-full-name "TEC"
user-mail-address "tec@tecosaur.com")
#+end_src
Apparently this is used by ~GPG~, and all sorts of other things.
Speaking of ~GPG~, I want to use =~/.authsource.gpg= instead of the default in
=~/.emacs.d=. Why? Because my home directory is already cluttered, so this won't
make a difference, and I don't want to accidentaly purge this file (I have done
~rm -rf~/.emac.d~ before). I also want to cache as much as possible, as my home
machine is pretty safe, and my laptop is shutdown a lot.
#+begin_src emacs-lisp
(setq auth-sources '("~/.authinfo.gpg")
auth-source-cache-expiry nil) ; default is 7200 (2h)
#+end_src
** Better defaults
*** Simple settings
Browsing the web and seeing [[https://github.com/angrybacon/dotemacs/blob/master/dotemacs.org#use-better-defaults][angrybacon/dotemacs]] and comparing with the values
shown by =SPC h v= and selecting what I thought looks good, I've ended up adding the following:
#+begin_src emacs-lisp
(setq-default
delete-by-moving-to-trash t ; Delete files to trash
window-combination-resize t ; take new window space from all other windows (not just current)
x-stretch-cursor t) ; Stretch cursor to the glyph width
(setq undo-limit 80000000 ; Raise undo-limit to 80Mb
evil-want-fine-undo t ; By default while in insert all changes are one big blob. Be more granular
auto-save-default t ; Nobody likes to loose work, I certainly don't
truncate-string-ellipsis "…") ; Unicode ellispis are nicer than "...", and also save /precious/ space
(display-time-mode 1) ; Enable time in the mode-line
(unless (equal "Battery status not available"
(battery))
(display-battery-mode 1)) ; On laptops it's nice to know how much power you have
(global-subword-mode 1) ; Iterate through CamelCase words
#+end_src
*** Fullscreen
I also like the idea of fullscreen-ing when opened by ~Emacs~ or the ~.desktop~ file.
#+begin_src emacs-lisp
(if (eq initial-window-system 'x) ; if started by emacs command or desktop file
(toggle-frame-maximized)
(toggle-frame-fullscreen))
#+end_src
*** Auto-customisations
By default changes made via a customisation interface are added to =init.el=.
I prefer the idea of using a separate file for this. We just need to change a
setting, and load it if it exists.
#+begin_src emacs-lisp
(setq-default custom-file (expand-file-name ".custom.el" doom-private-dir))
(when (file-exists-p custom-file)
(load custom-file))
#+end_src
*** Windows
I find it rather handy to be asked which buffer I want to see after splitting
the window. Let's make that happen.
First, we'll enter the new window
#+begin_src emacs-lisp
(setq evil-vsplit-window-right t
evil-split-window-below t)
#+end_src
Then, we'll pull up ~ivy~
#+begin_src emacs-lisp
(defadvice! prompt-for-buffer (&rest _)
:after '(evil-window-split evil-window-vsplit)
(+ivy/switch-buffer))
#+end_src
Oh, and previews are nice
#+begin_src emacs-lisp
(setq +ivy-buffer-preview t)
#+end_src
Window rotation is nice, and can be found under =SPC w r= and =SPC w R=.
/Layout/ rotation is also nice though. Let's stash this under =SPC w SPC=, inspired
by Tmux's use of =C-b SPC= to rotate windows.
We could also do with adding the missing arrow-key variants of the window
navigation/swapping commands.
#+begin_src emacs-lisp
(map! :map evil-window-map
"SPC" #'rotate-layout
;; Navigation
"%s
\n" (concat "\n" (org-html-close-tag "br" nil info) "\n" "%s\n")) (org-export-data subtitle info)) ""))))) contents (format "\n" (nth 1 (assq 'content (plist-get info :html-divs)))) ;; Postamble. (org-html--build-pre/postamble 'postamble info) ;; Possibly use the Klipse library live code blocks. (when (plist-get info :html-klipsify-src) (concat "")) ;; Closing document. "