The Art Of Not Asking Why

Don't ask me why, I'll tell you anyway

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.

Auto-generated description: A mythical creature resembling a satyr with glasses is sitting cross-legged in a forest setting, holding a glowing orb in front of a laptop.
    ■

    GCC drive error on macOS: This seems to show up with almost every new Emacs package I’ve been trying recently on my Mac. I remember trying to dig into it, and I went in circles trying to install something from Homebrew. Has anyone fixed this? I’m on GNU Emacs plus 30.2.

    A terminal window displays repeated error messages indicating a failure to invoke the GCC driver while compiling with native-compiler in Emacs.
    ■

    A quick update for my Emacs config Gems series:

    I am working on part 5, and I’m trying to finalize a few things first. Currently it’s Ispell (I’ve not been using it to its full capacity) and completion… more details soon.

    ■

    RSI and Emacs: When Your Pinky Says Enough is Enough

    I’ve been doing so much Emacs writing lately, so I guess it’s time I get my Emacs pinky (which is a form of RSI). I made a quick reference to it three days ago and got a lot of responses.

    What happened?

    I started to feel a strain last week, but at first I didn’t think much about it. Sometimes my pinky rests awkwardly on the keyboard because I’m used to using the Caps Lock key, but it’s usually a hand-position issue. After I readjust and let my pinky rest, it goes away.

    This time the strain didn’t go away, and my pinky kept rebelling.

    My keyboard, Kinesis Freestyle Edge (the one here is the RGB+, the original RGB is discontinued), has a prominent Caps Lock key that just screams “use me as control!” For years, that’s what I did. As you can see in the picture, with my pinky resting on it.

    A hand is positioned on the left side of a Kinesis Gaming mechanical keyboard with blue backlit keys.

    The last week has been busy. I didn’t leave my small Manhattan apartment for two days, working straight from morning to evening, then gaming and sleeping. This isn’t normal for me and has taken a toll on my hands, and the RSI got worse.

    I think my new screen also exacerbated the problem somehow. It’s much bigger and has higher resolution, which I’m still adjusting to by how I sit and how I move my head and neck. I also have a standing desk I usually use in its standing position in the morning, when I write these posts or work on projects — these are easily my longest writing sessions, sometimes going for two hours straight without a break, especially in the last couple of weeks, and that’s all Emacs and pinky work.

    When I thought about Emacs pinky in the past, I mostly thought of it with a smirk. I mean, it’s your pinky. How can you not read a comment about someone having their little finger hurt and not chuckle a bit? But folks, let me tell you, once you have it, you realize how much you depend on that one small finger, especially as an Emacs user.

    My work, my organization, even my gaming in the evening (as it turns out), it’s all going through that little finger. Sure, it’s my “fault” for using Emacs, but if you’ve been reading this blog for a while you’d know that I owe many things to Emacs (including, among other things, my current job).

    What am I doing about it?

    For now, I’ve started using the keyboard’s dedicated control key again and changed how I use my hands. I try to use my right thumb, all the way to the side from the home row (my keyboard is huge, I will get to that in a minute) for when I need to use the left side of the keyboard, and then fold my pinky and use my knuckle to press it when I need the left control, for when I use the right side of the keyboard, as you can see in this picture:

    A hand is resting the keys X and A with the little finger curled over the Ctrl key on a backlit keyboard with blue lighting.

    This adjustment is the easiest, since I know where these Control keys are by muscle memory. I turned off my Caps as control on my Mac to make sure I don’t get tempted to go back to my old habit. It’s been working OK, and that’s what I’m doing right now for writing this post.

    Other Emacs users have suggested several things, and I’ve been considering and trying a few of them.

    god-mode came up a couple of times. It creates a chord (two keys pressed at once) key binding that triggers a control press. For example, sd, and then xs (separately) to save a file in Emacs — same as C-xC-s. This can be useful, but it has two problems.

    The obvious one is that this shortcut works only in Emacs. When I don’t use Emacs, which happens more often than I’d like for work, I have to use the OS shortcuts. Caps is so ingrained in my fingers’ memory that I just use it all the time, but now I need to start thinking of other options. I could probably program the keyboard’s firmware to do something similar, but that’s a topic in itself — and if I do that, I don’t need god-mode anyway. Another odd issue is that it doesn’t work on my Mac. It throws a GCC error, which from what I gather has to do with Emacs internals and how it works (or doesn’t work in this case) with its internal compiling mechanisms. Yes, I tried the fix, which doesn’t seem to work well with Homebrew, and I gave up on it.

    There are other packages like god-mode, but I think the next one I’m going to try is Xah Fly Keys, because what he’s after seems to make sense to me. Which brings me to the next point: a new keyboard.

    New Keyboards

    I’ve been considering a new keyboard for a while, and the RSI has sped up the process. I’ve looked at a couple reviews and YouTube videos in the last couple of days. Kinesis, my current keyboard brand, is a known name in the ergonomic keyboard world, but after checking out their Advantage 360 I’m not sure I’m sold. It’s an excellent premium-looking keyboard, but it’s having a huge and heavy keyboard again. My hands are small, and I’m not sure I want to commit to another expensive giant, especially when I already struggle with room for the mouse, especially when the two halves are spread apart for the shoulders. I already compromise on this, and my chest is closer than it should be. I also think that for the price of these keyboards (over $400), I might want to take them with me when I go to the office, and with a Kinesis keyboard, this is not going to happen. Another thing I’m considering is going wireless, because of my USB switch setup. It can take my Linux Desktop or the Mac up to 30 seconds to detect the keyboard when I switch, which is small, but still annoying. The mouse, connected by a Bluetooth dongle, takes a second to switch over.

    The above reasons, and Xah’s reviews, landed me on Glove80, which is even a weirder-looking keyboard. This keyboard takes ergonomics further (or just looks crazier, if you’re not into those). It’s wireless and lighter, which means taking it with me makes more sense, and will hopefully fix the USB lag issue. It has keywells for the fingers, which is basically a “dip” or a bowl (hence the name) that curves downwards so your fingers, which are naturally curled on a keyboard, are resting downwards. It has its own super-light switches, which, while I don’t think I need them, are another example of thinking of RSI and finger pain.

    Going further with light keyboards, there’s the Voyager, which is tiny, lighter, and minimal. It’s not wireless, but it’s meant to be mobile, and it’s probably the best one for small hands. However, the Voyager only has 52 keys. It’s meant to be used with layers — meaning, there’s a modifier key that creates another “layer” of keys, which makes your Alt act as Ctrl, for example. I’m not sure I’m sold on this idea, especially when we’re talking Emacs. If I’m already challenged by my lack of Caps Lock, I can only imagine how much time I will have to sink into this keyboard with its layers and grid layout (which the Glove80 has too, by the way) to become efficient with it. I also think the Keywell is something I could use, so I have a rough idea of what I want to try next.

    The problem with the Glove80 is that you can’t really try it out. They have a 30-day return policy, shipping not included, and they’re in New Zealand. A keyboard like that takes time to get used to, and 30 days for a $ 400-plus keyboard requires a level of confidence in the product I don’t have yet.

    My conclusion so far

    All in all, I think what I’m looking at is a combination of adjustments rather than one solution. I need to get used to the idea of different key bindings, be it something like god-mode or Xah Fly Keys, which will make it easier to use with a new keyboard and would also be beneficial now, until I get it. The idea of layering is a bit daunting, but I can see the wisdom in it, especially after I got an email back from BSAG, who was kind enough to share her experience with me (she’s the one who told me about the Voyager keyboard).

    It will be a while before I buy a new keyboard, then it will take some time to get here, and then it will take me even longer to get used to one. I’m not looking forward to having my typing hindered even further, especially because I’m so dependent on writing notes all the time, but it’s also because of it that I have to do it. This is one thing I know I need to do.

    ■

    Back to Solarized

    Years ago, when I started the old blog1, I discovered Solarized.

    I liked it. The colors were beautiful and worked for me, but eventually I switched to the Gotham theme in Emacs, which, if you take a look, is not much different — just a bit darker. I stayed with this theme for a long time, tweaking it a bit after a trip to New Mexico.

    When I received my Mac and started working on it at home, I enjoyed its automatic switching between dark and light themes. At the same time, Prot started coming out with more of his excellent Ef Themes, and I adopted ef-reverie for my light theme and ef-night for my dark one (once again, if you look at the images, you’d see they’re not far off from Solarized, especially my choice of a light theme).

    This has been the state of affairs until the beginning of this week, when I “found” Solarized again. I discovered Prot himself was heavily influenced by Solarized, and he discussed it several times on his blog. Here’s part of his background story for his project Prot16:

    My starting point for developing a colour scheme was Ethan Schoonover’s Solarized. A true masterpiece. I thus settled on a method of using a 16-colour palette that consists of 8 base values and 8 accents. As with Solarized, the themes would have to be able to transition from ’light’ to ‘dark’ environments with minor alteration to the mapping of colours (though not the values themselves).

    Prot’s quest is an interesting one. Like me, he enjoyed Solarized, but eventually decided the colors were not contrasting enough for his taste. His reaction was to create his well-known Modus themes, which, along with his Ef-themes and Prot16, set new theming standards for Emacs.

    Meanwhile, I have had the other issue since childhood:

    I’ve never liked harsh contrast for this reason. As a matter of fact, a more “gentle” contrasting theme is one of the reasons I like working in Emacs. My website and my wiki are a result of these preferences. The black text on the beige background is comfortable on my eyes. Enough contrast to read, but not enough to burn text into my vision, as many dark modes out there do.

    While Prot’s ef-themes offer softer contrast (I didn’t check, but it does seem so visually) which I find excellent, I decided to try out bbatsov’s Solarized for Emacs, which I didn’t know about in the past when I first picked up this theme for Emacs — the official Emacs port is not as good in my opinion.

    I’ve learned a couple of things I wasn’t aware of. For starters, you can have many variations of this theme, even though the main 16 colors are still preserved. It makes sense when you think about it: one person can choose Solarized’s red (#dc322f in hex) as an emphasis, while another can select its yellow (#b58900) or orange (#cb4b16), for example. Webpages and Emacs take it a step further, as certain texts can be bold or italicized, with solid underlines or dashed ones, etc. All of those changes take place without touching the colors themselves.

    Solarized also helps me with a certain itch I’ve had for a couple of months: a dark theme for my blog. I know most of you read my posts in your RSS reader, hopefully with a theme you enjoy, so this won’t matter much. For me, how my site looks and is styled is important, and getting there is fun.

    A minimalist (solarized) skyline of a city with a prominent tall building, set against a dark background with waves in the foreground and a red moon in the sky.

    1. This post is here, on the new blog, because I migrated it from the old. The date on it is accurate however, and it’s the first post I have saved in my old archive. The same is true about the New Mexico post. ↩︎

    ■

    Emacs Config Gems - Part 4

    Part four of Emacs Config Gems is about basic file operations and save functions. I realized as I was working on this that I have the frame configuration here, which is the wrong place for it. I will change it after posting. Alright, here we go.

    When deleting a file in Emacs, we should use the system’s trash (or recycle bin) instead of deleting the file permanently, giving us a chance to restore the file in case we’ve made a mistake.

    In addition, since we have this turned on, we can also tell Emacs to always delete non-empty directories (because they’ll go to the trash) instead of prompting. It’s just faster.

    (setq delete-by-moving-to-trash t)
(setq dired-recursive-deletes 'always)

    Let’s set the frame Emacs starts with to be a bit bigger. In Emacs, these measurements are in lines and columns (character width), so we’re basically saying: “make the default frame 100 characters wide and 55 lines high.”1

    (setq default-frame-alist
   '((width . 100)
     (height . 55))
    )

    We might want to move Emacs’ backup files and temp files (those are the ones with ~ and #)2 to a different dedicated folder (emacs-bks) instead of the main Emacs folder. Since Emacs won’t just create the directory for us, let’s ask it to do so3. It won’t throw an error if we already have it.

    (make-directory "~/emacs-bks" t)
(setq backup-directory-alist
      `((".*" . "~/emacs-bks")))
(setq auto-save-file-name-transforms
      `((".*" "~/emacs-bks" t)))

    Now, let’s turn on the option to automatically save files we are working on inside Emacs, and set how long Emacs needs to be idle before auto-save kicks in. In my case, 300 seconds (= 5 minutes) is good enough for idle time. Importantly, I want to emphasize again, idle time. It will not auto-save the file as long as you type, so if you type non-stop for an hour and suddenly lose power, this will not save you, since Emacs didn’t get the chance to be idle for 5 minutes (or even 30 seconds, which is the default). For this, we have auto-save-interval, which auto-saves every 300 characters (globally in Emacs) by default. In my case, I’m lowering it here to 100, since I write plenty of quick notes (using org-add-note, C-c C-z), and it’s common for me to keep using Emacs between those without hitting the 300 mark. Both of those are described in the manual under auto-saving.

    (auto-save-visited-mode t)
(setq auto-save-visited-interval 300)
(setq auto-save-interval 100)

    Auto-revert checks the buffer we’re visiting against the saved file itself. If the buffer has no changes, but the saved file does have changes, it loads those changes into the buffer silently. However, if the buffer has changes (meaning, we’re writing something into the file and we haven’t saved yet), it won’t do a thing and won’t say anything. Since my particular setup means that all of my org files are inside a folder synced by Syncthing, this is ideal: if I save changes to a file on my Mac, when I switch to my Linux desktop I’ll have the file and the buffer visiting it refreshed and ready to go, provided of course that Syncthing is working and the sync is complete4.

    (global-auto-revert-mode t)

    Activate recentf mode, so Emacs has a list of the recent files we worked on last time, up to 30 by my config. 10 is too little; 50 starts to feel more like “everything I opened this month,” which defeats the purpose. Useful when we don’t want to navigate to the same file each time, and we don’t want to have a bookmark. Note: since I’m using consult, recent files are integrated and show under the file header in the consult minibuffer, and can be quickly viewed with f while visiting the consult minibuffer.

    (recentf-mode t)
(setq recentf-max-saved-items 30)

    1. There are a couple of more interesting parameters (options) to choose from. For example, alpha is a thing, if you like your windows to be translucent (and you can set it so that the frame in focus has a different degree of alpha than those out of focus). I played with it a bit, but eventually found it to be too distracting. ↩︎

    2. But what are those anyway, and why do we need them? Let’s talk about auto-save first. It’s been there since the beginning. In the early 80s (and even before), when the idea of computers always being on and connected to some virtual cloud was science fiction, people lost their data quite often, either by hardware failure, power failures, and/or user errors, like hanging up the phone in the middle of a data transfer (these were the days of dial-up modems). Auto-saving a file was a feature that was a solution to a very common problem, and we can see it in computer magazines from the era (you can see those in the internet archive, look at page 70 in this magazine for example). As for backups, it’s a similar idea, but the purpose is slightly different. Think of backup literally means “back up.” The idea here is to restore the file from before you saved, backing up (as in going back) to what it was before you touched it. This idea is more closely associated with file-versioning, which Emacs also has, but that’s a slightly different story and it’s turned off by default. To differentiate the auto-save from backup files: In Emacs, auto-saved files are the ones marked with hashtags and the backup files are the ones with a trailing tilde: #autosave-file# and last-save-file~ ↩︎

    3. There are a bunch of these helpful OS-file level functions available to us from inside Emacs. They are scattered in the Lisp manual in the file section, depending what you’re looking for. If you want a quick cheat-sheet of sorts with examples, Xah Lee has something a bit old, but still relevant. ↩︎

    4. There are other functions around revert, particularly auto-revert-avoid-polling, which is off by default. it’s a bit confusing: auto-revert-avoid-polling means, avoid automatically polling for reverting. By default, this is nil (false) which means polling is on: Emacs does its own polling to check if a file was changed every 5 seconds by default (this is determined by auto-revert-interval). If this is flipped to true, Emacs does not check the file, and instead relies on the OS file notification system (inotify in Linux, FSEvents on macOS). This is good if we want to save battery and CPU cycles: our system checks if files were changed all the time, so Emacs just relies on that. In my case, with Syncthing, this is a bad idea because the OS may or may not catch changes done by Syncthing. My Desktop is always connected to power and my Mac is usually docked so leaving it as default makes sense. Check out the manual for auto-saving. ↩︎

    ■

    Emacs Config Gems - Part 3

    My actual configs start with pretty usual stuff you’d see across many other Emacs configs. As I was going through these however, I started to wonder how things work and why they ended up the way we have them today. In turn, that led to reading about the intention behind those, which led to more options I didn’t think about. Also, it’s kind of fun. I’ve made two more passes for this part alone in the last couple of weeks, and I could probably go for a third. When reading this post, if you want the good stuff (in my opinion), get lost in the footnotes as I did. There’s a lot to explore. I just scratched the surface.

    Load Melpa

    Melpa is where many Emacs packages live. The story behind it (from what I can tell) revolves around one of Emacs’ maintainers, Bozhidar Batsov, who pointed to Melpa at some point in 2012, when Emacs’s then go-to third-party package repository went offline. He is not its creator — Melpa has been around before this post — but this seems to be the turning point where Emacs package maintainers started to really use it. I don’t have good coder/repository maintainer knowledge, but from what I read, it’s built on the same idea as Homebrew (for Mac), which was familiar to many of the Emacs folks at the time.

    So let’s get Melpa:

    (require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)

    UI and Fundamental Emacs tweaks:

    Most Emacs folks with a config file like this like to kill the toolbar, scrollbar, and menu bar. I find that the menu bar makes Emacs look more like the other programs, especially in macOS1. Besides, it’s nice to look every now and then and be reminded of good Emacs kung-fu I forgot exists (org-sort, I’m sorry my friend, I’ll keep saying hi more often).

    This is why the menu-bar is commented out in my config; I want it, but I also want to remember I could turn it off if I wanted:

    (tool-bar-mode -1)
(scroll-bar-mode -1)
;; (menu-bar-mode -1)

    By default, help commands2 display the help buffer in a new window without selecting it. I find this annoying: if I bring up the help window, it’s usually because I want to scroll down to find something or copy (yank) something. On the other hand, if I just want to skim quickly in the help buffer, it’s helpful that the marker is on it for a quick q for quit.

    In addition, we want to be able to navigate help menus as Emacs intended if we follow the links in a help buffer. help-window-keep-selected allows us to keep help in its own dedicated window, so it won’t open in a separate window once we follow a link. Going back to the original is the same as we do in other browser-like buffers in Emacs, with l (like in Eww, for example). Likewise, we can go forward with r. I should also expand here on various help options; they definitely deserve a mention, but this is another huge topic (you can get an idea from the footer) that will take a couple of weeks. I will come back to this someday.

    (setq help-window-select t)
(setq help-window-keep-selected t)

    Lisp is full of parentheses, and it’s easy to lose track. Turning show-paren-mode on means that standing on an open or closed parentheses highlights its matching counterpart, which is handy.

    In addition, while we’re here: when we stand on an expression that is only showing a portion of an expression (meaning, we need to scroll down to see the rest) Emacs can highlight the expression for us to make sure we don’t get confused — this is the mixed option below for show-paren-style. If you want to see the whole expression highlighted every time you’re on it, there’s the option expression, which I’m leaving here for reference for myself. For now, I think it’s too much visual noise, especially since we’re using org-edit-special, which also highlights what we’re working on.

      (show-paren-mode t)
  (setq show-paren-style 'mixed)
;; (setq show-paren-style 'expression)

    And now, a true Emacs classic. I don’t think I’ve seen a config without it: shortening “yes” or “no,” answer to “y” or “n” like any other program known to mankind. use-short-answers was introduced in Emacs 28.1, which is a more graceful way to do this, intended exactly for this purpose. Before that, back when I started to use Emacs, it was done with (fset 'yes-or-no-p 'y-or-n-p). If you have an older Emacs version, you’d need it.

    ;;  (fset 'yes-or-no-p 'y-or-n-p)
(setq use-short-answers t)

    This one was annoying until I learned this option exists from someone else’s config years ago: “Emacs, please stop asking me if I want to kill process when exiting Emacs (Shell, etc.), just do it!” Yep.

    (setq confirm-kill-processes nil)

    Emacs has two annoying keyboard shortcuts that I should have disabled as soon as I started using it: C-x C-c (exit Emacs) and C-z (minimize Emacs). Both of them are too easy to press by mistake, especially C-z, which is undo in many other programs. If I had a penny for each time I minimized Emacs by mistake… When we want to minimize Emacs (and why would you want to do that? Emacs deserves a prominent space on your screen), we can just do it by clicking the minimize window itself, shamefully using our mouse, as we do with other apps. And Exiting Emacs? With a shortcut that seems like it fits somewhere in org-mode? No thanks. Let’s disable those:

    (global-unset-key (kbd "C-x C-c"))
(global-unset-key (kbd "C-z"))

    Turn off the annoying error beep, which I first discovered in SUSE Linux by turning on a visual warning (a flash) instead. This will flash the top and bottom lines of our window instead of going “beep!”

    (setq visible-bell t)

    Turn on visual line mode so text lines “wrap” inside the frame and don’t continue beyond the window’s edge. This is essential; I can’t read in Emacs without it. And a newcomer I discovered recently: since Emacs 30, we also have global-visual-wrap-prefix-mode, which preserves indentation on wrapped lines. For example, in a list in org-mode (made of dashes one under the other), a long line of text that wraps will align under its starting point (dash) in the list instead of jumping back to column 0 (the start of the window, to the most left). This has been a huge pet peeve. Finally!

    (global-visual-line-mode t)
(global-visual-wrap-prefix-mode t)

    Winner mode (included in Emacs) is sort of “undo” for changes in windows’ layout in Emacs. C-c ← goes back to our previous setting, and C-c → will “redo” the layout we just left. I use it all the time as in “oops, I closed the wrong window”3.

    (winner-mode t)

    Saw this over at https://emacsredux.com/blog/2026/04/07/stealing-from-the-best-emacs-configs/. This is a nice little trick, and it requires a bit of reading to understand what exactly it does: preventing Emacs from deleting whatever we have in the system’s clipboard when we kill a line, so it’s still in the kill ring. Here’s an example to help you grasp the idea and why it’s useful:

    1. We’re visiting a website with our default browser and copy its URL because we want to write about it in Emacs
    2. We go to Emacs, and we kill the line we’re on because we need some space
    3. Crap! Now we lost our paste in the clipboard, and we have to go back to the browser and grab that URL again!
    4. Wait, which tab was it? Did we close it? Should we look in our browsing history? Ugh!

    Not anymore! With this little guy, when we kill the line (step 2 above), Emacs “injects” it into the kill ring. Now, when we yank with C-y, we will still get the last line we killed, yes, butlook up the kill ring with M-y and voilà! Your URL is there. No need to go find that URL again:

    (setq save-interprogram-paste-before-kill t)

    You know how for years Emacs “jumped” when you scrolled down large embedded images in your org buffers? Let’s turn on pixel-scroll-precision-mode for pixel scrolling instead of the default line scrolling to fix this. It’s pretty much what it reads: the default old way would “scroll” (it’s actually not scrolling at all) by a line of text at a time. Since our image of, say, 600px in height is treated as a single line of text, it will jump to the end of it. With this option turned on, Emacs would read the pixels from your mouse wheels as you scroll, and we get the smooth scrolling we’re used to.

    Interesting to know: moving up and down the line without a mouse (arrows, or C-p and C-n) is moving by text lines, utilizing auto-windows-vscroll and line-move, which basically does in Emacs what arrow movement seems to be doing in modern applications: these apply this principle from the other direction — they natively work with pixels, so they treat these arrow movements as a fixed number of pixel movements, which is approximately a line of text. So, when you move up and down a large image (or say a PDF) in a browser, the browser thinks “ok, the user is moving up one line of text, which is.. hm.. let’s see… ah, it says it’s exactly 40 pixels, so let me show that”.

    (pixel-scroll-precision-mode t)

    test break

    “Emacs is the editor of tinkerers and artisans; those who are eternally dissatisfied with all other tools because of their adamantine rigidity. Crafting, or shaping, your tools to meet your exacting needs is what Emacs excels at. Because of that, Emacs is – much to the chagrin of everyone who picks it up for the first time – squarely aimed at people who already know Emacs.”

    In fact, if you’re curious about help and Emacs help, I suggest you head over there now and read that post. It expands on how to approach Emacs help by how to think Emacs, which is something that experienced Emacs users struggle to explain to newcomers.

    As for the history of help in Emacs, I think it’s pretty safe to say it’s been there since the start, or at least since Emacs became intended for public use, sometime around the 1980s. By that point, most of the core help parts we know today (the tutorial, C-h t; the Emacs Manual, C-h R; as well as the framework itself) were already in place. The help system was there before GNU Emacs, back in the days of TECO Emacs that RMS worked on at MIT in the 1970s. You could browse the original code from then (preserved by MIT) and see how Stallman explained what certain commands do in emacs.doc inside that repository. Another interesting find about Emacs itself (and the help system that comes with it) is the EMACS paper written by RMS back in 1981. For the help system, take a look at page 17: “6. Self-Documentation and Extensibility” and the following chapter in page 18: “7. History”. Fascinating stuff.

    1. And here, dear reader, I fell down a deep rabbit hole, one that pushed this post a couple of days. There are two parts to this. The Emacs part, which I will explore at some point in the near future, has to do with Emacs’ menu itself, which is controlled by easymenu.el. This is an old Emacs package that’s been around since 1994, written by RMS himself — kind of. It was first created by Per Abrahamsen (who seems to be a bit of a mystery, but that’s digging for another day). In turn, this package was taken from lmenu.el, which was part of yet a different Emacs fork at the time. In a regular Emacs style, the menu bar can be completely reconstructed and changed — and that’s something I want to explore soon as a way to recall useful functions I keep forgetting exist (like having an “organize” menu with something like “org-sort” under it). This will be a fun project of its own for another day. Meanwhile, the other, bigger rabbit hole is the story of the GUI menu itself as we have it today. Apple has a big role here, back in the days before Steve Jobs left Apple and worked on the Lisa. This seems to be the first usage of a graphical interface in personal computers, and the menu, which was taken from Xerox, was a big part of it (there’s a short YouTube video there that would give you a quick brief of what happened). This means that I am right on keeping the menu in theme with the rest of the Mac apps, based on history! ↩︎

    2. Emacs’ built-in help deserves its own series of posts. Looking at it now, from the eyes of someone who used it for a couple of years, I find Micky’s description satisfying, reflecting what I felt at the time: ↩︎

    3. I forget how exactly, but some research into winner-mode history (turns out it’s been around since 1997 — also, a lot of goodies here to look into!) led me down the path of tabs in Emacs, tab-bar in particular. I didn’t think much about tabs in Emacs, but since I’ve been using Kubuntu for a while and experimented with its Workspaces, I understand the concept better. I looked into BSAG’s post, and it looks like you can hide the tabs while still displaying them on the mode line, and of course, you don’t have to use the mouse. The concept of having a whole workplace completed with its unique window arrangement available with a single keyboard shortcut is alluring. Now, instead of playing around with where and how I want my windows to display, I can just save (or re-create) those, and I always have a “work” environment vs a “personal” environment within the same Emacs frame. This can be a good organizational feature. I’m going to dig more into this one. ↩︎

    ■

    Still working on Emacs Config Gems part 3. Fell into a deep rabbit hole and got lost for a couple of days, then climbed out just to discover another one I have to explore next. I wanted to crunch the first few tweaks of my Emacs config in one post, but there’s too much to explore. I’m getting there!

    ■

    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.

    1. 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. ↩︎

    ■

    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.

    1. 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 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:

    1. Emacs keyboard shortcuts and file paths should be placed in verbatim (between = and =)1
    2. Code (as part of an explanation) should be placed in code (between and )

    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

    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:

    1. 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.
    2. 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.

    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.

    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.

    1. 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.
    2. 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”.
    3. 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
    4. To insert a saved region: C-x r i, then the number/letter we previously selected.
    5. 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.

    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.