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

<<preamble>>

<<defvars>>

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

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

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

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.

The installation of minitest-emacs is an example in this config.

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

;; these need to be set before requiring the package
(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 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 describe-function
  k describe-variable
  n tab-next
  p project-prefix-map
  s consult-git-grep
  t consult-theme
  w which-key-mode
  <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.

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

Company is a modular completion framework. Modules for retrieving completion candidates are called backends, modules for displaying them are frontends.

Company comes with many backends, e.g. `company-etags'. These are distributed in separate files and can be used individually.

Enable `company-mode' in all buffers with M-x global-company-mode. For further information look at the documentation for `company-mode' (C-h f company-mode RET).

(package-install 'company)

(setq company-minimum-prefix-length 2
      company-idle-delay 0.3) ;; default is 0.2

(add-hook 'after-init-hook 'global-company-mode)

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)

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

(setq inferior-lisp-program "sbcl")

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)

Emacs MultiMedia System.

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

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.

(let* ((size (if (or (equal (system-name) "zebes") (equal (system-name) "ridley")) 16 12))
       (font (format "Victor Mono-%s" size)))
  (add-to-list 'default-frame-alist
               `(font . ,font)))