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

docs: edit prose

Browse source
This commit is contained in:
Kiana Sheibani 2024-07-22 13:45:41 -04:00
parent e8e6d0e8f8
commit 17bd8557db
Signed by: toki
GPG key ID: 6CB106C25E86A9F7
1 changed files with 12 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
config.org
View file

@ -67,22 +67,22 @@ 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 could be done by maintaining 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 codebase, storing the code inside source blocks in the document. This would provide the space for much more thorough commentary than regular comments, but also prevent the file from being interpreted as a program, which is the important part! 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 done 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, which involves two processing systems:
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, which involves two parallel processes:
1. /Tangling/, converting the file into raw source code. Tangling must be performed before the code is used; in Org, code is tangled into a new file, and this can be done to generate many source files at once.
1. /Tangling/, converting the file into raw source code. Tangling must be performed before the code is used; in Org, code is tangled into a new file, and this can be done to generate many source files from a single Org file.
2. /Weaving/, formatting the file into a human-readable document. Org conceptually divides this further into "exporting" and "publishing," where the latter is intended specifically for converting into web-ready HTML.
You are currently reading the published version of this literate program[fn:1]. If you were to download this repository and use it as your config, Emacs would be running the tangled version. These versions are generated in separate processes, but both are ultimately derived from the content and metadata inside of the Org file.
[fn:1] Unless you're reading the raw file on Github, in which case you are probably already decently familiar with =org-mode= to be able to read its markup.
**** From Code into Comprehension
**** Code and Comprehension
The simultaneous handling of documentation and code inherent to literate programming is reminiscent of documentation generation (doc comments) in traditional programming. Both systems involve superimposing code and documentation into one file, but the literate style takes the concept one step further; the document isn't embedded in the code, the code is embedded in the document.
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 literate macros and tangling configuration, features intended to break one's code out of the restrictions of standard programming.
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 literate macros, features intended to break one's code out of the restrictions of standard programming.
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 into categories.
@ -2172,7 +2172,7 @@ Doom's command to create a new snippet, ~+snippets/new~, defines a template insi
Doom's =file-templates= module extends =yasnippet= to provide a nice file template system. The idea is simple: the variable ~+file-templates-alist~ maps file predicates to snippets. If a file that matches a predicate is created, the corresponding snippet is automatically expanded inside of it.
This system works well for the most part, but there's a serious issue with its UI: the function that registers file templates, ~set-file-templates!~, takes a plist to configure the template. If this list is empty, an existing template is removed instead. This is not only unintuitive, but it prevents you from having an empty property list, which is often necessary! We'll advise the function to remove this issue with a =:remove= key, as well as to have templates appended to the alist instead of prepended to→
This system works well for the most part, but there's a serious issue with its UI: the function that registers file templates, ~set-file-templates!~, takes a plist to configure the template. If this list is empty, an existing template is removed instead. This is not only unintuitive, but it prevents you from having an empty property list, which is often necessary! We'll advise the function to remove this issue with a =:remove= key, as well as to have templates appended to the alist instead of prepended to make the order of templates more clear.
#+begin_src emacs-lisp
(defadvice! ~/file-templates-set (pred plist)
@ -2209,6 +2209,7 @@ Doom Emacs sets up spell-checking with ~ispell~ (Emacs-internal tool) and =aspel
#+end_src
We also need to generate a plain-text dictionary for some ~ispell~ functionality, which is annoying, but I haven't figured out a way around it. I could use my automated nix-build system for this, but I want to have access to my =aspell= config file, so it's easier to just put it in the usual location.
Now that we have our new-and-improved template registry system, we can add new file templates as we please.
#+begin_src emacs-lisp
(defvar ~/plaintext-dict (expand-file-name "ispell/dict.plain" doom-data-dir)
@ -2696,7 +2697,7 @@ While this is a complex problem, the solution is actually rather simple: just re
"<tab>" nil)
#+end_src
This also means we don't need ~org-cycle~ to emulate indentation, which is nice. Unfortunately, this breaks something else: ~org-cycle~ not only handles visibility cycling, but also navigating inside tables. This means that we need a little extra binding configuration so that we can make this properly work:
This also means we don't need ~org-cycle~ to emulate indentation, which is nice. Unfortunately, this breaks something else: ~org-cycle~ not only handles visibility cycling, but also navigating inside tables. If ~org-cycle~ isn't being called when in insert mode, then we can't use =TAB= to move fields. This means that we need a little extra binding configuration:
#+begin_src emacs-lisp
(let ((item
@ -3618,7 +3619,6 @@ The Org agenda is a very nice feature, but by default it doesn't really provide
(setq org-super-agenda-header-map nil))
#+end_src
The ~org-agenda~ dispatcher is occasionally useful, but most of the time when I want to open my agenda, it's to see my "preferred" view.
By customizing ~org-super-agenda-groups~ via a let-binding in my custom agenda view, I can set up a sophisticated multi-category agenda system.
#+begin_src emacs-lisp
@ -3722,7 +3722,7 @@ Let's start with some configuration. I use [[https://www.zotero.org/][Zotero]] t
*** Citation Settings
I primarily use the CSL export processor to create MLA-style citation, so let's configure that to make its citations more standard.
I primarily use the CSL export processor to create MLA-style citations, so let's configure that to make its citations more standard.
#+begin_src emacs-lisp
(after! org
@ -3946,9 +3946,9 @@ Since I've started using [[https://github.com/elkowar/eww/tree/master?tab=readme
This section is for code with little or no associated documentation. This could be because the code is:
1. Temporary
2. Unimportant
3. Self-explanatory
4. Just not really worth the time it takes to write these explanations
2. Self-explanatory
3. Hard to categorize
4. Just not really worth the time it takes to write commentary
** Org