~kl/.emacs.d

my Org-based Emacs config
aaf3dabe — Kevin Lipe 20 days ago
Revert "use LuaLaTeX instead of LuaTeX"
f49dc65c — Kevin Lipe 20 days ago
use LuaLaTeX instead of LuaTeX
362ff7e7 — Kevin Lipe a month ago
update README

refs

main
browse  log 

clone

read-only
https://git.sr.ht/~kl/.emacs.d
read/write
git@git.sr.ht:~kl/.emacs.d

You can also use your local clone with git send-email.

#An Org-based Emacs configuration

#About

This is my Emacs configuration, written in Org mode, which is mostly so I can look through it and remember how all of this works. Also, if it's going to be public, it might as well be well-documented. A lot of this setup (at least in spirit, and literally in the case of the tangle-and-compile bits) is borrowed from Lars Tveito's Emacs/Org setup.

#Meta

All changes to the configuration should be done in init.org, not in init.el. Any changes in the init.el will be overwritten by saving init.org. The init.el in this repo should not be tracked by git, and is replaced the first time Emacs is started (assuming it has been renamed to ~/.emacs.d).

Emacs can't load .org-files directly, but org-mode provides functions to extract the code blocks and write them to a file. There are multiple ways of handling this; like suggested by this StackOverflow post, one could just use org-babel-load-file, but I had problems with byte-compilation. Previously I tracked both the org.- and el.-files, but the git commits got a little messy. So here is a new approach.

When this configuration is loaded for the first time, the init.el is the file that is loaded. It looks like this:

;; This file replaces itself with the actual configuration at first run.

;; We can't tangle without org!
(require 'org)
;; Open the configuration
(find-file (concat user-emacs-directory "init.org"))
;; tangle it
(org-babel-tangle)
;; load it
(load-file (concat user-emacs-directory "init.el"))
;; finally byte-compile it
(byte-compile-file (concat user-emacs-directory "init.el"))

It tangles the org-file, so that this file is overwritten with the actual configuration.

There is no reason to track the init.el that is generated; by running the following command git will not bother tracking it:

git update-index --assume-unchanged init.el

If one wishes to make changes to the repo-version of init.el start tracking again with:

git update-index --no-assume-unchanged init.el

The init.el should (after the first run) mirror the source blocks in the init.org. We can use C-c C-v t to run org-babel-tangle, which extracts the code blocks from the current file into a source-specific file (in this case a .el-file).

To avoid doing this each time a change is made we can add a function to the after-save-hook ensuring to always tangle and byte-compile the org-document after changes.

(defun tangle-init ()
  "If the current buffer is 'init.org' the code-blocks are
tangled, and the tangled file is compiled."
  (when (equal (buffer-file-name)
               (expand-file-name (concat user-emacs-directory "init.org")))
    ;; Avoid running hooks when tangling.
    (let ((prog-mode-hook nil))
      (org-babel-tangle)
      (byte-compile-file (concat user-emacs-directory "init.el")))))

(add-hook 'after-save-hook 'tangle-init)

#Packages

Managing extensions for Emacs is simplified using package which is built in to Emacs 24 and newer. To load downloaded packages we need to initialize package. cl-lib is an alternative to the deprecated cl package.

(require 'cl-lib)
(require 'package)
(if (< emacs-major-version 27)(package-initialize))

Packages can be fetched from different mirrors; melpa is the largest archive and is well maintained.

(setq package-archives
      '(("gnu" . "http://elpa.gnu.org/packages/")
        ("MELPA" . "http://melpa.org/packages/")))

The configuration assumes that the packages listed below are installed. Missing packages will be downloaded and installed on startup.

(let* ((packages '(
      use-package          ; Lazy loading and requirements for Emacs packages
      plan9-theme          ; A color scheme inspired by Plan 9 from Bell Labs
      anti-zenburn-theme   ; anti-zenburn color scheme
      auctex               ; sophisticated document creation via LaTeX
      ivy                  ; abo-abo completion framework
      counsel              ; find things in the filesystem using ivy
      csharp-mode          ; Major mode for editing C# in Emacs
      csv-mode             ; For working with .csv files intelligently
      general              ; "convenience wrappers for keybindings"
      swiper               ; find things in an Emacs buffer using ivy
      markdown-mode        ; Major mode for editing Markdown files
      org                  ; Outline-based notes manager
      org-bullets          ; Fancy UTF-8 bullets for org
      ox-pandoc            ; org exporter for pandoc
      olivetti             ; Minor mode for a nice writing environment.
      pandoc-mode          ; Minor mode for interacting with pandoc via hydra
      paredit              ; Minor mode for Lisp editing goodness
      request              ; something URL related
      request-deferred     ; not really sure what this does
      wc-goal-mode         ; Set goal wordcounts (minor mode)
      which-key            ; show available keybindings in popup
      auto-compile         ; automatically compile Emacs Lisp libraries
      expand-region))      ; Increase selected region by semantic units

     ;; Remove all packages already installed
  (packages (cl-remove-if 'package-installed-p packages)))
     (when packages
       (ignore-errors (package-refresh-contents)
         (mapc 'package-install packages)
         ;; This package is only relevant for Mac OS X; it fixes some $PATH stuff.
         (when (memq window-system '(mac ns))
           (package-install 'exec-path-from-shell)))))

  (require 'use-package) ;; make sure this is already loaded.

#Configurations

#Defaults

Always start the server so that emacsclient works from the command line.

(server-start) ;; start the server on startup

Answering yes and no to each question from Emacs can be tedious, a single y or n will suffice.

(fset 'yes-or-no-p 'y-or-n-p)

To avoid file system clutter we put all auto saved files in a single directory. We also set up our backup-saving parameters here.

(defvar --backup-directory (concat user-emacs-directory "backups"))
(if (not (file-exists-p --backup-directory))
        (make-directory --backup-directory t))
(setq backup-directory-alist `(("." . ,--backup-directory)))
(setq make-backup-files t               ; backup of a file the first time it is saved.
      backup-by-copying t               ; don't clobber symlinks
      version-control t                 ; version numbers for backup files
      delete-old-versions t             ; delete excess backup files silently
      delete-by-moving-to-trash t
      kept-old-versions 6               ; oldest versions to keep when a new numbered backup is made (default: 2)
      kept-new-versions 9               ; newest versions to keep when a new numbered backup is made (default: 2)
      auto-save-default t               ; auto-save every buffer that visits a file
      auto-save-timeout 20              ; number of seconds idle time before auto-save (default: 30)
      auto-save-interval 200            ; number of keystrokes between auto-saves (default: 300)
      )

These are some other "sane" defaults:

Silently delete excess backup versions of files:

(setq delete-old-versions -1)

Use UTF-8 for everything by default (if this isn't already happening)

(setq coding-system-for-read 'utf-8)
(setq coding-system-for-write 'utf-8)
(set-terminal-coding-system 'utf-8)
(set-language-environment 'utf-8)
(set-keyboard-coding-system 'utf-8)
(prefer-coding-system 'utf-8)
(setq locale-coding-system 'utf-8)
(set-default-coding-systems 'utf-8)
;; Treat clipboard input as UTF-8 string first; compound text next, etc.
(setq x-select-request-type '(UTF8_STRING COMPOUND_TEXT TEXT STRING))

Garbage collect on focus-out, which should make Emacs feel a bit snappier, especially on Windows:

(add-function :after after-focus-change-function #'garbage-collect)

;; this method is deprecated as of Emacs 27.1, but saving the code for posterity:
;; (add-hook 'focus-out-hook #'garbage-collect)

We also want to empty the initial *scratch* buffer.

(setq-default initial-scratch-message "")

Finally, we want to confirm before exiting Emacs, just in case.

(setq-default confirm-kill-emacs 'yes-or-no-p)

Here are some other useful defaults borrowed from the default setup for emax64

(setq-default
 ad-redefinition-action 'accept                   ; Silence warnings for redefinition
 cursor-in-non-selected-windows t                 ; Hide the cursor in inactive windows
 delete-by-moving-to-trash t                      ; Delete files to trash
 display-time-default-load-average nil            ; Don't display load average
 display-time-format "%H:%M"                      ; Format the time string
 fill-column 80                                   ; Set width for automatic line breaks
 help-window-select t                             ; Focus new help windows when opened
 indent-tabs-mode nil                             ; Stop using tabs to indent
 inhibit-startup-screen t                         ; Disable start-up screen
 initial-scratch-message ""                       ; Empty the initial *scratch* buffer
 left-margin-width 1 right-margin-width 1         ; Add left and right margins
 mode-require-final-newline 'visit                ; Add a newline at EOF on visit
 mouse-yank-at-point t                            ; Yank at point rather than pointer
 ns-use-srgb-colorspace nil                       ; Don't use sRGB colors
 recenter-positions '(5 top bottom)               ; Set re-centering positions
 redisplay-dont-pause t                           ; don't pause display on input
 debug-on-error t
 jit-lock-defer-time 0
 frame-resize-pixelwise t
 fast-but-imprecise-scrolling t
 scroll-conservatively 10000                      ; Always scroll by one line
 scroll-margin 1                                  ; scroll N lines to screen edge
 scroll-step 1                                    ; keyboard scroll one line at a time
 scroll-preserve-screen-position 1
 select-enable-clipboard t                        ; Merge system's and Emacs' clipboard
 sentence-end-double-space nil                    ; End a sentence after a dot and a space
 show-trailing-whitespace nil                     ; Display trailing whitespaces
 split-height-threshold nil                       ; Disable vertical window splitting
 split-width-threshold nil                        ; Disable horizontal window splitting
 tab-width 4                                      ; Set width for tabs
 uniquify-buffer-name-style 'forward              ; Uniquify buffer names
 window-combination-resize t                      ; Resize windows proportionally
 x-stretch-cursor t)                              ; Stretch cursor to the glyph width
(delete-selection-mode)                           ; Replace region when inserting text
(setq line-number-mode t)                         ; Enable line numbers in the mode-line
(setq column-number-mode t)                       ; Enable column numbers in the mode-line
(size-indication-mode 1)                          ; Enable size status in the mode-line
(display-time-mode)                               ; Enable time in the mode-line
(fringe-mode 0)                                   ; Hide fringes
(global-hl-line-mode)                             ; Hightlight current line
(show-paren-mode t)

#Customized key bindings

First things first, I want the Escape key to quit whatever I'm doing in the minibuffer.

;; make Esc quit whatever's happening in the minibuffer

(define-key isearch-mode-map [escape] 'isearch-abort)   ;; isearch
(define-key isearch-mode-map "\e" 'isearch-abort)   ;; \e seems to work better for terminals
(global-set-key [escape] 'keyboard-escape-quit)         ;; everywhere else

Here are some keybindings I want to use, provided by general.el.

  • Map the Meta key to also be invoked by C-x C-m (and C-c C-m) so that you don't have to reach all over the place for them.
  • Map C-w to backward-kill-word for easier fixing of typos (which means less reaching for backspace) and then map kill-region to C-x C-k so that we can still get to it easily.

I want to start creating new keybindings using general instead of this old-school way, so I will make sure that it's installed using use-package, and then bind my keys:

(use-package general :ensure t
  :config 
  (general-define-key 
  "C-w" 'backward-kill-word 
  "\C-x\C-k" 'kill-region)

  (general-define-key
  ;; use M-o to switch windows
  "M-o" 'other-window)

  (general-define-key
  ;; replace default keybindings 
  "C-s" 'swiper)             ; search for string in current buffer

(general-define-key
 :prefix "C-c"
 ;; bind to simple key press
  "b"   'ivy-switch-buffer  ; change buffer, chose using ivy
  "/"   'counsel-git-grep   ; find string in git project
  ;; bind to double key press
  "f"   '(:ignore t :which-key "files")
  "ff"  'counsel-find-file
  "fr"  'counsel-recentf
  "p"   '(:ignore t :which-key "project")
  "pf"  '(counsel-git :which-key "find file in git dir")
  ))

(use-package which-key :ensure t)

#Theme, Fonts, and Appearance

#Theme

I like the plan9 color scheme, based on Plan 9 and its acme editor. In the terminal (including on Windows Subsystem for Linux), I like to use wheatgrass instead because it works much better there.

(if (window-system) (load-theme 'plan9 t nil) ;; (window-system) returns nil if emacs isn't running in one.
      (load-theme 'wheatgrass t nil)) ;; load wheatgrass if we can't use the base16 theme.

#Fonts

I like to use IBM Plex Mono, but it needs to be a different size depending on what OS I'm on. For some reason, font rendering on the Mac makes everything much smaller.

(if (memq window-system '(mac ns))
 (set-face-attribute 'default nil :font "IBM Plex Mono" :height 175) ;; on OS X
 (set-face-attribute 'default nil :font "IBM Plex Mono" :height 120)) ;; everywhere else

#GUI Appearance

We want to suppress the (hideous) Emacs splash screen, and also hide the icon-based toolbar, but not the menubar.

(when window-system
   (setq inhibit-startup-message t) ;; disable the startup screen
   (tool-bar-mode 0)                ;; disable the tool bar
   (tooltip-mode 0))                ;; disable the tooltips

We also want to maximize by default when the GUI version opens:

(add-hook 'window-setup-hook 'toggle-frame-maximized t)

#Load custom.el

We want to take the customization interface stuff from Emacs and load it, but keep it out of this file since adding stuff to this file might cause unpredictable behavior. We want Emacs to check for a custom.el file in the Emacs directory and then load it if it exists.

(setq-default custom-file (expand-file-name "custom.el" user-emacs-directory))
(when (file-exists-p custom-file)
  (load custom-file))

#Load local.el

We also want to allow for a local.el file that isn't tracked by version control, to allow for settings like API keys and such to be loaded without having to be stored in a public place, and to allow machine-specific settings to be stored somewhere out of the Git repo.


(let ((local.el (expand-file-name "local.el" "~/.emacs.d/")))
  (when (file-exists-p local.el)
    (load local.el)))

#Mode-specific

#counsel

Use counsel for finding stuff, and let M-x use it.

(global-set-key (kbd "M-x") 'counsel-M-x)             ;; Give M-x counsel features
(global-set-key (kbd "C-x C-f") 'counsel-find-file)   ;; Give C-x C-f counsel features
(global-set-key (kbd "C-c g") 'counsel-git)          ;; Use C-c g for counsel-git globally

#Markdown-mode

This is specific stuff for markdown-mode that makes things better.

We want to load pandoc-mode and wc-goal-mode every time we load markdown-mode so that we can export to everything and also keep track of word counts.

;; set up markdown-mode with the proper minor modes
(add-hook 'markdown-mode-hook 'pandoc-mode)
(add-hook 'markdown-mode-hook 'wc-goal-mode)

Whenever a file ends in text, markdown, md, or mmd, automatically load markdown-mode.

;; autoload these filetypes as markdown-mode
(autoload 'markdown-mode "markdown-mode"
   "Major mode for editing Markdown files" t)
(add-to-list 'auto-mode-alist '("\\.text\\'" . markdown-mode))
(add-to-list 'auto-mode-alist '("\\.markdown\\'" . markdown-mode))
(add-to-list 'auto-mode-alist '("\\.md\\'" . markdown-mode))
(add-to-list 'auto-mode-alist '("\\.mmd\\'" . markdown-mode))

Set up a special keyboard shortcut (that only works on the Mac, but for some reason I'm defining it everywhere) so that C-c m opens the current Markdown file in Marked.app for previewing.

;; C-c m opens the current file in Marked.app
(defun markdown-preview-file ()
   "run Marked on the current file and revert the buffer"
   (interactive)
   (shell-command
    (format "open -a /Applications/Marked\\ 2.app %s"
            (shell-quote-argument (buffer-file-name))))
   )
 (global-set-key "\C-cm" 'markdown-preview-file)

#Visual-line-mode

I want to automatically use visual-line-mode if I'm in a mode that is derived from text-mode or from org-mode.

;; use visual line mode while in anything derived from Text mode or Org
(add-hook 'text-mode-hook 'visual-line-mode)
(add-hook 'org-mode-hook (lambda () (visual-line-mode 1)))

#Org mode

#File associations

Automatically load Org for org files.


(use-package org
  :mode ("\\.org$" . org-mode)
  :config (setq org-log-done t)) ; don't remember what this does

#org-refile settings

We want to allow creation of new headers when refiling current headers.

(setq org-refile-allow-creating-parent-nodes 'confirm)

We also want to be able refile to any of the first three levels of an outline, on the local file and on any of the files in the org-agenda-files list (which we're currently not populating with anything, but might in the future).

(setq org-refile-targets `((nil :maxlevel . 3) (org-agenda-files :maxlevel . 3)))

#org-bullets

Make sure the fancy org-bullets is installed for fancy UTF-8 bullets in Org.

(add-hook 'org-mode-hook (org-bullets-mode))

#ox-pandoc

Set everything to be a standalone pandoc export. Typically on one of my systems luatex is installed, so we want to use that for PDF output from Org mode.

(setq org-pandoc-options '((standalone . t)))
(setq org-pandoc-options-for-latex-pdf '((latex-engine . "luatex")))

#nXML mode

A function borrowed from someone else borrowing it from Benjamin Ferrari for pretty-printing a region of XML being edited with nxml-mode.

(defun bf-pretty-print-xml-region (begin end)
  "Pretty format XML markup in region. You need to have nxml-mode
http://www.emacswiki.org/cgi-bin/wiki/NxmlMode installed to do
this.  The function inserts linebreaks to separate tags that have
nothing but whitespace between them.  It then indents the markup
by using nxml's indentation rules."
  (interactive "r")
  (save-excursion
      (nxml-mode)
      (goto-char begin)
      (while (search-forward-regexp "\>[ \\t]*\<" nil t) 
        (backward-char) (insert "\n"))
      (indent-region begin end))
    (message "Ah, much better!"))

#wc-goal-mode

Set the display for wc-goal-mode in the modeline.

;; Set wc-goal-mode modeline display
(setq wc-goal-modeline-format "WC[%w;%tw/%gw]")

#csv-mode

We want csv-mode to automatically load when we open a file with the .csv extension.

;; use use-package to associate .csv files with csv-mode
(use-package csv-mode
  :mode ("\\.csv\\'" . csv-mode))

#AUCTeX

Since I do a lot of writing using the novel document class, I want AUCTeX to always use LuaLaTeX as the TeX engine.

(setq TeX-engine 'luatex)

#Platform-specific configurations

#Windows configurations

Windows being what it is, there are configurations we need to make to make Emacs (the emax distribution for W64) behave in a Windows environment.

#Root directories

We need to set all the right root directories, and then make sure emax knows that we're supposed to be using UTF-8 everywhere:

(when (string-equal system-type "windows-nt") ; test whether we're on Windows

  ;; set variables for all of the various paths
  (defvar emax-root (concat (expand-file-name "~") "/emax"))
  (defvar emax-bin (concat emax-root "/bin"))
  (defvar emax-bin64 (concat emax-root "/bin64"))
  (defvar emax-mingw64 (concat emax-root "/mingw64/bin"))
  (defvar emax-lisp (concat emax-root "/lisp"))

  ;; add the various paths to the $PATH (get it?)
  (setq exec-path (cons emax-bin exec-path))
  (setenv "PATH" (concat emax-bin ";" (getenv "PATH")))

  (setq exec-path (cons emax-bin64 exec-path))
  (setenv "PATH" (concat emax-bin64 ";" (getenv "PATH")))

  (setq exec-path (cons emax-mingw64 exec-path))
  (setenv "PATH" (concat emax-mingw64 ";" (getenv "PATH")))

  (setenv "PATH" (concat "C:\\msys64\\usr\\bin;C:\\msys64\\mingw64\\bin;" (getenv "PATH"))))

The other important thing, since we're on Windows, where things get weird sometimes, is to make sure Emacs always knows everything should be UTF-8 instead of some weird Windows thing.

(when (string-equal system-type "windows-nt") ; test whether we're on Windows
  ;; make sure everything is expecting UTF-8
  (set-language-environment 'utf-8)
  (setq locale-coding-system 'utf-8)
  (set-default-coding-systems 'utf-8)
  (set-terminal-coding-system 'utf-8)
  (prefer-coding-system 'utf-8))

#Garbage collection fixes

There's an issue with garbage collection on Windows as of Emacs 25 that can cause org-mode and visual-line-mode to run very slowly when moving from line to line. This is a hack to make the GC run less often on Windows than it would by default (not until 500MB have been allocated, and then only when Emacs is idle for 5s).

(Credit for this fix goes to reddit user /u/DrSpotter.)


(when (string-equal system-type "windows-nt") ; test whether we're on Windows
  (setq gc-cons-threshold (* 511 1024 1024)) ; put off GC until 500MB of allocation
  (setq gc-cons-percentage 0.5)
  (run-with-idle-timer 5 t #'garbage-collect) ; GC only when idle for 5s
  (setq garbage-collection-messages t))

#Other Windows slowness mitigations

From this post:


(setq-default w32-pipe-read-delay 0
  inhibit-compacting-font-caches t
  bidi-display-reordering nil)

#macOS configurations

These are the bits of the configuration which are only necessary on Mac OS X (which is where I run this configuration half the time; the other half is spent on Fedora). exec-path-from-shell includes environment variables from the shell (things like $PATH and such).

;; code to run only if we're on an OS X system
(when (memq window-system '(mac ns))
  ;; use GNU coreutils for dired (installed from Homebrew)
  (setq insert-directory-program (executable-find "gls")) 
  ;; use Command instead of Option as Meta
  ; (setq mac-command-modifier 'meta) 
  ;; don't do anything with Option
  ; (setq mac-option-modifier nil))
  )

#License

My Emacs configurations written in Org mode. Format based on the Emacs configuration of Lars Tveito.

Copyright (c) 2015-2022 Kevin Lipe

Copyright (c) 2013-2015 Lars Tveito

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.