Commit 9b755f6c authored by Neil Mather's avatar Neil Mather
Browse files

Literate config

parent 247263de
......@@ -19,7 +19,7 @@
- I'd like to the issue on [[file:../flock.org][Flock]] where reloading a page with stacked notes sometimes gives a 'page not redirecting correctly' error.
- Also some links from subfolders don't work.
- Definitely enjoyed the [[file:../literate-config.org][Literate config]] approach for my spacemacs config. It probably makes sense for config - stuff that is cobbled together over time from various sources. Was thinking about if it would be worth trying it with other code - i.e. [[file:../literate-programming.org][Literate programming]]. It could be problematic on shared projects though, presumably - you'd be forcing everyone in to doing it that way, otherwise your literate file and the code would get out of sync.
- Definitely enjoyed the [[file:../literate-configuration.org][Literate config]] approach for my spacemacs config. It probably makes sense for config - stuff that is cobbled together over time from various sources. Was thinking about if it would be worth trying it with other code - i.e. [[file:../literate-programming.org][Literate programming]]. It could be problematic on shared projects though, presumably - you'd be forcing everyone in to doing it that way, otherwise your literate file and the code would get out of sync.
- [[file:../adding-timestamps-to-org-roam-notes.org][Adding timestamps to org-roam notes]].
......
#+title: Literate config
[[file:literate-programming.org][Literate programming]].
#+title: Literate configuration
The application of [[file:literate-programming.org][Literate Programming]] to configuration files.
The book [[https://leanpub.com/lit-config/read][Literate Configuration]] is great on this, and gives a good overview of why you might do it and why literatre programming works pretty well for config files.
#+TITLE: My Spacemacs User Config
#+property: header-args:elisp :tangle ~/.spacemacs.d/user-config.el :comments org
#+LAST_MODIFIED: [2020-11-26 Thu 21:51]
#+LAST_MODIFIED: [2020-11-27 Fri 16:21]
* Preamble
This is the [[file:literate-config.org][literate]] source for my [[file:spacemacs.org][spacemacs]] user config. I use [[file:org-babel.org][org-babel]] to tangle it together into the actual config file.
This is the [[file:literate-configuration.org][literate]] source for my [[file:spacemacs.org][spacemacs]] user config. I use [[file:org-babel.org][org-babel]] to tangle it together into the actual config file.
#+begin_src elisp :exports none
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
......
#+title: Setting up a spacemacs literate config file
I spent a bit of time switching my spacemacs config in to a [[file:literate-configuration.org][Literate configuration]] style.
* Why?
I use [[file:spacemacs.org][spacemacs]] *a lot*. For coding, for work, for organisation, for org-roam. It's central to to most of my day-to-day activities. I've been using for maybe 4 years now, and have built up quite a mess of a configuration file with various tweaks over the years.
I use [[file:spacemacs.org][spacemacs]] *a lot*. For coding, for writing, for work, for organisation, for my personal knowledge management. It's central to to most of my day-to-day activities on my computer. I've been using for maybe 4 years now, and have built up quite a mess of a configuration file with various tweaks over the years.
Given how much I use it, it seems sensible to give a bit of TLC to this configuration. I've tried to comment it as I've tweaked it, but it still has gotten messy. And there's lots of longer form notes that get a bit lost as I don't put them in short comments.
Given how much I use it, it seems sensible to give a bit of TLC to this configuration. I've tried to comment it as I've tweaked it, but it still has gotten messy. I've learned and copied a lot from other people's configs, so endeavouring to make my own readable to others seems like a good thing to do.
I'm also just keen to try out org-babel for some literate coding, and this is an easy way in to doing that.
* What I did
Here's what I've done to get there.
Here's what I've done to get started on this.
** File reorganisation
First off, I put my existing .spacemacs file into a folder structure where you can split it up into multiple files.
#+begin_src shell
mkdir ~/.spacemacs.d
cp ~/.spacemacs .spacemacs.d/init.el
#+end_src
Try that, make sure things still work.
In classic refactoring fashion - just do this simple thing, and make sure that things still work.
** Extract out user-config into own file
- move everything in user-config function in to .spacemacs.d/user-config.el
- source that from init.el
OK, after that, the next refactoring was to move move everything in the user-config function out in to it's own file, .spacemacs.d/user-config.el.
When its in its own file, you can source that from init.el like so:
#+begin_src elisp
(defun dotspacemacs/user-config ()
......@@ -33,13 +38,30 @@ Try that, make sure things still work.
(load-file uc)))
#+end_src
(above source came from here: [[https://www.reddit.com/r/emacs/comments/7ntc6p/spacemacs_configuration_in_a_structured_orgmode/][Spacemacs configuration in a structured org-mode file : emacs]])
Again, check that everything still works fine afterwards.
* Move config into an org file and set up tangling on it
The section on [[https://leanpub.com/lit-config/read#leanpub-auto-converting-your-existing-config-files][Converting your existing config files]] in Literature Configuration was really helpful for this. Basically allowing you to move things piece by piece, and also a few handy tips and tricks such as ~org-babel-demarcate-block~ and file level properties.
The section on [[https://leanpub.com/lit-config/read#leanpub-auto-converting-your-existing-config-files][Converting your existing config files]] in Literature Configuration was really helpful for this. It recommends a great path for moving things incrementally to the literate configuration. Essentially you start off with one huge source block, and gradually split that up in to smaller blocks with ~org-babel-demarcate-block~.
I did that, putting each new source block in to a logical org heading, and adding a bit of description and narrative around them. Each time I split out a new bit, I ran ~org-babel-tangle~ to check things were still working.
I have the following config properties at the top of the file:
#+begin_src org :exports code
#+property: header-args:elisp :tangle ~/.spacemacs.d/user-config.el :comments org
#+end_src
which says for all the elisp source blocks in this file, combine them together in to user-config.el when I tangle the file. And also include my narrative as comments.
So I moved my user-config in to [[file:my-spacemacs-user-config.org][My Spacemacs User Config]] here in my wiki, and set it up so that I can tangle that to ~.spacemacs/user-config.el~. I started off with one huge source block, but that gradually split that up with ~org-babel-demarcate-block~, putting each section in to an org heading.
So my user-config is now *literally* all in [[file:my-spacemacs-user-config.org][My Spacemacs User Config]] here in my wiki. As in, that is the file that I use to generate my ~.spacemacs/user-config.el~ that spacemacs runs. (The source is [[https://gitlab.com/ngm/commonplace/-/blob/master/my-spacemacs-user-config.org][here]].)
I like it, and think it works pretty well for config files. I'm going to try it on my org-roam config next.
* Resources
- [[https://leanpub.com/lit-config/read][Read Literate Configuration | Leanpub]]
- [[http://www.howardism.org/Technical/Emacs/literate-programming-tutorial.html][Introduction to Literate Programming]]
- [[https://www.reddit.com/r/emacs/comments/7ntc6p/spacemacs_configuration_in_a_structured_orgmode/][Spacemacs configuration in a structured org-mode file : emacs]]
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment