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 -*-
;;; Commentary:
;;; Personal configuration rewritten from basics.

;;; Code:

<<preamble>>

<<defvars>>

<<user-info>>

;;; Package Management
<<package-management>>

;;; Major Keybinding
<<keybinding>>

;;; Completion
<<completion>>

;;; Editing
<<editing>>

;;; Programming
<<programming>>

;;; Projects
<<projects>>

;; Applications
<<applications>>

;;; External Services
<<external-services>>

;;; User Interface
<<user-interface>>

(provide 'shoshimacs)
;;; shoshimacs.el ends here

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

This is one of the primary community archives. It is very exhaustive, primarily because it has been the easiest place to add packages. On the other hand, it is not hosted on a libre platform, though that could change in the future. Ever since I've started using Emacs over a decade ago, adding MELPA to the package archive list was one of the very first things to do. I'm coming back "full-circle" to use it again in this config after finally getting tired of needing to add/manage certain libraries manually that I could just get through the package manager.

(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)

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-initialize)
(package-refresh-contents)  ;; this will make internet requests on start up

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.

(require 'comp)
(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

There's some oddity with some of the variables in the package when trying to lint/compile my init, so i'm declaring some of the special vars here too.

;; these need to be set before requiring the package
(defvar xah-fly-use-control-key)
(defvar xah-fly-use-meta-key)
(defvar xah-fly-leader-key-map)
(defvar xah-fly-command-map)
(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.

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 PAIRS in it."
  (declare (indent 2))
  `(progn
     (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 helpful-function
  k helpful-variable
  n tab-next
  p project-prefix-map
  s consult-git-grep
  t consult-theme
  w which-key-mode
  z my-start-repl
  <f1> my-reload-config)

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.

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

(package-install 'consult)
(require 'consult)

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

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)
(which-key-mode)

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)

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.

(recentf-mode)

Adding a key binding to start an appropriate REPL for the current major mode.

(defun my-start-repl ()
  (interactive)
  (let ((mode-name (symbol-name major-mode)))
    (funcall
     (cond
      ((string-search "ruby" (print mode-name)) #'inf-ruby-console-auto)
      (t #'ielm)))))

Mickey Peterson has a great article about getting started here.

https://www.masteringemacs.org/article/how-to-get-started-tree-sitter

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

(setq inferior-lisp-program "sbcl")

For mixed templates like ERB, HTML + CSS etc

(package-install 'web-mode)
(setq web-mode-code-indent-offset 2
      web-mode-indent-style 2
      web-mode-css-indent-offset 2
      web-mode-sql-indent-offset 2
      web-mode-markup-indent-offset 2)

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)

https://djcbsoftware.nl/code/mu/mu4e/index.html

• Install mu from source
  • requires dependencies with package manager
• install a program to get IMAP mail
  • isync / mbsync
• install something to send mail SMTP
• sync mail down
• initialize mu index
• configure emacs to use mu4e to read and send

Emacs MultiMedia System.

(package-install 'emms)
(require 'emms-setup)
(emms-all)
(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))
(add-to-list 'emms-player-mpv-parameters "--no-video")

Load the script that lets me connect to the cicadas.surf infrastructure

(setq cicadas-project-dir "~/code/projects/cicadas.org/")
(mapc (lambda (p) (load (concat cicadas-project-dir p)))
      '("cicadas-config.el" "foghorn.el" "cicatasks.el"))

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.

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

(defun my-use-large-font? ()
  (or (equal (system-name) "zebes")
      (equal (system-name) "ridley")
      (equal (system-name) "chozo.local")))

(let* ((size (if (my-use-large-font?) 16 12))
       (font (format "Victor Mono-%s" size)))
  (add-to-list 'default-frame-alist
               `(font . ,font)))

Helpful is a package that enhances the default Emacs help buffers. I'm remapping the xah fly keys that point at the corresponding describe- commands.

(package-install 'helpful)

(xah-fly--define-keys
 xah-fly-leader-key-map
 '(("h h" . helpful-callable)
   ("h k" . helpful-key)
   ("h n" . helpful-variable)
   ("h x" . helpful-command)))

This library provides the frontend UI to display information either on the left/right side of the buffer window.

1. You would need to first set up the backends,

   (setq sideline-backends-left '(sideline-flycheck))

2. Then enable the sideline in the target buffer,

   M-x sideline-mode

(package-install 'sideline)
(setq sideline-backends-left '(sideline-flymake))