Refactoring Prose

emacs/+keybinds.el

@@ -1,3 +1,7 @@
+;;; -*- lexical-binding: t; -*-
+;;; This file is generated via tangles from the config.org file. Do not modify this file.
+;;; Any modifications here will be clobbered and versioned over. Seriously just don't.
+
 ;;; +keybinds.el -*- lexical-binding: t; -*-
 
 ;;; This file is generated via tangles from the config.org file. Do not modify this file.

emacs/+orgmode.el

@@ -1,3 +1,7 @@
+;;; -*- lexical-binding: t; -*-
+;;; This file is generated via tangles from the config.org file. Do not modify this file.
+;;; Any modifications here will be clobbered and versioned over. Seriously just don't.
+
 ;;; +orgmode.el -*- lexical-binding: t; -*-
 
 ;;; This file is generated via tangles from the config.org file. Do not modify this file.

emacs/config.el

@@ -1,8 +1,17 @@
-;;; config.el -*- lexical-binding: t; -*-
+;;; -*- lexical-binding: t; -*-
 
 ;;; This file is generated via tangles from the config.org file. Do not modify this file.
 ;;; Any modifications here will be clobbered and versioned over. Seriously just don't.
 
+;;; -*- lexical-binding: t; -*-
+;;; This file is generated via tangles from the config.org file. Do not modify this file.
+;;; Any modifications here will be clobbered and versioned over. Seriously just don't.
+
+(setq fancy-splash-image (concat doom-user-dir "./.resources/doom.png"))
+
+(setq ispell-dictionary "en"
+      ispell-personal-dictionary "~/org/.ispell.en.pws")
+
 (setq which-key-idle-delay 0.1)
 
 (setq doom-fallback-buffer-name "Doom"
@@ -28,14 +37,8 @@
 (add-to-list 'auto-mode-alist '("/\\(tmp\\|private/var\\)/.*/tmp_.*.greenfiling.com.*\\.txt" . markdown-mode))
 (add-to-list 'auto-mode-alist '("/\\(tmp\\|private/var\\)/.*/tmp_.*.github.com.*\\.txt" . markdown-mode))
 
-(setq fancy-splash-image (concat doom-user-dir "./.resources/doom.png"))
-
-(setq ispell-dictionary "en"
-      ispell-personal-dictionary "~/org/.ispell.en.pws")
-
 (load! "+keybinds")
 
 (load! "+orgmode")
 
-
 (use-package! gptel)

emacs/config.org

@@ -4,34 +4,23 @@
 I'll fill out the how and why of this all as I figure out what the hell I'm doing. My current Emacs Configuration is a mess of copy and pasted snippet loosely grouped together. There's a fair number of work around, to transient configuration issues that now no longer exist, and more of stuff cribbed off StackOverflow & held together with string & bubble gum. While not yet calling Configuration Bankrupt's, I am going to try to see if I can restructure this technical debt.
 
 
-This Emacs configuration is written using the [[https://en.wikipedia.org/wiki/Literate_programming][Literate Programming]] (sort of) paradigm (well sort of) proposed by [[https://en.wikipedia.org/wiki/Donald_Knuth][Donald Knuth]] in 1984, and uses Hlissner's awesome [[https://github.com/doomemacs/doomemacs][Doom Emacs]] configuration framework.
+This Emacs configuration is written using the [[https://en.wikipedia.org/wiki/Literate_programming][Literate Programming]] (sort of) paradigm (well sort of) proposed by [[https://en.wikipedia.org/wiki/Donald_Knuth][Donald Knuth]] in 1984, and uses Hlissner's awesome [[https://github.com/doomemacs/doomemacs][Doom Emacs]] configuration framework. While I like Literate Programming, literate configuration can be a mixed bag. Literate Programming produces more prose then code. Discoverability & readability can be drowned out under the prose about the current thoughts, pros & cons, backstory, deciding thoughts, & moral pondering. While this verbosity[fn:4] aids documentation and understanding, its often at the cost of readability. As a compromise I'm going to version both to the verbose =config.org= file and all of the produced configuration files; this will allow us to =git blame= both the this file and the generated files.
-
-While I like Literate Programming, I kind of think that literate configuration is largely a mixed bag. Literate Programming produces often more words then code. For even medium size configurations discoverability & readability of what is happening can be bogged down in the weight of prose explaining the backstory, current thought, moral pondering, pros & cons, and deciding thoughts. This extra cruft potentially makes understanding more through, but at cost of readability & readability is king. As a compromise I'm going to version both to the verbose =config.org= file and all of the produced configuration files. As an example about that verbosity mentioned prior this entire paragraph could have been skipped.
 
 * Document Structure
-This section will be the what & how of things. There will no directly tangled code in this section.
-
 ** Doom Emacs
-This is built on top of Hlissner's awesome [[https://github.com/doomemacs/doomemacs][Doom Emacs]] configuration frameworks. Configuration is divided into 150 modules, & fair number of convenience functions. Rather than detailing stuff about I'll say to go read [[https://github.com/doomemacs/doomemacs/blob/master/docs/faq.org][FAQs]] & [[https://github.com/doomemacs/doomemacs/blob/master/docs/index.org][Index]].
+I'm utilizing Hlissner's [[https://github.com/doomemacs/doomemacs][Doom Emacs]] frameworks. Doom Emac's configuration is divided into 150 modules, & fair number of convenience functions. Rather than detailing stuff about I'll say to go read [[https://github.com/doomemacs/doomemacs/blob/master/docs/faq.org][FAQs]] & [[https://github.com/doomemacs/doomemacs/blob/master/docs/index.org][Index]].
-
-Configuration is located in the ~DOOMDIR~ directory. This is default value is located is the ~$HOME/.doom.d~ directory. Typically this directory contains:
-
-+ =init.el= :: Enabled Doom Modules
-+ =config.el= :: General Emacs configuration
-+ =package.el= :: Packages to fetch from MELPA, Github, etc.
-
-Additional configuration for scoped functionality will be named as =+name.el=.
 
+Configuration is located in the ~$DOOMDIR~ directory; this can be located either[fn:3]  at =~/.doom.d= or =$XDG_CONFIG_HOME/doom=.
 ** Tangle
 This org-mode document works by using [[https://orgmode.org/manual/Extracting-Source-Code.html][tangles]]. By default Doom's literate config mode adds any ~#+begin_src~ blocks into the =config.el= file[fn:1]. If you want to tangle to a specific file you pass in a file name.
 
-#+begin_src orgmode :tangle no
+#+begin_src org :tangle no
 #+begin_src emacs-lisp :tangle "example.el"
 #+end_src
 
 or to disable it tangling for a codeblock set the =:tangle= property in code block header to =no=.
 
-#+begin_src orgmode :tangle no
+#+begin_src org :tangle no
 #+begin_src orgmode :tangle no
 #+end_src
 
@@ -45,6 +34,7 @@ This document uses [[https://orgmode.org/manual/Noweb-Reference-Syntax.html][now
 #+END_SRC
 
 #+BEGIN_SRC emacs-lisp :noweb yes
+  <<initialization>>
   (reverse sentence)
 #+END_SRC
 #+end_example
@@ -60,23 +50,76 @@ will produce
 
 NOTE: unless you explicitly turn off the named code block will be tangled into =config.el=. Use the no tangle option if you want to disable this.
 
-* Doom Configuration
+** Files tree
-** Configuration
+There's a fair number of files located in ~$DOOMDIR~.  Some are configuration, some are additional tooling not use directly by emacs.
+
+#+begin_src bash :tangle no :exports result :results output verbatim
+tree $DOOMDIR -L 2
+#+end_src
+
+#+RESULTS:
+#+begin_example
+.
+├── +keybinds.el
+├── +orgmode.el
+├── config.el
+├── config.html
+├── config.org
+├── dist
+│   ├── bundle.js
+│   ├── code.css
+│   ├── custom.css
+│   ├── setup.org
+│   └── tufte.css
+├── init.el
+├── makefile
+├── packages.el
+└── snippets
+    └── org-mode
+
+4 directories, 13 files
+#+end_example
+
+*** Emacs Configuration Files
+Doom will automatically load the following files.
+
++ =init.el= :: Enabled Doom Modules
++ =package.el= :: Packages to fetch from MELPA, Github, etc.
++ =config.el= :: General Emacs configuration
+
+Any additional files should follow the pattern of =+name.el= and should be scoped to that individual purpose.
+
+This should be loaded by the =config.el= file by using the =load!= macro[fn:7] e.g.
+
+#+begin_src emacs-lisp :tangle no
+(load! "+name")
+#+end_src
+
+Currently this includes
+
+- =+orgmode.el= :: Additional configuration for Orgmode. Considering this is one of the primary modes I use emacs in there's a fair bit of configuration there.
+- =+keybinds.el= ::  A relatively new and not fully utilized file. The plan is to use this as a centralized location for all custom keybinds.
+
+*** Other files
+There are several other files here not directly used by emacs but are related to it.
+
+- =makefile= :: Install script using make[fn:6].
+- =dist/*= :: These are files used by the output of [[https://github.com/ox-tufte/ox-tufte][ox-tufte]].[fn:5]
+- =config.html= :: This org file exported from [[https://github.com/ox-tufte/ox-tufte][ox-tufte]]. This is not versioned.
+- =snippets/[major mode]/*= :: These are [[https://github.com/joaotavora/yasnippet][YASnippets]]. These are manage by this document. See [[*Snippets][Snippets]] for more.
+
+Everything else should be emacs configuration.
+**  Emacs file prefixing
 *** Lexical Bindings
 There [[https://nullprogram.com/blog/2016/12/22/][minor but non-zero start time benefits]] for using Lexical Bindings comments. All files created should start with
+
+#+name:lexical-binding
 #+BEGIN_SRC emacs-lisp
-;;; config.el -*- lexical-binding: t; -*-
+;;; -*- lexical-binding: t; -*-
-#+END_SRC
-
-replace =config.el= with the filename being loaded.
-
-**** =packages.el=
-Also go a head and add this to the =packages.el=
-#+BEGIN_SRC emacs-lisp :tangle "packages.el"
-;;; packages.el -*- lexical-binding: t; -*-
 #+END_SRC
 
 *** Warn user not to modify =*.el= files directly.
+As mentioned above, we are versioning the generated emacs lisp configuration. We shouldn't modified these files as they'll be clobbed anytime the org-tangle is run. Lets include a warning to this effect.
 
 #+name:modification-warning
 #+begin_src emacs-lisp
@@ -84,52 +127,53 @@ Also go a head and add this to the =packages.el=
 ;;; Any modifications here will be clobbered and versioned over. Seriously just don't.
 #+end_src
 
-*** Speedup =whichkey= response
+*** Applying to all files
-=whichkey= is slow to respond, lets make it a bit faster.
+We need to apply this to all of the following files.
-
+#+begin_src bash :tangle no :exports result :results output verbatim
-#+begin_src emacs-lisp
+find ~/.doom.d/* -iname '*.el' | sed "s/.*\///"
-(setq which-key-idle-delay 0.1)
 #+end_src
 
-*** Window Titlebar
+#+RESULTS:
-The titlebar display string will display =♢= if there exist unsaved buffer modifications & =♦= otherwise.
+: +keybinds.el
+: +orgmode.el
+: config.el
+: init.el
+: packages.el
 
-#+begin_src emacs-lisp
+=+keybinds.el=
-(setq doom-fallback-buffer-name "Doom"
+#+begin_src emacs-lisp :tangle "+keybinds.el" :noweb no-export :comments no
-      +doom-dashboard-name "Doom Dashboard")
+<<lexical-binding>>
+<<modification-warning>>
+#+END_SRC
 
-(setq frame-title-format
+=+orgmode.el=
-      '(""
+#+begin_src emacs-lisp :tangle "+orgmode.el" :noweb no-export :comments no
-        (:eval
+<<lexical-binding>>
-         (if (s-contains-p org-roam-directory (or buffer-file-name ""))
+<<modification-warning>>
-             (replace-regexp-in-string
+#+END_SRC
-              ".*/[0-9]*-?" "☰ "
-              (subst-char-in-string ?_ ?  buffer-file-name))
-           "%b"))
-        (:eval
-         (let ((project-name (projectile-project-name)))
-           (unless (string= "-" project-name)
-             (format (if (buffer-modified-p)  " ♢ %s" " ♦ %s") project-name))))))
-#+end_src
 
-*** Fonts
+=config.el=
-I use the [[https://www.nerdfonts.com/][nerdfont]]'s [[https://github.com/i-tu/Hasklig][Hasklig]] for my monospace font &  Huerta Tipografica's  [[https://www.huertatipografica.com/en/fonts/alegreya-ht-pro][ Alegreya]] serif font.
+#+begin_src emacs-lisp :tangle "config.el" :noweb no-export :comments no
+<<lexical-binding>>
+<<modification-warning>>
+#+END_SRC
 
-#+begin_src emacs-lisp
+=init.el=
-(setq doom-font (font-spec :family "Hasklig" :size 14 :height 1)
+#+begin_src emacs-lisp :tangle "init.el" :noweb no-export :comments no
-      doom-variable-pitch-font (font-spec :family "Alegreya" :height 1.3)
+<<lexical-binding>>
-      doom-big-font (font-spec :family "Hasklig" :size 18))
+<<modification-warning>>
-#+end_src
+#+END_SRC
 
-*** Tridactyl
+=packages.el=
-I am currently using Firefox with [[https://github.com/tridactyl/tridactyl][Tridactyl]].  The =editorcmd= creates a temporary file & opens it with the editor of choice.  The domain is included in the temporary file name. We can use this to set the syntax of the file in question. This likely just be markdown.
+#+begin_src emacs-lisp :tangle "packages.el" :noweb no-export :comments no
+<<lexical-binding>>
+<<modification-warning>>
+#+END_SRC
 
-#+begin_src emacs-lisp
-(add-to-list 'auto-mode-alist '("/\\(tmp\\|private/var\\)/.*/tmp_.*.greenfiling.com.*\\.txt" . markdown-mode))
-(add-to-list 'auto-mode-alist '("/\\(tmp\\|private/var\\)/.*/tmp_.*.github.com.*\\.txt" . markdown-mode))
-#+end_src
 
-** Doom Modules
+
+
+* Doom Modules
 The configuration is below is pulled from the template =init.example.el= provided by doom. This one is based off commit [[https://github.com/doomemacs/doomemacs/blob/e96624926d724aff98e862221422cd7124a99c19/templates/init.example.el][e966249]].
 
 #+name: init.el
@@ -192,7 +236,7 @@ The configuration is below is pulled from the template =init.example.el= provide
 
 The code of these can be found in the [[https://github.com/doomemacs/doomemacs/tree/master/modules][modeules directory]], the read me for each module will list any additional configuration options.
 
-*** Completion
+** Completion
 https://github.com/doomemacs/doomemacs/tree/master/modules/completion
 
 #+name:doom-completion
@@ -211,7 +255,7 @@ https://github.com/doomemacs/doomemacs/tree/master/modules/completion
 
 =+childframe= exists for both company & vertico, but looks a little weird with Vertico. We have for gone it for the time being.
 
-*** UI
+** UI
 https://github.com/doomemacs/doomemacs/tree/master/modules/ui
 
 #+name:doom-ui
@@ -243,7 +287,7 @@ workspaces        ; tab emulation, persistence & separate workspaces
 zen               ; distraction-free coding or writing
 #+end_src
 
-**** Fancy Welcome Image
+*** Fancy Welcome Image
 Rather than the boring ascii doom logo. Lets some the one off the box art. This is enabled by the =doom-dashboard= module.
 
 #+CAPTION:Doom Welcome Icon
@@ -252,7 +296,7 @@ Rather than the boring ascii doom logo. Lets some the one off the box art. This
 #+begin_src emacs-lisp
 (setq fancy-splash-image (concat doom-user-dir "./.resources/doom.png"))
 #+end_src
-*** Editor
+** Editor
 https://github.com/doomemacs/doomemacs/tree/master/modules/editor
 
 #+name:doom-editor
@@ -271,7 +315,7 @@ snippets          ; my elves. They type so I don't have to
 ;;word-wrap         ; soft wrapping with language-aware indent
 #+end_src
 
-*** Emacs
+** Emacs
 https://github.com/doomemacs/doomemacs/tree/master/modules/emacs
 #+name:doom-emacs
 #+begin_src emacs-lisp :tangle no
@@ -282,7 +326,7 @@ electric          ; smarter, keyword-based electric-indent
 vc                ; version-control and Emacs, sitting in a tree
 #+end_src
 
-*** Term
+** Term
 https://github.com/doomemacs/doomemacs/tree/master/modules/term
 
 #+name:doom-term
@@ -295,7 +339,7 @@ vterm             ; the best terminal emulation in Emacs
 
 Vterm is great. It does require some additional configuration to work properly. See [[https://github.com/doomemacs/doomemacs/tree/master/modules/term/vterm][relavant doc]] for more.
 
-*** Checker
+** Checker
 https://github.com/doomemacs/doomemacs/tree/master/modules/checker
 
 #+name:doom-checker
@@ -307,12 +351,12 @@ https://github.com/doomemacs/doomemacs/tree/master/modules/checker
 grammar           ; tasing grammar mistake every you make
 #+end_src
 
-**** Custom Dictionary
+*** Custom Dictionary
 #+begin_src emacs-lisp
 (setq ispell-dictionary "en"
       ispell-personal-dictionary "~/org/.ispell.en.pws")
 #+end_src
-*** Tools
+** Tools
 https://github.com/doomemacs/doomemacs/tree/master/modules/tools
 
 #+name:doom-tools
@@ -347,8 +391,7 @@ tree-sitter       ; syntax and parsing, sitting in a tree...
 
 NOTE: =:leader r= is currently being used by roam. See [[id:f9ffe9df-a417-45c4-8bf2-6ee655140648][Roam Keybinds]]. This conflicts with the =upload= module. If you wish to use this module in the future you will need to updated one of the keybinds to not conflict.
 
-
+***  Magit Forge Support
-****  Magit Forge Support
 For use with Github this requires the creation of a Github Token (see [[https://github.com/settings/tokens][here]]). This will need to be appended to your =~/.authinfo.gpg= file using the format below[fn:2].
 
 #+begin_src authinfo :tangle no
@@ -356,7 +399,7 @@ machine api.github.com login yourlogin^code-review password MYTOKENGOESHERE
 #+end_src
 
 For more on Forge see [[https://magit.vc/manual/forge.html][Magit's Forge documentation]].
-*** Language
+** Language
 https://github.com/doomemacs/doomemacs/tree/master/modules/lang
 
 #+name:doom-lang
@@ -448,7 +491,7 @@ markdown          ; writing docs for people to ignore
 ;;zig               ; C, but simpler
 #+end_src
 
-*** Emails
+** Emails
 https://github.com/doomemacs/doomemacs/tree/master/modules/email
 
 #+name:doom-email
@@ -458,7 +501,7 @@ https://github.com/doomemacs/doomemacs/tree/master/modules/email
 ;;(wanderlust +gmail)
 #+end_src
 
-*** App
+** App
 https://github.com/doomemacs/doomemacs/tree/master/modules/app
 
 #+name:doom-app
@@ -471,7 +514,7 @@ https://github.com/doomemacs/doomemacs/tree/master/modules/app
 ;;twitter           ; twitter client https://twitter.com/vnought
 #+end_src
 
-*** Config
+** Config
 https://github.com/doomemacs/doomemacs/tree/master/modules/config
 
 #+name:doom-config
@@ -480,6 +523,53 @@ literate
 (default +bindings +smartparens)
 #+end_src
 
+* Doom Configuration
+** Configuration
+*** Speedup =whichkey= response
+=whichkey= is slow to respond, lets make it a bit faster.
+
+#+begin_src emacs-lisp
+(setq which-key-idle-delay 0.1)
+#+end_src
+
+*** Window Titlebar
+The titlebar display string will display =♢= if there exist unsaved buffer modifications & =♦= otherwise.
+
+#+begin_src emacs-lisp
+(setq doom-fallback-buffer-name "Doom"
+      +doom-dashboard-name "Doom Dashboard")
+
+(setq frame-title-format
+      '(""
+        (:eval
+         (if (s-contains-p org-roam-directory (or buffer-file-name ""))
+             (replace-regexp-in-string
+              ".*/[0-9]*-?" "☰ "
+              (subst-char-in-string ?_ ?  buffer-file-name))
+           "%b"))
+        (:eval
+         (let ((project-name (projectile-project-name)))
+           (unless (string= "-" project-name)
+             (format (if (buffer-modified-p)  " ♢ %s" " ♦ %s") project-name))))))
+#+end_src
+
+*** Fonts
+I use the [[https://www.nerdfonts.com/][nerdfont]]'s [[https://github.com/i-tu/Hasklig][Hasklig]] for my monospace font &  Huerta Tipografica's  [[https://www.huertatipografica.com/en/fonts/alegreya-ht-pro][ Alegreya]] serif font.
+
+#+begin_src emacs-lisp
+(setq doom-font (font-spec :family "Hasklig" :size 14 :height 1)
+      doom-variable-pitch-font (font-spec :family "Alegreya" :height 1.3)
+      doom-big-font (font-spec :family "Hasklig" :size 18))
+#+end_src
+
+*** Tridactyl
+I am currently using Firefox with [[https://github.com/tridactyl/tridactyl][Tridactyl]].  The =editorcmd= creates a temporary file & opens it with the editor of choice.  The domain is included in the temporary file name. We can use this to set the syntax of the file in question. This likely just be markdown.
+
+#+begin_src emacs-lisp
+(add-to-list 'auto-mode-alist '("/\\(tmp\\|private/var\\)/.*/tmp_.*.greenfiling.com.*\\.txt" . markdown-mode))
+(add-to-list 'auto-mode-alist '("/\\(tmp\\|private/var\\)/.*/tmp_.*.github.com.*\\.txt" . markdown-mode))
+#+end_src
+
 ** Additional Keybinds
 Keybinds custom keybinds can be located at =$DOOMDIR/+keybinds.el=.
 
@@ -979,5 +1069,11 @@ A large amount of the details listed here have been lifted from:
 - https://www.gtrun.org/custom/config.htm
 
 * Footnotes
+
+[fn:7]Documentation [[https://github.com/doomemacs/doomemacs/blob/d38787edf48f4c08bdf7ea8b3b54fcbc268f13b5/docs/getting_started.org#additional-files][here]].
+[fn:6]Yes, I'm aware make is a terrible task runner.
+[fn:5] this is documented in [[*Export to Tufte][Export to Tufte]]
+[fn:4] for example this entire paragraph could have been skipped.
+[fn:3]See documentation [[https://github.com/doomemacs/doomemacs/blob/d38787edf48f4c08bdf7ea8b3b54fcbc268f13b5/docs/getting_started.org#configure][here]].
 [fn:2] See [[https://github.com/doomemacs/doomemacs/tree/master/modules/tools/magit#i-recently-updated-and-now-i-get-deferred-error--wrong-type-argument-sequencep-code-reviewauth-token-set-whenever-i-try-to-review][Doom Magit documentation.]]
 [fn:1] See [[https://github.com/doomemacs/doomemacs/tree/master/modules/config/literate#change-where-src-blocks-are-tangled-or-prevent-it-entirely][Doom FAQ on this for more.]]

emacs/init.el

@@ -1,3 +1,7 @@
+;;; -*- lexical-binding: t; -*-
+;;; This file is generated via tangles from the config.org file. Do not modify this file.
+;;; Any modifications here will be clobbered and versioned over. Seriously just don't.
+
 ;;; init.el -*- lexical-binding: t; -*-
 ;;; This file is generated via tangles from the config.org file. Do not modify this file.
 ;;; Any modifications here will be clobbered and versioned over. Seriously just don't.

emacs/packages.el

@@ -1,4 +1,6 @@
-;;; packages.el -*- lexical-binding: t; -*-
+;;; -*- lexical-binding: t; -*-
+;;; This file is generated via tangles from the config.org file. Do not modify this file.
+;;; Any modifications here will be clobbered and versioned over. Seriously just don't.
 
 (package! ob-mermaid)