diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 754 |
1 files changed, 754 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..04fd956 --- /dev/null +++ b/README.md @@ -0,0 +1,754 @@ + +# Table of Contents + +1. [A New Start](#org6378b0a) + 1. [Overview](#orgf75c2fa) +2. [Package Management](#org61791fb) + 1. [ELPA and Non-GNU ELPA](#org95af7d0) + 1. [Add non-gnu ELPA to Emacs < 28](#org72edc5a) + 2. [Installing Packages](#orga224227) + 3. [Packages not in the default repos](#orgebd5a28) + 4. [Emacs 28 native compilation](#org963c88f) +3. [Keybinding](#org1a1a30c) + 1. [xah-fly-keys](#orgf63beaf) +4. [Completion](#orgfba2de8) + 1. [Two kinds of completion](#orgf697578) + 2. [Emacs completion styles](#org20abf4d) + 3. [consult - Consulting completing-read](#org6c190de) + 1. ["Virtual Buffers"](#orgd1c1ed5) + 2. [consult keybindings](#org0b648bc) + 3. [consult-themes](#org337f5c5) + 4. [consult-project-buffer](#org741a9e3) + 4. [embark](#orgd2a5d63) + 5. [marginalia](#orga45ae36) + 6. [vertico](#org52eaf95) + 1. [vertico-directory](#org97760fe) + 7. [corfu](#orgb29ade8) + 1. [corfu-terminal enables in terminal interface](#org310c193) + 8. [which-key](#org2858ba4) +5. [Editing](#org842c710) + 1. [electric pair mode](#org0da7160) + 2. [markdown mode](#org5df7933) + 3. [org mode](#orgf146406) + 1. [exporting](#org235e78d) + 4. [recentf-mode](#org4b63300) +6. [Programming](#org60dfaf1) + 1. [Languages](#org3392d23) + 1. [Common Lisp](#org4fac1d7) + 2. [Javascript](#orgc2bab44) + 3. [Ruby](#orge3e61d5) + 2. [Dev Docs](#org68e8559) +7. [Projects](#orgf6a6094) + 1. [project.el](#org0b25641) + 2. [version control](#orge8287c8) + 1. [magit](#org9bcbb6c) +8. [External Services](#orge74b8ee) + 1. [plz - http library](#org331edc6) + 2. [sourcehut](#orgfe409d4) +9. [UI](#orgbe8f828) + 1. [basic Emacs UI tweaks](#org1f86a37) + 2. [darkroom - distraction free writing](#org2fa843c) + 3. [Fonts](#orge1003c4) + 4. [Highlights](#org2b9f87e) + 1. [global-hl-mode](#orgb646076) + 5. [Themes](#org4a2fb6f) + 6. [windresize](#orge1dc0b5) + + + +<a id="org6378b0a"></a> + +# 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. + + +<a id="orgf75c2fa"></a> + +## 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) + + +<a id="org61791fb"></a> + +# Package Management + +I've been using [straight.el](https://github.com/radian-software/straight.el#start-of-content) +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. + + +<a id="org95af7d0"></a> + +## 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. + + +<a id="org72edc5a"></a> + +### 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)) + + +<a id="orga224227"></a> + +## Installing Packages + +`package.el` provides the [package-install](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](package-selected-packages). + +You can also use `list-packages` to browse, install and upgrade packages as +well. + + +<a id="orgebd5a28"></a> + +## Packages not in the default repos + +Any elisp package that is in Emacs's [load-path](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. + + +<a id="org963c88f"></a> + +## Emacs 28 native compilation + +[elisp#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)) + + +<a id="org1a1a30c"></a> + +# 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. + + +<a id="orgf63beaf"></a> + +## 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. + + +<a id="orgfba2de8"></a> + +# 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. + + +<a id="orgf697578"></a> + +## 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](emacs#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. + + +<a id="org20abf4d"></a> + +## Emacs completion styles + +Emacs has a quite sophisticated way of selecting candidates for completion. +You can read about them here: [emacs#Completion Styles](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. + + +<a id="org6c190de"></a> + +## [consult](consult#Top) - Consulting [completing-read](elisp#Minibuffer Completion) + +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. + + +<a id="orgd1c1ed5"></a> + +### "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. + + +<a id="org0b648bc"></a> + +### 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) + + +<a id="org337f5c5"></a> + +### 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](elisp#Advising Functions) +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))) + + +<a id="org741a9e3"></a> + +### 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. + + +<a id="orgd2a5d63"></a> + +## embark + + (package-install 'embark) + + +<a id="orga45ae36"></a> + +## marginalia + + (package-install 'marginalia) + (marginalia-mode) + + +<a id="org52eaf95"></a> + +## 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) + + +<a id="org97760fe"></a> + +### 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) + + +<a id="orgb29ade8"></a> + +## corfu + + (package-install 'corfu) + (setq corfu-auto t + corfu-cycle t + corfu-quit-no-match t) + (global-corfu-mode t) + + +<a id="org310c193"></a> + +### corfu-terminal enables in terminal interface + + (package-install 'corfu-terminal) + (unless (display-graphic-p) + (corfu-terminal-mode +1)) + + +<a id="org2858ba4"></a> + +## which-key + + (package-install 'which-key) + (which-key-mode) + + +<a id="org842c710"></a> + +# Editing + + +<a id="org0da7160"></a> + +## [electric pair mode](emacs#Matching) + +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) + + +<a id="org5df7933"></a> + +## markdown mode + + (package-install 'markdown-mode) + + +<a id="orgf146406"></a> + +## org mode + + +<a id="org235e78d"></a> + +### exporting + + (require 'ox-md) + +1. htmilze + + this seems to be required to fontify source blocks + + (package-install 'htmlize) + + +<a id="org4b63300"></a> + +## recentf-mode + +this tracks recently operated on files (by default) and enables quick selection +from them in various Emacs menus. [consult](#org6c190de) hooks into it as well. + + (recentf-mode) + + +<a id="org60dfaf1"></a> + +# Programming + + +<a id="org3392d23"></a> + +## Languages + + +<a id="org4fac1d7"></a> + +### Common Lisp + + (package-install 'sly) + + +<a id="orgc2bab44"></a> + +### Javascript + + (package-install 'json-mode) + + +<a id="orge3e61d5"></a> + +### Ruby + + +<a id="org68e8559"></a> + +## Dev Docs + + (package-install 'devdocs) + + +<a id="orgf6a6094"></a> + +# Projects + + +<a id="org0b25641"></a> + +## project.el + + +<a id="orge8287c8"></a> + +## version control + + +<a id="org9bcbb6c"></a> + +### magit + +its the best! 🪄 + + (package-install 'magit) + + +<a id="orge74b8ee"></a> + +# External Services + +Packages that enable communication via HTTP or connect with external APIs or other +resources outside of Emacs and/or the local machine. + + +<a id="org331edc6"></a> + +## 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` + + +<a id="orgfe409d4"></a> + +## 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. + + +<a id="orgbe8f828"></a> + +# UI + + +<a id="org1f86a37"></a> + +## basic Emacs UI tweaks + + (when (display-graphic-p) + (scroll-bar-mode -1) + (fringe-mode '(8 . 0))) + + (tab-bar-mode t) + (display-battery-mode t) + + +<a id="org2fa843c"></a> + +## [darkroom](elpa/darkroom-0.3/darkroom.el) - distraction free writing + +the notes suggest using `darkroom-tentative-mode` which auto switches +depending on the window layout currently in use. + + (package-install 'darkroom) + + +<a id="orge1003c4"></a> + +## Fonts + +For code, I've grown fond of Victor Mono. + + (set-frame-font "Victor Mono") + + +<a id="org2b9f87e"></a> + +## Highlights + + +<a id="orgb646076"></a> + +### [global-hl-mode](global-hl-line-mode) + +i enjoy having the current line highighted as a visual cue. + + (global-hl-line-mode t) + +can be toggled with <leader> l 2 + + +<a id="org4a2fb6f"></a> + +## Themes + + (setq my-chosen-themes + '(cyberpunk-theme dracula-theme)) + (mapc #'package-install my-chosen-themes) + + +<a id="orge1dc0b5"></a> + +## windresize + + (package-install 'windresize) + |