toki/doom-config
1
0
Fork 0
Code Issues Pull requests Activity

docs: prose edits

Browse source
This commit is contained in:
Kiana Sheibani 2025-10-22 13:37:59 -04:00
parent 102b0fb19c
commit 925a937649
Signed by: toki
GPG key ID: 6CB106C25E86A9F7
1 changed files with 8 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

18
config.org
View file

@ -67,7 +67,7 @@ The second block above was automatically generated by =org-mode=.
**** Tangle, Weave, Export, Publish
Since Org's ability to execute code and process its output is so robust, it's only natural that one might consider using Org to annotate a codebase, storing the code inside source blocks in the document. This would provide the space for much more thorough commentary than regular comments; however, it would prevent the file from being readable as a program, which is the entire point! You could maintain both the Org file and the actual source files separately, but that would require manually duplicating edits in both files, which is not ideal.
Since Org's ability to execute code and process its output is so robust, it's only natural that one might consider using Org to annotate a code-base, storing the code inside source blocks in the document. This would provide the space for much more thorough commentary than regular comments; however, it would prevent the file from being readable as a program, which is the entire point! You could maintain both the Org file and the actual source files separately, but that would require manually duplicating edits in both files, which is not ideal.
The solution is [[https://en.wikipedia.org/wiki/Literate_programming][literate programming]], the practice of embedding usable code into a markup document. Literate programming can be handled in a few different ways. A handful of languages support directly processing these markup documents, such as Haskell and Julia; however, the way Org implements it is closer to the traditional method, in which a singular file is processed in two different ways:
@ -84,7 +84,7 @@ The simultaneous handling of documentation and code inherent to literate program
Instead of documentation having to be bent around the restrictions of source code, the source code can be written and organized with all the freedoms of prose. If written well, the literate program can be structured in a manner closer to how the human mind understands code, rather than how a computer processes it. This is assisted by features such as macros, which provide further flexibility in structure.
It's not the right tool for every codebase, but proper use of literate programming can make a program much, much easier to comprehend and maintain. This is especially true for configuration languages like Emacs Lisp, where much of the code is conceptually disconnected and can easily be split apart.
It's not the right tool for every code-base, but proper use of literate programming can make a program much, much easier to comprehend and maintain. This is especially true for configuration languages like Emacs Lisp, where much of the code is conceptually disconnected and can easily be split apart.
** Current Issues
@ -808,7 +808,7 @@ The package allows you to define /patches/ which modify the definitions of funct
Some packages in this config such as =dirvish=, =org-roam=, etc. require certain tools to be in the environment. On a Nix-based system, there are a few different ways to handle this:
1. Put that tool in the actual environment, e.g. in a profile. This makes sense for simple things (=ripgrep=, =sqlite=, etc) but for more opinionated things like a specific version of Python it becomes less desirable.
1. Put that tool in the actual environment, e.g. in a profile. This makes sense for simple things (=ripgrep=, =sqlite=, etc) but for more opinionated things like a specific version of a compiler it becomes less desirable.
2. Build the tool and put a symlink to the output somewhere, e.g. in the HOME directory. This avoids polluting the environment, but you still have to deal with an unwieldy symlink that breaks Emacs if you accidentally delete it.
This was my approach before coming up with the third option:
3. Build the tool and point Emacs directly to the store path. This is the most automatic solution, but requires the most complex Emacs configuration.
@ -928,7 +928,7 @@ I'm a big fan of the Vertico ecosystem, as it's lightweight and easy to use. Let
The two most common syntax checking engines seem to be =flymake= and =flycheck=. =flymake= is built in to Emacs, is generally faster and currently has better support in the ecosystem, so let's use that one.
We'll also enable a dedicated spell checking module using ~aspell~, as that seems to be the recommended option.
In the past I used Doom Emacs's ~spell~ checker as well, but I eventually switched to a different system for spell-checking.
#+name: doom-checkers
#+begin_src emacs-lisp
@ -1294,7 +1294,7 @@ If PARENTS is non-nil, the parents of the specified directory will also be creat
*** Prefer Vertical Split
Emacs has a sophisticated system for controlling how windows and buffers are arranged on the screen, called ~display-buffer~. This works out of the box for almost every case I've thrown at it, except for one issue: it prefers horizontal splitting of windows to vertical splitting, despite the fact that the latter is far better in most cases.
Emacs has a sophisticated system for controlling how windows and buffers are arranged on the screen, called ~display-buffer~. This works out of the box for almost every case I've thrown at it, except for one issue: it prefers horizontal splitting of windows to vertical splitting (side-by-side), despite the fact that the latter is far better in most circumstances.
#+begin_src emacs-lisp
(defpatch! nil
@ -1392,7 +1392,7 @@ If you're going to be staring at your screen for hours a day, you might as well
** Theme
My favorite color theme has always been Tokyo Night. I use it literally everywhere I can, and Emacs is no exception.
My favorite color theme has always been [[https://marketplace.visualstudio.com/items?itemName=enkia.tokyo-night][Tokyo Night]]. I use it literally everywhere I can, and Emacs is no exception.
#+begin_src emacs-lisp
(setq doom-theme 'doom-tokyo-night)
@ -2416,7 +2416,6 @@ Emacs comes with a few standard commands for selecting different windows. These
There's just one wrinkle: Doom Emacs's popup management system. Popups are treated as separate from "real" windows, usually displayed on the edge of the frame and without a modeline. =winum= has no knowledge of popup windows and assigns them numbers exactly the same as any other window. This can get really confusing, since windows get renumbered every time a new popup appears.
To solve this issue, I've written my own fork of =winum=:
#+begin_src emacs-lisp :tangle packages.el
@ -3605,7 +3604,6 @@ Since Org-roam is currently my primary method of using Org, I only use its templ
I want there to only be one capture template when I'm making new links, so that I don't get distracted by a prompt. However, when I'm explicitly telling Roam to use node capture, it would be a shame if there was only one option. To fix this, I can split my capture templates into three contexts: a default template for when not explicitly capturing, a list of templates for capturing on a node that already exists, and the regular list for when the node is new.
#+begin_src emacs-lisp
(defvar org-roam-capture-default-template nil
"The default capture template to use when not explicitly capturing.")
@ -3880,7 +3878,7 @@ Let's start with some configuration. I use [[https://www.zotero.org/][Zotero]] t
(setq org-cite-csl-styles-dir "~/Zotero/styles"
;; MLA style by default
org-cite-csl--fallback-style-file
"/home/kiana/Zotero/styles/modern-language-association.csl"
(expand-file-name "modern-language-association.csl" org-cite-csl-styles-dir)
org-cite-global-bibliography
(list (expand-file-name "library.json" org-directory))
citar-bibliography org-cite-global-bibliography))
@ -4082,7 +4080,7 @@ it defaults to `project-current'."
**** Window Numbering
If a side session is open, we'll configure =winum= to give it the index ~(popup . 0)~, i.e. the 0th popup window. It's not actually a popup, since the popup system's window management clashes with =dirvish='s, but it's convenient to treat it as one.
If a side session is open, we'll configure =winum= to give it the index ~(popup\nbsp{}.\nbsp{}0)~, i.e. the 0th popup window. It's not actually a popup, since the popup system's window management clashes with =dirvish='s, but it's convenient to treat it as one.
#+begin_src emacs-lisp
(after! (winum dirvish-side)