‎

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