Emacs org-mode
Welcome to the Emacs org-mode category.
You can subscribe to this category only via RSS!
I am working on restoring some of my related posts from my old blog, so keep checking here for new content.
-
Prot has a related, interesting video about expanding abbrevs with non-word-like characters, which I already use. The problem here is that there’s nothing “word-like” in —. We can work with something like “!word” or “word!” because the mechanism that catches abbrevs will recognize a word-like character before or after the “!” (using regex, as explained in the post) and trigger it, but in the case we have above, there’s nothing that looks like a word to trigger it at all, so it does not work. ↩︎
-
I realize that most of you read this via RSS, which might translate these tags as code anyway, making the entire point moot… if you want to see what I mean, you might have to actually use your browser and visit my page as is, just this once. ↩︎
- Emacs keyboard shortcuts and file paths should be placed in
verbatim(between = and =)1 - Code (as part of an explanation) should be placed in
code(betweenand ) - A separate temporary buffer, without the
#+begin_src…#+end_src, which we can evaluate any time, without worrying about being at the end of an expression (parentheses) and use C-x C-e3. - Safety net: as long as we don’t close it with another C-c ‘, it doesn’t save the code, and we can run it in that separate buffer to see what it does.
- To save a location: C-x r SPC, then a number or a letter to name the register. So C-x r SPC and then 1 will save a register called “1” in the position the marker is on.
- To jump to a saved location in a register: C-x r j, then the number/letter we previously selected. So in this example, C-x r j and then 1 will take us back to the location we saved as “1”.
- To save a region in a register: First, highlight (select) a region in Emacs. Then C-x r s, then a number or a letter to name the register. So selecting this sentence, then C-x r s and then 1 will save the sentence in register 1.4
- To insert a saved region: C-x r i, then the number/letter we previously selected.
- To view saved registers: M-x
view-register, which allows you to select one by number. A good replacement for C-x r j if you need a visual reminder like I do.
Em Dashes in org-mode and the Nuances of Abbrev
Since I confessed my enjoyment of em dash in my writing last week, I started using them more freely. On a Mac, it’s Option Shift Hyphen, as Sasha would tell you. In Linux, it’s a bit more involved: Ctrl Shift U to bring up a search for Unicode number reference, and then the number for em dash: 2014.
This is all good and well, but what about Emacs, where I write most of my text?
Emacs comes with abbrev-mode, a powerful text-expanding option that automatically converts something like “om” to “org-mode”, or even “fox” to “The quick brown fox jumps over the lazy dog” if I wanted to. But the em dash is a bit more tricky. I could, if I wanted, create an abbreviation like “em” to simply expand to “â”. But this doesn’t make much sense.
When converting org-mode to markdown (as I do when I post something), the built-in solution for Emacs’ markdown exporter is to convert --- (three dashes) to â, em dash â but this presents two annoyances. First, the built-in exporter would convert those to their character reference, as we just saw: ߞ. I explained this more in-depth previously. Second, even after I fixed this issue by using pandoc, I still see --- in org-mode, not â. This looks like the kind of thing abbrev-mode was made for, right?
But it’s a bit more complicated. abbrev-mode triggers only when you type a space after a letter. So, “em” to â would work, but - to â would not, because a dash is not part of a word1.
The solution was simpler than I thought: expand-abbrev, which “Expands the abbrev before point, if there is an abbrev there. Effective when explicitly called even when ‘abbrev-mode’ is nil.” In other words, it calls expand-abbrev without needing to trigger it the usual way. We simply call the abbrev replacement directly.
Now whenever I want an em dash, I type --- first, and then I make sure the marker is right after the last dash, and call expand-abbrev, which in my config is tied to C-x ‘. I then get an em dash in Emacs, and the exporter in Emacs (or pandoc, in my case) leaves it alone.
Style & Emacs Config: A Semantic HTML Reckoning
For years, I’ve been using verbatim emphasis in org-mode to mark files and keyboard strokes, while reserving code emphasis to show function names, variables, and other elements of code.
With the reintroduction of <kbd></kbd> tags to the blog yesterday1, I wanted these tags to follow the same logic derived from my usage in org-mode: if I used verbatim in org-mode to indicate keystrokes and filenames, then I should use <kbd></kbd> tags on the blog to indicate the same thing. I explained in a footnote in the post: “The reason I have it different here is because I often talk about files in my posts without referring to code.” That might have been my preference, but it was wrong. We’ll get back to it in a minute.
I wanted to get my markdown-exported posts to preserve the verbatim emphasis from org-mode. But Markdown doesn’t distinguish between verbatim and code emphasis in org-mode â it treats both as ``, or <code></code> tags in HTML. So I started looking for a way to fix this.
The abridged version (the research took over an hour): I ended up with a wrapper function that would add Markdown raw code injection specifically for that code (I’m still working on it) to work with Pandoc. Why Pandoc and not Emacs’s built-in Markdown exporter? Because Emacs’s built-in exporter outputs certain characters, like my now beloved em-dash again, as character reference numbers, which results in a character reference (â specifically) instead of an em-dash. Why’s that? Look, have you eaten breakfast today? Because I haven’t. Let me just tell you, these rabbits dig deep holes.
So now, after I had a working way (more or less) to produce my newly introduced <kbd></kbd> tags, I wanted to start using them for filenames. But I was bothered by the fact that while I can do whatever the hell I want this is not considered standard. And when I say “bothered,” I mean this is the thought I woke up to at around 05:40 this morning, which is what you get from a delirious dork Emacs brain like mine.
I knew HTML has standards, but I didn’t connect the logic behind it to semantic HTML â not until I browsed on my phone, in my bed, for another half an hour of impulsive research. Turns out, this is something that some folks take very seriously. And according to these folks, filenames and paths do not and should not have a dedicated HTML tag (surely not <kbd></kbd>, which is for keystrokes only â actually, it’s for “textual user input” which can include voice, for example). Authority has it that I should be indicating filenames using the <code></code> tags (and code emphasis in org-mode), and there’s a good reason for that. Just take my word for it for now (breakfast, remember?)
Reading through their tomb of standards, I realized I need to correct my headings on the blog too (I jump directly to <h3></h3> tags instead of going by order, because the CSS for these tags looks better â in other words, I’ve been lazy by not fixing this), among potentially many other things. There are over a hundred semantic tags in HTML, and there’s a reason for each one.
Damn those rabbits.
Emacs Config Gems - Part 2
You know how I said last time Part 1 was just the introduction? I lied.
My emacs-settings.org file includes an introduction that covers what I already went over and more. I thought I’d skip it, but as I looked through the notes I left to myself â various guidelines, warnings, and tips â I realized that this is exactly the kind of stuff I should share.
Style
As I was writing this, I fell into a rabbit hole (of course) and made a couple of additional changes.
Style and style guides are important to me. In college, as an editor, I used the AP Stylebook as a bible almost, along with the Chicago Manual of Style for academic papers. When I worked as a technical writer, it was Microsoft’s stylebook I checked constantly â and some of it stuck (don’t say “click”; say “select”, don’t say “sign in”; say “log in,” etc.) The main point is to stick to a style and keep using it â which one matters less.
Here are the notes:
Code blocks: use structure templates (C-c C-,) and choose emacs-lisp from the list (this is defined below). It should be in lower case: #+begin_src emacs-lisp and #+end_src.
When explaining code: the explanation follows the code immediately (no space). Use a space after the code (new line) for the next item:
explanation for item 1
#+begin_src emacs-lisp
code for item 1
#+end_src
explanation for item 2
#+begin_src emacs-lisp
code for item 2
#+end_src
Navigation Tips
My settings file is long and requires that I jump around to different sections. As I was working on revamping it, I’ve learned quite a few useful “tricks” that I started sharing in earlier posts. These are always good to know, not just in our setting file.
Jump Back With the Mark Ring
While registers (I have a section about them below) are a nice org-mode feature I keep forgetting about, they’re a bit of an in-between too much or too little for most cases in this file. For quickly getting around, we should use the mark ring:
Use C-u C-SPC (built on set-mark-command) to jump back to where our marker was before, which is usually where we ended scrolling or moving to see something. Keep pressing to keep going back â it remembers all the positions we landed on. By default, it remembers the last 16 positions.
Editing Code Blocks
Edit code blocks with C-c ‘ instead of just working with the text inside the org buffer directly2
Don’t edit the text in a code block (#+begin_src… #+end_src) directly. While it works, we’re missing out on the power of org-edit-special, and this is one powerful org-mode feature. Here are some of the highlights relevant to me, in bold:
*When at a table, call the formula editor with 'org-table-edit-formulas'.*
When at table.el table, edit it in dedicated buffer.
When in a source code block, call 'org-edit-src-code'; with prefix
argument, switch to session buffer.
When in an example block, call 'org-edit-src-code'.
*When in an inline code block, call 'org-edit-inline-src-code'.* **(this is what we're doing here!)**
When in a fixed-width region, call 'org-edit-fixed-width-region'.
When in an export block, call 'org-edit-export-block'.
When in a comment block, call 'org-edit-comment-block'.
When in a LaTeX environment, call 'org-edit-latex-environment'.
When at an INCLUDE, SETUPFILE or BIBLIOGRAPHY keyword, visit the included file.
*When at a footnote reference, call 'org-edit-footnote-reference'.*
When at a planning line call, 'org-deadline' and/or 'org-schedule'.
When at an active timestamp, call 'org-timestamp'.
What it gives us when we work with the settings here:
Also, nice bonus: it highlights the code we’re in with a separate color, and it will keep highlighting it as long as org-edit-special is open. Need a coffee refill? No problem, you know exactly where you left off.
Links
In my config, I started using links more often instead of setting registers (as I noted earlier, registers are too much for moving around, but too little as permanent location savers). I stole the thunder from this section in this post, but it deserves its own post anyway. org-mode internal links are very powerful, and I don’t think the manual explains them well enough (examples would be good), so go check it out.
Registers
Registers can save a location in a file to be recalled later from anywhere else in Emacs, or, to save a chunk of code to be pasted (yanked) later.
It’s a good idea to keep numbers for positions and letters for text so we don’t get them confused and overwrite our registers.
Footnotes
1 Most Emacs users, I believe, use code for file paths. The reason I have it different here is because I often talk about files in my posts without referring to code, and I will now make use of the <kbd></kbd> tags as well, which I forgot about. This is good for clarity, especially when we talk about Emacs, since Emacs and keyboard shortcuts are mentioned together all the time.
2 Those of you who code and write functions on Emacs regularly would probably find this “trick” trivial. However, as a person who does not have this background, I’ve been editing my code blocks directly in org for years â I had no idea org-edit-special exists. I’m sure some folks out there are in the same boat.
3 Which is, as I explained in my previous footnote, exactly what I’ve been doing for years. It works, but it can lead to mistakes, and it’s not as safe (you’re changing your settings, so if something goes wrong, Emacs’ startup will stop at the error).
4 In a usual discovery manner, I found out that C-x r + appends text to the register. So, if you were to select this footer here from the word “In” to the dot after “register”, you could then go to the word “So” and mark again to the word “footer” 7 words later, hit C-x r +, and then when you ready to yank (paste), hit C-x r i and both sections will be yanked as one. Actually, you could forgo C-x r i altogether and use C-x r + from the start, because if you append to an empty register, it will just append that first chunk.
Emacs Config Gems - Part 1
I’ve been working on my Emacs config for three weeks now, coming this weekend. It’s one of the deepest and most fun rabbit holes I’ve been exploring. As I stumble upon new ways to do things, I dig deeper, learn more, and keep tweaking my config, which makes this rabbit lair even bigger.
Eventually I realized that if I wait until I’m done to upload the config file, it will never happen: by the time I’m done, I will accumulate enough fixes and additional tricks and tweaks to warrant a whole new file.
The conclusion is what I should have done from the beginning: apply changes in chunks and explain what I’m doing and why as these happen.
I’m starting with changes to my .emacs1 file on my mac2, before we’re even touching the “good stuff” in my main emacs-settings.org file. Why? Because Emacs was built with Linux in mind, and we need to make some important adjustments to how Emacs works on a Mac before we use it. As you will see, I’m using this conceptually too: while some of the configurations in the .emacs file (the “init” file) could technically be placed in the big emacs-settings.org file, I still place them in what I consider Emacs’ “booting” process.
My .emacs file contains only these four code blocks, which are separated with spaces for visual convenience:
(when (memq window-system '(mac ns x))
(exec-path-from-shell-initialize))
(setq insert-directory-program "gls" dired-use-ls-dired t)
(setq custom-file (expand-file-name "emacs_custom.el" user-emacs-directory))
(load custom-file 'noerror)
(org-babel-load-file
"/Users/user/Sync/Public/emacs_settings/emacs_settings.org")
exec-path-from-shell-initialize
(when (memq window-system '(mac ns x))
(exec-path-from-shell-initialize))
This tells Emacs that if its windowing system is macOS-related (ns or x; there’s also the old mac version of Emacs that is not being used today â the Homebrew emacs-plus one we are using here is ns, which can be checked with M-x emacs-version), it should run exec-path-from-shell-initialize.
This function copies the PATH from the shell, as if we were using a terminal program. By design, macOS GUI applications (those that live in the user’s Applications folder and have an .app extension) are not exposed to this PATH because they’re launched by a different process altogether (launchd)3. But Emacs needs this PATH, as many of its core components integrate with the OS as a terminal application, which is what it is, at its core.
In fact, this is why we need this condition in a file that resides on a Mac, and why this condition is triggered by the windowing system, and not the OS itself (every other condition in our config would be written as eq system-type 'darwin or similar). If we run Emacs in terminal, the program already has access to PATH, and this execution is not needed.
Use gls in Dired
(setq insert-directory-program "gls" dired-use-ls-dired t)
This doesn’t have to live in our .emacs file, as it can live as part of our Dired options in emacs-settings.org, which will come later. However, this is a macOS-only thing, and since we need to get gls from Homebrew, it’s one of those things to prepare before we start Emacs for the first time. After all, we will probably use Dired right away after install, and we want to make sure it’s ready.
gls, GNU’s ls command, is bundled with other utilities inside coreutils, so we install it with brew install coreutils. Then the above command makes sense â we’re telling Emacs to use this flavor of this ls command instead of the one that comes with macOS, which is lighter and doesn’t have what we’re used to seeing in Emacs Dired (at least, not for me). As it turns out, there are other well-known utilities in this package, such as rm and mkdir, but we don’t use them, so it’s really just for gls.
Changing Emacs’ custom default file to emacs_custom.el
(setq custom-file (expand-file-name "emacs_custom.el" user-emacs-directory))
(load custom-file 'noerror)
This is something I discovered while working on my .emacs file. It was cluttered with comments and configurations from Emacs’s custom, Emacs’ settings wizard. This is because by default, Emacs doesn’t have a definition for it:
File used for storing customization information. The default is nil, which means to use your init file as specified by ‘user-init-file’. If the value is not nil, it should be an absolute file name.
It makes sense if you use custom often, which probably means you don’t bother with babel (coming up) and writing long Emacs posts like this one, but in reality, I haven’t met an Emacs user who used it for more than a few months at most without getting their hands dirty. It’s just too tempting.
The first line tells Emacs where the custom file config is (inside /.emacs.d/, the default for user-emacs-directory), and the second line tells it to “not worry” if the file is not there. Why? Because the first time we run Emacs (or a clean reinstall), we might not have this file at all yet, as it’s created by custom. If we don’t have this file, Emacs will do whatever it does whenever it encounters an error: tell us there’s an error and stop running the rest of the config. And this happens right at the beginning, so essentially our entire config will be skipped. So this is a good safety option4, and probably good practice.
Org-babel: load the configuration from an org file
(org-babel-load-file
"/Users/user/Sync/Public/emacs_settings/emacs_settings.org")
Now, after we put all the critical macOS5 configuration in place, it’s time to tell Emacs where the rest of the configurations are. This here was just the introduction, the Emacs “boot” for Mac only, after all6.
So here we are, done with part 1. It took me way longer to write than I thought it would take (I’ve been standing at my desk for about 2 hours now), but this is exactly the sort of thing that keeps me hooked on Emacs. Everything leads to more… everything. There’s a story behind every dot, apparently. As you can see from my footnotes, I’ve found additional tangents to go on while writing this just now, and that’s on top of a growing list I already have, of about 10 other things I want to check â and my config is only about 25% done. And as I said, by the time I’m done, it will be time for round 2, which in turn will probably lead to round 3…
“Emacs. It really whips the GNU’s…” errm. Anyway. See you next time!
Footnotes
1 The story of dot files (files that start with a dot, like .emacs) is an interesting one. Turns out it was a programming mistake back in the days when Unix started, and it stuck as an idea. These became convenient to use as configuration files because they are the sort of files that are usually created when you install something and configure it once, probably to never see it again (this was before Emacs users started popping up, obviously), so the bug became a feature.
2 On a Mac, you have several options when installing Emacs. The one I’ve been using over the years, and what seems to be the most popular, is emacs-plus at https://github.com/d12frosted/homebrew-emacs-plus. Some of the choices I made in my .emacs file are based on this fact.
3 There’s another rabbit hole here I didn’t explore much: Emacs on Homebrew, at least in some versions, has incorporated the option to grab the PATH during installation; however, it seems Apple blocked this option at some point, so we need to run it like this. I don’t recall ever getting a warning that Emacs needs access to my PATH or something similar, but I wouldn’t be surprised if something to that effect is happening when you first install it.
4 As I’m writing this, I realize there’s another worthwhile rabbit hole here: the option to tell Emacs to ignore errors for non-critical configurations, such as the theme, or the way org-mode displays, etc. While I want these in place, if there’s an error, I’d like Emacs to keep loading the config if it can. Since there are different “skip error” options depending on where and what is being skipped, and since I need to be sure what I’m skipping, I’ll do more digging another time.
5 Ah ha, but that last one, the custom file location, is also good on Linux! Good thing I’m writing this blog post. When I go back to my Linux machine, I will include this line there as well.
6 By the way, while there is no org-babel.el, it can almost be one from a quick look (yes, yet another rabbit hole). There are many different .el files scattered in Emacs that relate to org-babel which can do different things.
Interesting trick, discovered by mistake:
Dragging and dropping a file into Emacs while in a folder with Dired copies it there, just as Finder would. Did you know that? I didn’t!
Still working with Claude on my Emacs settings as a reference. Need to start a new session, so asked it to write a summary with instructions on how I like it to help me. It wrote this:
I know it’s complementing me on purpose, but that emphasized why? That’s why my blog is called this way đ
Say you go jump to a header in org-mode somewhere with C-c C-o. Did you know that you can go back with C-c &? And that it has history, so you can keep going back??
Years of isearch-backwards… wasted. Mind blown. đ¤¯
A Quick org-mode Internal Links Reference
As I mentioned yesterday, I started organizing (and cleaning) my Emacs config. What may have seemed like an annoying and boring task has proven to be fun and addicting (reminds me of this, which is part of this video đ).
I’ve already discovered a couple of new improvements to my current config as I was researching individual settings and why I have them, and as I said I do plan to share it. For now though, one important section I added to my config is a quick org-mode links reference. This is actually the first time I figured out the difference between radio links and “regular” plain links and how to use them.
Here it is, slightly modified:
Org-ID
We know about links to other files using org-id: You give a header an :ID: property (this is generated automatically1 when you link to a header) and you get a slug, usually a UUID (for me it’s something slightly else, more on that soon below). This stores the links in org-id-locations, which in turn points to a local file with all of these unique IDs. This is good for linking between headers in different files.
Custom-ID
We can set a :CUSTOM_ID: property for a header, and it’s only active in that file. Kind of like a table of contents in a book, with chapters (= headers) listed. If you don’t have the book, you don’t have its table of contents, so you know nothing about it. To point to a header that has a custom ID: [[#custom-id-value][description]].
Plain Target and Radio Target link
These are buffer-specific only (no cross-reference between files). In this case, the links are tied to words (anchors), not headers. There are two kinds.
The regular plain target link works when we set the anchor first with <<an anchor>>, then call it again with [[an anchor]].
Its more “magical” brother is a radio target link, where we set an anchor like so <<<very special anchor>>> (three angle brackets) and then all we need to do is type very special anchor (no brackets this time), and it works. Note though that when you create a radio target for the first time, you have to revert the buffer or M-x org-update-radio-target-regexp for it to take effect.
Footnotes
1 : this can be done with a function, org-id-get-create. For a deeper dive into how and why I set my org-id with a date format (not UUID), look here.
Thought my Emacs init file needs a bit of cleaning - it contains configs from maybe 5 and 6 years ago. It’s a nostalgic learning experience. More fun than I thought. More to come soon đ¤
Meta Journal Notes in denote-journal with Journelly
Wow, I’m so good at overcomplicating things, I already made you go “huh?!” with the title alone! I have some mad skillz!
On with the show:
In the last couple of weeks, I slowly improved and tinkered with my Linux environment (Kubuntu). I’m not sure if it was a single thing that nudged me to do that, but between installing the latest version of Harper and switching to Vivaldi with its great features I keep discovering, I also started using denote-journal.
Denote-journal, from the prolific Prot who also made Denote, was something I wanted to try for a while. I didn’t really have a good reason to, because I’ve been using Journelly for a long time, and on my Mac or Linux desktop, I’d call a capture template that would append to the file, adding my additional entries.
But I always had one major issue with journaling on my iPhone: privacy. My iPhone is owned and regulated (with a system profile) by my workplace. So even if I’m fine writing personal notes on my Mac (I’m not, I’m iffy about it as well, I don’t trust Apple to respect my privacy much more than I trust Google), at the end of the day, these notes also sync to my iPhone.
On a day-to-day basis, for quick thoughts and work notes, Journelly and my iPhone are great, but when it comes to writing longer notes about my future plans, how I spent the weekend with my partners, and basically anything else that involves people whose privacy I respect, I always self-censor.
For this reason, I came up with a way to create private notes with Denote only on Linux. These notes only live on my Linux Desktop, with a few of those syncing to my Android1 (again, not great, but at least it’s not work-managed).
I always feel more like myself on Linux because I am more myself - whether it’s customizing my shortcuts and workflow exactly how I like it, or if it’s the built-in privacy that can be further fortified and inspected. Journaling on Linux, without the world’s biggest nanny peeping over my shoulder, is where I really open up and write my most personal thoughts.
A couple of times I looked at my Journelly notes, those that I wrote on the Mac where I could write at length and use the full power of Emacs, and compared them to my older journal on Linux. Well, there is no comparison. And while creating a private note in Denote in Linux and linking it back to the original works2, it introduces friction that hinders the flow of my thoughts.
So I looked into denote-journal, realized it’s very easy to use, and gave it a try one day, and since then:
Essentially, it’s what I used to do when I started using Journelly: refile my Journelly headers into my journal files when I get the chance. Or, as a matter of fact, I use org-refile-copy, which does exactly what it says, because I want to keep the original in Journelly. Since I now use individual journal files instead of a big file split into weeks (as I did in the past), this process is even easier. The only catch is the images.
Images in Journelly are saved in its /Journelly.org.assets folder, where my journal files can’t see them directly; and even if it did, these images are too big and cause freezes, and also oriented the wrong way, so they need at least a minimal treatment. For these reasons, I attach each image to the correct header in the journal daily file which I moved over from Journelly.
These journal notes are fantastic. I have my quick notes from the day available, but when I want to extend, all I do now is just write a new entry for that day (which looks just like the Journelly entries) and write to my heart’s content. There’s also a bonus: denote-journal allows me to make up for days if I didn’t create a “meta journal note” for the day (so far this happened only once) directly from the calendar, so if I miss a day, I go to the calendar, point at the missing day, and use denote-journal-new-or-existing-entry to take care of things. If I already have an entry, it jumps to it; if I don’t, it creates one.
Between my journal on Linux, the emails I write to other bloggers, my blog posts, and the occasional instructions I write in Denote, I think I write more than I did in my entire life. I’m thinking I need to start capturing it in some sort of book, though I have no idea what it will be about and how to edit my writings in a way that makes sense. This is only a vague concept at the moment.
Footnotes
1 : I keep skirting around this issue so I’ll just mention it quickly: I used GrapheneOS in the past, and it’s great for these kinds of things, but GrapheneOS protects your phone to an extent that certain apps don’t work.
2 : I’ve been doing this often enough that I have a whole tag in Denote called “supplemental” with additional thoughts and notes. In Journelly, I was just linking to those, and writing something like “I have more to say about this” and this would include a Denote link to the Linux-only note.