diff options
| -rw-r--r-- | README.html | 1214 | ||||
| -rw-r--r-- | README.md | 754 | ||||
| -rw-r--r-- | shoshimacs.el (renamed from shoshin-config.el) | 0 | ||||
| -rw-r--r-- | shoshimacs.org (renamed from shoshin-config.org) | 0 |
4 files changed, 0 insertions, 1968 deletions
diff --git a/README.html b/README.html deleted file mode 100644 index 403c6e1..0000000 --- a/README.html +++ /dev/null @@ -1,1214 +0,0 @@ -<?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> diff --git a/README.md b/README.md deleted file mode 100644 index 04fd956..0000000 --- a/README.md +++ /dev/null @@ -1,754 +0,0 @@ - -# 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) - diff --git a/shoshin-config.el b/shoshimacs.el index ffd98c1..ffd98c1 100644 --- a/shoshin-config.el +++ b/shoshimacs.el diff --git a/shoshin-config.org b/shoshimacs.org index b597e19..b597e19 100644 --- a/shoshin-config.org +++ b/shoshimacs.org |