‎

1. A New Start +
- 1.1. Overview
+
2. Package Management +
+
3. Keybinding +
- 3.1. xah-fly-keys
+
4. Completion +
- 4.1. Two kinds of completion
- 4.2. Emacs completion styles
- 4.3. consult - Consulting completing-read +
  +
- 4.4. embark
- 4.5. marginalia
- 4.6. vertico +
  - 4.6.1. vertico-directory
  +
- 4.7. corfu +
  - 4.7.1. corfu-terminal enables in terminal interface
  +
- 4.8. which-key
+
5. Editing +
- 5.1. electric pair mode
- 5.2. markdown mode
- 5.3. org mode +
  - 5.3.1. exporting
  +
- 5.4. recentf-mode
+
6. Programming +
- 6.1. Languages +
  - 6.1.1. Common Lisp
  - 6.1.2. Javascript
  - 6.1.3. Ruby
  +
- 6.2. Dev Docs
+
7. Projects +
- 7.1. project.el
- 7.2. version control +
  - 7.2.1. magit
  +
+
8. External Services +
- 8.1. plz - http library
- 8.2. sourcehut
+
9. UI +
- 9.1. basic Emacs UI tweaks
- 9.2. darkroom - distraction free writing
- 9.3. Fonts
- 9.4. Highlights +
  - 9.4.1. global-hl-mode
  +
- 9.5. Themes
- 9.6. windresize
+

+ +

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 shoshin-config.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
+(when (< emacs-major-version 28)
+  (package-initialize)
+  (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/"))
+  (package-refresh-contents))
+
+(when (and (functionp #'native-comp-available-p) (native-comp-available-p))
+  (setq native-comp-always-compile t
+        package-native-compile t))
+
+;;; Major Keybinding
+(package-install 'xah-fly-keys)
+(require 'xah-fly-keys)
+(xah-fly-keys-set-layout "qwerty")
+(setq xah-fly-use-control-key nil
+      xah-fly-use-meta-key nil)
+(xah-fly-keys t)
+
+;;; Completion
+(setq completion-styles '(flex basic partial-completion emacs22)
+      completion-cycle-threshold 3
+      tab-always-indent 'complete)
+
+(package-install 'consult)
+
+(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)
+
+(with-eval-after-load 'consult
+  (consult-customize consult-theme :preview-key '(:debounce 0.5 any)))
+
+(package-install 'embark)
+
+(package-install 'marginalia)
+(marginalia-mode)
+
+(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
+      #'command-completion-default-include-p)
+(setq enable-recursive-minibuffers t)
+(vertico-mode)
+
+(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)
+
+(package-install 'corfu)
+(setq corfu-auto t
+      corfu-cycle t
+      corfu-quit-no-match t)
+(global-corfu-mode t)
+
+(package-install 'corfu-terminal)
+(unless (display-graphic-p)
+    (corfu-terminal-mode +1))
+
+(package-install 'which-key)
+(which-key-mode)
+
+;;; Editing
+(electric-pair-mode)
+
+(package-install 'markdown-mode)
+
+(package-install 'htmlize)
+
+(recentf-mode)
+
+;;; Programming
+(package-install 'sly)
+
+(package-install 'json-mode)
+
+(package-install 'devdocs)
+
+;;; Projects
+(package-install 'magit)
+
+;;; External Services
+(package-install 'plz)
+
+(package-install 'srht)
+(setq srht-username "shoshin")
+
+;;; User Interface
+(when (display-graphic-p)
+  (scroll-bar-mode -1)
+  (fringe-mode '(8 . 0)))
+
+(tab-bar-mode t)
+(display-battery-mode t)
+
+(package-install 'darkroom)
+
+(set-frame-font "Victor Mono")
+
+(global-hl-line-mode t)
+
+(setq my-chosen-themes
+      '(cyberpunk-theme dracula-theme))
+(mapc #'package-install my-chosen-themes)
+
+(package-install 'windresize)
+

+ +

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 certainly more useful +to experienced Emacs users. +

+ +

+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)
+  (package-initialize)
+  (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/"))
+  (package-refresh-contents))
+

+ +

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. +

+ +

+You can also use list-packages to browse, install and upgrade packages as +well. +

+ +

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. +

+ +

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 +

+ +

(package-install 'xah-fly-keys)
+(require 'xah-fly-keys)
+(xah-fly-keys-set-layout "qwerty")
+(setq xah-fly-use-control-key nil
+      xah-fly-use-meta-key nil)
+(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. +

+ +

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)))
+

+ +

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)
+

+ +

4.5. marginalia

(package-install 'marginalia)
+(marginalia-mode)
+

+ +

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
+      #'command-completion-default-include-p)
+(setq enable-recursive-minibuffers t)
+(vertico-mode)
+

+ +

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. corfu

(package-install 'corfu)
+(setq corfu-auto t
+      corfu-cycle t
+      corfu-quit-no-match t)
+(global-corfu-mode t)
+

+ +

4.7.1. corfu-terminal enables in terminal interface

(package-install 'corfu-terminal)
+(unless (display-graphic-p)
+    (corfu-terminal-mode +1))
+

4.8. which-key

(package-install 'which-key)
+(which-key-mode)
+

+ +

5. Editing

5.1. electric pair mode

+I've been using smartparens -> (bookmark-jump "smartparens package") in my +main config. electric pair mode does some of what smartparens does out of +the box. what i'm missing is the generalized sp-hybrid-slurp or +whatever it was called. but using the built in is good for now. further +config might get what i want with vanilla built ins. +

+ +

(electric-pair-mode)
+

+ +

5.2. markdown mode

(package-install 'markdown-mode)
+

+ +

5.3. org mode

5.3.1. exporting

+(require 'ox-md)
+

htmilze
+
+
+this seems to be required to fontify source blocks +
+ +
+
```
(package-install 'htmlize)
+
```
+
+
+

+ +

5.4. recentf-mode

+this tracks recently operated on files (by default) and enables quick selection +from them in various Emacs menus. consult hooks into it as well. +

+ +

(recentf-mode)
+

+ +

6. Programming

6.1. Languages

6.1.1. Common Lisp

(package-install 'sly)
+

+ +

6.1.2. Javascript

(package-install 'json-mode)
+

+ +

6.1.3. Ruby

+ +

6.2. Dev Docs

(package-install 'devdocs)
+

7. Projects

+ +

7.1. project.el

7.2. version control

7.2.1. magit

+its the best! 🪄 +

+ +

(package-install 'magit)
+

8. External Services

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

+ +

8.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 +

+ +

8.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 I was going +

+ +

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

+ +

+an API token is stored in my .authinfo file. +

+ +

9. UI

9.1. basic Emacs UI tweaks

(when (display-graphic-p)
+  (scroll-bar-mode -1)
+  (fringe-mode '(8 . 0)))
+
+(tab-bar-mode t)
+(display-battery-mode t)
+

+ +

9.2. [BROKEN LINK: No match for fuzzy expression: ;;; Commentary:] - distraction free writing

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

+ +

(package-install 'darkroom)
+

+ +

9.3. Fonts

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

+ +

(set-frame-font "Victor Mono")
+

+ +

9.4. Highlights

9.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 +

+ +

9.5. Themes

(setq my-chosen-themes
+      '(cyberpunk-theme dracula-theme))
+(mapc #'package-install my-chosen-themes)
+

+ +

9.6. windresize

(package-install 'windresize)
+

Table of Contents