path: root/config.org

#+TITLE: Emacs configuration, literate-style
#+AUTHOR: Case Duckworth
#+PROPERTY: header-args :tangle yes :tangle-mode (identity #o444) :comments both

* Settings

Basic settings necessary for a decent editing experience in Emacs.
These should not require non-built-in packages.

** Prelude

*** Enable lexical binding

#+begin_src emacs-lisp :comments no
  ;; config.el -*- lexical-binding: t -*-
#+end_src

*** Disclaimer

#+NAME: disclaimer
#+begin_src emacs-lisp :comments no
  ;; This file is automatically tangled from config.org.
  ;; Hand edits will be overwritten!
#+end_src

** Customization

*** Emulate use-package's =:custom=

#+begin_src emacs-lisp
  (defmacro cuss (var val &optional _docstring)
    "`use-package''s `:custom', without `use-package'."
    (declare (doc-string 3)
	     (indent 2))
    `(funcall (or (get ',var 'custom-set) #'set-default)
	      ',var ,val))
#+end_src

*** Emulate use-package's =:custom-face=

#+begin_src emacs-lisp
  (defvar acdw--custom-faces ()
    "List of custom faces to run through `acdw/set-custom-faces'.")

  (defun acdw/set-custom-faces ()
    "Customize faces using `customize-set-faces'.

  I only want to run this once, per the documentation of `customize-set-faces'."
    (when acdw--custom-faces
      (let ((msg "Customizing faces"))
	(message "%s..." msg)
	(apply #'custom-set-faces acdw--custom-faces)
	(message "%s...Done." msg)
	(remove-function after-focuse-change-function #'acdw/set-custom-faces))))

  (add-function :before after-focus-change-function #'acdw/set-custom-faces)

  (defmacro cussface (face spec &optional _docstring)
    "Add the form (FACE SPEC) to `acdw--custom-faces'."
    (declare (doc-string 3)
	     (indent defun))
    `(add-to-list 'acdw--custom-faces '(,face ,spec)))
#+end_src

*** Only do something when Emacs is unfocused

Since Emacs is single-threaded, I only want to run really expensive
operations when I won't notice, say .. when I'm focused on another
window.

#+begin_src emacs-lisp
  (defun when-unfocused (func &rest args)
    "Run FUNC with ARGS iff all frames are out of focus."
    (when (seq-every-p #'null (mapcar #'frame-focus-state (frame-list)))
      (apply func args)))
#+end_src

*** Throw customizations away

I use Emacs's Customize interface, but really only to learn about what
options a package presents to /be/ customized.  I don't want to use
the custom file for anything at all.

#+begin_src emacs-lisp
  (cuss custom-file null-device)
#+end_src

** About me

My name and email address.

#+begin_src emacs-lisp
  (setq user-full-name "Case Duckworth"
	user-mail-address "acdw@acdw.net")
#+end_src

** Look and feel

*** Cursor

#+begin_src emacs-lisp
  ;; Show a vertical bar cursor
  (cuss cursor-type 'bar)

  ;; Hide the cursor in other windows
  (cuss cursor-in-non-selected-windows nil)

  ;; Don't blink the cursor
  (blink-cursor-mode -1)
#+end_src

*** Tabs

**** Tab names should be current buffer + a count of windows

#+begin_src emacs-lisp
  (cuss tab-bar-tab-name-function
      #'tab-bar-tab-name-current-with-count)
#+end_src

**** Only show the tab bar when there's more than one tab

For some reason, this doesn't work with multiple frames.

#+begin_src emacs-lisp
  (cuss tab-bar-show 1)
#+end_src

*** Frames

/Frames/ are Emacs's concepts that generally correspond to other
programs' /windows/ -- that is, they're the boxen on the screen that
contain the Emacs programmen.

**** Initial frame setup
:PROPERTIES:
:header-args: :noweb-ref initial-frame-setup
:END:

***** Tool bar

#+begin_src emacs-lisp
  (add-to-list 'default-frame-alist
	       '(tool-bar-lines . 0))

  (tool-bar-mode -1)
#+end_src

***** Menu bar

#+begin_src emacs-lisp
  (add-to-list 'default-frame-alist
	       '(menu-bar-lines . 0))

  (menu-bar-mode -1)
#+end_src

***** Scroll bars

#+begin_src emacs-lisp
  (add-to-list 'default-frame-alist
	       '(vertical-scroll-bars . nil)
	       '(horizontal-scroll-bars . nil))

  (scroll-bar-mode -1)
  (horizontal-scroll-bar-mode -1)
#+end_src

**** Frame titles

Set the frame title to something more useful than the default: include
the current buffer and the current filename.

#+begin_src emacs-lisp
  (cuss frame-title-format
      (concat invocation-name "@" (system-name)
	      ": %b %+%+ %f"))
#+end_src

**** Fringes

I have grown to love Emacs's little fringes on the side of the
windows.  In fact, I love them so much that I really went overboard
and have made a custom fringe bitmap.

***** Indicate empty lines after the end of the buffer

#+begin_src emacs-lisp
  (cuss indicate-empty-lines t)
#+end_src

***** Indicate the boundaries of the buffer

#+begin_src emacs-lisp
  (cuss indicate-buffer-boundaries 'right)
#+end_src

***** Indicate continuation lines, but only on the left fringe

#+begin_src emacs-lisp
  (cuss visual-line-fringe-indicators '(left-curly-arrow nil))
#+end_src

***** Customize fringe bitmaps

****** Curly arrows (continuation lines)

#+begin_src emacs-lisp
  (define-fringe-bitmap 'left-curly-arrow
    [#b11000000
     #b01100000
     #b00110000
     #b00011000])

  (define-fringe-bitmap 'right-curly-arrow
    [#b00011000
     #b00110000
     #b01100000
     #b11000000])
#+end_src

****** Arrows (truncation lines)

#+begin_src emacs-lisp
  (define-fringe-bitmap 'left-arrow
    [#b00000000
     #b01010100
     #b01010100
     #b00000000])

  (define-fringe-bitmap 'right-arrow
    [#b00000000
     #b00101010
     #b00101010
     #b00000000])
#+end_src

*** Windows

**** Winner mode

I don't really /use/ winner-mode as of yet, but it seems like a really
good thing to have.  It lets you move between window configurations
with =C-c <-/->=.

#+begin_src emacs-lisp
  (when (fboundp 'winner-mode)
    (winner-mode +1))
#+end_src

**** Switch windows, or buffers if there's only one

from [[https://www.reddit.com/r/emacs/comments/kz347f/what_parts_of_your_config_do_you_like_best/gjlnp2c/][u/astoff1]].

#+begin_src emacs-lisp
  (defun other-window-or-buffer ()
    "Switch to the other window, or previous buffer."
    (interactive)
    (if (eq (count-windows) 1)
	(switch-to-buffer nil)
      (other-window 1)))
#+end_src

*** Buffers

**** Startup buffers

I don't want to see Emacs's splash screen, and I want the =*scratch*=
buffer to have a little message.

#+begin_src emacs-lisp
  (cuss inhibit-startup-screen t
    "Don't show the startup buffer.")

  (cuss initial-buffer-choice t
    "Start with *scratch*.")

  (cuss initial-scratch-message
      (concat ";; Hello, " (nth 0 (split-string user-full-name)) "!\n"
	      ";; Happy hacking ..."))
#+end_src

**** Immortal =*scratch*= buffer

I don't want to accidentally kill the =*scratch*= buffer.

#+begin_src emacs-lisp
  (defun immortal-scratch ()
    (if (eq (current-buffer) (get-buffer "*scratch*"))
	(progn (bury-buffer)
	       nil)
      t))

  (add-hook 'kill-buffer-query-functions #'immortal-scratch)
#+end_src

**** Uniquify buffers

I like the =forward= style, which uniquifies buffers by including path
elements up the tree until the names are unique.

#+begin_src emacs-lisp
  (require 'uniquify)
  (cuss uniquify-buffer-name-style 'forward)
#+end_src

**** Kill buffers more smarter-ly

#+begin_src emacs-lisp
  (defun kill-a-buffer (&optional prefix)
    "Kill buffers and windows sanely.

  `kill-a-buffer' works based on the prefix argument as follows:

  - 0            => kill the CURRENT buffer and window
  - 4 (C-u)      => kill the OTHER window and its buffer
  - 16 (C-u C-u) => kill ALL OTHER buffers and windows

  Prompt iff there are unsaved changes."
    (interactive "P")
    (pcase (or (car prefix) 0)
      (0  (kill-current-buffer)
	  (unless (one-window-p) (delete-window)))
      (4  (other-window 1)
	  (kill-current-buffer)
	  (unless (one-window-p) (delete-window)))
      (16 (mapc #'kill-buffer (delq (current-buffer) (buffer-list)))
	  (delete-other-windows))))
#+end_src

*** Fonts

**** Function: =set-face-from-alternatives=

To be honest, this might be better off using =cussface=, but that's
another story for another day.

#+begin_src emacs-lisp
  (defun set-face-from-alternatives (face frame &rest fontspecs)
    "Set FACE on FRAME from first available font from FONTSPECS.
  FACE and FRAME work the same as with `set-face-attribute'."
    (catch :return
      (dolist (spec fontspecs)
	(when-let ((found (find-font (apply #'font-spec spec))))
	  (set-face-attribute face frame :font found)
	  (throw :return found)))))
#+end_src

**** Add a hook to setup fonts after the first window focus change

Of course, I only need to setup the fonts on a graphical session.

#+begin_src emacs-lisp
  (when (display-graphic-p)
    (add-function :before after-focus-change-function #'acdw/setup-fonts))
#+end_src

**** Setup my fonts

Notice that this function removes itself from
=after-focus-change-function=, since ideally you'll only need to set
the fonts once.

#+begin_src emacs-lisp
  (defun acdw/setup-fonts ()
    "Setup fonts.

  This has to happen after the frame is setup for the first time,
  so it should be added to `after-focus-change-function'.  It
  removes itself."
    (set-face-from-alternatives 'default nil
				'(:family "Input Mono"
				  :slant normal
				  :weight normal
				  :height 110)
				'(:family "Consolas"
				  :slant normal
				  :weight normal
				  :height 100))
    ;; `fixed-pitch' should just inherit from `default'
    (set-face-attribute 'fixed-pitch nil :inherit 'default)

    (set-face-from-alternatives 'variable-pitch nil
				'(:family "Input Sans"
				  :slant normal
				  :weight normal)
				'(:family "Georgia"
				  :slant normal
				  :weight normal))

    (remove-function after-focus-change-function #'acdw/setup-fonts))
#+end_src

**** Underlines

#+begin_src emacs-lisp
  (cuss x-underline-at-descent-line t)
#+end_src

** Interactivity
*** Dialogs and alerts

**** Don't use a dialog box

#+begin_src emacs-lisp
  (cuss use-dialog-box nil)
#+end_src

**** Yes or no questions

#+begin_src emacs-lisp
  (fset 'yes-or-no-p #'y-or-n-p)
#+end_src

**** The Bell

#+begin_src emacs-lisp
  ;; Don't flash the whole screen on bell
  (cuss visible-bell nil)

  ;; Instead, flash the mode line
  (cuss ring-bell-function #'flash-mode-line)

  (defun flash-mode-line ()
    (invert-face 'mode-line)
    (run-with-timer 0.2 nil #'invert-face 'mode-line))
#+end_src

t*** Minibuffer

*** Minibuffer

**** Keep the cursor away from the minibuffer prompt

#+begin_src emacs-lisp
  (cuss minibuffer-prompt-properties
      '(read-only t cursor-intangible t face minibuffer-prompt))
#+end_src

**** Enable recursive minibuffer

#+begin_src emacs-lisp
  (cuss enable-recursive-minibuffers t)
#+end_src

**** Show how deep the minibuffer goes in the modeline

#+begin_src emacs-lisp
  (minibuffer-depth-indicate-mode +1)
#+end_src

*** Completing-read

**** Shadow file names

When typing =~= or =/= in the file-selection dialog, Emacs "pretends"
that you've typed them at the beginning of the line.  By default,
however, it only /fades out/ the previous contents of the line.  I
want to /hide/ those contents.

#+begin_src emacs-lisp
  (cuss file-name-shadow-properties '(invisible t))

  (file-name-shadow-mode +1)
#+end_src

**** Ignore case

#+begin_src emacs-lisp
  (cuss completion-ignore-case t)
  (cuss read-buffer-completion-ignore-case t)
  (cuss read-file-name-completion-ignore-case t)
#+end_src

** Persistence

*** Minibuffer history

The =savehist= package saves the minibuffer history between sessions.
It can also save some other variables alongside the minibuffer
history.  Since storage is cheap, I'm also going to keep all my
history.

#+begin_src emacs-lisp
  (require 'savehist)

  (cuss savehist-additional-variables
      '(kill-ring
	search-ring
	regexp-search-ring))

  ;; Don't truncate history
  (cuss history-length t)

  ;; Delete history duplicates
  (cuss history-delete-duplicates t)

  (savehist-mode +1)
#+end_src

*** File places

The =saveplace= package saves where I've been in the files I've
visited, so I can return back to them.

#+begin_src emacs-lisp
  (require 'saveplace)

  ;; Forget the place in unreadable files
  (cuss save-place-forget-unreadable-files t)

  (save-place-mode +1)
#+end_src

*** Recent files

#+begin_src emacs-lisp
  (require 'recentf)

  ;; Limit the number of items in the recentf menu
  (cuss recentf-max-menu-items 100)
  ;; But not the number of items in the actual list
  (cuss recentf-max-saved-items nil)

  (recentf-mode +1)
#+end_src

**** Save the recentf list periodically

#+begin_src emacs-lisp
  (defun acdw/maybe-save-recentf ()
    "Save `recentf-file every five minutes, but only when out of focus."
    (defvar recentf--last-save (time-convert nil 'integer)
      "When we last ran `recentf-save-list'.")

    (when (> (time-convert (time-since recentf--last-save) 'integer)
	     (* 60 5))
      (setq recentf--last-save (time-convert nil 'integer))
      (acdw/when-unfocused #'recentf-save-list)))

  (add-function :after after-focus-change-function #'acdw/maybe-save-recentf)
#+end_src

** Files

*** Encoding

* System-specific

I use both Linux (at home) and Windows (at work).  To make Emacs
easier to use in both systems, I've included various system-specific
settings and written some ancillary scripts.

** Determine where I am

#+begin_src emacs-lisp
  (defmacro when-at (conditions &rest commands)
    "Run COMMANDS when at a specific place.

  CONDITIONS are one of `:work', `:home', or a list beginning with
  those and other conditions to check.  COMMANDS are only run if
  all CONDITIONS are met."
    (declare (indent 1))
    (let ((at-work (memq system-type '(ms-dos windows-nt)))
	  (at-home (memq system-type '(gnu gnu/linux gnu/kfreebsd))))
      (pcase conditions
	(:work `(when ',at-work ,@commands))
	(:home `(when ',at-home ,@commands))
	(`(:work ,others) `(when (and ',at-work ,others)
			     ,@commands))
	(`(:home ,others) `(when (and ',at-home ,others)
			     ,@commands)))))
#+end_src

** Linux

*** Settings

*** Scripts

**** em
:PROPERTIES:
:header-args: :tangle-mode (identity #o755) :tangle bin/em :mkdirp yes
:END:

Here's a wrapper script that'll start =emacs --daemon= if there isn't
one, and then launch =emacsclient= with the arguments.  Install it to
your =$PATH= somewhere.

#+begin_src sh :shebang "#!/bin/sh"
  if ! emacsclient -nc "$@"; then
      emacs --daemon
      emacsclient -nc "$@"
  fi
#+end_src

**** emacsclient.desktop
:PROPERTIES:
:header-args: :tangle bin/emacsclient.desktop :mkdirp yes
:END:

I haven't really tested this yet, but it should allow me to open other
files and things in Emacs.  From [[https://www.taingram.org/blog/emacs-client.html][taingram]].

#+begin_src conf-desktop
  [Desktop Entry]
  Name=Emacs Client
  GenericName=Text Editor
  Comment=Edit text
  MimeType=text/english;text/plain;text/x-makefile;text/x-c++hdr;text/x-c++src;text/x-chdr;text/x-csrc;text/x-java;text/x-moc;text/x-pascal;text/x-tcl;text/x-tex;application/x-shellscript;text/x-c;text/x-c++;
  Exec=emacsclient -c %f
  Icon=emacs
  Type=Application
  Terminal=false
  Categories=Utility;TextEditor;
#+end_src

** Windows

I use Windows at work, where I /also/ don't have Admin rights.  So I
kind of fly-by-night there.  Much of the ideas and scripts in this
section come from [[https://github.com/termitereform/JunkPile/blob/master/emacs-on-windows.md][termitereform]] on Github.

*** Settings

#+NAME: w32-settings
#+begin_src emacs-lisp
  (when (memq system-type '(windows-nt ms-dos cygwin))
    (setq w32-allow-system-shell t ; enable cmd.exe as shell
	  ))
#+end_src

*** Scripts
:PROPERTIES:
:header-args: :noweb tangle :mkdirp yes
:END:

**** Common variables

#+NAME: w32-bat-common
#+begin_src bat
set HOME=%~dp0..\..\
set EMACS=%~dp0..\..\..\bin\runemacs.exe
#+end_src

**** Emacs Daemon

Either run this once at startup, or put a shortcut of it in the
Startup folder: 
=%USERPROFILE%\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup=.

#+begin_src bat :tangle "bin/Emacs Daemon.cmd"
<<w32-bat-common>>
"%EMACS%" --daemon
#+end_src

**** Emacs Client

This will try to connect to the daemon above.  If that fails, it'll
run =runemacs.exe=.

*This is the main shortcut for running Emacs.*

#+begin_src bat :tangle bin/Emacs.cmd
<<w32-bat-common>>
set EMACSC=%~dp0..\..\..\bin\emacsclientw.exe
"%EMACSC%" -n -c -a "%EMACS%" %*
#+end_src

**** Emacs Safe Start

This runs Emacs with the factory settings.

#+begin_src bat :tangle "bin/Emacs Safe Start.cmd"
<<w32-bat-common>>
"%EMACS%" -Q %*
#+end_src

**** Emacs Debug

This runs Emacs with the =--debug-init= option enabled.

#+begin_src bat :tangle "bin/Emacs Debug.cmd"
<<w32-bat-common>>
"%EMACS%" --debug-init %*
#+end_src
* Appendices
** Emacs's files

*** init.el
:PROPERTIES:
:header-args: :tangle init.el :comments both
:END:

The classic Emacs initiation file.

**** Use lexical binding when evaluating =init.el=

#+begin_src emacs-lisp :comments no :noweb tangle
  ;; init.el -*- lexical-binding: t -*-
  <<disclaimer>>
#+end_src

**** Prefer newer files to older files

#+begin_src emacs-lisp
  (setq load-prefer-newer t)
#+end_src

**** Load the config

I keep most of my config in =config.el=, which is tangled directly
from this file.  This init just loads that file, either from lisp or
directly from Org if it's newer.

#+begin_src emacs-lisp
  (let* (;; Speed up init
         (gc-cons-threshold most-positive-fixnum)
         (file-name-handler-alist nil)
         ;; Config file names
         (conf (expand-file-name "config"
                                 user-emacs-directory))
         (conf-el (concat conf ".el"))
         (conf-org (concat conf ".org")))
    (unless (and (file-newer-than-file-p conf-el conf-org)
                 (load conf 'no-error))
      ;; A plain require here just loads the older `org'
      ;; in Emacs' install dir.  We need to add the newer
      ;; one to the `load-path', hopefully that's all.
      (add-to-list 'load-path (expand-file-name "straight/build/org"
                                                user-emacs-directory))
      (require 'org)
      (org-babel-load-file conf-org)))
#+end_src

*** early-init.el
:PROPERTIES:
:header-args: :tangle early-init.el :comments both
:END:

Beginning with 27.1, Emacs also loads an =early-init.el= file, before
the package manager or the UI code.  The Info says we should put as
little as possible in this file, so I only have what I need.

**** Don't byte-compile this file

#+begin_src emacs-lisp :comments no :noweb tangle
  ;; early-init.el -*- no-byte-compile: t; -*-
  <<disclaimer>>
#+end_src

****  Disable loading of =package.el=

I use =straight.el= instead.

#+begin_src emacs-lisp
  (setq package-enable-at-startup nil)
#+end_src

**** Don't resize the frame when loading fonts

#+begin_src emacs-lisp
  (setq frame-inhibit-implied-resize t)
#+end_src

**** Resize frame by pixels

#+begin_src emacs-lisp
  (setq frame-resize-pixelwise t)
#+end_src

**** Shoe-horned from elsewhere in =config.org=

A fundamental tension of literal programming is logical versus
programmatic ordering.  I understand that's a problem it's meant to
solve but hey, maybe I'm not quite there yet.  I feel that having this
weird shoe-horning of other bits of my config here, in a backwater
heading in an appendix, isn't quite the future I wanted.  But it's
what I have for now.

#+begin_src emacs-lisp :noweb tangle
  <<initial-frame-setup>>
#+end_src

** License
:PROPERTIES:
:header-args: :tangle LICENSE :comments no
:END:

Copyright © 2020 Case Duckworth <acdw@acdw.net>

This work is free.  You can redistribute it and/or modify it under the
terms of the Do What the Fuck You Want To Public License, Version 2,
as published by Sam Hocevar.  See the =LICENSE= file, tangled from the
following source block, for details.

#+begin_src text
  DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE

  Version 2, December 2004

  Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>

  Everyone is permitted to copy and distribute verbatim or modified copies of
  this license document, and changing it is allowed as long as the name is changed.

  DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE

  TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. You just DO WHAT THE FUCK YOU WANT TO.
#+end_src

*** Note on the license

It's highly likely that the WTFPL is completely incompatible with the
GPL, for what should be fairly obvious reasons.  To that, I say:

*SUE ME, RMS!*