<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<!-- 2022-07-03 Sun 21:12 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>‎</title>
<meta name="generator" content="Org Mode" />
<style>
#content { max-width: 60em; margin: auto; }
.title { text-align: center;
margin-bottom: .2em; }
.subtitle { text-align: center;
font-size: medium;
font-weight: bold;
margin-top:0; }
.todo { font-family: monospace; color: red; }
.done { font-family: monospace; color: green; }
.priority { font-family: monospace; color: orange; }
.tag { background-color: #eee; font-family: monospace;
padding: 2px; font-size: 80%; font-weight: normal; }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.org-right { margin-left: auto; margin-right: 0px; text-align: right; }
.org-left { margin-left: 0px; margin-right: auto; text-align: left; }
.org-center { margin-left: auto; margin-right: auto; text-align: center; }
.underline { text-decoration: underline; }
#postamble p, #preamble p { font-size: 90%; margin: .2em; }
p.verse { margin-left: 3%; }
pre {
border: 1px solid #e6e6e6;
border-radius: 3px;
background-color: #f2f2f2;
padding: 8pt;
font-family: monospace;
overflow: auto;
margin: 1.2em;
}
pre.src {
position: relative;
overflow: auto;
}
pre.src:before {
display: none;
position: absolute;
top: -8px;
right: 12px;
padding: 3px;
color: #555;
background-color: #f2f2f299;
}
pre.src:hover:before { display: inline; margin-top: 14px;}
/* Languages per Org manual */
pre.src-asymptote:before { content: 'Asymptote'; }
pre.src-awk:before { content: 'Awk'; }
pre.src-authinfo::before { content: 'Authinfo'; }
pre.src-C:before { content: 'C'; }
/* pre.src-C++ doesn't work in CSS */
pre.src-clojure:before { content: 'Clojure'; }
pre.src-css:before { content: 'CSS'; }
pre.src-D:before { content: 'D'; }
pre.src-ditaa:before { content: 'ditaa'; }
pre.src-dot:before { content: 'Graphviz'; }
pre.src-calc:before { content: 'Emacs Calc'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-fortran:before { content: 'Fortran'; }
pre.src-gnuplot:before { content: 'gnuplot'; }
pre.src-haskell:before { content: 'Haskell'; }
pre.src-hledger:before { content: 'hledger'; }
pre.src-java:before { content: 'Java'; }
pre.src-js:before { content: 'Javascript'; }
pre.src-latex:before { content: 'LaTeX'; }
pre.src-ledger:before { content: 'Ledger'; }
pre.src-lisp:before { content: 'Lisp'; }
pre.src-lilypond:before { content: 'Lilypond'; }
pre.src-lua:before { content: 'Lua'; }
pre.src-matlab:before { content: 'MATLAB'; }
pre.src-mscgen:before { content: 'Mscgen'; }
pre.src-ocaml:before { content: 'Objective Caml'; }
pre.src-octave:before { content: 'Octave'; }
pre.src-org:before { content: 'Org mode'; }
pre.src-oz:before { content: 'OZ'; }
pre.src-plantuml:before { content: 'Plantuml'; }
pre.src-processing:before { content: 'Processing.js'; }
pre.src-python:before { content: 'Python'; }
pre.src-R:before { content: 'R'; }
pre.src-ruby:before { content: 'Ruby'; }
pre.src-sass:before { content: 'Sass'; }
pre.src-scheme:before { content: 'Scheme'; }
pre.src-screen:before { content: 'Gnu Screen'; }
pre.src-sed:before { content: 'Sed'; }
pre.src-sh:before { content: 'shell'; }
pre.src-sql:before { content: 'SQL'; }
pre.src-sqlite:before { content: 'SQLite'; }
/* additional languages in org.el's org-babel-load-languages alist */
pre.src-forth:before { content: 'Forth'; }
pre.src-io:before { content: 'IO'; }
pre.src-J:before { content: 'J'; }
pre.src-makefile:before { content: 'Makefile'; }
pre.src-maxima:before { content: 'Maxima'; }
pre.src-perl:before { content: 'Perl'; }
pre.src-picolisp:before { content: 'Pico Lisp'; }
pre.src-scala:before { content: 'Scala'; }
pre.src-shell:before { content: 'Shell Script'; }
pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
/* additional language identifiers per "defun org-babel-execute"
in ob-*.el */
pre.src-cpp:before { content: 'C++'; }
pre.src-abc:before { content: 'ABC'; }
pre.src-coq:before { content: 'Coq'; }
pre.src-groovy:before { content: 'Groovy'; }
/* additional language identifiers from org-babel-shell-names in
ob-shell.el: ob-shell is the only babel language using a lambda to put
the execution function name together. */
pre.src-bash:before { content: 'bash'; }
pre.src-csh:before { content: 'csh'; }
pre.src-ash:before { content: 'ash'; }
pre.src-dash:before { content: 'dash'; }
pre.src-ksh:before { content: 'ksh'; }
pre.src-mksh:before { content: 'mksh'; }
pre.src-posh:before { content: 'posh'; }
/* Additional Emacs modes also supported by the LaTeX listings package */
pre.src-ada:before { content: 'Ada'; }
pre.src-asm:before { content: 'Assembler'; }
pre.src-caml:before { content: 'Caml'; }
pre.src-delphi:before { content: 'Delphi'; }
pre.src-html:before { content: 'HTML'; }
pre.src-idl:before { content: 'IDL'; }
pre.src-mercury:before { content: 'Mercury'; }
pre.src-metapost:before { content: 'MetaPost'; }
pre.src-modula-2:before { content: 'Modula-2'; }
pre.src-pascal:before { content: 'Pascal'; }
pre.src-ps:before { content: 'PostScript'; }
pre.src-prolog:before { content: 'Prolog'; }
pre.src-simula:before { content: 'Simula'; }
pre.src-tcl:before { content: 'tcl'; }
pre.src-tex:before { content: 'TeX'; }
pre.src-plain-tex:before { content: 'Plain TeX'; }
pre.src-verilog:before { content: 'Verilog'; }
pre.src-vhdl:before { content: 'VHDL'; }
pre.src-xml:before { content: 'XML'; }
pre.src-nxml:before { content: 'XML'; }
/* add a generic configuration mode; LaTeX export needs an additional
(add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
pre.src-conf:before { content: 'Configuration File'; }
table { border-collapse:collapse; }
caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
td, th { vertical-align:top; }
th.org-right { text-align: center; }
th.org-left { text-align: center; }
th.org-center { text-align: center; }
td.org-right { text-align: right; }
td.org-left { text-align: left; }
td.org-center { text-align: center; }
dt { font-weight: bold; }
.footpara { display: inline; }
.footdef { margin-bottom: 1em; }
.figure { padding: 1em; }
.figure p { text-align: center; }
.equation-container {
display: table;
text-align: center;
width: 100%;
}
.equation {
vertical-align: middle;
}
.equation-label {
display: table-cell;
text-align: right;
vertical-align: middle;
}
.inlinetask {
padding: 10px;
border: 2px solid gray;
margin: 10px;
background: #ffffcc;
}
#org-div-home-and-up
{ text-align: right; font-size: 70%; white-space: nowrap; }
textarea { overflow-x: auto; }
.linenr { font-size: smaller }
.code-highlighted { background-color: #ffff00; }
.org-info-js_info-navigation { border-style: none; }
#org-info-js_console-label
{ font-size: 10px; font-weight: bold; white-space: nowrap; }
.org-info-js_search-highlight
{ background-color: #ffff00; color: #000000; font-weight: bold; }
.org-svg { width: 90%; }
</style>
</head>
<body>
<div id="content" class="content">
<div id="table-of-contents" role="doc-toc">
<h2>Table of Contents</h2>
<div id="text-table-of-contents" role="doc-toc">
<ul>
<li><a href="#orgdf5e4c2">1. A New Start</a>
<ul>
<li><a href="#org1b5827d">1.1. Overview</a></li>
</ul>
</li>
<li><a href="#org2e40c73">2. Package Management</a>
<ul>
<li><a href="#org4ac5c97">2.1. ELPA and Non-GNU ELPA</a>
<ul>
<li><a href="#orged85165">2.1.1. Add non-gnu ELPA to Emacs < 28</a></li>
</ul>
</li>
<li><a href="#org2769506">2.2. Installing Packages</a></li>
<li><a href="#org16d63c2">2.3. Packages not in the default repos</a></li>
<li><a href="#org4215bb7">2.4. Emacs 28 native compilation</a></li>
</ul>
</li>
<li><a href="#orgdeffb30">3. Keybinding</a>
<ul>
<li><a href="#org5621c19">3.1. xah-fly-keys</a></li>
</ul>
</li>
<li><a href="#orgd7dd270">4. Completion</a>
<ul>
<li><a href="#org9b9dac8">4.1. Two kinds of completion</a></li>
<li><a href="#orge1b4621">4.2. Emacs completion styles</a></li>
<li><a href="#org5883ba7">4.3. consult - Consulting completing-read</a>
<ul>
<li><a href="#org64b8a2b">4.3.1. "Virtual Buffers"</a></li>
<li><a href="#org403305c">4.3.2. consult keybindings</a></li>
<li><a href="#org031cb06">4.3.3. consult-themes</a></li>
<li><a href="#org7fbc5e7">4.3.4. <span class="todo TODO">TODO</span> consult-project-buffer</a></li>
</ul>
</li>
<li><a href="#org7b55f29">4.4. embark</a></li>
<li><a href="#org8e12307">4.5. marginalia</a></li>
<li><a href="#orge6036f2">4.6. vertico</a>
<ul>
<li><a href="#orgba3f7f7">4.6.1. vertico-directory</a></li>
</ul>
</li>
<li><a href="#org33ed736">4.7. corfu</a>
<ul>
<li><a href="#org3ebbe44">4.7.1. corfu-terminal enables in terminal interface</a></li>
</ul>
</li>
<li><a href="#orge300cfc">4.8. which-key</a></li>
</ul>
</li>
<li><a href="#org19750d2">5. Editing</a>
<ul>
<li><a href="#orgd49b424">5.1. electric pair mode</a></li>
<li><a href="#orgf23fec9">5.2. markdown mode</a></li>
<li><a href="#org709f02c">5.3. org mode</a>
<ul>
<li><a href="#orge7954c4">5.3.1. exporting</a></li>
</ul>
</li>
<li><a href="#org4c2680d">5.4. recentf-mode</a></li>
</ul>
</li>
<li><a href="#org6f22775">6. Programming</a>
<ul>
<li><a href="#org1a56e09">6.1. Languages</a>
<ul>
<li><a href="#orgea87347">6.1.1. Common Lisp</a></li>
<li><a href="#org66f16ab">6.1.2. Javascript</a></li>
<li><a href="#org9801164">6.1.3. Ruby</a></li>
</ul>
</li>
<li><a href="#org3e1a4c8">6.2. Dev Docs</a></li>
</ul>
</li>
<li><a href="#org7b5b481">7. Projects</a>
<ul>
<li><a href="#orgeb5a0f7">7.1. project.el</a></li>
<li><a href="#org05ca46c">7.2. version control</a>
<ul>
<li><a href="#org7d03814">7.2.1. magit</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#org6d3c8fa">8. External Services</a>
<ul>
<li><a href="#orgd733e10">8.1. plz - http library</a></li>
<li><a href="#org721adef">8.2. sourcehut</a></li>
</ul>
</li>
<li><a href="#org7ba8dba">9. UI</a>
<ul>
<li><a href="#orgb0526ec">9.1. basic Emacs UI tweaks</a></li>
<li><a href="#orga727260">9.2. darkroom - distraction free writing</a></li>
<li><a href="#org99e1861">9.3. Fonts</a></li>
<li><a href="#org033b480">9.4. Highlights</a>
<ul>
<li><a href="#org1aa916e">9.4.1. global-hl-mode</a></li>
</ul>
</li>
<li><a href="#orgc642392">9.5. Themes</a></li>
<li><a href="#orgb9e69a0">9.6. windresize</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="outline-container-orgdf5e4c2" class="outline-2">
<h2 id="orgdf5e4c2"><span class="section-number-2">1.</span> A New Start</h2>
<div class="outline-text-2" id="text-1">
<p>
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.
</p>
<p>
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.
</p>
</div>
<div id="outline-container-org1b5827d" class="outline-3">
<h3 id="org1b5827d"><span class="section-number-3">1.1.</span> Overview</h3>
<div class="outline-text-3" id="text-1-1">
<p>
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.
</p>
<p>
The program bits will be tangled into <a href="shoshin-config.el">shoshin-config.el</a>. 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.
</p>
<p>
The following code block is the "table of contents" that determines what
is tangled into the resulting elisp file:
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp"><span style="color: #6272a4;">;;; </span><span style="color: #6272a4;">shoshimacs.el --- Beginner's Mind Config -*- lexical-binding:t -*-</span>
<span style="color: #6272a4;">;;; </span><span style="color: #6272a4;">Package Management</span>
(<span style="color: #ff79c6; font-weight: bold;">when</span> (< emacs-major-version 28)
(package-initialize)
(add-to-list 'package-archives '(<span style="color: #f1fa8c;">"nongnu"</span> . <span style="color: #f1fa8c;">"https://elpa.nongnu.org/nongnu/"</span>))
(package-refresh-contents))
(<span style="color: #ff79c6; font-weight: bold;">when</span> (<span style="color: #ff79c6; font-weight: bold;">and</span> (functionp #'native-comp-available-p) (native-comp-available-p))
(<span style="color: #ff79c6; font-weight: bold;">setq</span> native-comp-always-compile t
package-native-compile t))
<span style="color: #6272a4;">;;; </span><span style="color: #6272a4;">Major Keybinding</span>
(package-install 'xah-fly-keys)
(<span style="color: #ff79c6; font-weight: bold;">require</span> '<span style="color: #8be9fd;">xah-fly-keys</span>)
(xah-fly-keys-set-layout <span style="color: #f1fa8c;">"qwerty"</span>)
(<span style="color: #ff79c6; font-weight: bold;">setq</span> xah-fly-use-control-key nil
xah-fly-use-meta-key nil)
(xah-fly-keys t)
<span style="color: #6272a4;">;;; </span><span style="color: #6272a4;">Completion</span>
(<span style="color: #ff79c6; font-weight: bold;">setq</span> completion-styles '(flex basic partial-completion emacs22)
completion-cycle-threshold 3
tab-always-indent 'complete)
(package-install 'consult)
(global-set-key (kbd <span style="color: #f1fa8c;">"C-x b"</span>) #'consult-buffer)
(define-key xah-fly-leader-key-map (kbd <span style="color: #f1fa8c;">"f"</span>) #'consult-buffer)
(define-key xah-fly-command-map (kbd <span style="color: #f1fa8c;">"n"</span>) #'consult-line)
(<span style="color: #ff79c6; font-weight: bold;">with-eval-after-load</span> 'consult
(<span style="color: #ff79c6; font-weight: bold;">consult-customize</span> consult-theme <span style="color: #ffb86c;">:preview-key</span> '(<span style="color: #ffb86c;">:debounce</span> 0.5 any)))
(package-install 'embark)
(package-install 'marginalia)
(marginalia-mode)
(package-install 'vertico)
(<span style="color: #ff79c6; font-weight: bold;">setq</span> minibuffer-prompt-properties
'(read-only t cursor-intangible t face minibuffer-prompt))
(add-hook 'minibuffer-setup-hook #'cursor-intangible-mode)
(<span style="color: #ff79c6; font-weight: bold;">setq</span> read-extended-command-predicate
#'command-completion-default-include-p)
(<span style="color: #ff79c6; font-weight: bold;">setq</span> enable-recursive-minibuffers t)
(vertico-mode)
(<span style="color: #ff79c6; font-weight: bold;">require</span> '<span style="color: #8be9fd;">vertico-directory</span>)
(define-key vertico-map (kbd <span style="color: #f1fa8c;">"RET"</span>) #'vertico-directory-enter)
(define-key vertico-map (kbd <span style="color: #f1fa8c;">"DEL"</span>) #'vertico-directory-delete-char)
(define-key vertico-map (kbd <span style="color: #f1fa8c;">"M-DEL"</span>) #'vertico-directory-delete-word)
(define-key vertico-map (kbd <span style="color: #f1fa8c;">"M-j"</span>) #'vertico-quick-insert)
(package-install 'corfu)
(<span style="color: #ff79c6; font-weight: bold;">setq</span> corfu-auto t
corfu-cycle t
corfu-quit-no-match t)
(global-corfu-mode t)
(package-install 'corfu-terminal)
(<span style="color: #ff79c6; font-weight: bold;">unless</span> (display-graphic-p)
(corfu-terminal-mode +1))
(package-install 'which-key)
(which-key-mode)
<span style="color: #6272a4;">;;; </span><span style="color: #6272a4;">Editing</span>
(electric-pair-mode)
(package-install 'markdown-mode)
(package-install 'htmlize)
(recentf-mode)
<span style="color: #6272a4;">;;; </span><span style="color: #6272a4;">Programming</span>
(package-install 'sly)
(package-install 'json-mode)
(package-install 'devdocs)
<span style="color: #6272a4;">;;; </span><span style="color: #6272a4;">Projects</span>
(package-install 'magit)
<span style="color: #6272a4;">;;; </span><span style="color: #6272a4;">External Services</span>
(package-install 'plz)
(package-install 'srht)
(<span style="color: #ff79c6; font-weight: bold;">setq</span> srht-username <span style="color: #f1fa8c;">"shoshin"</span>)
<span style="color: #6272a4;">;;; </span><span style="color: #6272a4;">User Interface</span>
(<span style="color: #ff79c6; font-weight: bold;">when</span> (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 <span style="color: #f1fa8c;">"Victor Mono"</span>)
(global-hl-line-mode t)
(<span style="color: #ff79c6; font-weight: bold;">setq</span> my-chosen-themes
'(cyberpunk-theme dracula-theme))
(mapc #'package-install my-chosen-themes)
(package-install 'windresize)
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-org2e40c73" class="outline-2">
<h2 id="org2e40c73"><span class="section-number-2">2.</span> Package Management</h2>
<div class="outline-text-2" id="text-2">
<p>
I've been using <a href="https://github.com/radian-software/straight.el#start-of-content">straight.el</a>
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.
</p>
<p>
This configuration will stick to packages available through the built-in
<code>package.el</code> system. As of Emacs 28, this is everything in the ELPA and
non-gnu ELPA package repositories.
</p>
</div>
<div id="outline-container-org4ac5c97" class="outline-3">
<h3 id="org4ac5c97"><span class="section-number-3">2.1.</span> ELPA and Non-GNU ELPA</h3>
<div class="outline-text-3" id="text-2-1">
<p>
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.
</p>
<p>
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.
</p>
</div>
<div id="outline-container-orged85165" class="outline-4">
<h4 id="orged85165"><span class="section-number-4">2.1.1.</span> Add non-gnu ELPA to Emacs < 28</h4>
<div class="outline-text-4" id="text-2-1-1">
<p>
Emacs 28 is the first version to include non-gnu ELPA by default. Some
distributions may not yet have it as an available package.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp" id="orge67d88c">(<span style="color: #ff79c6; font-weight: bold;">when</span> (< emacs-major-version 28)
(package-initialize)
(add-to-list 'package-archives '(<span style="color: #f1fa8c;">"nongnu"</span> . <span style="color: #f1fa8c;">"https://elpa.nongnu.org/nongnu/"</span>))
(package-refresh-contents))
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-org2769506" class="outline-3">
<h3 id="org2769506"><span class="section-number-3">2.2.</span> Installing Packages</h3>
<div class="outline-text-3" id="text-2-2">
<p>
<code>package.el</code> provides the <a href="package-install">package-install</a> 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 <a href="package-selected-packages">package-selected-packages</a>.
</p>
<p>
You can also use <code>list-packages</code> to browse, install and upgrade packages as
well.
</p>
</div>
</div>
<div id="outline-container-org16d63c2" class="outline-3">
<h3 id="org16d63c2"><span class="section-number-3">2.3.</span> Packages not in the default repos</h3>
<div class="outline-text-3" id="text-2-3">
<p>
Any elisp package that is in Emacs's <a href="load-path">load-path</a> can be <code>require</code>'d and used.
<code>(add-to-list 'load-path (expand-file-name "some-package/" user-emacs-directory))</code>
is an example of putting the directory <code>some-package/</code> into the load path.
</p>
</div>
</div>
<div id="outline-container-org4215bb7" class="outline-3">
<h3 id="org4215bb7"><span class="section-number-3">2.4.</span> Emacs 28 native compilation</h3>
<div class="outline-text-3" id="text-2-4">
<p>
<a href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Native-Compilation">elisp#Native Compilation</a>
</p>
<p>
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
<code>*Async-native-compile-log*</code> buffer if you are curious. Mostly you shouldn't
have to worry about it, though you may see some compilation warnings at times.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(<span style="color: #ff79c6; font-weight: bold;">when</span> (<span style="color: #ff79c6; font-weight: bold;">and</span> (functionp #'native-comp-available-p) (native-comp-available-p))
(<span style="color: #ff79c6; font-weight: bold;">setq</span> native-comp-always-compile t
package-native-compile t))
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-orgdeffb30" class="outline-2">
<h2 id="orgdeffb30"><span class="section-number-2">3.</span> Keybinding</h2>
<div class="outline-text-2" id="text-3">
<p>
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.
</p>
<p>
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.
</p>
</div>
<div id="outline-container-org5621c19" class="outline-3">
<h3 id="org5621c19"><span class="section-number-3">3.1.</span> xah-fly-keys</h3>
<div class="outline-text-3" id="text-3-1">
<p>
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
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp" id="org6dcf623">(package-install 'xah-fly-keys)
(<span style="color: #ff79c6; font-weight: bold;">require</span> '<span style="color: #8be9fd;">xah-fly-keys</span>)
(xah-fly-keys-set-layout <span style="color: #f1fa8c;">"qwerty"</span>)
(<span style="color: #ff79c6; font-weight: bold;">setq</span> xah-fly-use-control-key nil
xah-fly-use-meta-key nil)
(xah-fly-keys t)
</pre>
</div>
<p>
i'm setting it up early in the config so that its keymaps are available
to modify / integrate with other packages.
</p>
</div>
</div>
</div>
<div id="outline-container-orgd7dd270" class="outline-2">
<h2 id="orgd7dd270"><span class="section-number-2">4.</span> Completion</h2>
<div class="outline-text-2" id="text-4">
<p>
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.
</p>
<p>
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.
</p>
</div>
<div id="outline-container-org9b9dac8" class="outline-3">
<h3 id="org9b9dac8"><span class="section-number-3">4.1.</span> Two kinds of completion</h3>
<div class="outline-text-3" id="text-4-1">
<p>
I want to point out that there are two distinct but similar features
both grouped under the concept of "completion". The first is <b>Minibuffer</b>
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 <b>Buffer</b> 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 <a href="https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Symbol-Completion">Symbol Completion</a>
for free, since Emacs itself is a running Lisp process with knowledge of
all the defined symbols in the system.
</p>
<p>
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.
</p>
</div>
</div>
<div id="outline-container-orge1b4621" class="outline-3">
<h3 id="orge1b4621"><span class="section-number-3">4.2.</span> Emacs completion styles</h3>
<div class="outline-text-3" id="text-4-2">
<p>
Emacs has a quite sophisticated way of selecting candidates for completion.
You can read about them here: <a href="https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Completion-Styles">emacs#Completion Styles</a>
</p>
<p>
I've grown used to the <code>flex</code> style of completion where typing
<code>pr/s/sho.o</code> at the find file prompt expands to
<code>projects/shoshimacs/shoshin-config.org</code>. There are other alternatives
and you can even write your own. The <code>completion-styles</code> 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 <code>flex</code> to the front of the default completion styles.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(<span style="color: #ff79c6; font-weight: bold;">setq</span> completion-styles '(flex basic partial-completion emacs22)
completion-cycle-threshold 3
tab-always-indent 'complete)
</pre>
</div>
<p>
<code>completion-cycle-threshold</code> 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.
</p>
<p>
<code>tab-always-indent</code> changes the behavior of the TAB key:
</p>
<blockquote>
<p>
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.
</p>
</blockquote>
</div>
</div>
<div id="outline-container-org5883ba7" class="outline-3">
<h3 id="org5883ba7"><span class="section-number-3">4.3.</span> <a href="consult.html#Top">consult</a> - Consulting <a href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Minibuffer-Completion">completing-read</a></h3>
<div class="outline-text-3" id="text-4-3">
<p>
consult offers enhanced completion similar to ivy and helm, but with the
built in completing read functionality of the minibuffer.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'consult)
</pre>
</div>
<p>
main entry point would be <code>consult-buffer</code>. however, there are many consult
commands that can enhance any completing read function.
</p>
</div>
<div id="outline-container-org64b8a2b" class="outline-4">
<h4 id="org64b8a2b"><span class="section-number-4">4.3.1.</span> "Virtual Buffers"</h4>
<div class="outline-text-4" id="text-4-3-1">
<p>
it introduces this concept of "Virtual Buffers", but i'm not certain what
it means. consult "supports … narrowing to the virtual buffer types".
</p>
<p>
perhaps a Virtual Buffer is a "grouping" of actual Emacs buffers or "things"
that can be materialized in a buffer. For example, I can <code>consult-buffer</code>
and press <code>m SPC</code> to narrow the "buffer list" to any bookmarks.
</p>
</div>
</div>
<div id="outline-container-org403305c" class="outline-4">
<h4 id="org403305c"><span class="section-number-4">4.3.2.</span> consult keybindings</h4>
<div class="outline-text-4" id="text-4-3-2">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(global-set-key (kbd <span style="color: #f1fa8c;">"C-x b"</span>) #'consult-buffer)
(define-key xah-fly-leader-key-map (kbd <span style="color: #f1fa8c;">"f"</span>) #'consult-buffer)
(define-key xah-fly-command-map (kbd <span style="color: #f1fa8c;">"n"</span>) #'consult-line)
</pre>
</div>
</div>
</div>
<div id="outline-container-org031cb06" class="outline-4">
<h4 id="org031cb06"><span class="section-number-4">4.3.3.</span> consult-themes</h4>
<div class="outline-text-4" id="text-4-3-3">
<p>
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 <a href="https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Advising-Functions">advice</a>
to <code>load-theme</code> to automatically disable the old one before enabling
the new.
</p>
<p>
it seems like <code>consult-theme</code> 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.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(<span style="color: #ff79c6; font-weight: bold;">with-eval-after-load</span> 'consult
(<span style="color: #ff79c6; font-weight: bold;">consult-customize</span> consult-theme <span style="color: #ffb86c;">:preview-key</span> '(<span style="color: #ffb86c;">:debounce</span> 0.5 any)))
</pre>
</div>
</div>
</div>
<div id="outline-container-org7fbc5e7" class="outline-4">
<h4 id="org7fbc5e7"><span class="section-number-4">4.3.4.</span> <span class="todo TODO">TODO</span> consult-project-buffer</h4>
<div class="outline-text-4" id="text-4-3-4">
<p>
how do project buffers get filtered? i'm seeing buffers assigned to a project
that in my mind, shouldn't be.
</p>
<p>
looks like it interfaces with <code>project-switch-to-buffer</code> 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.
</p>
<p>
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 <code>default-directory</code>
variable which is buffer-local.
</p>
<p>
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 <code>perspectives</code> provided by a MELPA package
that hooked into <code>projectile</code>'s project definitions. it would keep a list of
perspective-local buffers where the perspective was tied to a project.
</p>
</div>
</div>
</div>
<div id="outline-container-org7b55f29" class="outline-3">
<h3 id="org7b55f29"><span class="section-number-3">4.4.</span> embark</h3>
<div class="outline-text-3" id="text-4-4">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'embark)
</pre>
</div>
</div>
</div>
<div id="outline-container-org8e12307" class="outline-3">
<h3 id="org8e12307"><span class="section-number-3">4.5.</span> marginalia</h3>
<div class="outline-text-3" id="text-4-5">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'marginalia)
(marginalia-mode)
</pre>
</div>
</div>
</div>
<div id="outline-container-orge6036f2" class="outline-3">
<h3 id="orge6036f2"><span class="section-number-3">4.6.</span> vertico</h3>
<div class="outline-text-3" id="text-4-6">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'vertico)
(<span style="color: #ff79c6; font-weight: bold;">setq</span> minibuffer-prompt-properties
'(read-only t cursor-intangible t face minibuffer-prompt))
(add-hook 'minibuffer-setup-hook #'cursor-intangible-mode)
(<span style="color: #ff79c6; font-weight: bold;">setq</span> read-extended-command-predicate
#'command-completion-default-include-p)
(<span style="color: #ff79c6; font-weight: bold;">setq</span> enable-recursive-minibuffers t)
(vertico-mode)
</pre>
</div>
</div>
<div id="outline-container-orgba3f7f7" class="outline-4">
<h4 id="orgba3f7f7"><span class="section-number-4">4.6.1.</span> vertico-directory</h4>
<div class="outline-text-4" id="text-4-6-1">
<p>
i'd like to emulate the behavior in <code>find-file</code> 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.
</p>
<p>
this is implemented with the <code>vertico-directory</code> extension.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(<span style="color: #ff79c6; font-weight: bold;">require</span> '<span style="color: #8be9fd;">vertico-directory</span>)
(define-key vertico-map (kbd <span style="color: #f1fa8c;">"RET"</span>) #'vertico-directory-enter)
(define-key vertico-map (kbd <span style="color: #f1fa8c;">"DEL"</span>) #'vertico-directory-delete-char)
(define-key vertico-map (kbd <span style="color: #f1fa8c;">"M-DEL"</span>) #'vertico-directory-delete-word)
(define-key vertico-map (kbd <span style="color: #f1fa8c;">"M-j"</span>) #'vertico-quick-insert)
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-org33ed736" class="outline-3">
<h3 id="org33ed736"><span class="section-number-3">4.7.</span> corfu</h3>
<div class="outline-text-3" id="text-4-7">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'corfu)
(<span style="color: #ff79c6; font-weight: bold;">setq</span> corfu-auto t
corfu-cycle t
corfu-quit-no-match t)
(global-corfu-mode t)
</pre>
</div>
</div>
<div id="outline-container-org3ebbe44" class="outline-4">
<h4 id="org3ebbe44"><span class="section-number-4">4.7.1.</span> corfu-terminal enables in terminal interface</h4>
<div class="outline-text-4" id="text-4-7-1">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'corfu-terminal)
(<span style="color: #ff79c6; font-weight: bold;">unless</span> (display-graphic-p)
(corfu-terminal-mode +1))
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-orge300cfc" class="outline-3">
<h3 id="orge300cfc"><span class="section-number-3">4.8.</span> which-key</h3>
<div class="outline-text-3" id="text-4-8">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'which-key)
(which-key-mode)
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-org19750d2" class="outline-2">
<h2 id="org19750d2"><span class="section-number-2">5.</span> Editing</h2>
<div class="outline-text-2" id="text-5">
</div>
<div id="outline-container-orgd49b424" class="outline-3">
<h3 id="orgd49b424"><span class="section-number-3">5.1.</span> <a href="https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Matching">electric pair mode</a></h3>
<div class="outline-text-3" id="text-5-1">
<p>
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 <code>sp-hybrid-slurp</code> 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.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(electric-pair-mode)
</pre>
</div>
</div>
</div>
<div id="outline-container-orgf23fec9" class="outline-3">
<h3 id="orgf23fec9"><span class="section-number-3">5.2.</span> markdown mode</h3>
<div class="outline-text-3" id="text-5-2">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'markdown-mode)
</pre>
</div>
</div>
</div>
<div id="outline-container-org709f02c" class="outline-3">
<h3 id="org709f02c"><span class="section-number-3">5.3.</span> org mode</h3>
<div class="outline-text-3" id="text-5-3">
</div>
<div id="outline-container-orge7954c4" class="outline-4">
<h4 id="orge7954c4"><span class="section-number-4">5.3.1.</span> exporting</h4>
<div class="outline-text-4" id="text-5-3-1">
<pre class="example">
(require 'ox-md)
</pre>
</div>
<ol class="org-ol">
<li><a id="org196310c"></a>htmilze<br />
<div class="outline-text-5" id="text-5-3-1-1">
<p>
this seems to be required to fontify source blocks
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'htmlize)
</pre>
</div>
</div>
</li>
</ol>
</div>
</div>
<div id="outline-container-org4c2680d" class="outline-3">
<h3 id="org4c2680d"><span class="section-number-3">5.4.</span> recentf-mode</h3>
<div class="outline-text-3" id="text-5-4">
<p>
this tracks recently operated on files (by default) and enables quick selection
from them in various Emacs menus. <a href="#org5883ba7">consult</a> hooks into it as well.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(recentf-mode)
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-org6f22775" class="outline-2">
<h2 id="org6f22775"><span class="section-number-2">6.</span> Programming</h2>
<div class="outline-text-2" id="text-6">
</div>
<div id="outline-container-org1a56e09" class="outline-3">
<h3 id="org1a56e09"><span class="section-number-3">6.1.</span> Languages</h3>
<div class="outline-text-3" id="text-6-1">
</div>
<div id="outline-container-orgea87347" class="outline-4">
<h4 id="orgea87347"><span class="section-number-4">6.1.1.</span> Common Lisp</h4>
<div class="outline-text-4" id="text-6-1-1">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'sly)
</pre>
</div>
</div>
</div>
<div id="outline-container-org66f16ab" class="outline-4">
<h4 id="org66f16ab"><span class="section-number-4">6.1.2.</span> Javascript</h4>
<div class="outline-text-4" id="text-6-1-2">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'json-mode)
</pre>
</div>
</div>
</div>
<div id="outline-container-org9801164" class="outline-4">
<h4 id="org9801164"><span class="section-number-4">6.1.3.</span> Ruby</h4>
</div>
</div>
<div id="outline-container-org3e1a4c8" class="outline-3">
<h3 id="org3e1a4c8"><span class="section-number-3">6.2.</span> Dev Docs</h3>
<div class="outline-text-3" id="text-6-2">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'devdocs)
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-org7b5b481" class="outline-2">
<h2 id="org7b5b481"><span class="section-number-2">7.</span> Projects</h2>
<div class="outline-text-2" id="text-7">
</div>
<div id="outline-container-orgeb5a0f7" class="outline-3">
<h3 id="orgeb5a0f7"><span class="section-number-3">7.1.</span> project.el</h3>
</div>
<div id="outline-container-org05ca46c" class="outline-3">
<h3 id="org05ca46c"><span class="section-number-3">7.2.</span> version control</h3>
<div class="outline-text-3" id="text-7-2">
</div>
<div id="outline-container-org7d03814" class="outline-4">
<h4 id="org7d03814"><span class="section-number-4">7.2.1.</span> magit</h4>
<div class="outline-text-4" id="text-7-2-1">
<p>
its the best! 🪄
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'magit)
</pre>
</div>
</div>
</div>
</div>
</div>
<div id="outline-container-org6d3c8fa" class="outline-2">
<h2 id="org6d3c8fa"><span class="section-number-2">8.</span> External Services</h2>
<div class="outline-text-2" id="text-8">
<p>
Packages that enable communication via HTTP or connect with external APIs or other
resources outside of Emacs and/or the local machine.
</p>
</div>
<div id="outline-container-orgd733e10" class="outline-3">
<h3 id="orgd733e10"><span class="section-number-3">8.1.</span> plz - http library</h3>
<div class="outline-text-3" id="text-8-1">
<p>
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 <code>plz</code> is that it is dependent on <code>curl</code>, rather
than being pure elisp. however, this is a non-issue for me, especially since my
use case had devolved into using <code>make-process</code> to call <code>wget</code> and then implement
a "callback" with a process sentinel. kinda neat, but maybe too much.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'plz)
</pre>
</div>
<p>
the sourcehut package in this config also depends on <code>plz</code>
</p>
</div>
</div>
<div id="outline-container-org721adef" class="outline-3">
<h3 id="org721adef"><span class="section-number-3">8.2.</span> sourcehut</h3>
<div class="outline-text-3" id="text-8-2">
<p>
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.
</p>
<p>
it also depends on <code>plz</code> which is another new package providing a nicer API for
HTTP requests I was going
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'srht)
(<span style="color: #ff79c6; font-weight: bold;">setq</span> srht-username <span style="color: #f1fa8c;">"shoshin"</span>)
</pre>
</div>
<p>
an API token is stored in my <code>.authinfo</code> file.
</p>
</div>
</div>
</div>
<div id="outline-container-org7ba8dba" class="outline-2">
<h2 id="org7ba8dba"><span class="section-number-2">9.</span> UI</h2>
<div class="outline-text-2" id="text-9">
</div>
<div id="outline-container-orgb0526ec" class="outline-3">
<h3 id="orgb0526ec"><span class="section-number-3">9.1.</span> basic Emacs UI tweaks</h3>
<div class="outline-text-3" id="text-9-1">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(<span style="color: #ff79c6; font-weight: bold;">when</span> (display-graphic-p)
(scroll-bar-mode -1)
(fringe-mode '(8 . 0)))
(tab-bar-mode t)
(display-battery-mode t)
</pre>
</div>
</div>
</div>
<div id="outline-container-orga727260" class="outline-3">
<h3 id="orga727260"><span class="section-number-3">9.2.</span> [BROKEN LINK: No match for fuzzy expression: ;;; Commentary:] - distraction free writing</h3>
<div class="outline-text-3" id="text-9-2">
<p>
the notes suggest using <code>darkroom-tentative-mode</code> which auto switches
depending on the window layout currently in use.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'darkroom)
</pre>
</div>
</div>
</div>
<div id="outline-container-org99e1861" class="outline-3">
<h3 id="org99e1861"><span class="section-number-3">9.3.</span> Fonts</h3>
<div class="outline-text-3" id="text-9-3">
<p>
For code, I've grown fond of Victor Mono.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(set-frame-font <span style="color: #f1fa8c;">"Victor Mono"</span>)
</pre>
</div>
</div>
</div>
<div id="outline-container-org033b480" class="outline-3">
<h3 id="org033b480"><span class="section-number-3">9.4.</span> Highlights</h3>
<div class="outline-text-3" id="text-9-4">
</div>
<div id="outline-container-org1aa916e" class="outline-4">
<h4 id="org1aa916e"><span class="section-number-4">9.4.1.</span> <a href="global-hl-line-mode">global-hl-mode</a></h4>
<div class="outline-text-4" id="text-9-4-1">
<p>
i enjoy having the current line highighted as a visual cue.
</p>
<div class="org-src-container">
<pre class="src src-emacs-lisp">(global-hl-line-mode t)
</pre>
</div>
<p>
can be toggled with <leader> l 2
</p>
</div>
</div>
</div>
<div id="outline-container-orgc642392" class="outline-3">
<h3 id="orgc642392"><span class="section-number-3">9.5.</span> Themes</h3>
<div class="outline-text-3" id="text-9-5">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(<span style="color: #ff79c6; font-weight: bold;">setq</span> my-chosen-themes
'(cyberpunk-theme dracula-theme))
(mapc #'package-install my-chosen-themes)
</pre>
</div>
</div>
</div>
<div id="outline-container-orgb9e69a0" class="outline-3">
<h3 id="orgb9e69a0"><span class="section-number-3">9.6.</span> windresize</h3>
<div class="outline-text-3" id="text-9-6">
<div class="org-src-container">
<pre class="src src-emacs-lisp">(package-install 'windresize)
</pre>
</div>
</div>
</div>
</div>
</div>
<div id="postamble" class="status">
<p class="date">Created: 2022-07-03 Sun 21:12</p>
<p class="validation"><a href="https://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>
</html>