Table of Contents

#+AUTHOR Shoshin Shangreaux

1 A New Start

To welcome in Emacs 28 I intend to re-aquaint myself with the application and its ecosystem. I've been perusing the packages available through the default ELPA and non-gnu ELPA repos and trying to put together the various things that I've grown accustomed to.

However, with a beginner's mind, I've been trying to avoid going down the same old idiosyncratic paths. Courting a bit of discomfort in order to learn what newcomers might experience coming to Emacs in this current version.

1.1 Overview

This document is a journal, manual, and a program at once. I'm no expert at writing a document like this. If you happen to be reading it, the journal nature may be confusing. Over time, the journal will be incorporated into the bits that are a manual, solidified knowledge gained through the experience.

The program bits will be tangled into ./shoshimacs.el. As a program, it requires a certain structure from top to bottom. Here, the snippets may be scattered around. I'll attempt to have a system to keep them organized, but this is all an experiment.

The following code block is the "table of contents" that determines what is "tangled" into the resulting elisp file:

;;; shoshimacs.el --- Beginner's Mind Config  -*- lexical-binding:t -*-



;;; Package Management

;;; Major Keybinding

;;; Completion

;;; Editing

;;; Programming

;;; Projects

;; Applications

;;; External Services

;;; User Interface

1.2 Preamble

This section covers initialization that works best before anything else is configured. For example, it is much easier to manage the "custom variables" if they are not automatically tacked onto your initialization file. You can set and load a separate file to keep it clean:

(let ((my-custom-file (expand-file-name
                       "shoshimacs-custom.el" user-emacs-directory)))
  (unless (file-exists-p my-custom-file)
    (make-empty-file my-custom-file))
  (setq custom-file my-custom-file)
  (load custom-file))

1.2.1 shortcuts to this configuration document

I use a special variable to hold the path to this org file in its project directory (under version control), then two functions to quickly jump to it and reload it.

(defvar *my-config* "~/projects/shoshimacs/shoshimacs.org"
  "Path to my main configuration file.")

(defun my-configuration ()
  "Opens my configuration file in buffer."
  (find-file *my-config*))

(defun my-reload-config ()
  "Tangles and reloads a literate config with `org-babel-load-file'"
  (org-babel-load-file *my-config*))

1.2.2 using a hostname to tweak the config for different machines

I use this config on several machines. Using their individual hostnames, I can add conditional configuration for each of them as needed. As an example, I use a smaller font size on an older low-resolution laptop.

Turns out Emacs has the function system-name to do this. Unclear why I couldn't find it at the time I wrote the following function. I'm leaving it as a historical example of foolish Elisp hackery. I couldn't quickly figure out how to do it via Emacs itself, so I just shelled out to the hostname command (which is probably not going to work on every system)

(defun my-hostname ()
  "Helper function to determine on which host Emacs is starting."
  (string-trim (with-temp-buffer (shell-command "hostname" t) (buffer-string))))

2 Package Management

I've been using straight.el as my package manager since 2019 when I moved away from Spacemacs as my main configuration for day-to-day work. While I definitely recommend it as a flexible yet minimal package manager, it is targeted more to experienced Emacs users. In my opinion, the main benefit of something like straight is having all of the packages' source code cloned into local repos on your machine. This makes it easier to fix bugs and make contributions to the packages you're using.

This configuration will stick to packages available through the built-in package.el system. As of Emacs 28, this is everything in the ELPA and non-gnu ELPA package repositories.

2.1 ELPA and Non-GNU ELPA

ELPA packages have their copyright assigned to the FSF, which is a requirement for any code to be included into Emacs itself. ELPA packages are thus the most likely to be merged into Emacs as a new feature. Some, like EMMS, are likely to continue as "add-on" optional features only some users may choose.

Non-gnu ELPA is relatively new, and does not require copyright assignment to the FSF. Packages are added to both repositories through the emacs-devel mailing list and the maintainers there. It intends to extend the packages available to the base Emacs installation while providing a bridge to inclusion in ELPA or Emacs proper at some time in the future.

2.1.1 Add non-gnu ELPA to Emacs < 28

Emacs 28 is the first version to include non-gnu ELPA by default. Some distributions may not yet have it as an available package.

(when (< emacs-major-version 28)
  (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/")))

2.2 Installing Packages

package.el provides the package-install command which can be used interactively or from Lisp code like this configuration. If a package is already installed, it won't try to install it again. When you install a package this way, Emacs will add its name to package-selected-packages. Packages will also not be upgraded when running a configuration that calls package-install.

M-x list-packages provides an interface to browse, install and upgrade packages as well. Often, I will try something out by installing it through this UI, and then add it to my config with package-install if I intend to keep it around.

I'll initialize the package functionality and refresh the contents to look for updates, and ensure any additional archives are fetched. this may have a startup impact, but i'm not concerned about that.

(package-refresh-contents)  ;; this will make internet requests on start up

2.3 Packages not in the default repos

Any elisp package that is in Emacs's load-path can be require'd and used. (add-to-list 'load-path (expand-file-name "some-package/" user-emacs-directory)) is an example of putting the directory some-package/ into the load path.

The installation of minitest-emacs is an example in this config.

2.4 Emacs 28 native compilation

elisp#Native Compilation

This is a new feature in Emacs 28 that will compile all of the Elisp as native machine code, rather than byte-code, which can result in major performance boosts. Compilation will happen in the background and is logged to the *Async-native-compile-log* buffer if you are curious. Mostly you shouldn't have to worry about it, though you may see some compilation warnings at times.

(when (and (functionp #'native-comp-available-p) (native-comp-available-p))
  (setq native-comp-always-compile t
        package-native-compile t))

3 Keybinding

Keybindings are the key to playing Emacs like an instrument. no matter what you choose, keep in mind that you can always bind keys to your most commonly used commands to make things convienient.

I highly recommend creating a personal key map bound to a "leader key". You initiate it with the leader, and then bind following key sequences to commands you use. creating your own will make it easier to remember and keep organized.

3.1 xah-fly-keys

This is what I adopted to combat RSI. my muscle memory is tied into it tightly right now. you may have other opinions about keybindings

;; these need to be set before requiring the package
(setq xah-fly-use-control-key nil
      xah-fly-use-meta-key nil)
(package-install 'xah-fly-keys)
(require 'xah-fly-keys)
(xah-fly-keys-set-layout "qwerty")
(xah-fly-keys t)

i'm setting it up early in the config so that its keymaps are available to modify / integrate with other packages.

3.1.1 adding some custom commands to xah maps

  1. SPC 1 delete-other-windows

    i want this often, feels as if i'm constantly wanting that other window to go away.

    (define-key 'xah-fly-leader-key-map (kbd "1") #'delete-other-windows)

3.2 with-map-defkey

This is an experiment in learning to write Elisp macros, all with the result of being able to have a mini "dsl" to define keybindings in my personal (or any given) keymap. The only thing being a macro really does in this case is to avoid evaluating the pairs arguments. A tiny bit of ergonomics essentially avoiding some parens and quotes ๐Ÿ˜‚

(defmacro with-map-defkey (keymap leader &rest pairs)
  "Define a new KEYMAP with prefix key LEADER, and list of bindings in it."
  (declare (indent 2))
     (defvar ,keymap (make-sparse-keymap))
     (define-prefix-command (quote ,keymap))
     (global-set-key (kbd ,leader) ,keymap)
     (mapc (lambda (pair)
             (define-key ,keymap
               (kbd (if (numberp (car pair)) (number-to-string (car pair))
                      (symbol-name (car pair))))
               (cadr pair)))
           (quote ,(seq-partition pairs 2)))))

(with-map-defkey my-key-map "M-m"
  1 delete-other-windows
  a apropos
  b consult-buffer
  c my-configuration
  d embark-act
  e eshell
  f find-file
  g magit
  h info
  i consult-imenu
  j describe-function
  k describe-variable
  n tab-next
  p project-prefix-map
  s consult-git-grep
  t consult-theme
  w which-key-mode
  <f1> my-reload-config)

4 Completion

Completion is a huge part of my experience using Emacs. I have been on an evolving journey of from the basic type of terminal tab completion to spaceship level UI implemented as almost a sub-application in Emacs.

This configuration is aiming at using a new crop of completion enhancements that tie into Emacs's native completion API. This is a more modular approach that allows a sort of composition of extensions to completion behavior and its appearance in the user interface.

4.1 Two kinds of completion

I want to point out that there are two distinct but similar features both grouped under the concept of "completion". The first is Minibuffer completion. Any time you use the minibuffer to enter commands or arguments, there is a completion system available to help you enter text there. The second is Buffer completion, offering candidates for text you are typing in any buffer. Code completion provided by a language server is one example. In vanilla Emacs, you get Symbol Completion for free, since Emacs itself is a running Lisp process with knowledge of all the defined symbols in the system.

I've been confused by this in the past, because the features are so similar. However, completing text in an arbitrary buffer really depends on context, and it is much more complex than completing commands and arguments that are appropriate to a specific situation.

4.2 Emacs completion styles

Emacs has a quite sophisticated way of selecting candidates for completion. You can read about them here: emacs#Completion Styles

I've grown used to the flex style of completion where typing pr/s/sho.o at the find file prompt expands to projects/shoshimacs/shoshin-config.org. There are other alternatives and you can even write your own. The completion-styles is a list of all the styles you'd like to use. It starts at the front, and if no matches are found, moves to the next style of completion. In this config, I just added flex to the front of the default completion styles.

(setq completion-styles '(flex basic partial-completion emacs22)
      completion-cycle-threshold 3
      tab-always-indent 'complete)

completion-cycle-threshold defines when you want to just cycle through alternatives on each <TAB> (or whatever key you use) rather than presenting options. Setting it to 3 means if my options are "FOO, FOP, FOR" or less, hitting complete will change FOO->FOP, FOP->FOR, FOR->FOO.

tab-always-indent changes the behavior of the TAB key:

If โ€˜completeโ€™, TAB first tries to indent the current line, and if the line was already indented, then try to complete the thing at point.

4.3 consult - Consulting completing-read

consult offers enhanced completion similar to ivy and helm, but with the built in completing read functionality of the minibuffer.

(package-install 'consult)

main entry point would be consult-buffer. however, there are many consult commands that can enhance any completing read function.

4.3.1 "Virtual Buffers"

it introduces this concept of "Virtual Buffers", but i'm not certain what it means. consult "supports … narrowing to the virtual buffer types".

perhaps a Virtual Buffer is a "grouping" of actual Emacs buffers or "things" that can be materialized in a buffer. For example, I can consult-buffer and press m SPC to narrow the "buffer list" to any bookmarks.

4.3.2 consult keybindings

(global-set-key (kbd "C-x b") #'consult-buffer)
(define-key xah-fly-leader-key-map (kbd "f") #'consult-buffer)
(define-key xah-fly-command-map (kbd "n") #'consult-line)

4.3.3 consult-themes

i had a bit of a mess with it at first, because i'd implemented my own solution to a quirk of theme loading. enabling themes is additive, and can cause unexpected results. so i added advice to load-theme to automatically disable the old one before enabling the new.

it seems like consult-theme does this as well. additionally, as it will preview the theme as you are narrowing the selection. i did not expect this behavior and it got all kinds of wonky. the manual has a nice example of delaying the theme-switch-preview since it is slow. this way you can scroll / narrow your list of themes without the colors changing with every keypress.

(with-eval-after-load 'consult
  (consult-customize consult-theme :preview-key '(:debounce 0.5 any))
  (setq consult-themes my-chosen-themes))

I set a special list of my-chosen-themes but sometimes I want to turn it off. Its nice to have a filtered list most times, but sometimes I just want all of them in the consult-themes list.

(defun my-show-all-themes ()
  (setq consult-themes nil))

4.3.4 TODO consult-project-buffer

how do project buffers get filtered? i'm seeing buffers assigned to a project that in my mind, shouldn't be.

looks like it interfaces with project-switch-to-buffer which has its own logic about which project a buffer belongs to. some of the mistakes i was seeing earlier were simply due to starting a repl in a particular directory.

it appears that "special" buffers may get assigned to a particular project as well. for example the EWW buffer is part of a project, but it is unclear as to why. appears likely to have to do with the behavior of the default-directory variable which is buffer-local.

i may want to figure out ways to mark "special" buffers as having a non-project default-directory set so they don't show up, or just filter them out if it becomes annoying. i'm accustomed to perspectives provided by a MELPA package that hooked into projectile's project definitions. it would keep a list of perspective-local buffers where the perspective was tied to a project.

4.4 embark

(package-install 'embark)
(package-install 'embark-consult)
(global-set-key (kbd "C-;") #'embark-act)
(setq prefix-help-command #'embark-prefix-help-command)

4.5 marginalia

(package-install 'marginalia)

4.6 vertico

(package-install 'vertico)
(setq minibuffer-prompt-properties
      '(read-only t cursor-intangible t face minibuffer-prompt))
(add-hook 'minibuffer-setup-hook #'cursor-intangible-mode)
(setq read-extended-command-predicate
(setq enable-recursive-minibuffers t)

4.6.1 vertico-directory

i'd like to emulate the behavior in find-file that i'm used to from Ivy. basically, when i press DEL it should act normally until i hit a directory boundary, then it should jump up a dir with the following press.

this is implemented with the vertico-directory extension.

(require 'vertico-directory)
(define-key vertico-map (kbd "RET") #'vertico-directory-enter)
(define-key vertico-map (kbd "DEL") #'vertico-directory-delete-char)
(define-key vertico-map (kbd "M-DEL") #'vertico-directory-delete-word)
(define-key vertico-map (kbd "M-j") #'vertico-quick-insert)

4.7 company - complete anywhere

Company is a modular completion framework. Modules for retrieving completion candidates are called backends, modules for displaying them are frontends.

Company comes with many backends, e.g. `company-etags'. These are distributed in separate files and can be used individually.

Enable `company-mode' in all buffers with M-x global-company-mode. For further information look at the documentation for `company-mode' (C-h f company-mode RET).

(package-install 'company)

(setq company-minimum-prefix-length 2
      company-idle-delay 0.3) ;; default is 0.2

(add-hook 'after-init-hook 'global-company-mode)

4.8 which-key

which-key is an excellent package that helps provide guide posts for command discoverability. many key commands in Emacs are in sequences. for example, org-babel-tangle is C-c C-v t. as a user, the commands you use often become muscle memory, or you map them to something more convienient. but sometimes you know there is some command to do what you want but you don't quite remember what the sequence is. or perhaps you're in a new major-mode and you know there must be several handy commands under C-c. which-key pops up a buffer with a listing of all the possible continuations from where you are in a key sequence. for that reason, it can be useful at times even for experienced users.

this config installs which-key, but does not activate it automatically. some advice from Daniel Mendler (consult author) suggested that limiting the amount Emacs pops things up automatically is a better user experience. which-key is just a toggle away when needed, and there is also embark which has a command to show prefix key continuations.

(package-install 'which-key)

5 Editing

5.1 smartparens

Going back to smartparens for some of the paredit behavior I want, plus the paren balancing. We'll see how it goes

(package-install 'smartparens)
(require 'smartparens-config)
(smartparens-global-mode 1)
;(sp-local-pair 'sly-mrepl-mode "'" nil :actions nil)
(sp-local-pair 'slime-repl-mode "'" nil :actions nil)

5.2 markdown mode

(package-install 'markdown-mode)

5.3 org mode

5.3.1 capture

Org capture is a way to quickly get entries from various places into one of your org files.

(setq org-directory (expand-file-name "~/Nextcloud/org"))
(setq org-default-notes-file (concat org-directory "/notes.org"))

(setq org-capture-templates
    `(("p" "Protocol" entry (file+headline ,org-default-notes-file "Inbox")
       "* %^{Title}\nSource: %u, %c\n #+BEGIN_QUOTE\n%i\n#+END_QUOTE\n\n\n%?")
      ("L" "Protocol Link" entry (file+headline ,org-default-notes-file "Inbox")
       "* %? [[%:link][%:description]] \nCaptured On: %U")))

5.3.2 refile

(setq org-refile-use-outline-path t
      org-refile-allow-creating-parent-nodes t
      org-refile-targets '((nil . (:maxlevel . 2))))

5.3.3 jump to top level parent heading

a friend was wanting this functionality, so i dug around in the org functions to find one i could build a command out of:

(defun my-org-top-level-heading ()
  (let ((moo 1))
    (while moo (setq moo (org-up-heading-safe)))))

org-up-heading-safe is designed not to throw an error and returns the level of the headline found (as it goes up) or nil if no higher level is found. this just uses a dumb while loop to call it until it returns nil, which should get us where we are looking to go ๐Ÿ˜ƒ

5.3.4 exporting

(with-eval-after-load 'org (require 'ox-md))
  1. htmilze

    this seems to be required to fontify source blocks

    (package-install 'htmlize)

5.3.5 babel

 '((emacs-lisp . t)
   (lisp . t)
   (org . t)
   (plantuml . t)
   (ruby . t)
   (shell . t)))

5.3.6 org-tree-slide

This is a simple presentation mode for org documents that uses narrowing to turn an org tree into slides. I've used it for many presentations, including some at EmacsConf. Its great for doing presentation run throughs, since you can edit at the same time you're using the slides.

(package-install 'org-tree-slide)

There are many settings for how it presents available, but I usually just set them on the fly, depending on the presentation, rather than in my main config.

5.3.7 Structure Templates

(add-to-list 'org-structure-template-alist '("se" . "src emacs-lisp"))
(add-to-list 'org-structure-template-alist '("sr" . "src ruby"))
(add-to-list 'org-structure-template-alist '("ss" . "src shell"))

5.4 recentf-mode

this tracks recently operated on files (by default) and enables quick selection from them in various Emacs menus. [BROKEN LINK: *\[\[info:consult#Top\]\[consult\]\] - Consulting \[\[info:elisp#Minibuffer Completion\]\[completing-read\]]] hooks into it as well.


5.5 whitespace, tabs, and spaces

(setq indent-tabs-mode nil
      show-trailing-whitespace t)

5.6 crdt - buffer sharing

(package-install 'crdt)

6 Programming

6.1 Common Lisp

I primarily use SBCL, so I set it as the inferior-lisp-program

(setq inferior-lisp-program "sbcl")

6.1.1 Slime

The slime package v2.26.1 in the nongnu repo seems to have an issue with emacs 28.1 (?) so I'm installing it from source.

(defvar slime-repo "https://github.com/slime/slime")
(defvar slime-src-dir (expand-file-name "~/src/slime/"))

(unless (file-directory-p slime-src-dir)
   (format "git clone %s %s" slime-repo slime-src-dir)))

(add-to-list 'load-path slime-src-dir)
(require 'slime-autoloads)

There is a command slime-info to read the locally built manual file, but i need to ensure it is built:

(let ((default-directory (concat slime-src-dir "doc/"))
      (buf (get-buffer-create "*slime-make-info*")))
  (unless (file-exists-p "slime.info")
    (shell-command "make clean" "*slime-make-info*")
    (shell-command "make slime.info" "*slime-make-info*")))
  1. Slime company

    Company backend for slime

    (defvar slime-company-repo "https://github.com/anwyn/slime-company")
    (defvar slime-company-src-dir (expand-file-name "~/src/slime-company/"))
    (unless (file-directory-p slime-company-src-dir)
       (format "git clone %s %s" slime-company-repo slime-company-src-dir)))
    (add-to-list 'load-path slime-company-src-dir)
    (setq slime-company-completion 'fuzzy
          slime-company-display-arglist 1)
    (setq slime-contribs
        slime-fancy ;; default value, includes many fundamental contribs

    Slime Presentations

    (defun my-slime-return (_)
      "Function to advise `slime-repl-return' to make <RET> inspect the presentation at point."
      (when (slime-presentation-around-or-before-point-p)
        (slime-inspect-presentation-at-point (point))))
    (advice-add 'slime-repl-return :before #'my-slime-return)

6.2 Javascript

(package-install 'json-mode)

6.3 Ruby

6.3.1 Linting

The Emacs ruby-mode defines a backend for flymake, which use rubocop by default if it is available. If it isn't, it will try ruby -wc which will check syntax and warnings in the file. If a project is NOT using rubocop, or if it is say… running in a container, the flymake backend function will need to be hacked on a bit. A few config variables are available, primarily for rubocop.

ruby-flymake-use-rubocop-if-available t ruby-rubocop-config ".rubocop.yml"

(add-hook 'ruby-mode-hook #'flymake-mode)

6.3.2 inf-ruby

inf-ruby provides an interface to the various REPLs available in the Ruby-verse its currently provided by non-gnu ELPA:

(package-install 'inf-ruby)

I prefer pry when its available, and it generally is on my system:

(when (executable-find "pry")
  (setq inf-ruby-default-implementation "pry"))

6.3.3 TODO minitest-emacs

this is a package i happen to maintain, and i would like to get it into non-gnu elpa. however, at the moment i must install from source:

(defvar minitest-emacs-repo "https://github.com/arthurnn/minitest-emacs.git")
(defvar minitest-emacs-src-dir "~/src/minitest-emacs")

(unless (file-directory-p minitest-emacs-src-dir)
   (format "git clone %s %s" minitest-emacs-repo minitest-emacs-src-dir)))

(add-to-list 'load-path minitest-emacs-src-dir)
(require 'minitest)

6.3.4 haml mode

(package-install 'haml-mode)

6.4 Dev Docs

(package-install 'devdocs)

6.5 Flymake

(with-eval-after-load 'flymake
  (define-key flymake-mode-map (kbd "M-n") 'flymake-goto-next-error)
  (define-key flymake-mode-map (kbd "M-p") 'flymake-goto-prev-error))

6.6 PlantUML

(defvar plantuml-mode-repo "https://github.com/skuro/plantuml-mode")
(defvar plantuml-mode-src-dir "~/src/plantuml-mode")

(unless (file-directory-p plantuml-mode-src-dir)
   (format "git clone %s %s" plantuml-mode-repo plantuml-mode-src-dir)))

(add-to-list 'load-path plantuml-mode-src-dir)
(require 'plantuml-mode)
(customize-set-value 'plantuml-default-exec-mode 'executable)

7 Projects

7.1 project.el

project.el is the built in project management tool. previously, I've used projectile, which is great, but some of the more recent tools (like eglot) use the built in project.el api for their features.

I've got the project-prefix-map on the key p in my-key-map. Interestingly, in order to refer to a a prefix map with a quoted symbol like you would a command, the keymap must be in the symbol's function definition place. The project.el package doesn't do this, which is normally done with define-prefix-command (in my experience). In order to make this prefix map work correctly with the with-map-defkey macro, we set the symbol-function place on the project-prefix-map to be the value, the actual keymap structure, of the project-prefix-map symbol. ๐Ÿ˜ต

(fset 'project-prefix-map project-prefix-map)

7.2 version control

7.2.1 magit

its the best! ๐Ÿช„

(package-install 'magit)

8 Applications

8.1 EMMS

Emacs MultiMedia System.

(require 'emms-setup)
(setq emms-player-list '(emms-player-mpv))
(setq emms-source-file-default-directory "~/Music/")
(add-to-list 'emms-tag-editor-tagfile-functions '("wav" . emms-tag-tracktag-file))

8.2 erc

(setq erc-server "irc.libera.chat"
      erc-nick "shoshin"
      erc-autojoin-channels-alist '(("libera.chat" "#emacs" "#emacsconf" "#lispgames"))
      erc-interpret-mirc-color t
      erc-hide-list '("JOIN" "PART" "QUIT"))

9 External Services

Packages that enable communication via HTTP or connect with external APIs or other resources outside of Emacs and/or the local machine.

9.1 plz - http library

this is an http library that intends to solve some of the "pain points" of url.el. i ran into some of them trying to download and install the Victor Mono font used by my configuration. the downside of plz is that it is dependent on curl, rather than being pure elisp. however, this is a non-issue for me, especially since my use case had devolved into using make-process to call wget and then implement a "callback" with a process sentinel. kinda neat, but maybe too much.

(package-install 'plz)

the sourcehut package in this config also depends on plz

9.2 sourcehut

there's a new package in GNU ELPA for some basic interaction with the sr.ht http api. i'm interested to try it out since i still pay for the account, plus the forge is free software and could be self-hosted if it comes to it.

it also depends on plz which is another new package providing a nicer API for HTTP requests.

(package-install 'srht)
(setq srht-username "shoshin")

an API token is stored in my .authinfo file.

9.3 paste.cicadas.surf

(defun read-file-into-string (f)
    (insert-file-contents f)

(setq cicadas-paste-pw (read-file-into-string "~/.bepasty-key"))

(defun cicadas-paste-current-buffer () 
  (let ((tmpfile
         (concat "/tmp/" (buffer-name))))
    (write-region nil nil tmpfile)
    (let ((url 
           (cl-first (last (butlast
                           (format "pastebinit -i '%s' -p %s -t '%s' -f text/plain"
      (delete-file tmpfile)
      (kill-new url)
      (message "Pasted to %s (on kill ring)" url))))

9.4 restclient

(defvar restclient-repo "https://github.com/pashky/restclient.el.git")
(defvar restclient-dir "~/src/restclient.el")

(unless (file-directory-p restclient-dir)
   (format "git clone %s %s" restclient-repo restclient-dir)))

(add-to-list 'load-path restclient-dir)
(require 'restclient)

10 UI

10.1 basic Emacs UI tweaks

(when (display-graphic-p)
  (scroll-bar-mode -1)
  (fringe-mode '(8 . 0))
  (menu-bar-mode -1)
  (tool-bar-mode -1))

10.2 darkroom - distraction free writing

the notes suggest using darkroom-tentative-mode which auto switches depending on the window layout currently in use.

(package-install 'darkroom)

10.3 Fonts

For code, I've grown fond of Victor Mono.

(let* ((size (if (or (equal (system-name) "zebes") (equal (system-name) "ridley")) 16 12))
       (font (format "Victor Mono-%s" size)))
  (add-to-list 'default-frame-alist
               `(font . ,font)))

10.4 Highlights

10.4.1 global-hl-mode

i enjoy having the current line highighted as a visual cue.

(global-hl-line-mode t)

can be toggled with <leader> l 2

10.5 Themes

10.5.1 theme packages / installation

to keep it concise, i'll define a special variable to hold the theme packages i'd like to install anytime this config is loaded on a system where they are not there. then i can mapc #'package-install over the list of themes.

(defvar my-themes-to-install
  '(cyberpunk-theme dracula-theme nano-theme ef-themes)
  "List of themes to install when loading shoshimacs config.")
(mapc #'package-install my-themes-to-install)

10.5.2 kaolin themes

(defvar emacs-kaolin-repo "https://github.com/ogdenwebb/emacs-kaolin-themes")
(defvar emacs-kaolin-src-dir (expand-file-name "~/src/emacs-kaolin/"))

(unless (file-directory-p emacs-kaolin-src-dir)
   (format "git clone %s %s" emacs-kaolin-repo emacs-kaolin-src-dir)))

(add-to-list 'load-path emacs-kaolin-src-dir)

(require 'kaolin-themes)

10.5.3 chosen theme list and random loading on init

i generally haven't used built-in themes much, but there's a few i like, and the ones i specifically install i'd like to keep in a list of "chosen" ones. i can load one at random if i please, and perhaps provide it as candidates to consult-themes.

(defvar my-chosen-themes
  '(cyberpunk dichromacy dracula leuven modus-operandi modus-vivendi
              nano-dark nano-light tango tango-dark
              ef-day ef-dark ef-light ef-night
              ef-autumn ef-spring ef-summer ef-winter
              ef-deuteranopia-dark ef-deuteranopia-light)
  "List of themes I prefer for narrowing and random selection.")

10.5.4 autothemer

autothemer is a dependency of some nice themes, and a great tool for theme development.

(package-install 'autothemer)

10.6 modeline

10.6.1 telephone line

(setq telephone-line-lhs
      '((evil   . (telephone-line-evil-tag-segment))
        (accent . (telephone-line-vc-segment
        (nil    . (
                   ;; telephone-line-minor-mode-segment
(setq telephone-line-rhs
      '((nil    . (telephone-line-misc-info-segment
        (accent . (telephone-line-major-mode-segment))
        (evil   . (telephone-line-airline-position-segment))))

(telephone-line-mode t)
(set-face-background 'telephone-line-evil-normal "deep pink")
(set-face-background 'telephone-line-evil-insert "Dark Turquoise")

10.7 SVG Screenshot

(defun screenshot-svg ()
  "Save a screenshot of the current frame as an SVG image.
Saves to a temp file and puts the filename in the kill ring."
  (let* ((filename (make-temp-file "Emacs" nil ".svg"))
         (data (x-export-frames nil 'svg)))
    (with-temp-file filename
      (insert data))
    (kill-new filename)
    (message filename)))

10.8 windresize

(package-install 'windresize)

Created: 2023-12-07 Thu 17:21