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)

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.

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.

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.

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

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.

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.

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.

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.

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)

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)

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

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.

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

(package-install 'darkroom)

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

(set-frame-font "Victor Mono")