dotfiles/README.org

#+TITLE: Dotfiles
#+SUBTITLE: I showed you my source code, pls respond
#+AUTHOR: Christopher James Hayward
#+EMAIL: chris@chrishayward.xyz

#+ROAM_KEY: https://github.com/chayward1/dotfiles/

#+ATTR_ORG: :width 420px
#+ATTR_HTML: :width 420px
#+ATTR_LATEX: :width 420px
[[./docs/images/desktop-alt.png]]

Immutable GNU Emacs dotfiles. Built for Life, Liberty, and the Open Road.
+ 100% Literate
+ 100% Immutable
+ 100% Reproducible

Heavily inspired by [[https://github.com/hlissner/doom-emacs][Doom Emacs]] and [[https://youtube.com/c/SystemCrafters][System Crafters]].

* Init
:PROPERTIES:
:header-args: :tangle init.el
:END:

Although later versions of Emacs introduce =early-init.el=, it's not used in this configuration for two reasons:

+ It's not required due to the modularity
+ Maintaining support for older versions

Assuming you have completed all of the following tasks prior to proceeding further:

1. Imported the =secrets=
2. Initialized the =passwords=
3. Defined the =host= file
4. Created all required symbolic links

Launch emacs: ~emacs -mm --debug-init~
   
** Options

Here's a complete list of all of the options configurable for each host, and their default values. If a host configuration does not exist, the default values will remain.

Configure the system font with a single ~font-family~ and define the size, of which variations to the font size are relative to this value.

#+begin_src emacs-lisp
(defvar dotfiles/font
  "Fira Code"
  "Unified system font family, used on all font faces.")
#+end_src

#+begin_src emacs-lisp
(defvar dotfiles/font-size
  96
  "Unified font size, of which all variations are relative to.")
#+end_src

Used by the desktop module to find the appropriate browser.

#+begin_src emacs-lisp
(defvar dotfiles/browser
  (getenv "BROWSER")
  "The default browser used by the system.")
#+end_src

Used by the writing module to determine the system language.

#+begin_src emacs-lisp
(defvar dotfiles/language
  (getenv "LANG")
  "The default system language.")
#+end_src

#+RESULTS:
: dotfiles/language

All of the available modules defined in the ~dotfiles/modules-available~ constant.

#+begin_src emacs-lisp
(defconst dotfiles/modules-available
  '(core editor desktop writing projects interface)
  "All of the available modules for hosts to load.")
#+end_src

Add the modules you want to initialize to the ~dotfiles/modules~ variable.

#+begin_src emacs-lisp
(defvar dotfiles/modules
  dotfiles/modules-available
  "Enabled modules, modify this in your host configuration.")
#+end_src

Specify the emacs home, and the cache directory.

#+begin_src emacs-lisp
(defvar dotfiles/home
  user-emacs-directory
  "Original value of `user-emacs-directory'.")
#+end_src

Used to seperate the immutable configuration from the stateful package files.

#+begin_src emacs-lisp
(defvar dotfiles/cache
  (expand-file-name "~/.cache/emacs")
  "Where `user-emacs-directory' redirects to.")
#+end_src

Functionality like =completion= and =hints= delayed to avoid popups for common manuevers.

#+begin_src emacs-lisp
(defvar dotfiles/idle
  0.0
  "Length of time to wait before offering completions.")
#+end_src

Required for the all powerful leader key.

#+begin_src emacs-lisp
(defvar dotfiles/leader-key
  "SPC"
  "Custom leader key for custom actions.")
#+end_src

The desktop module requires the global leader key set.

#+begin_src emacs-lisp
(defvar dotfiles/leader-key-global
  (concat "C-" dotfiles/leader-key)
  "Global leader key available everywhere.")
#+end_src

Define where the source repositories exist on disk, for integration with the projects module.

#+begin_src emacs-lisp
(defvar dotfiles/projects
  (expand-file-name "~/.local/source/")
  "Location where source code projects exist on disk.")
#+end_src

Where the password store exists on disk.

#+begin_src emacs-lisp
(defvar dotfiles/passwords
  (expand-file-name "~/.password-store/")
  "Directory containing the password store.")
#+end_src

** Startup

The host configuration loads (if it exist) using the systems name.

#+begin_src emacs-lisp
;; Load the host configuration.
(let ((host-file (concat dotfiles/home "/hosts/" system-name ".el")))
  (when (file-exists-p host-file)
    (load-file host-file)))
#+end_src

Load all of the enabled modules:

#+begin_src emacs-lisp
;; Load the enabled modules.
(dolist (m dotfiles/modules)
  (let ((mod-file (concat dotfiles/home "/modules/" (symbol-name m) ".el")))
    (when (file-exists-p mod-file)
      (load-file mod-file))))
#+end_src

* Hosts

Each host system that runs Emacs has a file defined in the =hosts/= sub directory, following the pattern of ~$HOSTNAME.el~. All of the configurations definitions are in this file. Modules will read these values during initialization.

** Acernitro
:PROPERTIES:
:header-args: :tangle hosts/acernitro.el
:END:

The first machine with real hardware to deploy this configuration to. It's an Acer Nitro AN-515 with the NVIDIA / Intel hybrid graphics card. Due to the issues I encountered with this hardware setup, I again opted to install Ubuntu 20.04, and stripped away the components I don't need.

+ Set the browser to use the flatpak of firefox
+ Set the language to Canadian english
+ Increase font size for high DPI screen

Configure the browser.

#+begin_src emacs-lisp
(setq dotfiles/browser "flatpak run org.mozilla.firefox"
      dotfiles/language "en_CA"
      dotfiles/font-size 132)
#+end_src

This machine has a screen with a high =DPI=, requiring modification to ~dotfiles/font-size~.

#+begin_src emacs-lisp
(setq dotfiles/font-size 132)
#+end_src

** Virtualbox
:PROPERTIES:
:header-args: :tangle hosts/virtualbox.el
:END:

The first configuration, built using the Ubuntu 20.04 LTS server edition. I decided to incorporate =flatpaks= into this build.

+ Set the browser to use the flatpak of firefox
+ Set the language to Canadian english

#+begin_src emacs-lisp
(setq dotfiles/browser "flatpak run org.mozilla.firefox"
      dotfiles/language "en_CA")
#+end_src

* Modules

Breaking down the project into logical units or chapters to keep the code more maintainable and organized. This is also a fundemental requirement to achieve the goal of modularity. Incorporating just the =core= module on a build server to build literate programming projects is just one example.

** Core
:PROPERTIES:
:header-args: :tangle modules/core.el :results silent
:END:

Minimal configuration to make Emacs usable for my own personal workflow. This does little in the ways of improving the visuals, only removing what's included by default and not required. Read more about my technique in my post [[file:docs/posts/immutable-emacs.org.gpg][Immutable Emacs]].

*** Startup

Emacs creates a lot of files relative to ~user-emacs-directory~, these files are not part of this immutable configuration and do not belong in the emacs directory. How can we solve this issue? Shortly after initialization, before most packages load, we change the value to ~dotfiles/cache~. I elaborate more on the technique in my post [[https://chrishayward.xyz/posts/immutable-emacs/][Immutable Emacs]].

#+begin_src emacs-lisp
(setq user-emacs-directory dotfiles/cache)
#+end_src

Because this project uses version-control, we can disable more unwanted features:
+ Lock files
+ Backup files

#+begin_src emacs-lisp
(setq create-lockfiles nil
      make-backup-files nil)
#+end_src

*** Packages

Download and install packages using [[https://github.com/raxod502/straight.el][straight.el]], a functional package manager that integrates with =use-package=, giving us more control over sourcing our packages.

+ Use the development branch
+ Integrate with ~use-package~
  
Apply the configurations prior to bootstrapping the package manager, by setting (writing) to the variables that =straight= will ultimately read from.
  
#+begin_src emacs-lisp
(setq straight-repository-branch "develop"
      straight-use-package-by-default t)
#+end_src

Bootstrap the package manager, downloading, installing, or configuring depending on the state of the configuration. All packages build from source, pinned to specific git commit hashes.
  
#+begin_src emacs-lisp
(defvar bootstrap-version)
(let ((bootstrap-file
       (expand-file-name "straight/repos/straight.el/bootstrap.el" user-emacs-directory))
      (bootstrap-version 5))
  (unless (file-exists-p bootstrap-file)
    (with-current-buffer
        (url-retrieve-synchronously
         "https://raw.githubusercontent.com/raxod502/straight.el/develop/install.el"
         'silent 'inhibit-cookies)
      (goto-char (point-max))
      (eval-print-last-sexp)))
  (load bootstrap-file nil 'nomessage))
#+end_src

Complete the integration with ~use-package~ by installing it with =straight=.
  
#+begin_src emacs-lisp
(straight-use-package 'use-package)
#+end_src

*** Cleanup

Despite having our *stateful* and *immutable* configurations seperate, it's good practice to make efforts to reduce the trash created by Emacs. Install [[https://github.com/emacscollective/no-littering][no-littering]] to reduce the files created by Emacs.

#+begin_src emacs-lisp
(use-package no-littering)
#+end_src

Emacs' default user interface is horrendous, but with less than 10 lines of code we can change that.

#+begin_src emacs-lisp
(setq inhibit-startup-message t)
(global-prettify-symbols-mode)

(scroll-bar-mode -1)
(menu-bar-mode -1)
(tool-bar-mode -1)
(tooltip-mode -1)
#+end_src

*** Babel

*Organize your plain life in plain text*

[[https://orgmode.org][Org-mode]] is one of the hallmark features of Emacs, and provides the basis for my Literate Programming platform. It's essentially a markdown language with rich features for project management, scheduling, development, and writing. It's hard to convey everything within its capabilities.

+ [[https://orgmode.org/worg/org-contrib/babel/languages/index.html][Babel languages]]
+ [[https://orgmode.org/manual/Structure-Templates.html][Structure templates]]

#+begin_src emacs-lisp
(use-package org
  :hook (org-mode . (lambda ()
          (org-indent-mode)
          (visual-line-mode 1)
          (variable-pitch-mode 1)))
  :custom (org-ellipsis " ▾")
          (org-log-done 'time)
          (org-log-into-drawer t)
          (org-image-actual-width nil)
          (org-directory dotfiles/home)
          (org-src-preserve-indentation t)
          (org-todo-keywords '((sequence "TODO" "START" "WAIT" "DONE")))
  :config (require 'org-tempo)
          (add-to-list 'org-structure-template-alist '("s" . "src"))
          (add-to-list 'org-structure-template-alist '("q" . "quote"))
          (add-to-list 'org-structure-template-alist '("e" . "example"))
          (add-to-list 'org-structure-template-alist '("sh" . "src shell"))
          (add-to-list 'org-structure-template-alist '("el" . "src emacs-lisp"))
          (org-babel-do-load-languages 'org-babel-load-languages '((shell . t)
                                                                   (emacs-lisp . t))))
#+end_src

Build all of the =org= files within a given directory.

#+begin_src emacs-lisp
(defun dotfiles/tangle (dir)
  "Recursively tangle the Org files within a directory."
  (let ((org-files (directory-files-recursively dir "org")))
    (dolist (f org-files)
      (org-babel-tangle-file f))))
#+end_src

** Editor
:PROPERTIES:
:header-args: :tangle modules/editor.el :results silent
:END:

This section contains configuration for improving the editor experience within Emacs.

*** Keys

Make the =ESC= key quit (most) prompts, instead of the default =C-g=.

#+begin_src emacs-lisp
(global-set-key (kbd "<escape>") 'keyboard-escape-quit)
#+end_src

Download [[https://github.com/justbur/emacs-which-key][which-key]], a package that displays the current incomplete keybinding input in a mini-buffer, showing available completion options.

#+begin_src emacs-lisp
(use-package which-key
  :diminish which-key-mode
  :custom (which-key-idle-delay dotfiles/idle)
  :config (which-key-mode))
#+end_src

Turn Emacs into Vim with [[https://evil.readthedocs.io/en/latest/index.html][evil-mode]], the extensible VI layer for Emacs.

#+begin_src emacs-lisp
(use-package evil
  :custom (evil-want-integration t)  ;; Required for `evil-collection'.
          (evil-want-keybinding nil) ;; Same as above
  :config (evil-mode 1))
#+end_src

Unfortunately the default keybindings are *lacking*, but there is a community curated package [[https://github.com/emacs-evil/evil-collection][evil-collection]], which does a much better job implementing keybindings you would expect to find.

#+begin_src emacs-lisp
(use-package evil-collection
  :after evil
  :config (evil-collection-init))
#+end_src

Surround text with functions, quotations, and any other symbols using the [[https://github.com/emacs-evil/evil-surround][evil-surround]] package.

#+begin_src emacs-lisp
(use-package evil-surround
  :after evil
  :config (global-evil-surround-mode 1))
#+end_src

Toggle block comments using [[https://github.com/redguardtoo/evil-nerd-commenter][evil-nerd-commentor]] and =M-;=.

#+begin_src emacs-lisp
(use-package evil-nerd-commenter
  :after evil
  :bind ("M-;" . evilnc-comment-or-uncomment-lines))
#+end_src

Implement the *leader* key using [[https://github.com/noctuid/general.el][general.el]], letting us easily configure prefixed keybindings in a much cleaner manner than the default methods.

#+begin_src emacs-lisp
(use-package general
  :after evil
  :config
  (general-create-definer dotfiles/leader
    :states '(normal motion)
    :keymaps 'override
    :prefix dotfiles/leader-key
    :global-prefix dotfiles/leader-key-global))
#+end_src 

Use [[https://github.com/abo-abo/hydra][hydra]] for transient keybindings sharing a common prefix.

#+begin_src emacs-lisp
(use-package hydra
  :defer t)
#+end_src

*** Help

Use the built-in ~describe-*~ functionality of Emacs to quickly access documentation for packages, variables, and functions. Run helper functions with =SPC h=.

+ Packages =p=
+ Variables =v=
+ Functions =f=

#+begin_src emacs-lisp
(dotfiles/leader
  "h" '(:ignore t :which-key "Help")
  "hp" '(describe-package :which-key "Package")
  "hv" '(describe-variable :which-key "Variable")
  "hf" '(describe-function :which-key "Function"))
#+end_src

*** Files

For file navigation I use =dired=, included with Emacs by default. Dired feels more modern with prioritized icon fonts using [[https://github.com/domtronn/all-the-icons.el][all-the-icons]]. This makes navigation and visually parsing directories much faster, given that file types are quickly identified by their corresponding icons.

#+begin_src emacs-lisp
(use-package all-the-icons)
#+end_src

Integration with =dired= comes from the [[https://github.com/jtbm37/all-the-icons-dired][all-the-icons-dired]] package.

#+begin_src emacs-lisp
(use-package all-the-icons-dired
  :hook (dired-mode . all-the-icons-dired-mode))
#+end_src

When opening =dired=, I don't want to have to press =RET= twice to navigate to the current directory. Avoided this with ~dired-jump~, included in the =dired-x= package shipped with =dired= and Emacs.

#+begin_src emacs-lisp
(require 'dired-x)
#+end_src

By default =dired= will create a new buffer everytime you press =RET= over a directory. This leads to unwanted =dired= buffers needing closure. Avoid this behaviour with [[https://github.com/crocket/dired-single][dired-single]], reusing the same dired buffer.

+ Move up a directory with =h=
+ Open a single buffer with =l=

#+begin_src emacs-lisp
(use-package dired-single
  :config (evil-collection-define-key 'normal 'dired-mode-map
            "h" 'dired-single-up-directory
            "l" 'dired-single-buffer))
#+end_src

Open a dired buffer with =SPC d=.

#+begin_src emacs-lisp
(dotfiles/leader
  "d" '(dired-jump :which-key "Dired"))
#+end_src

*** Shell

While not a traditional terminal emulator, =eshell= provides me with all of the functionality I expect and require from one. Some users may be wanting more, I would recommend they look into =vterm= included in the destkop module. Configure the infamous lambda prompt using [[https://github.com/zwild/eshell-prompt-extras][eshell-prompt-extras]] package.

#+begin_src emacs-lisp
(use-package eshell-prompt-extras
  :custom (eshell-highlight-prompt nil)
	        (eshell-prompt-function 'epe-theme-lambda))
#+end_src

Open an =eshell= buffer with =SPC e=.

#+begin_src emacs-lisp
(dotfiles/leader
  "e" '(eshell :which-key "Shell"))
#+end_src

Configure =vterm=, a complete POSIX compliant shell within Emacs, this is suitable when =eshell= is not up to the task.

#+begin_src emacs-lisp
(use-package vterm)
#+end_src

Open a =vterm= buffer in a new window with =SPC v=.

#+begin_src emacs-lisp
(dotfiles/leader
  "v" '(vterm-other-window :which-key "Terminal"))
#+end_src

*** Source

Another hallmark feature is [[https://github.com/magit/magit][Magit]], a complete git porcelain within Emacs.

#+begin_src emacs-lisp
(use-package magit
  :custom (magit-display-buffer-function
           #'magit-display-buffer-same-window-except-diff-v1))
#+end_src

Work directly with github issues / pull requests using [[https://github.com/magit/forge][Forge]].
+ Requires a valid ~$GITHUB_TOKEN~

#+begin_src emacs-lisp
(use-package forge
  :after magit)
#+end_src

Open the *status* page for the current repository with =SPC g=.

#+begin_src emacs-lisp
(dotfiles/leader
  "g" '(magit-status :which-key "Magit"))
#+end_src

*** Windows

Window management with =SPC w=.
+ Swap with =w=
+ Close with =c=
+ Motions with =h,j,k,l=
+ Split with =s + <MOTION>=

#+begin_src emacs-lisp
(dotfiles/leader
  "w" '(:ignore t :which-key "Window")
  "ww" '(window-swap-states :which-key "Swap")
  "wc" '(delete-window :which-key "Close")
  "wh" '(windmove-left :which-key "Left")
  "wj" '(windmove-down :which-key "Down")
  "wk" '(windmove-up :which-key "Up")
  "wl" '(windmove-right :which-key "Right")
  "ws" '(:ignore t :which-key "Split")
  "wsj" '(split-window-below :which-key "Down")
  "wsl" '(split-window-right :which-key "Right"))
#+end_src

*** Shortcuts

Implement shortcut bindings, cherry picked from Doom emacs.

+ Close buffers with =SPC c=
+ Find files with =SPC . (period)=

#+begin_src emacs-lisp
(dotfiles/leader
  "." '(find-file :which-key "Files")
  "c" '(kill-buffer-and-window :which-key "Close"))
#+end_src

Quit emacs with =SPC q=.
+ Saving =q=
+ Without =w=
+ Frame (daemon) =f=

#+begin_src emacs-lisp
(dotfiles/leader
  "q" '(:ignore t :which-key "Quit")
  "qq" '(save-buffers-kill-emacs :which-key "Save")
  "qw" '(kill-emacs :which-key "Now")
  "qf" '(delete-frame :which-key "Frame"))
#+end_src

Place runtime tweaks behind =SPC t=.

#+begin_src emacs-lisp
(dotfiles/leader
  "t" '(:ignore t :which-key "Tweaks"))
#+end_src

** Desktop
:PROPERTIES:
:header-args: :tangle modules/desktop.el :results silent
:END:

#+ATTR_ORG: :width 420px
#+ATTR_HTML: :width 420px
#+ATTR_LATEX: :width 420px
[[./docs/images/2021-02-13-example-mu4e.gif]]

I use Emacs as a Desktop Environment with the [[https://github.com/ch11ng/exwm][exwm]] package. It allows Emacs to function as a complete tiling window manager for =X11=. My workflow includes launching the window manager with =xinitrc=, without the use of a display manager, controlling *everything* within Emacs.

#+begin_src conf :tangle config/xinitrc
exec dbus-launch --exit-with-session emacs -mm --debug-init
#+end_src

*** Email


Plain text email delivered via mu, mu4e and mbsync. I run my own email server, so your configuration may differ from mine. This is the ~mbsyncrc~ file I use to synchronize my local mail with my server. This is required for mu4e in Emacs.

#+begin_src conf :tangle config/mbsyncrc
IMAPStore xyz-remote
Host mail.chrishayward.xyz
User chris@chrishayward.xyz
PassCmd "pass chrishayward.xyz/chris"
SSLType IMAPS

MaildirStore xyz-local
Path ~/.cache/mail/
Inbox ~/.cache/mail/inbox
SubFolders Verbatim

Channel xyz
Master :xyz-remote:
Slave :xyz-local:
Patterns * !Archives
Create Both
Expunge Both
SyncState *
#+end_src

The system typically expects to find this file at ~$HOME/.mbsyncrc~, but you may also specify a custom path if launching the command using arguments. I chose to symlink the default location to my repository.

#+begin_src shell :tangle no
mbsync -a
mu index --maildir="~/.cache/mail"
#+end_src

Once the mail is being synchronized, and the mail has been indexed with =mu=, it's time to install the required packages for Emacs.

+ Update every 5 minutes
+ Scale text for all devices
+ Sign outbound mail with GPG key
+ Configure mail account(s)

#+begin_src emacs-lisp
(use-package mu4e
  :load-path "/usr/share/emacs/site-lisp/mu4e"
  :custom (mu4e-maildir "~/.cache/mail")
          (mu4e-update-interval (* 5 60))
          (mu4e-get-mail-command "mbsync -a")
          (mu4e-compose-format-flowed t)
          (mu4e-change-filenames-when-moving t)
          (message-send-mail-function 'smtpmail-send-it)  
          (mml-secure-openpgp-signers '("37AB1CB72B741E478CA026D43025DCBD46F81C0F"))
          (mu4e-compose-signature (concat "Chris Hayward\n"
                                          "https://chrishayward.xyz\n"))
  :config
  (add-hook 'message-send-hook 'mml-secure-message-sign-pgpmime)
  (setq mu4e-contexts
    (list
      ;; Main
      ;; chris@chrishayward.xyz
      (make-mu4e-context
        :name "Main"
        :match-func
          (lambda (msg)
            (when msg 
              (string-prefix-p "/Main" (mu4e-message-field msg :maildir))))
        :vars
          '((user-full-name . "Christopher James Hayward")
            (user-mail-address . "chris@chrishayward.xyz")
            (smtpmail-smtp-server . "mail.chrishayward.xyz")
            (smtpmail-smtp-service . 587)
            (smtpmail-stream-type . starttls))))))
#+end_src

Use [[https://github.com/iqbalansari/mu4e-alert][mu4e-alert]] to give us desktop notifications about incoming mail.

#+begin_src emacs-lisp
(use-package mu4e-alert
  :after mu4e
  :custom (mu4e-alert-set-default-style 'libnotify)
  :config (mu4e-alert-enable-notifications)
          (mu4e-alert-enable-mode-line-display))
#+end_src

Create a keybinding to open the mail dashboard with =SPC m=.

#+begin_src emacs-lisp
(dotfiles/leader
  "m" '(mu4e :which-key "Mail"))
#+end_src

*** Browser

Write out the ~$BROWSER~ environment variable.

#+begin_src emacs-lisp
(setenv "BROWSER" dotfiles/browser)
#+end_src

*** Startup

When launching into a session, if the display server is not running then =startx= should be invoked, to run the window manager.

#+begin_src sh :tangle config/profile
if [ -z "${DISPLAY}" ] && [ "${XDG_VTNR}" -eq 1 ]; then
    exec startx
fi
#+end_src

*** Methods

Define a method to run an external process, allowing us to launch any application on a new process without interferring with Emacs.

#+begin_src emacs-lisp
(defun dotfiles/run (command)
  "Run an external process."
  (interactive (list (read-shell-command "λ ")))
  (start-process-shell-command command nil command))
#+end_src

Some methods must be called and applied to the current call process in order to function correctly with Emacs hooks.

#+begin_src emacs-lisp
(defun dotfiles/run-in-background (command)
  (let ((command-parts (split-string command "[ ]+")))
    (apply #'call-process `(,(car command-parts) nil 0 nil ,@(cdr command-parts)))))
#+end_src

Place keybindings for executing shell commands behind =SPC x=.

+ Run shell commands with =x=
+ Run async shell commands with =z=

#+begin_src emacs-lisp
(dotfiles/leader
  "x" '(:ignore t :which-key "Run")
  "xx" '(dotfiles/run :which-key "Run")
  "xz" '(async-shell-command :which-key "Async"))
#+end_src

*** Displays

When the window manager first launches the ~init-hook~ will be called, this allows us to define some custom logic when it's initialized.

+ Display time and date
+ Display battery info (if available)

In my personal configuration, I do not want the battery or time displayed within Emacs when it's not running as desktop environment because that information is typically already available.

#+begin_src emacs-lisp
(defun dotfiles/init-hook ()
  (exwm-workspace-switch-create 1)
  (setq display-time-and-date t)
  (display-battery-mode 1)
  (display-time-mode 1))
#+end_src

Using =autorandr= with pre configured profiles, switching screens (AKA hot plugging) is also handled through a hook.

#+begin_src emacs-lisp
(defun dotfiles/update-display ()
  (dotfiles/run-in-background "autorandr --change --force"))
#+end_src

*** Configuration

 Connect our custom hooks and configure the input keys, a custom layer for defining which keys are captured by Emacs, and which are passed through to =X= applications.

+ Enable =randr= support
+ Pass through to Emacs
  + =M-x= to Emacs
  + =C-g= to Emacs
  + =C-SPC= to Emacs
+ Bindings with =S= (Super / Win)
  + Reset =S-r=
  + Launch =S-&=
  + Workspace =S-[1..9]=
    
#+begin_src emacs-lisp
(use-package exwm
  :demand t
  :custom (exwm-workspace-show-all-buffers t)
          (exwm-input-prefix-keys
            '(?\M-x
              ?\C-c
              ?\C-g
              ?\C-\ ))
          (exwm-input-global-keys
            `(([?\s-r] . exwm-reset)
              ,@(mapcar (lambda (i)
                          `(,(kbd (format "s-%d" i)) .
                          (lambda ()
                          (interactive)
                          (exwm-workspace-switch-create ,i))))
                          (number-sequence 1 9))))
  :config (require 'exwm-randr)
          (exwm-randr-enable)
          (add-hook 'exwm-init-hook #'dotfiles/init-hook)
          (add-hook 'exwm-randr-screen-change-hook #'dotfiles/update-display)
          (dotfiles/update-display)
          (exwm-enable))
#+end_src

** Writing
:PROPERTIES:
:header-args: :tangle modules/writing.el :results silent
:END:

I am using [[https://orgmode.org][org-mode]] extensively for writing projects for different purposes. Most of the improvements are done in the *Core* module for the Literate programming configuration. [[https://github.com/integral-dw/org-superstar-mode][org-superstar-mode]] for making headline stars more *super*.

#+begin_src emacs-lisp
(use-package org-superstar
  :after org
  :hook (org-mode . org-superstar-mode))
#+end_src

*** Roam

Download and install [[https://orgroam.com][org-roam]], a plain text knowledge management system for Emacs. Organize the capture templates, this allows me to quickly dictate where each new item should be placed.

+ ~posts/~ contains blog posts
+ ~notes/~ contains cited notes on others' work
+ ~slides/~ contains presentations / screencasts

#+begin_src emacs-lisp
(use-package org-roam
  :hook (after-init . org-roam-mode)
  :custom (org-roam-directory org-directory)
          (org-roam-encrypt-files t)
          (org-roam-capture-templates
          '(("p" "Post" plain (function org-roam-capture--get-point)
             "%?"
             :file-name "docs/posts/${slug}"
             :unnarrowed t
             :head
"
,#+TITLE: ${title}
,#+AUTHOR: Christopher James Hayward
,#+DATE: %<%Y-%m-%d>

,#+EXPORT_FILE_NAME: ${slug}
,#+ROAM_KEY: https://chrishayward.xyz/posts/${slug}/

,#+HUGO_BASE_DIR: ../
,#+HUGO_AUTO_SET_LASTMOD: t
,#+HUGO_SECTION: posts
,#+HUGO_DRAFT: true
")
            ("n" "Notes" plain (function org-roam-capture--get-point)
             "%?"
             :file-name "docs/notes/${slug}"
             :unnarrowed t
             :head
"
,#+TITLE: ${title}
,#+AUTHOR: Christopher James Hayward

,#+EXPORT_FILE_NAME: ${slug}
,#+ROAM_KEY: https://chrishayward.xyz/notes/${slug}/

,#+HUGO_BASE_DIR: ../
,#+HUGO_AUTO_SET_LASTMOD: t
,#+HUGO_SECTION: notes
,#+HUGO_DRAFT: true
")
            ("c" "Course" plain (function org-roam-capture--get-point)
             "%?"
             :file-name "docs/courses/${slug}"
             :unnarrowed t
             :head
"
,#+TITLE: ${title}
,#+SUBTITLE:
,#+AUTHOR: Christopher James Hayward
")
            ("s" "Slides" plain (function org-roam-capture--get-point)
             "%?"
             :file-name "docs/slides/${slug}"
             :unnarrowed t
             :head
"
,#+TITLE: ${title}
,#+AUTHOR: Christopher James Hayward

,#+REVEAL_ROOT: https://cdn.jsdelivr.net/npm/reveal.js
")))
          (org-roam-dailies-capture-templates
          '(("d" "Default" entry (function org-roam-capture--get-point)
             "* %?"
             :file-name "docs/daily/%<%Y-%m-%d>"
             :head
"
,#+TITLE: %<%Y-%m-%d>
,#+AUTHOR: Christopher James Hayward
"))))
#+end_src

Place keybindings behind =SPC r=.

+ Find with =f=
+ Toggle buffer with =b=
+ Dailies with =d=
  + Arbitrary date with =d=
  + Today with =t=
  + Tomorrow with =m=
  + Yesterday with =y=

#+begin_src emacs-lisp
(dotfiles/leader
  "r" '(:ignore t :which-key "Roam")
  "rf" '(org-roam-find-file :which-key "Find")
  "rb" '(org-roam-buffer-toggle-display :which-key "Buffer")
  "rd" '(:ignore t :which-key "Dailies")
  "rdd" '(org-roam-dailies-find-date :which-key "Date")
  "rdt" '(org-roam-dailies-find-today :which-key "Today")
  "rdm" '(org-roam-dailies-find-tomorrow :which-key "Tomorrow")
  "rdy" '(org-roam-dailies-find-yesterday :which-key "Yesterday"))
#+end_src

Visualize the org-roam database with the server, available when the editor is running at http://localhost:8080

#+begin_src emacs-lisp
(use-package org-roam-server
  :hook (org-roam-mode . org-roam-server-mode))
#+end_src

*** Hugo

I use [[https://gohugo.io][Hugo]] for my personal [[https://chrishayward.xyz][website]], which I write in =Org-mode= before compiling to =hugo-markdown=. [[https://github.com/kaushalmodi/ox-hugo][Ox-hugo]], configured for =one-post-per-file= is my technique for managing my blog.

#+begin_src emacs-lisp
(use-package ox-hugo 
  :after ox)
#+end_src

*** Slides

Produce high quality presentations that work anywhere with =HTML/JS= and the [[https://revealjs.com][Reveal.js]] package. [[https://github.com/hexmode/ox-reveal][Ox-reveal]], configured to use a =cdn= allows us to produce ones that are not dependent on a local version of =Reveal.js=.

#+begin_src emacs-lisp
(use-package ox-reveal
  :after ox
  :custom (org-reveal-root "https://cdn.jsdelivr.net/npm/reveal.js"))
#+end_src

*** Agenda

Override ~org-agenda-file-regexp~ to include =.org.gpg= files.

#+begin_src emacs-lisp
(unless (string-match-p "\\.gpg" org-agenda-file-regexp)
  (setq org-agenda-file-regexp
        (replace-regexp-in-string "\\\\\\.org" "\\\\.org\\\\(\\\\.gpg\\\\)?"
                                  org-agenda-file-regexp)))
#+end_src

Configure agenda sources.
  
#+begin_src emacs-lisp
(setq org-agenda-files '("~/.emacs.d/docs/"
                         "~/.emacs.d/docs/courses/"
                         "~/.emacs.d/docs/daily/"))
#+end_src

Open an agenda buffer with =SPC a=.

#+begin_src emacs-lisp
(dotfiles/leader
  "a" '(org-agenda :which-key "Agenda"))
#+end_src

*** Images

Create screencasts with =one-frame-per-action= GIF recording via [[https://github.com/takaxp/emacs-gif-screencast][emacs-gif-screencast]].

+ Can be paused / resumed
+ High quality images
+ Optimized size

It requires the installation of ~scrot~, ~gifsicle~, and ~convert~ from the =ImageMagick= library.
  
#+begin_src emacs-lisp
(use-package gif-screencast
  :commands (gif-screencast-start-or-stop gif-screencast-toggle-pause)
  :custom (gif-screencast-output-directory (concat dotfiles/home "docs/images/")))
#+end_src

Screencast controls behind =SPC s=.
+ Start / stop with =s=
+ Pause with =t=

#+begin_src emacs-lisp
(dotfiles/leader
  "s" '(:ignore t :which-key "Screencast")
  "ss" '(gif-screencast-start-or-stop :which-key "Start / Stop")
  "sp" '(gif-screencast-toggle-pause :which-key "Pause"))
#+end_src

*** Grammar

I use [[https://github.com/bnbeckwith/writegood-mode][writegood-mode]] to find common writing problems such as cliches and poor wording. Grammarly for the peons!

#+begin_src emacs-lisp
(use-package writegood-mode
  :after org
  :config (writegood-mode))
#+end_src

Toggle ~writegood~ mode with =SPC t w=.

#+begin_src emacs-lisp
(dotfiles/leader
  "tw" '(writegood-mode :which-key "Grammar"))
#+end_src

*** Spelling

Use the built in =ispell= package to add spell checking features to buffers.

#+begin_src emacs-lisp
(use-package ispell
  :after org
  :custom (ispell-dictionary dotfiles/lang))
#+end_src

** Projects
:PROPERTIES:
:header-args: :tangle modules/projects.el :results silent
:END:

#+ATTR_ORG: :width 420px
#+ATTR_HTML: :width 420px
#+ATTR_LATEX: :width 420px
[[./docs/images/2021-02-13-example-ccls.gif]]

An IDE like experience (or better) can be achieved in Emacs using two *Microsoft* open source initiatives. Turn Emacs into an *IDE* (or better) with the [[https://microsoft.github.io/language-server-protocol/][Language Server Protocol]], an open source initiative from *Microsoft* for the *VSCode* editor. [[https://emacs-lsp.github.io/lsp-mode/][lsp-mode]] brings support for language servers into Emacs.
  
#+begin_src emacs-lisp
(use-package lsp-mode
  :commands (lsp lsp-deferred)
  :custom (lsp-idle-delay 0.500))
#+end_src

[[https://emacs-lsp.github.io/lsp-ui/][lsp-ui]] provides UI improvements for =lsp-mode=.

#+begin_src emacs-lisp
(use-package lsp-ui
  :after lsp
  :custom (lsp-ui-doc-position 'at-point)
          (lsp-ui-doc-delay 0.500))
#+end_src

*** Containers

Use ~docker~ for running containers. Download and install https://github.com/Silex/docker.el, allowing us to manage containers within Emacs.

#+begin_src emacs-lisp
(use-package docker
  :commands (docker))
#+end_src

Open the management screen with =SPC k=.

#+begin_src emacs-lisp
(dotfiles/leader
  "k" '(docker :which-key "Docker"))
#+end_src

*** Management

Configure [[https://projectile.mx][projectile]], a project interaction library for Emacs. It provides a nice set of features for operating on a project level without introducing external dependencies.

#+begin_src emacs-lisp
(use-package projectile
  :custom (projectile-project-search-path '("~/.local/source"))
  :config (projectile-mode))
#+end_src

*** Passwords

Pass makes managing passwords extremely easy, encrypring them in a file structure and providing easy commands for generating, modify, and copying passwords. =password-store.el= provides a wrapper for the functionality within Emacs.

#+begin_src emacs-lisp
(use-package password-store
  :custom (password-store-dir dotfiles/passwords))
#+end_src

Configure keybindings behind =SPC p=.
+ Copy with =p=
+ Rename with =r=
+ Generate with =g=

#+begin_src emacs-lisp
(dotfiles/leader
  "p" '(:ignore t :which-key "Passwords")
  "pp" '(password-store-copy :which-key "Copy")
  "pr" '(password-store-rename :which-key "Rename")
  "pg" '(password-store-generate :which-key "Generate"))
#+end_src

*** Debugging

Handled through the [[https://microsoft.github.io/debug-adapter-protocol/][Debug Adapter Protocol]], an open source initiative from *Microsoft* for the *VSCode* editor.

[[https://emacs-lsp.github.io/dap-mode/][Dap-mode]] adds support for the protocol to Emacs.

#+begin_src emacs-lisp
(use-package dap-mode
  :commands (dap-debug))
#+end_src

*** Completion

Text completion framework via =company= aka *Complete Anything*.

http://company-mode.github.io/
+ Integrate with =lsp-mode=
  
#+begin_src emacs-lisp
(use-package company
  :after lsp)

(use-package company-lsp
  :after (lsp company)
  :custom (company-backend 'company-lsp))
#+end_src

*** Languages

Support for individual languages are implemented here.

**** Go
  
Install the =gopls= language server.

#+begin_src sh :tangle no
GO111MODULE=on go get golang.org/x/tools/gopls@latest
#+end_src

Set the ~GOPATH~ environment variable prior to loading, this allows us to change the default value of ~$HOME/go~ to ~$HOME/.go~.

#+begin_src emacs-lisp
(setenv "GOPATH" (concat (getenv "HOME") "/.go/"))
#+end_src

Additionally, include the =bin= subdirectory of the ~$GOPATH~ in the ~$PATH~ variable, adding compiled golang programs.

#+begin_src emacs-lisp
(setenv "PATH" (concat (getenv "GOPATH") "bin:" (getenv "PATH")))
#+end_src

Finally we can include the =go-mode= package, integrating it with =lsp=.

#+begin_src emacs-lisp
(use-package go-mode
  :hook (go-mode . lsp)
  :custom (lsp-go-gopls-server-path "~/.go/bin/gopls"))
#+end_src

Apply some custom behaviour before saving:

+ Format buffer
+ Organize imports

#+begin_src emacs-lisp
(defun dotfiles/go-hook ()
  (add-hook 'before-save-hook #'lsp-format-buffer t t)
  (add-hook 'before-save-hook #'lsp-organize-imports t t))
#+end_src
  
#+begin_src emacs-lisp
(add-hook 'go-mode-hook #'dotfiles/go-hook)
#+end_src

Add a golang source code block structure template with ~<go~:

#+begin_src emacs-lisp
(add-to-list 'org-structure-template-alist '("go" . "src go"))
#+end_src

**** HTTP

Instead of the popular =restclient= package, I use [[https://github.com/zweifisch/ob-http][ob-http]] as a lightweight alternative.

#+begin_src emacs-lisp
(use-package ob-http
  :after org
  :config (org-babel-do-load-languages
            'org-babel-load-languages
            '((http . t))))
#+end_src

**** C/C++

Install the [[https://github.com/MaskRay/ccls][ccls]] language server, and allow us to create a new structure template for C/C++ with ~<cc~.

#+begin_src emacs-lisp
(use-package ccls
  :hook ((c-mode c++-mode objc-mode cuda-mode) .
         (lambda ()
           (require 'ccls)
           (lsp-deferred)))
  :config (add-to-list 'org-structure-template-alist '("cc" . "src cc")))
#+end_src

**** Python

Install the =pyls= language server.

#+begin_src shell :tangle no
pip install --user "python-language-server[all]"
#+end_src

[[https://www.emacswiki.org/emacs/PythonProgrammingInEmacs][Python-mode]] is an Emacs built in mode.

+ Load the babel language module for Python
+ Add a python source code block structure template with ~<py~
  
#+begin_src emacs-lisp
(use-package python-mode
  :hook (python-mode . lsp-deferred)
  :config (require 'dap-python)
          (add-to-list 'org-src-lang-modes '("python" . python))
          (add-to-list 'org-structure-template-alist '("py" . "src python"))
          (org-babel-do-load-languages 'org-babel-load-languages '((python . t)))
  :custom (python-shell-interpreter "python3") ;; Required if "python" is not python 3.
          (dap-python-executable "python3")    ;; Same as above.
          (dap-python-debugger 'debugpy))
#+end_src

**** PlantUML

Download and install [[https://plantuml.com][PlantUML]], a text-based markup language for creating UML diagrams.

+ Load the babel language module for PlantUML
+ Create a structure template with ~<pl~

#+begin_src emacs-lisp
(use-package plantuml-mode
  :after org
  :custom (plantuml-default-exec-mode 'jar)
          (plantuml-jar-path "~/.local/bin/plantuml.jar")
          (org-plantuml-jar-path (expand-file-name "~/.local/bin/plantuml.jar"))
          (org-startup-with-inline-images t)
  :config (add-to-list 'org-src-lang-modes '("plantuml" . plantuml))
          (add-to-list 'org-structure-template-alist '("pl" . "src plantuml"))
          (org-babel-do-load-languages 'org-babel-load-languages '((plantuml . t))))
#+end_src

Toggle inline images with =SPC t i=.

#+begin_src emacs-lisp
(dotfiles/leader
  "ti" '(org-display-inline-images :which-key "Images"))
#+end_src

** Interface
:PROPERTIES:
:header-args: :tangle modules/interface.el :results silent
:END:

*Bring Emacs out of the eighties*

*** Ivy

Download and configure [[https://oremacs.com/swiper/][ivy]], a powerful selection menu for Emacs.

#+begin_src emacs-lisp
(use-package ivy
  :diminish
  :config (ivy-mode 1))
#+end_src

Counsel is a customized set of commands to replace built in completion buffers.

#+begin_src emacs-lisp
(use-package counsel
  :after ivy
  :custom (counsel-linux-app-format-function #'counsel-linux-app-format-function-name-only)
  :config (counsel-mode 1))
#+end_src

Switch buffers with =SPC , (comma)=.

#+begin_src emacs-lisp
(dotfiles/leader
  "," '(counsel-switch-buffer :which-key "Buffers"))
#+end_src

Provide more information about each item with [[https://github.com/Yevgnen/ivy-rich][ivy-rich]].

#+begin_src emacs-lisp
(use-package ivy-rich
  :after counsel
  :init (ivy-rich-mode 1))
#+end_src

*** Fonts

Write out to all *3* of Emacs' default font faces.

#+begin_src emacs-lisp
(set-face-attribute 'default nil :font dotfiles/font :height dotfiles/font-size)
(set-face-attribute 'fixed-pitch nil :font dotfiles/font :height dotfiles/font-size)
(set-face-attribute 'variable-pitch nil :font dotfiles/font :height dotfiles/font-size)
#+end_src

Define a transient keybinding for scaling the text.
  
#+begin_src emacs-lisp
(defhydra hydra-text-scale (:timeout 4)
  "Scale"
  ("j" text-scale-increase "Increase")
  ("k" text-scale-decrease "Decrease")
  ("f" nil "Finished" :exit t))
#+end_src

Increase the font size in buffers with =SPC t f=.
+ Increase =j=
+ Decrease =k=
+ Finish =f=

#+begin_src emacs-lisp
(dotfiles/leader
  "tf" '(hydra-text-scale/body :which-key "Font"))
#+end_src

*** Lines

Relative line numbers are important when using =VI= emulation keys. You can prefix most commands with a *number*, allowing you to jump up / down by a line count.

#+begin_example
  5:
  4:
  3:
  2:
  1:
156: << CURRENT LINE >>
  1:
  2:
  3:
  4:
  5:
#+end_example

https://github.com/emacsmirror/linum-relative
+ Integrate with ~display-line-numbers-mode~ for performance

#+begin_src emacs-lisp
(use-package linum-relative
  :custom (linum-relative-backend 'display-line-numbers-mode)
  :config (linum-relative-global-mode))
#+end_src

Add line numbers to the toggles behind =SPC t l=.

#+begin_src emacs-lisp
(dotfiles/leader
  "tl" '(linum-relative-global-mode :which-key "Lines"))
#+end_src

https://github.com/Fanael/rainbow-delimiters
+ Colourize nested parenthesis

#+begin_src emacs-lisp
(use-package rainbow-delimiters
  :hook (prog-mode . rainbow-delimiters-mode))
#+end_src

*** Themes

Cherry pick a few modules from =doom-emacs=. High quality and modern colour themes are provided in the [[https://github.com/hlissner/emacs-doom-themes][doom-themes]] package.

#+begin_src emacs-lisp
(use-package doom-themes
  :init (load-theme 'doom-moonlight t))
#+end_src

[[https://github.com/seagle0128/doom-modeline][doom-modeline]] provides an elegant status bar / modeline.

#+begin_src emacs-lisp
(use-package doom-modeline
  :custom (doom-modeline-height 16)
  :config (doom-modeline-mode 1))
#+end_src

Load a theme with =SPC t t=.

#+begin_src emacs-lisp
(dotfiles/leader
  "tt" '(counsel-load-theme t t :which-key "Theme"))
#+end_src

*** Ligatures

Enable font ligatures via [[https://github.com/jming422/fira-code-mode][fira-code-mode]], perform this action *only* when ~Fira Code~ is set as the current font.

#+begin_src emacs-lisp
(when (display-graphic-p)
  (use-package fira-code-mode
    :hook (prog-mode org-mode)))
#+end_src

Toggle global ligature mode with =SPC t g=.

#+begin_src emacs-lisp
(dotfiles/leader
  "tg" '(global-fira-code-mode :which-key "Ligatures"))
#+end_src

*** Dashboard

#+ATTR_ORG: :width 420px
#+ATTR_HTML: :width 420px
#+ATTR_LATEX: :width 420px
[[./docs/images/desktop.png]]

Present a dashboard when first launching Emacs. Customize the buttons of the navigator:

+ Brain @ http://localhost:8080
+ Homepage @ https://chrishayward.xyz
+ Athabasca @ https://login.athabascau.ca/cas/login
+ Bookshelf @ https://online.vitalsource.com

#+begin_src emacs-lisp
(use-package dashboard
  :custom (dashboard-center-content t)
          (dashboard-set-init-info t)
          (dashboard-set-file-icons t)
          (dashboard-set-heading-icons t)
          (dashboard-set-navigator t)
          (dashboard-startup-banner 'logo)
          (dashboard-projects-backend 'projectile)
          (dashboard-items '((projects . 5) (recents  . 5) (agenda . 10)))
          (dashboard-navigator-buttons `(((,(all-the-icons-fileicon "brain" :height 1.1 :v-adjust 0.0)
                                          "Brain" "Knowledge base"
                                          (lambda (&rest _) (browse-url "http://localhost:8080"))))
                                         ((,(all-the-icons-material "public" :height 1.1 :v-adjust 0.0)
                                          "Homepage" "Personal website"
                                          (lambda (&rest _) (browse-url "https://chrishayward.xyz"))))
                                         ((,(all-the-icons-faicon "university" :height 1.1 :v-adjust 0.0)
                                          "Athabasca" "Univeristy login"
                                          (lambda (&rest _) (browse-url "https://login.athabascau.ca/cas/login"))))
                                         ((,(all-the-icons-faicon "book" :height 1.1 :v-adjust 0.0)
                                          "Bookshelf" "Vitalsource bookshelf"
                                          (lambda (&rest _) (browse-url "https://online.vitalsource.com"))))))
  :config (dashboard-setup-startup-hook))
#+end_src

When running in *daemon* mode, ensure that the dashboard is the initial buffer.

#+begin_src emacs-lisp
(setq initial-buffer-choice
      (lambda ()
        (get-buffer "*dashboard*")))
#+end_src