Preview: Some time ago I had a need to “convert” a phrase, or even a whole sentence, into an identifier. By “converting to an identifier” I mean lower-casing the whole thing and changing non-letter characters into underscores. For example, “Hello, world!” should become hello_world. I came up with some simple code to do that – but it turned out that there were some pitfalls I did not expect.
M-x Research (contact them for password): TBA https://m-x-research.github.io/ Tue Oct 4 0800 Vancouver / 1000 Chicago / 1100 Toronto / 1500 GMT / 1700 Berlin / 2030 Kolkata / 2300 Singapore
Emacs users group Slovenia https://emacs.si/ Thu Oct 6 1100 Vancouver / 1300 Chicago / 1400 Toronto / 1800 GMT / 2000 Berlin / 2330 Kolkata – Fri Oct 7 0200 Singapore
Atelier Emacs Montpellier (in person) https://lebib.org/date/atelier-emacs Fri Oct 14 0900 Vancouver / 1100 Chicago / 1200 Toronto / 1600 GMT / 1800 Berlin / 2130 Kolkata – Sat Oct 15 0000 Singapore
I just added ef-frost to my ef-themes collection. It is a legible
light theme with cool colours ranging from blue to teal with touches
of purple.
[ The ef-themes are a collection of light and dark themes for GNU
Emacs whose goal is to provide colourful (“pretty”) yet legible
options for users who want something with a bit more flair than the
modus-themes (also designed by me). ]
Note that some themes in the collection are designed as pairs. Those
have -light or -dark in their name. The others are standalone.
Regardless, the user can specify any two themes in the value of the
user option ef-themes-to-toggle and then switch between them with
the command ef-themes-toggle. Or just use the other available
commands: ef-themes-select for minibuffer completion and the
ef-themes-load-random to load one from the collection (with C-u
limit the effect to light or dark themes). The official manual
explains more.
ef-frost
Comparison between ef-light and ef-frost
There is no other light theme quite like ef-frost. The closest is
ef-light, which is more colourful as those pictures demonstrate
(each theme in the collection has a unique colour mapping and its own
colour palette).
Coming in version 0.7.0 (next stable release)
The ef-frost theme is in development. I think its design is final,
though I might tweak it further. Expect this and other updates to be
widely available via GNU ELPA some time in mid October.
Building on Exploring the Denote Emacs Package, I want to layout a migration plan. For the migration to be successful, I have the following criteria:
Glossary Migration
When I pull glossary entries into Take on Rules I expect the ./data/glossary.yml to be functionally identical to it’s current state. That is to say no nodes dropped nor added and keys being similar. I would go so far as to say after the migration the pull event should result in no change to ./data/glossary.yml.
Blog Export
I am able to export an Org-Mode📖 format Denote file for publication on Take on Rules.
Data Structures
I am able to organize and discover notes via different attributes.
Keywords and Controlled Vocabularies
I spent time establishing the tags I use for blogging; I’d want assistance in adhering to that exercise.
Other Stuff
As I write this document, I’m certain other things will emerge.
Feature Tests
These are my guiding “feature tests.” Revisiting Exploring the Denote Emacs Package, you’ll notice that I’ve already introduced feature creep. Such is the life of any project, but especially a software project.
Glossary Migration
I need to consider how I’m handling abbr: and abbr-plural: links; due to the newness of this functionality I don’t have many to consider. This does require navigating the export of Hugo shortcode fragments.
I will need to migrate the Rake📖 task that I wrote for pulling data into my Hugo📖data/glossary.yml file. This should be relatively straight-forward and easier by introducing the convention of a glossary directory.
Yes, I Org-Roam📖 I could have created a custom directory and template, but I was relying on the search function as my intermediary. In hindsight, having a specific directory for Glossary is something I’m now sensing I want.
Given that I’m uncertain I want to migrate to Denote, it makes sense to move my glossary items to a glossary directory.
Blog Export
I’ll need to revisit the Extending the Ox section of my Emacs configuration. With this document, I did a called jf/export-org-to-tor to see what happened. The main thing I observed was that the Ox-Hugo front-matter I inject into this document was placed at the top of the file.
That clobbers the Denote convention of it’s front-matter at the top of the file. The fix is somewhat straight-forward; I know what to do but not yet how I’ll go about it.
There likely exists a function to detect the entirety of a Denote document’s front-matter. Use that to find where to insert the Ox-Hugo front matter.
Another thing I noticed was that I was adding an :ID: to a properties drawer. This is not necessary as Denote has the :identifier: front-matter entry. This does, however, remind me that I’ll need to consider migrating nodes.
In the last week, I recall reading a post regarding exporting Org-Roam to Denote; I’ll want to go track that down.
One thing I love thinking about, and all too often forget to think about, is the data structure.
And Denote, by it’s conventions, has me thinking about the data structure; in part because of it’s opinions regarding front-matter. In this case there are two data structure components to consider:
File System Conventions
Document Metadata
File System Conventions
As a refresher, Denote uses the file name to encode:
Identifier
Title
Keywords (aka Tags)
There is further consideration about the directory structure. There is guidance on how to isolate directories (e.g. “work”, “personal”, “volunteer”) such that they are siloed from each other.
See Section 3.3 “Maintain separate directories for notes” of Denote’s manual for further details on separate directories.
However, directories need not be siloed. My aforementioned glossary is something I might not want siloed; after all these terms are useful for many contexts.
I do wonder how I might have three directories: glossary, employer, personal. I would want the glossary available to the employer and personal but disallow employer and personal “knowledge” of each other.
To put a name to metadata role of directory, I think of namespace or domain. Namespace feels too generic. Let’s go with domain, and lean on Webster’s 1913 definition:
The territory over which dominion or authority is exerted; the possessions of a sovereign or commonwealth, or the like. Also used figuratively.
I also like overlaying/amalgamating the definition with the Mathematical concept of domain:
The domain of a function is the set of its possible inputs, i.e., the set of input values where for which the function is defined.
With domain I have four pieces of metadata: title, identifier, keywords, and domain.
I should probably consider what are my implicit domains:
Glossary
I reference many terms.
Epigraphs
I collect passages and reference them in posts.
Blog Posts
I’ve written a lot of blog posts; should I move a note into this domain when I publish an internal note?
Do all of these warrant their own directory? Before I get carried away, I should do some preliminary exploration. As previously mentioned, the Glossary domain is a good experiment for adoption.
Document Metadata
I wrote about this quite a bit already, but will reiterate; because Denote allows writing in Org-Mode format, I have access to Org-Mode’s property syntax; though I’ll need to use a different method than I’ve previously used.
Keywords and Controlled Vocabularies
On I migrated the tags of my Blog; compressing 378 tags into 59.
I checked Changelog // Take on Rules to see when I made this unceremonious switch. How to Use Tags spurred me to revisit my tagging.
This migration inter-relates with my glossary migration; the glossary asserts what tags are allowed on Take on Rules.
To my knowledge, Org-Roam, does not have a concept of a controlled vocabulary for tags. And since I’m using Org-Roam as the mechanism for the initial composition of my blog, I’m butting up against tagging; namely I have to be disciplined about how I tag things.
In my quick read of the documentation, denote-infer-keywords provides the ability to limit tags to only those explicitly set in denote-known-keywords.
Further Considering and Pondering
One thing rattling around in my brain is how I’ve been using my agenda.org file. For my work at Scientist.com I use it as a TODO list and my monthly timesheet. When the month is done, I archive my timesheet.
What if I rethink things just a bit; each month get’s a journal.org file. Then I amend my org-agenda=files variable to point to the timesheet? This would mean I’m not archiving entries but instead removing them from my agenda workflow.
This is a future tangent but one that I’m pondering and considering. And none of this is really dependent on Denote; it is simply a byproduct of thinking about my organization system.
But I do like the idea of not archiving the entries. Why?
I use Git📖 for version control of my Org-Mode files; and moving a subtree from one file to another gives me trepedations.
Conclusion
This document is about helping me think through a potential migration. And in writing this all down, I’m thinking about what it means to go through a migration.
If you’re like me and want to do all your writing from within Org-mode, one problem you need to solve is how to write letters—especially professional letters. I use a LaTeX template and write the letter in LaTeX but mostly it’s just text so it’s pretty easy. Still, it would be nice to move all that to Org so that I could just use, say, a Yasnippet to include the LaTeX boiler plate and then write in the comfortable Org environment.
Ravi Sagar has a short video on how he’s solved this problem. One of the problems he needed to solve was how to produce a letterhead. That turns out to be pretty easy once you have the letterhead graphic. He has all his LaTeX boilerplate in a separate file and just includes it in the individual letters. It works well and is pretty easy.
If you’d like to move even your formal letters to Org-mode, take a look at Sagar’s video to see how to set it up. It’s worth doing this if only to free yourself from the tyranny of Word and its ugly siblings. As this week’s Red Meat Friday hinted, you’d do well to avoid hitching yourself to the Microsoft wagon.
I have been using the Emacs X Window Manager, EXWM, for a couple of years now and I have come to depend on it for an efficient and friendly workflow for most of what I do at the computer. Before that, I had been using StumpWM for 4 or 5 years and I was already sold on tiling window managers. For someone like me who does everything in Emacs except for browsing sites that need Javascript or watching videos, EXWM seems to be the perfect setup.
The pain point with EXWM is that its development and maintenance suddenly stopped after the creator and maintainer went AWOL. There have been discussions here and there to continue the development, but, to the best of my knowledge, no initiative has really taken off.
Some well known EXWM users in the community started migrating to other WMs, like StumpWM, Herbstluftwm or or QTile. I also tried to get back to StumpWM, since I had used it for a long time, but I found the experience inferior to EXWM: having M-x everywhere and not having to use different key bindings when talking to the WM or to Emacs is a real comfort.
However, some time ago, floating windows started behaving annoyingly. For instance, when saving a file in Firefox, the file chooser application would be too high and the Save button would be below the bottom of the screen. I then would have to move the window up so that I could click. Not knowing anything about X, I wasn't able to diagnose the issue.
I ended writing a little function to resize a floating window:
So now, instead of grabbing the mouse and manually moving the window, I could just use s-x r and hit enter, since the Save button is selected by default. This is a big win, but after a couple of days, I became tired of this and thought that this could be automated. Also, the arbitrary fixed size may not be appropriate depending on the monitor I am using.
So with a little more elisp, I wrote a function that computes the size of the window and works with a hook which is called by EXWM and the end of the setup of the floating window:
All this may seem complex and one could think that too much elisp-foo is needed to do all this. This is absolutely not the case. With a little effort and time, it is not difficult to navigate the source code and test things interactively to see how they behave. In this particular case, searching for hooks in the EXWM package (M-x describe-variable) and trying little code snippets on the *scratch* buffer got me there rather quickly.
This is yet another demonstration of the power of Emacs: you can modify its behavior interactively and all source code and documentation is immediately accessible. You don't need to be a skilled programmer to do that.
That's user freedom, the real meaning of software freedom.
I just added ef-bio to my ef-themes collection. It is a legible
dark theme with green, teal, blue, purple colors.
[ The ef-themes are a collection of light and dark themes for GNU
Emacs whose goal is to provide colourful (“pretty”) yet legible
options for users who want something with a bit more flair than the
modus-themes (also designed by me). ]
Just a sample with two other dark themes from the ef-themes
collection.
Coming in version 0.7.0 (next stable release)
The ef-bio theme is in development. It will probably not change
much, though I might make some further tweaks to it. Expect this and
other updates to be widely available via GNU ELPA some time in mid
October.
When you think about it, the title of this post doesn’t appear to make sense. Yasnippet is a template system for adding customized boiler plate to an Emacs buffer. It’s raison d’être is to enable shortcuts for various programming constructs such as the C for loop.
Still, it’s a flexible system so it finds all sorts of uses. If you’re writing in LaTeX, it can help with things like the environment boilerplate. Similarly, it’s great for things like blog headers.
Erik L. Arneson has a post that describes how he uses Yasnippet for his writing. After explaining how to install Yasnippet, Arneson describes his uses. That turns out to be mostly things like blog headers and Org headers for certain other structured files. You can read his post for the details.
My personal use is almost entirely things like that. I never think to use it when I’m programming even though I do have the appropriate snippets loaded so the snippets I use are mostly for prose and various record keeping applications where the snippet provides a sort of form that I can easily fill out by tabbing through the fields.
The takeaway is that technology like Yasnippet doesn’t have a lot of application for writing prose except for headers and other boilerplate and perhaps for markup if you’re using something like LaTeX. Still, even those seemingly minimal applications can save a lot of time.
If you haven't heard of Plain Org, it gives you access to org files on iOS while away from your beloved Emacs.
Hadn't had time to post, but v1.5 has been available on the App Store for a couple of weeks now. The update is mostly a bugfix release, primarily addressing inline editing issues that appeared on iOS 16, along with a few other changes:
Render form feeds at end of headings at all times.
Fixes new files not recognized by org-roam.
Fixes share sheet saving from cold launch.
Fixes inline editing on iOS 16.
I love org markup, but we (iPhone + org users) are a fairly niche bunch. If you're finding Plain Org useful, please help support this effort by getting the word out. Tell your friends, tweet, or blog about it. Or just support via the App Store :)
As of I use Org-Roam📖 for writing and linking. Those notes can be glossary entries, blog posts, people, epigraphs, or just about anything text.
Org-Roam utilizes a SQLite database for storing and linking metadata. This is a feature that I consider a nice to have.
An emerging note taking utility is Denote; in this document I want to explore my usage of Org-Roam; what I’ve come to expect (e.g. consider a “must have”) and what I’ve come to appreciate (e.g. consider a “nice to have”). I then want to look at how to achieve that in Denote.
The foundational tooling that I want:
Org-Mode aware
Note taking that “understands” Org-Mode📖; or more appropriately that Org-Mode tooling can understand.
Tags
Tag each note.
Quick filing
Insert a new note with minimal thought of where it goes.
Linking
Link to other notes.
Metadata
Add metadata that can power my epigraphs and glossary.
Search
Prompt for notes by searching title and tags and other metadata.
Export Links
When I link to a node and export, I want to export the world facing URL.
The above definitions are my “feature list”; I’ll reference those later.
A nice to have feature would be prompting for a file by more advanced searching. An example of that would be as follows:
Filter on the programming tag
Search the resulting filter set for the words Hello World
Another nice to have feature is collision detection; I don’t want two notes to have the same glossary key, nor alias.
Right now I believe Org-Roam enforces unique aliases but not glossary keys.
Diving into Denote
You might be wondering why this document? There’s a two-fold reason. First, I want a place to think about what this change would mean. Second, I want to remember and be able to later evaluate all of the code I’m writing and loading into Emacs📖 without adding it to my Emacs Configuration.
In away, this post is my sandbox exploration of the Denote package.
With this quick establishment of my note-taking requirements I’m going to explore Denote.
First, I found myself reading the Denote documentation for pleasure. It is one well-documented package; accessible and helpful at learning not just Denote but also Emacs Lisp as well.
More importantly (maybe?) is a statement I recall from a seminar with Neil Jeffries regarding the Oxford Common File Layout (OCFL 📖). The statement was along the lines of favoring Posix, the Unix file system. It is a consistent and underpinning technology that is very likely to continue as other technologies light the stage and fade away. In other words, it has attributes that are ideal for “preservation” of digital objects. Too Long; Didn't Read📖 Favor it over any other system of preservation.
I’ve long worked in the fields adjacent to digital preservation concerns and have felt the anguish of Fedora Commons wending a path to, from, and back to the sensible consideration of storing things on a file system.
In other words, the sensibility of Denote echoes my wariness of too many tools. However, there’s quite a bit of tooling in Org-Roam that uses SQLite to help facilitate; but the fundamentals of portability remain.
The key consideration is that Org-Roam has one more external dependency than Denote.
Reading Denote’s documentation on Portability, I see common consideration:
Notes are plain text and should remain portable. The way Denote writes file names, the front matter it includes in the note’s header, and the links it establishes must all be adequately usable with standard Unix tools. No need for a database or some specialised software.
Protesilaos Stavrou (aka Prot), the maintainer and originator of Denote, stewards many Emacs packages. A consistent attribute of those packages is fantastic documentation; both inline and of the “README” variety.
When I first started, I had the minimal package declaration (use-package denote :straight t). As I explored I amended that basic declaration to the following code block.
(use-package denote
:straight t
:commands (denote-directory)
:bind ("H-c a" . jf/denote-create-abbreviation)
:custom ((denote-directory "~/git/org/denote")
;; These are the minimum viable prompts for notes
(denote-prompts '(title keywords))
;; I love org-mode format; reading ahead I'm setting this
(denote-file-type 'org)
;; And `org-read-date' is an amazing bit of tech
(denote-date-prompt-denote-date-prompt-use-org-read-date t)))
(cl-defun jf/denote-create-abbreviation
(&key
(title (denote--title-prompt))
(abbr (read-from-minibuffer "Abbreviation: ")))
"Create a `denote' entry for the given TITLE and ABBR.
NOTE: At present there is no consideration for uniqueness."
(interactive)
(let ((template (concat "#+GLOSSARY_KEY: glossary---" abbr "\n"
"#+ABBR: " abbr "\n")))
(denote title
'("glossary" "abbreviation")
'org
(f-join (denote-directory) "glossary")
nil
template)))
Exploration Notes
I arrived at the above code-block via the following exploration.
Customizing denote-directory
Prior to configuration my denote directory was ~/git/org/main/notes; I’m unclear why it chose this but it was a good guess as my org-roam-directory is ~/git/org and I have a capture template that writes to ~/git/org/main/.
With the configuration I’m partially sequestering my playground and will begin exploring.
Creating jf/denote-create-abbreviation
I had originally started exploring the denote-templates but chose to pursue a more explicit pathway which, based on my knowledge of Lisp, was straight forward and very quick.
There were a few turns that I took. An existing implementation for much of my tooling is that I’m assuming an Org-Mode properties drawer for the GLOSSARY_KEY and ABBR properties.
In Org-Roam the properties for the node go above the TITLE property; however by convention that is not how Denote is structured to work. I made some revisions.
I tested the above by creating a new Denote node for “Digital Humanities” with the abbreviation of “DH”.
Pause To Review Requirements and Reflect
At this point, I have verified checked off 4 of the 7 requirements. And reading ahead of the documentation I see that there are considerations for Linking and Exporting Links as well as searching.
Org-Mode aware
Tags
Quick filing
Linking
Metadata
Search
Export Links
At this point, what I really like is the interface to creating a note. The denote function does the magic and allows for me to pass parameters that override the default methods.
Contrast with Org-Roam, where I provide the title/text and then say what the template shouldl be.
I’m also liking the ease at which I could create a function for creating glossary entries. To do that in Org-Roam via capture is certainly doable.
The thing I need to check is how moving from the properties drawer approach I’ve used in Org-Roam varies from using keywords. Most of my interactions with properties are via Org-Mode’s API.
This sounds like the next pathway to explore.
Investigating Moving from Property Drawer to Keywords
Before I get too much further, I need to verify that I can continue to get properties from my notes.
The following function verifies that I can retrieve a property for the Denote note I made.
(cl-defun jf/denote-org-property-from-id (&key id property)
"Given an ID and PROPERTY return it's value or nil.
Return nil when:
- is not a denote file
- ID is not an `org-mode' file
- property does not exist on the file"
(when-let ((filename (denote-get-path-by-id id)))
(when (string= (file-name-extension filename) "org")
(with-current-buffer (find-file-noselect filename)
(cadar (org-collect-keywords (list property)))))))
(message "%s" (jf/denote-org-property-from-id :id "20220930T215235"
:property "ABBR"))
Let’s Look at Linking
For this, I’ll need another node. I now have two nodes: 20220930T221757 and 20220930T215235. Using denote-link I create a link in 20220930T221757 to 20220930T215235.
Then in 20220930T221757 I call denote-link-backlinks. The backlink buffer is an enumeration of links. Whereas in Org-Roam the backlink and reference buffer includes the surrounding context; a nice feature but not something I consider mandatory.
And below is my must haves:
Org-Mode aware
Tags
Quick filing
Linking
Metadata
Search
Export Links
What About Search?
I need to further explain what I mean by this. I am accustomed to using my own jf/org-roam-find-node which wraps org-roam-find-node. I can filter by tags and title. With denote, I have to consider directory structure.
Prefix the search with - for a tag and and _ for a word. This matches the functionality of what I have.
Conclusion
Reading and testing Denote, I have established feature parity in my functional needs.
What does that mean?
I am prepared to further pursue what it might mean to migrate my some 2800 Org-Roam notes to denote. I just completed a migration of my Hugo📖./data/glossary.yml file to Org-Roam, so I know that it’s not an arduous process to migrate.
Read about this data migration in On Storing Glossary Terms in Org Roam Nodes.
I already identified the need to move from property drawers to properties that are positioned in the file after the Denote front-matter. I’d need to revisit the Ox-Hugo export process I’ve developed. As well as how I’m exporting and creating links.
I would also want to look at different directories. I like separating the different concerns (e.g. glossary, epigraph) and the ease at which I could set this up.
There is quite a bit more to consider regarding this migration. But it is an interesting (to me) exercise of consideration.
01 October 2022 dwim-shell-command usages: pdftotext and scp
dwim-shell-command is a little Emacs package I wrote to enable crafting more reusable shell commands. I intended to use it as an async-shell-command alternative (and I do these days). The more surprising win was bringing lots of command-line utilities (sometimes with complicated invocations) and making them quickly accessible. I no longer need to remember their respective parameters, order, flags, etc.
Take u/TiMueller's Reddit comment, showcasing pdftotext. Neat utility I was unaware of. It does as it says on the tin and converts a pdf to text. Can be easily saved to your accessible repertoire with:
( defundwim-shell-commands-pdf-to-txt ()
"Convert pdf to txt."
( interactive)
(dwim-shell-command-on-marked-files
"pdf to txt""pdftotext -layout '' '.txt'":utils"pdftotext"))
tareefdev wanted a quick command to secure copy remote files to a local directory. Though this use-case is already covered by Tramp, I suspect a DWIM command would make it a little more convenient (async by default). However, Tramp paths aren't usable from the shell unless we massage them a little. We can use dwim-shell-command-on-marked-files's :post-process-template to drop the "/ssh:" prefix.
( defundwim-shell-commands-copy-remote-to-downloads ()
( interactive)
(dwim-shell-command-on-marked-files
"Copy remote to local Downloads""scp '' ~/Downloads/":utils"scp":post-process-template
( lambda (script file)
;; Tramp file path start with "/ssh:". Drop it.
(string-replace file
(string-remove-prefix "/ssh:" file)
script))))
When working on a large monorepo (like a ten-year-old Ruby on Rails app), we can use projectile-find-file to go to files but it be slow when the file list is long.
From projectile documentation, we can set the indexing method to alien to speed up the find file command:
(setqprojectile-indexing-method'alien)
This saves seconds when going to files and makes my action much crispier!
I just published the latest stable release of the Modus
themes. The change log
entry is reproduced below. For any questions, feel welcome to contact
me.
I will now prepare the patch for emacs.git (currently Emacs 29) which
will then trickle down to GNU ELPA (the modus-themes is a :core
package). Thank you for your patience!
Package name (GNU ELPA): modus-themes (also built into Emacs >= 28)
Backronym: My Old Display Unexpectedly Sharpened … themes
Support for packages or faces
Reinstated support for centaur-tabs. I had removed it in commit
2235ce5 (done on 2022-08-02) for version 2.5.0 of the modus-themes.
At the time I wrote:
centaur-tabs has a bug where it cannot read the value of a face if it
uses the standard `:inherit` attribute. I have sent a patch to fix it,
but have received no response since February:
<https://github.com/ema2159/centaur-tabs/pull/179>.
Relevant reports:
- <https://github.com/protesilaos/modus-themes/issues/30>
- <https://gitlab.com/protesilaos/modus-themes/-/issues/288>
- <https://github.com/protesilaos/modus-themes/issues/15>
I am happy to reinstate support for centaur-tabs as soon as the package
gets the maintenance it needs.
My patch/pull-request is now merged and the package is actively
maintained once again. Hence the decision to bring back support for
it, as promised.
Applied styles for the icon-button face of Emacs 29.
Styled the log-edit-headers-separator face of Emacs 29 (it was
introduced upstream by a patch of mine).
Made the gnus-summary-low-unread face inherit from the italic
face like the rest of that subgroup of faces. This helps
differentiate it from the gnus-summary-high-unread face. Thanks
to Mark Simpson for pointing out the possibility of conflating those
two faces: https://lists.sr.ht/~protesilaos/modus-themes/%3Cm2r0zszc2z.fsf@gmail.com%3E.
Covered the read-multiple-choice-face by adding a noticeable
background colour to it. The default attributes it has, which look
like other key bindings (bold and blue) plus an underline are
technically okay, though the context of this face is in the echo
area which is one line tall. Moreover, the highlighted keys are
inlined with other text. These make it difficult to spot the
highlights without some extra spacing. I use the addition of a
background in Org’s export dispatcher interface which also has some
unique requirements (the org-dispatcher-highlight face). The
principle is to have theme-wide consistency (e.g. “all key bindings
must look the same”) EXCEPT when the specifics require a different
set of styles in the interest of usability.
Added support for crontab-mode. Thanks to Antonio Ruiz for the
patch: https://lists.sr.ht/~protesilaos/modus-themes/patches/35080. It
is below the ~15 line threshold and thus requires no copyright
assignment to the Free Software Foundation.
Extended support for the company package’s company-scrollbar-bg
and company-scrollbar-fg faces.
Moved the selectrum-prescient faces to the prescient group, to
be consistent with changes in the respective upstream packages.
Thanks to okamsn for the contribution, which was done in pull
request 41 on the GitHub mirror: https://github.com/protesilaos/modus-themes/pull/41.
The user okamsn has assigned copyright assignment to the Free
Software Foundation, although this patch is within the allowed
limits.
Change to ‘fill-column-indicator’
Made the fill-column-indicator face more noticeable. It is what the
display-fill-column-indicator-mode uses to draw a line on where the
fill-column is.
[ I do not follow that mailing list, by the way. All my projects have
multiple communication channels and I always reply in a timely
fashion. Social media, fora about Emacs, generic mailing lists,
etc. are not among those channels.
https://protesilaos.com/codelog/2022-07-24-report-issues-official-channels/. ]
The core idea is that the previous design was (1) considered
“invisible” and (2) it prevented the customisation of the user option
display-fill-column-indicator-character.
I am addressing point 1, but point 2 puts us in an awkward spot as we
would then not be allowed to use a background and a height value. Not
doing so produces a dashed line by default, with the dashes further
apart the greater the line-spacing is (especially in, say, Org
headings that can have a greater height than paragraph text). It
looks broken and I keep getting requests to fix what is not the
themes’ fault. So no, the themes will remain opinionated in this
regard by ignoring display-fill-column-indicator-character through
the styling they apply to make the line contiguous.
For context, also read Emacs bug#57424 and please don’t take my words
in a private message out of context. If I need to state my opinion in
a public setting, I know how to do it.
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=57424.
Refinement to modus-vivendi ‘bg-diff-focus-removed’ colour
Made the default removed diff background slightly more luminant. The
colour is seen in diff-mode, ediff, and the Magit focused diff hunk.
When the user option modus-themes-diffs is set to either bg-only or
desaturated, this colour is used to highlight word-wise (“refined”)
changes. The increased luminance lets it stand out more compared to the
more subtle backdrop.
The built-in 'goto-address-mode' uses heuristics to identify URLs and
email addresses in the current buffer. It then applies a face to them
to change their style. Some packages, such as 'notmuch', use this
minor-mode automatically.
The faces are not declared with 'defface', meaning that it is better
that the theme does not modify them. The user is thus encouraged to
consider including (or equivalent) this in their setup:
(setq goto-address-url-face 'link
goto-address-url-mouse-face 'highlight
goto-address-mail-face 'link
goto-address-mail-mouse-face 'highlight)
My personal preference is to set 'goto-address-mail-face' to nil, as
it otherwise adds too much visual noise to the buffer (email addresses
stand out more, due to the use of the uncommon '@' character but also
because they are often enclosed in angled brackets).
Changes to the manual
Fixed a few typos and ensured that spelling using American English
as that is what emacs.git requires.
01 October 2022 dwim-shell-command usages: pdftotext and scp
dwim-shell-command is a little Emacs package I wrote to enable crafting more reusable shell commands. I intended to use it as an async-shell-command alternative (and I do these days). The more surprising win was bringing lots of command-line utilities (sometimes with complicated invocations) and making them quickly accessible. I no longer need to remember their respective parameters, order, flags, etc.
Take u/TiMueller's Reddit comment, showcasing pdftotext. Neat utility I was unaware of. It does as it says on the tin and converts a pdf to text. Can be easily saved to your accessible repertoire with:
(defundwim-shell-commands-pdf-to-txt ()
"Convert pdf to txt."
(interactive)
(dwim-shell-command-on-marked-files
"pdf to txt""pdftotext -layout '' '.txt'":utils"pdftotext"))
tareefdev wanted a quick command to secure copy remote files to a local directory. Though this use-case is already covered by Tramp, I suspect a DWIM command would make it a little more convenient (async by default). However, Tramp paths aren't usable from the shell unless we massage them a little. We can use dwim-shell-command-on-marked-files's :post-process-template to drop the "/ssh:" prefix.
(defundwim-shell-commands-copy-remote-to-downloads ()
(interactive)
(dwim-shell-command-on-marked-files
"Copy remote to local Downloads""scp '' ~/Downloads/":utils"scp":post-process-template
(lambda (script file)
;; Tramp file path start with "/ssh:". Drop it.
(string-replace file
(string-remove-prefix "/ssh:" file)
script))))
Denote is a simple note-taking tool. It is based on the idea that notes
should follow a predictable and descriptive file-naming scheme. The
file name must offer a clear indication of what the note is about,
without reference to any other metadata. Denote basically streamlines
the creation of such files while providing facilities to link between
them.
Backronyms: Denote Everything Neatly; Omit The Excesses. Don’t Ever
Note Only The Epiphenomenal.
Below are the release notes.
This is the first major release of Denote. A part of the changes
documented herein is for advanced users or developers who wish to
extend Denote with their custom code. Though we first cover what
applies to everyone.
Changes for all users
The custom Org hyperlink type of denote: can be visited from
outside the denote-directory. We now provide the necessary glue
code that Org needs to store these denote: links. Storing them
can be done with an org-capture template or via the command
org-store-link. Use this to, for example, capture a TODO that
references one of your notes.
denote: links work for as long as the referenced file is somewhere
in the denote-directory or one of its subdirectories.
Thanks to Marc Fargas for the contribution. Marc did not need to
assign copyright to the Free Software Foundation, as the patch was
within the ~15 line limit that is permissible.
Following from above, the command denote-link-find-file finds
files reliably, regardless of where the link is stored. All it
needs is for the target file to be inside the denote-directory.
The command denote-link-buttonize-buffer, which “buttonizes”
denote: links in plain text and Markdown files, now performs its
task regardless of where the current file is stored. Those links
work for as long as the file they reference is somewhere inside the
denote-directory.
The commands denote-link-after-creating, denote-link-or-create
provide a convenience for users who need to create link to notes
that may not exist yet. The idea is that one is expounding on a
given topic and wants to create a link to a relevant issue. They
are not sure if they have written anything about it yet, so they
invoke the relevant command. Consult their doc strings or read the
manual: https://protesilaos.com/emacs/denote#h:9e41e7df-2aac-4835-94c5-659b6111e6de.
Thanks to user sienic for suggesting the idea and for testing the
prototypes. And thanks to Juanjo Presa for participating in the
discussion to share the view that this functionality should be part of
denote.el. This happened in issue 96 over at the GitHub mirror:
https://github.com/protesilaos/denote/issues/96.
The command denote-open-or-create offers the convenience of
visiting a file, if it exists, else prompting for its creation.
Thanks to Alan Schmitt for the contribution. The patch was sent on
the mailing list: https://lists.sr.ht/~protesilaos/denote/%3C87fsgvddny.fsf%40protesilaos.com%3E.
It is within the limit of what is allowed without assigning
copyright to the Free Software Foundation, though Alan has done the
relevant paperwork.
The manual expands on two sections: (1) Variants of
denote-open-or-create, (2) Variants of denote-link-or-create.
They show how one can use the above “do or create” commands with
different permutations of the Denote prompts for new note creation.
The manual includes a section titled “Create a note with the
region’s contents”. Quote:
Sometimes it makes sense to gather notes in a single file and later
review it to make multiple notes out of it. With the following
code, the user marks a region and then invokes the command
my-denote-create-new-note-from-region: it prompts for a title and
keywords and then uses the region’s contents to fill in the newly
created note.
This is not part of denote.el, though we provide it in the manual
for users that may need it. Thanks to sundar bp for suggesting the
idea. This was done via a private channel and the information is
shared with permission.
The manual has another entry titled “Split an Org subtree into its
own note”, which is similar to the above idea of using the region’s
contents but has some extra niceties provided by Org. Quote:
With Org files in particular, it is common to have nested headings which
could be split off into their own standalone notes. In Org parlance an
entry with all its subheadings is a “subtree”. With the following code,
the user places the point inside the heading they want to split off and
invokes the command my-denote-split-org-subtree. It will create a
note using the heading’s text and tags for the new file. The contents
of the subtree become the contents of the new note and are removed from
the old one.
Thanks to Sven Seebeck for suggesting the idea and for testing my
prototypes. This information is shared with permission, as it was
provided via a private channel.
The manual describes how a user can leverage the built-in
dired-virtual-mode to perform arbitrary sorting of their list of
notes. It also includes code for Eshell to quickly “export” a
command’s output into a dedicated buffer (which can then be used to
derive a “virtual” Dired). Thanks to Yi Liu for asking the question
that inspired this entry:
https://lists.sr.ht/~protesilaos/denote/%3C1C75FF01-EC76-49DF-9AEB-ED718A2795FF@gmail.com%3E.
The denote-faces-broken-link has been removed. It was used for
Org links. The idea was to apply a different style if the link was
broken. However, the way fontification works means that there may
be a performance penalty as Org tries to check again and again if
the link is broken or note. As denote: links are robust (unless
the user tries to break them), this penalty is unacceptable. Thanks
to Peter Prevos for reporting the issue and discussing it with me on
the mailing list:
https://lists.sr.ht/~protesilaos/denote/%3C87k05umyyo.fsf%40prevos.net%3E.
The “denote” group in Custom UI buffers now provides a link to the
Info manual that is shipped with the package. To read the manual,
evaluate (info "(denote) Top"). Else visit the official web page:
https://protesilaos.com/emacs/denote.
Fixed a case where an internal check for a note would throw an error
if the buffer was not visiting a file. Thanks to Hilde Rhyne was
the patch: it is below the ~15 line threshold and thus does not
require copyright assignment to the Free Software Foundation. The
issue was discussed on the mailing list and was pushed to users as
version 0.6.1:
https://lists.sr.ht/~protesilaos/denote/%3Cm035d7nq22.fsf%40disroot.org%3E.
When linking to a file that has no front matter, Denote tries to use
the TITLE component of the file name (per our file-naming scheme) as
the link’s descriptive text. We now make this look a bit better, by
capitalising only the first letter while dehyphenating the text,
converting this-is-a-test to This is a test. Before, we would
capitalise all words. Thanks to Clemens Radermacher for the patch.
It was sent via a private channel. Clemens has assigned copyright
to the Free Software Foundation.
Changes for developers or advanced users
Lots of functions and variables which once were for “private” use (the
presence of double hyphens in the symbol) are now made public.
Concretely this means that they no longer have double hyphens in their
name and we pledge to support them henceforth. “Support” means that
we (i) consider them stable, (ii) document them properly, (iii) will
record any changes made to them such as in a change log, a blog post
on my website, and via make-obsolete.
Normally, we do not support private forms and can delete/modify them
without notice. However, I decided to write obsoletion aliases for
all forms I made public or otherwise revised, in an effort not to
break any existing custom code. The following table covers all
obsolete symbols and their new counterparts. PLEASE UPDATE YOUR CODE
as those aliases will be removed in the near future.
Index
Old symbol
New symbol
1
denote–id-format
denote-id-format
2
denote–id-regexp
denote-id-regexp
3
denote–title-regexp
denote-title-regexp
4
denote–keywords-regexp
denote-keywords-regexp
5
denote–punctuation-regexp
denote-excluded-punctuation-regexp
6
denote-punctuation-excluded-extra-regexp
denote-excluded-punctuation-extra-regexp
7
denote–sluggify
denote-sluggify
8
denote–sluggify-and-join
denote-sluggify-and-join
9
denote–sluggify-keywords
denote-sluggify-keywords
10
denote–desluggify
denote-desluggify
11
denote–only-note-p
denote-file-is-note-p
12
denote–file-has-identifier-p
denote-file-has-identifier-p
13
denote–file-supported-extension-p
denote-file-has-supported-extension-p
14
denote–writable-and-supported-p
denote-file-is-writable-and-supported-p
15
denote–file-name-relative-to-denote-directory
denote-get-file-name-relative-to-denote-directory
16
denote-link–id-from-string
denote-extract-id-from-string
17
denote–directory-files
denote-directory-files
18
denote–subdirs
denote-directory-subdirectories
19
denote–get-note-path-by-id
denote-get-path-by-id
20
denote–directory-files-matching-regexp
denote-directory-files-matching-regexp
21
denote–retrieve-read-file-prompt
denote-file-prompt
22
denote–extract-keywords-from-path
denote-extract-keywords-from-path
23
denote–keywords-prompt
denote-keywords-prompt
24
denote–retrieve-filename-identifier
denote-retrieve-filename-identifier
25
denote–file-name-id
denote-retrieve-or-create-file-identifier
26
denote–retrieve-filename-title
denote-retrieve-filename-title
27
denote–retrieve-title-value
denote-retrieve-title-value
28
denote–retrieve-title-line
denote-retrieve-title-line
29
denote–retrieve-keywords-value
denote-retrieve-keywords-value
30
denote–retrieve-keywords-line
denote-retrieve-keywords-line
31
denote–format-file
denote-format-file-name
32
denote–barf-duplicate-id
denote-barf-duplicate-id
33
denote–title-prompt
denote-title-prompt
34
denote–file-type-prompt
denote-file-type-prompt
35
denote–date-prompt
denote-date-prompt
36
denote–subdirs-prompt
denote-subdirectory-prompt
37
denote–template-prompt
denote-template-prompt
38
denote–filetype-heuristics
denote-filetype-heuristics
39
denote–rename-file
denote-rename-file-and-buffer
40
denote–rename-file-prompt
denote-rename-file-prompt
If you are writing code that extends Denote and feel that something is
either missing or has remained private, please contact us on the
mailing list, the GitHub/GitLab mirror, or send me an email directly.
I always respond in a timely fashion.
Open to everyone
The most common feedback I get about Denote is that its documentation
is good. As you can tell from these change logs, the plan is to
continue on this path.
Please note that the communication channels for Denote (mailing list,
mirrors, my personal email) are open to users of all levels. Do not
hesitate to contact us/me.
Thanks again to everyone for their contributions, direct or indirect,
either in the form of code or the discussion of ideas. Quoting from
the “Acknowledgements” section of the manual (all my packages have
such a section):
Denote is meant to be a collective effort. Every bit of help matters.
Author/maintainer: Protesilaos Stavrou.
Contributions to code or the manual: Abin Simon, Alan Schmitt,
Benjamin Kästner, Clemens Radermacher, Colin McLear, Damien Cassou,
Eshel Yaron, Hilde Rhyne, Jack Baty, Jean-Philippe Gagné Guay, Jürgen
Hötzel, Kaushal Modi, Kyle Meyer, Marc Fargas, Peter Prevos, Philip
Kaludercic, Quiliro Ordóñez, Stefan Monnier.
Ideas and/or user feedback: Abin Simon, Alan Schmitt, Alfredo
Borrás, Benjamin Kästner, Colin McLear, Damien Cassou, Elias Storms,
Frank Ehmsen, Hanspeter Gisler, Jack Baty, Juanjo Presa, Kaushal
Modi, M. Hadi Timachi, Paul van Gelder, Peter Prevos, Shreyas
Ragavan, Summer Emacs, Sven Seebeck, Taoufik, Yi Liu, Ypot, atanasj,
hpgisler, pRot0ta1p, sienic, sundar bp.
Special thanks to Peter Povinec who helped refine the file-naming
scheme, which is the cornerstone of this project.
Special thanks to Jean-Philippe Gagné Guay for the numerous
contributions to the code base.
The video is a series of demonstrations of some of that ancient code. It starts with showing what a pain it was to use TECO. It did, however, have a macro language that was fairly capable and Emacs famously began life as a set of macros for TECO. It’s where the name Emacs comes from: Editing MACroS. It was a sort of compilation of the TECO macros that individual users at MIT’s AI labs had written. The idea was that then everyone would be working in the same environment.
Since Emacs was originally written as TECO macros, it wasn’t very portable so it was rewritten in various languages such as LISP and C. The video gives a demonstration of some of those old systems. If nothing else, watching them will show you how good we have it now.
Now, of course, Emacs is synonymous with GNU Emacs, which is available on essentially any platform that matters. Brinkhoff tells a nice story. What began as a way of letting hackers share someone else’s TECO session has blossomed into what many of us consider the world’s best editor. Not everyone agrees with that last assessment but none but the ignorant doubt that it’s certainly a contender.
The video is about 41 and a half minutes long so you’ll need to schedule some time. If you’re interested in old Emacs implementations and how things used to be, take a look at the video.
Before I explain what this is, here is the dictionary entry for
AGITATE: Another Git Interface Trying to Agitate Tranquil
Emacsers. 🙃
agitate is a work-in-progress collection of commands or potentially
useful functions that expand on the available version control features
of Emacs. Those are meant to complement a workflow that relies on the
built-in Version Control (VC) framework and its accoutrements:
diff-mode.el, log-view.el, log-edit.el, vc-git.el, and
potentially others.
The package is available only on the GNU-devel ELPA for the time
being. I shall release a stable version when the time is right. I
explain all about it the “devel” archive and relevant topics here:
https://protesilaos.com/codelog/2022-05-13-emacs-elpa-devel/.
At this stage, the intent is to iterate on the agitate code in order
to surface the best practices and, perhaps, discover the most common
missing requirements of VC users. The emphasis is on the Git backend,
as that is what I am using, but there is no reason to limit the code
to it. I do want to learn about other version control systems.
Unlike most of my packages, agitate has a maximalist scope by
design. Instead of, say, adding only to vc-git.el it takes a
broader view of the entire workflow of VC, which ties together
processes from different libraries (e.g. on Emacs 29, C-x v v
(vc-next-action) in a diff-mode buffer will produce a
log-edit-mode buffer to commit the changes).
Torstein Johansen has an interesting video on using Emacs as an IDE for shell programming—especially Bash shell programming. We, or at least I, don’t usually think of shell programming as requiring an IDE but as Johansen shows, a bit of Emacs configuration can significantly ease the task.
He starts off with sh-mode and shows how to adjust the indentation. That gives you syntax highlighting and automatic indentation. Add autocompletion (with Hippie Expand) to help with entering code and navigation (mostly with Projectile) to make finding functions—even if they’re in a different file—easy and you’ve got a good basic Emacs setup for working on shell files but Johansen doesn’t stop there.
He adds LSP and flycheck-mode for advanced navigation and code linting. He shows how to run your script right from Emacs and even how to output an execution trace. He also shows how to run unit tests and perform debugging. Those require adding separate packages and binaries, of course, but if you do a lot of shell programming it’s well worth the effort and space on your system.
Finally, he covers some of the yasnippets that he uses and gives a quick demonstration of git-change-markers. Neither is particular to shell scripts, of course, but they can be useful.
Again, if you regularly work with shell scripts, this video is worth your time. It’s about 18 and a quarter minutes so plan accordingly.
WEATHER UPDATE[2022-09-28 Wed 14:03]: Ian came ashore near Ft. Myers (about 100 miles south of Tampa). Lots of flooding there but things in Tampa are still calm except for moderate, continuous rain. We’re still expecting strong winds and lots more rain as Ian moves up the peninsula.
This post was originaly published on 2022-09-27. Updated 2022-09-28, to include the improved script.
It’s been a year, since I figured out the hack that finally let me use my Compose key in Emacs.1
Without it, I am unable to type any kind of quotation marks or umlauts in emacs.
A year in, and I’m tired of restarting the service everytime the machine comes on. The computer can do that for me.
So I whipped up this tiny bash script
1
2
3
4
5
6
#!/usr/bin/env bash
if[[$(($(pidof -s emacs))) -le 10000]]; then systemctl --user restart emacs;
else :;
fi
It just arbitrarily checks for the Emacs service’s PID and then if it’s lesser than or equal to 10000, it goes ahead and restarts the service.
This is just some superstitious thing I did, because when I was troubleshooting all those months ago, I assumed that if Emacs started at an ID in the low thousands, it must not have been loading something and restarting it to get a higher process ID meant what ever it needed must have loaded.
I learnt a couple of things doing it this way too.
The output of a bash command is a string.
I use $(( some_numerical_string )) to convert said string into an integer
: means pass in bash-speak
What I ought to do is to check for the existence of a PID and if there is one, to then go ahead and restart emacs. I’ll do that some other time. Because right now, I put this script into my system startup and it just works.
Update 2022-09-28
I obviously am incapable, of leaving well enough alone.
As I was in the bath this morning, it struck me that I was restarting the service using systemctl restart …
So I could just check for the exit status of a systemctl status command, and then depending on what I got, do something. If it was running, I could just restart it.
I checked on the command line and sure enough, if a service is running, the exit status is 0 and if it isn’t, the status is 3 .2
So … then I monkeyed with the script to this
1
2
3
4
5
6
7
#!/usr/bin/env bash
if systemctl --user status emacs > /dev/null; then systemctl --user restart emacs;
else :;
fi;
If the emacs service is running, restart it, else do nothing.
This ought to quiet the monkey brain for a while.
I hope 🙂
As is our wont, we spent the day gallivanting in a jungle and having an accident.
And then crying for a while and then laughing about what a story it would be for the rest of our lives.
Much like our marriage.
We make the best stories, don’t we?
And I am who I am, because of you.
Eleven years, and it still feels like only yesterday. 1
I love you.
Like the old hymn goes …
You alone are my strength, my shield … to you alone may my spirit yield
You alone are my hearts desire … 🎵
We still compare our wedding pics with other folks, unilaterally declaring ours the much better set. ↩︎
I remember, when I first learned it, the Org Manual mentioning I could have code, quotes, poetry and sundry self structured blocks of text, where the text in that block would flow like I wanted it to. I could have indentation or line breaks as I pleased.
And then I promptly forgot about it.
The only thing I did remember were code blocks.
And that I needed to do a #+begin_src and then a #+end_src and put my code in the middle. And all this while, I would keep typing it in, by hand.
Until I tired of keeping on doing that shit, because there are more and more notes that are now going into my zettelkasten and decided well, the computer can do that for me.
So, I went back to the Org Mode documentation and discovered Structure Templates.
And now, I am at peace!
Turns out, all I needed was (org-insert-structure-template) aka C-c C-,
Here’s some code I’ve selected in a document
Now I hit C-c C-,, which brings up a whole host of options, with a prompt!
Do I want this block of text to be a quote? Or some verse?
Well, this is just boring code, so I choose source with the s key
And tada! The block is surrounded by the begin and end tags, and is now a source block! I could add the programming language after #+begin_src to get highlighting as well, but that’s a story for another day.
I’m practicing this, so that I get C-c C-, into my muscle memory, because be it verse, quote, code, example or exports, I know I will be making heavy use of Structure Templates.
This post started as a place for me to perform analaysis on my existing blogging ecosystem. The goal is to consolidate where I’m “storing” information. The strategy is moving elements of my blogging ecosystem into my Personal Knowledge Management (PKM 📖) system; and then exporting those back to my blog.
Table 240:
Take on Rules’s Glossary Entity Attributes
Attribute
Status
Description
abbr
Optional
A short-hand means of referencing the entity; it’s abbreviation
auto_mention
To Remove
Used by `glossary:autoMention` rake task
content_disclaimers
Optional
Connects this entry to a content disclaimer
described
To Remove
Have we already described this node; useful for preventing repeat querying of Wikidata
description
Optional
A terse explanation of the entry; often imported from Wikidata
game
Optional
Indicates the entry is a game; the value should be the entry’s key
itemid
Optional
A URL that disambiguates this entry ; From https://schema.org
itemtype
Optional
Further specification on the classification of this entry; From https://schema.org
key
Required
How we programatically reference this entry
mention_as
Optional
When we add a mentionAs attribute use this value; From https://schema.org
offer
Optional
The URL from which you can buy the item; From https://schema.org
plural_abbr
Optional
The plural form of the abbreviation
plural_title
Optional
The plural form of the title
same_as
Optional
Connect the item to a more verbose description (e.g. a Wikipedia article)
tag
Optional
When used as a tag, add a "mention" node
title
Required
How we linguistically reference this entry
verbose_title
Optional
A more expressive title
Considerations for Migrating Glossary into Org Ecosystem
What would it look like to move the glossary into my Org ecosystem?
Let’s consider the following:
What would be the benefit?
What would be the storage strategy?
How to map the YAML entry to the Node’s data structure?
What are the ways in which Take on Rules references the glossary?
What Would be the Benefit?
The primary benefit that I see is in consolidation. Right now the benefits of the glossary are only available in my blogging ecosystem. And the “capture” process for those entries is outside of my normal capture process.
Further, in consolidation there is the process of thinking through the “problem” and designing a solution. The very thought exercise itself is enriching.
What Would Be the Storage Strategy?
I see two options: ./glossary or ./refs. The advantages of ./glossary is crisp demarkation. However I envision “promotion” or “drift” of refs into glossary items.
Decision
Store nodes in ./refs and add tag :glossary:
How to map the YAML entry to the Node’s data structure?
Org-Mode📖 has different link handlers. One example is the roam: scheme; a scheme added by Org-Roam📖.
The org-link-set-parameters exposes a means of registering new schemes.
I have two “links” that I want to add: abbr: and abbr-plural:. The goal is to use my glossary to “link” to an entry that has an abbreviation and then at the point of export expand that abbreviation.
Reading the org-link-parameters documentation there are functions I want to set for both abbr: and abbr-plural::
:complete
What are the possible entries I have that meet the criteria? (e.g. have an abbreviation?)
:export
When I export this link, what should logic should I use? (e.g. for HTML 📖, I should use an ABBR-tag, for other things the title (abbreviation) is perhaps best)
:follow
When I “click” on the link in my Org-Mode document, how should it resolve? Where should it go?
In my blog I’ve used the DFN-tag; and that could be useful. But there’s always a matter of flow regarding a term and it’s definition.
Data Migration
I want to export my ./data/glossary.yml to Org-Mode. There are some glossary entries that already have nodes in Org-Roam; for those I need to reconcile and adjust. For the others, I need to create a node for each glossary entry.
Once that is complete, I will stop adding and editing entries in ./data/glossary.yml; instead I will export them from my org repository to that file. An ideal test is that when I complete the round trip, my ./data/glossary.yml is unchanged.
I already do this for Epigraphs, so follow a similar “public” api process.
Conclusion
After a bit of time and exploration, I have enriched my understanding of the Org-Mode / Org-Roam ecosystem and further worked towards treating my blog as a “consumer” of my PKM system.
I’ve also solidified my love of cl-defun, &key parameters, and providing defaults. This helps me repurpose functions and think about their interactions. It’s a pattern I’ve also applied in my Ruby code.
An example perhaps? The following is a method signature: (cl-defun jf/org-roam-external-url-for (&key node (scheme "http"))
To call that method I write the following: (jf/org-roam-external-url-for :node the_node); where the_node is an Org-Roam node. By default I’m looking for URLs that start with the http scheme.
Instead of burying the default http in the method definition, I parameterize it and specify the default.
This is just a quick update on the status of Eclipse JDT Language Server support
in Eglot.
Since my Python skills are close to none, Roland Grunberg kindly stepped
forward1 to make sure that jdtls can take care of setting up everything in
order to avoid ugly workarounds in Emacs2 and, I guess, other text editors
and IDEs as well.
The fix will be available on the next Eclipse JDT milestone3. However,
nothing stops you from grabbing the latest snapshot build4 and M-x
eglot away in your Java projects.
Even though I am not working with Java these days, it’s good to know that I
could do it in Emacs with the nice features LSP offers.
Emacs Berlin (virtual, in English) https://emacs-berlin.org/ Wed Sep 28 0930 Vancouver / 1130 Chicago / 1230 Toronto / 1630 GMT / 1830 Berlin / 2200 Kolkata – Thu Sep 29 0030 Singapore
M-x Research (contact them for password): TBA https://m-x-research.github.io/ Tue Oct 4 0800 Vancouver / 1000 Chicago / 1100 Toronto / 1500 GMT / 1700 Berlin / 2030 Kolkata / 2300 Singapore
Emacs users group Slovenia https://emacs.si/ Thu Oct 6 1100 Vancouver / 1300 Chicago / 1400 Toronto / 1800 GMT / 2000 Berlin / 2330 Kolkata – Fri Oct 7 0200 Singapore
I tried folks, I really tried, but for now, I can’t use Emacs for my technical writing, as much as I’d like to. This is far from over though. I’m planning a comeback sooner than later… Here are some of my thoughts so far.
The first, obvious reason I’m working in Word is: Everyone has it. We all have Office 365 accounts at work, which means everyone has either the full version of Word, access to the lighter online version, or even the app.
As I mentioned, I can paste HTML code directly from Emacs, but the problem is that KB articles are static. As I work with different subject matter experts (SME/SMEs in techcomm lingo) and technicians, Word’s ability to add comments to highlighted lines is critical. Indeed, when I work on a draft, it makes sense to start with a Word document first and worry about copy-pasting the article itself to ServiceNow later.
Ah yes, copy-pasting. The bread and butter of text editing outside of Emacs. Yes, I know how horrible Word’s HTML code is when you paste it directly, but it seems to litter less junk through ServinceNow’s WYSIWYG editor. That is, if I skip inserting HTML code directly (which is what I do with Emacs) and simply copy-paste from Word, the headers, links, and even the images are pasted and uploaded to the KB I’m working on automatically.
That last part is big. Working with images in Emacs is cumbersome. If I want to keep things organized, I need to attach images to the org file I’m working on (with org-attach) and attach the image file (with C-u C-c C-l) to see them in the org file1. I then need to individually upload the images into ServiceNow and place them where they belong in the text again, since copy-pasting from an HTML file does not copy over the images into ServiceNow.
Besides the easy copy-paste from Word and having comments in the article, There are plugins. For example, we might use Grammarly, which plugs into Word directly2. Of course, Word also plays nice with Outlook and Teams, and it’s easy to attach and share documents and work with OneDrive, all part of the Office family that is available to and used by all.
Am I happy? No. But I’m satisfied for now.
I’ve created great workflows in org-mode. Checklists, clear steps with fewer images that show numbers and arrows for those steps3, helpful links that link to other related entries using my custom IDs, Footnotes, and more. These are great for my own notes and wikis, where I keep using org-mode for hours every day.
Also, Word sucks. I complained about it time and time again. It simply doesn’t make sense. The ribbon has a way of adjusting to the Window’s width, hiding important buttons (which I learned to recognize by the icon) until I adjust its size. Office also decided that since I use a dark theme for Windows, I will also want a dark theme for Word, and the color pallet for it is terrible; comments highlighting is nearly invisible, for example. It has this annoying feature that changes the direction of the mouse cursor to point right (as if I chose the left-handed cursor) whenever I edit a document, for whatever reason. It also decided to lay pages side by side for me, if my Window is wide enough, confusing my reading order. It takes forever to launch and has mysterious hangs that I’m trying to resolve. It… sigh. I’ll say it one more time: it sucks. The fact that everyone uses it does not make it better, but it does mean, unfortunately, that you have to know how to use it at least.
For all of its annoyances, Word has “features” Emacs doesn’t have. And you know what..? I’m fine with that. All of these things are terrible in Word, and I can’t even imagine how horrid they’d be in Emacs.
Still, this is just a setback. I figure I’ll learn to use Word again to the point I can get it to do what I need, and then turn around and see how I can make it work with Emacs without sacrificing efficiency. This will happen sometime down the line.
Comments?
Reply to this post on Mastodon,Twitter, or you can always email me: taonaw<at>protonmail<dot>ch (for GPG, click the lock icon on the navbar to the left).
Footnotes
Another issue with org-mode and my new technical writing workflow is placing an image in a numbered list. I often need to do this as I write instructions. The image has to come at the end of the line of text of that step, without a line break, or the org-mode will consider the line break as the next step or otherwise break out of the list structure. In the org file itself, this is not a big problem, the images will still show under the text (I usually work in a narrow frame). However, when you convert the file to HTML, it will mess up the text. This means placing images with text requires more work. ↩︎
Yes, alternative methods exist. I discussed langtool in Emacs, for example, which I use several times a week. While language tool is a good choice for my personal writing though, it is not the kind of service that offers the level of support Grammarly does. To me, it’s like comparing Gimp and Photoshop. ↩︎
To see an example of what I mean, take a look at my post about customizing a theme. The image at the bottom of the post has arrows and numbers. I use these for my notes often, one image that summaries several steps described in the text above. This method however is not as straightforward enough when you need to share instructions. ↩︎
I want to open youtube links in my notes in mpv instead of opening the
browser
When exporting to HTML, youtube links should become embedded videos instead
of hyperlinks
Implementation
Org has a concept of 'link types'. We can add a new type of link and have it
behave the way we want.
org-link-parameters
This variable contains link types and how they behave on follow (i.e when
someone opens the link with C-c C-o), export etc. A type of a link is
determined by the string before first ":" in it. e.g "https://bitspook.in" has
https type, "file:///etc" has file type.
Items in this list has 2 main components:
First element is string representing the link type
Key-value pairs of behavior name (e.g :follow, :export) and
function which handles that behavior
This function is used to add new link-types (and also to add new behavior to
existing ones). You can check the docs for org-link-parameters (with C-h v
org-link-parameters) to see arguments provided to each type of callback.
make-process will create a background buffer named *yt://<url>* which
allow monitoring and killing the mpv process.
Update: Use make-process instead of async-shell-command for launching mpv.
Thanks to nv-elisp on /r/emacs
Result
C-c C-o (i.e org-open-at-point) on a yt:// link opens the youtube video
in mpv
C-u C-c C-o (i.e org-open-at-point with an prefix argument) on a yt://
link opens the video in browser
When exported to HTML, all yt:// links file are exported as embedded
youtube videos
Bonus gains 💪
Recently I've been building a tool (cl-ownpress) which to make blogging a
zero-effort activity for me. Since I have already built a habit of judicious
note taking, publishing a subset of my notes will enable maintaining an active
blog without doing any "work".
I've also been making thickly-accented-awkardly-narrated youtube videos. These
are almost always tldr; videos for my blog posts. So they get embedded in my
blog posts.
'Blog with notes + embed youtube videos' become easier to do with this little
tinkering. Since cl-ownpress uses my running Emacs to publish my posts, I don't
need to make any change in my blogging setup. I can embed my tldr; videos in
my blog posts by just prefixing youtube links with yt:// instead of
https://.
I am pretty happy that I got zero work blogging-setup, and zero work
extending-the-blogging-setup as well.
Today I would like to talk about three separate tools, and how we can combine them with the power of Emacs.
Our tools for today are:
Fennel - a Lisp-like surface syntax for Lua that makes programming in Lua fun and more robust.
Org Mode - a markup language and an application inside Emacs, which allows its users to create documents that include interactive pieces of code.
LÖVE - a game engine that allows programming games in Lua.
This post is itself a program, describing how you could create similar Org documents and explore literate programming/reproducible research with Fennel, or other languages for that matter.
It’s possible thanks to Org Mode and my new package ob-fennel, which implements necessary functions for sending Fennel code blocks to the REPL process.
For a better experience, you should read this in Emacs, and you can get the original .org file from here.
If you want to follow the instructions, make sure to install Fennel and LÖVE for this to work.
Bootstrapping LÖVE
First, we need to bootstrap LÖVE so it could understand Fennel code:
local fennel = require "fennel"table.insert(package.loaders or package.searchers, fennel.searcher)
We’ve required fennel the library and registered the fennel.searcher function as one of the functions responsible to loading files.
With that, theoretically, we no longer need to write any more Lua code, and instead, we can write in Fennel, and then use plain Lua’s require to load the files.
Let’s create a REPL (Read Eval Print Loop) that will allow us to do interactive programming in LÖVE via its thread and event systems.
First, let’s require fennel once again, and also require love.event.
Next, we’ll do a little trick that I’ll explain later, but for now, we’ll only need to capture the module-scope value of ... into variables event and channel:
This will make sense in a moment.
Now, we need a REPL itself.
REPL consists of the prompt that asks for more input, and the loop that calls the prompt which reads some input and sends it to a channel.
Let’s define the prompt function first:
Now, we can create the infinite loop, that will read from stdin and push the read value into LÖVE’s event system.
That’s where we’ll use the captured event variable, however, we’ll need to run this loop only in a LÖVE thread, so we’ll check if the channel was bound:
Once data appears in the channel, this function exterminates what pattern it received.
It is always a table, where the first element means the kind of data, and the rest of the table is the data itself.
That’s the protocol we’re going to write in a moment.
The loop check if the event-type is either :data or :error and acts accordingly.
In addition to that, there’s a third event-type :next-line which represents the situation when the REPL receives incomplete input and waits for more lines.
Let’s implement this protocol:
This is an asynchronous REPL, made with Lua’s coroutines.
You may wonder, how it will start the loop function if it was under the when channel guard, but that’s exactly what this piece of code does.
First, it loads itself via love.filesystem.read and compiles Fennel code to Lua via fennel.compileString function.
Next, this compiled representation is used to create a FileData object, that is used to start a LÖVE thread with the love.thread.newThread function.
So this module will be executed twice - first when main.lua loads the file, and second, when LÖVE spawns the thread, but were not there, yet.
After we’ve created the thread we create an io-channel and the REPL coroutine.
Next, we start the coroutine by passing it a table of functions, each of which will push data to the io-channel.
Importantly, the readChunk function pauses the coroutine after every read, allowing it to run asynchronously within the main thread.
Finally, we start the thread by passing :eval which will be bound to the event variable, and io-channel which will be bound to channel.
This thread spins the loop function, which blocks the thread waiting for the input, while the main LÖVE thread continues to run.
With all of that, we can finally require the repl.fnl file in the main.lua like this:
require "repl"
Also, let’s disable vsync while we’re at it.
For some reason, it makes the REPL slow on my machine.
We won’t be needing it anyway:
functionlove.conf(t)
t.window.vsync = 0
end
Now we can start hacking in real time!
Drawing plots
Since we’re done with the literate programming example, let’s look at how the reproducible research can be organized.
I’m sure you should be familiar with the concept of a notebook, like R Markdonw or Jupiter.
We’re going to achieve something like that.
If you’re reading this file in Emacs, which you should, press the C-c C-v t shortcut, which will run the org-babel-tangle function.
After executing it, Emacs will create three files main.lua, conf.lua, and repl.fnl in the same directory as this file.
If you’re not reading this file in Emacs, then, well, get Emacs, or just believe me - it works.
Let’s plot a function via LÖVE2D and Fennel.
I’m not sure if there’s a library for drawing plots with LÖVE, but it’s ain’t fun to use something like that anyways, so let’s build our own!
First, we’ll need a Canvas object to draw to:
(local canvas (love.graphics.newCanvas 640 480))
Put the cursor in this source code block and press C-c C-c shortcut (or call the org-babel-execute-src-block function with M-x)
The empty LÖVE window will appear, and Emacs will display a message in the prompt area, with the contents something like “Please re-evaluate once Fennel is initialized”.
We won’t be needing this window, so you can minimize it - we’ll be drawing off-screen onto a canvas and then saving it as an image.
Org-mode provides us with all we’ll need to preview results without leaving Emacs.
Once Fennel is loaded, and all threads were spawned, hit C-c C-c again, and you should see "nil" in the echo area.
This means that the code was executed successfully and the canvas variable was created.
Now, let’s write a function that will draw a grid to the active canvas.
First, we’ll need a function that will calculate the grid step based on the zoom level.
Our zoom level is represented in percentages, which we’ll later convert to values by dividing by 100.
However, for our grid, we will be doing an infinite zoom with finite details.
This function computes the step between each grid line based on current zoom level.
It’s a bit convoluted, but the key here is the bitwise or operator - that’s what makes our grid cycle between zoom levels properly.
We now can define the function that computes and draws the grid itself:
This function actually draws two grids - one for unit size, and one for 1/10 of the unit size, and applies dynamic transparency based of the zoom level.
This way, we can create an illusion of the infinite zoom level, that
It’s a bit verbose, but all it really does is create a table of line segments from the center of the canvas in all four directions with the calculated step interval.
This only draws the grid, though, we also need to draw the X and Y axis, with some markings indicating the zoom level:
(fn draw-axis [zoom]
(let [(wh) (: (love.graphics.getCanvas) :getDimensions)
step (calc-stepzoom)]
(love.graphics.setLineWidth 1)
(love.graphics.setColor [0.3 0.3 0.3 1])
(love.graphics.line [(/ w 2) 0 (/ w 2) h])
(love.graphics.line [0 (/ h 2) w (/ h 2)])
(let [h (/ h 2) w (/ w 2)]
(for [xstepwstep]
(love.graphics.line [(+ xw) h (+ xw) (+ h 2)])
(love.graphics.print (string.format "%.1f" (/ xzoom)) (+ xw) (+ h 5)))
(for [x (- step) (- w) (- step)]
(love.graphics.line [(+ xw) h (+ xw) (+ h 2)])
(love.graphics.print (string.format "%.1f" (/ xzoom)) (+ xw) (+ h 5)))
(for [ystephstep]
(love.graphics.line [w (+ yh) (+ w 2) (+ yh)])
(love.graphics.print (string.format "%.1f" (- (/ yzoom))) (+ w 5) (+ yh)))
(for [y (- step) (- h) (- step)]
(love.graphics.line [w (+ yh) (+ w 2) (+ yh)])
(love.graphics.print (string.format "%.1f" (- (/ yzoom))) (+ w 5) (+ yh)))
(love.graphics.print 0 (+ w 5) (+ 5 h)))))
This function works similarly to the draw-grid one, except it only draws two lines intersecting at the canvas’ center, and the numbers, indicating units of measure.
Each number also has a small mark at the axis for better readability.
Finally, let’s write a function plot that will accept a function fun which it will plot on the canvas, and some additional arguments, like from, to, step.
Also, did I mention that you should press C-c C-con each code block in this section?
It will send the code to the running LÖVE process, and we will be able to see the results dynamically.
But before we do that, let’s write a function that transforms so-called world coordinates to screen coordinates:
This function uses the renderTo method of the canvas object.
It accepts an anonymous function, which draws the gird, the axis, sets the color of the plot to red, and finally draws the plot with love.graphics.points.
We can execute it like that, by pressing C-c C-c on the next code block:
This produces an image, which you should see if you call the org-toggle-inline-images function.
As you can see, it plots a simple function, but we can plot any other, like :
We can plot it like this, passing the table via the :var data=lines header property:
(plot-table {: data:zoom 1000})
You can build more complex functions, that, for example, draw several graphs on the same canvas, or draw entirely different types of graphs altogether.
Though this requires defining functions for all these kinds of visualizations, and I guess this is why people tend to use other languages for the task, like R.
Inline evaluation
Well, graphs are cool and all, but what about supplying values into the text directly?
We can do that too, and although, we don’t really need LÖVE for that, that’s a great way to showcase the ability to run multiple instances of Fennel, using completely different environments!
For example, suppose we have some kind of a formula, that, for example, calculates the Ackermann function:
(fn A [mn]
(if (= n 0) 0
(= m 0) (* 2 n)
(= n 1) 2
(A (- m 1)
(Am (- n 1)))))
We can define the function using the (fn square [n] (A 1 n)), and use it like (square 4) producing 16 as a result.
Or, we can define a function that computes like this: (fn two⇈n [n] (A 2 n)).
Calling it as (two⇈n 4) gives us 65536.
These code blocks are running in a separate session, using a regular Lua interpreter, instead of our LÖVE REPL.
This is done by specifying the :session header argument, and giving it a name, which instructs ob-fennel to spawn a new process.
Upon exporting, the results of the inline evaluation would update automatically which eliminates the problem of stale data in the paper.
The results always reflect the actual code they were computed with.
The power of Org
The examples above are just the tip of the iceberg of what you can do with the Org package.
Back when I wasn’t an Emacs user, I often found threads on the topic “why should I use Emacs?” and each of these threads contained at least one answer which just said “Org Mode”.
I never understood why - what’s so good about Org that I can’t get from, say, Markdown?
Since then, I’ve switched to Emacs and started this blog, using Org Mode, Hugo, and the ox-hugo package.
Org mode has a built-in exporting engine, which can export .org files to PDF, ODT, LaTeX, Markdown, or HTML files.
The ox-hugo package adds another backend for this engine, which exports to Hugo compatible markdown, which is then used by Hugo to build this website.
And when I was starting this blog, I wasn’t sure that I made the right investment - I’ve just switched to Emacs a couple of months before, and I’m using this Org thing for writing.
I was uneasy because if I would stop enjoying writing in this setup I might lose all motivation for writing altogether.
But thankfully, I’ve liked the Org+Hugo combination, and it became the reason why I haven’t left Emacs since - it’s just too good as a writing experience.
Literate programming was the way I learned Org.
I’ve used it to configure Emacs because Org Mode provides a way to load .org files as Emacs Lisp files, and you can replace your init.el with init.org if you want to.
But to be honest, it’s a fun experiment, but I don’t find literate programming to be that practical.
It’s even harder to consider, given that there aren’t a lot of tools besides Emacs, that allows writing programs in this style using any language.
And you can’t just make your coworkers use Emacs all of a sudden.
Yes, there are solutions specific to a particular language, but they lack usability in my opinion.
Reproducible research was a hot topic lately, and the growing popularity of Jupiter notebooks is a great indication.
Org Mode might not provide all the fancy UI elements, that Jupiter notebook has, but theoretically speaking, nothing prevents you from writing a UI in a standalone tool, like the game engine, and using it as a rendering frontend from the comfort of Emacs.
This post partly shows this, although, I went a more static route with embedded images.
But still, anything is possible if you have the dedication to do it.
I hope this post was an interesting read, and you’ve become interested in Emacs and Org Mode, or even in Fennel and LÖVE combo.
Feel free to contact me if you have any questions on the topic.
See you soon!
A short post for a lazy Sunday. Grant Rettke over at Wisdom and Wonder has a quick tip. He recommends trying describe-symbol for invoking Emacs builtin documentation. He says that it’s almost always what you want when you invoke describe-function or describe-variable. As far as I can see, it’s the same information. I looked at the source code but it was hard to tell if it adds extra data or not.
You invoke it with Ctrl+ho so if nothing else you need remember only one shortcut for your documentation needs.
UPDATE[2022-09-25 Sun 16:31]: Grant remarks in the comments that one of the reasons he likes describe-symbol is because it tells you when there is a variable and function with the same name.
Every now and then I've wished to write comments on files in a project, but I've
never found a good way to do that. annotate.el and org-annotate-file both
collect annotations in a central place (in my $HOME), while marginalia puts
annotations in files next to the source files but in a format that's rather
cryptic and tends to be messed up when attached to multiple lines. None of them
is ideal, I'd like the format to be org-mode, but not in a central file. At the
same time having one annotation file per source file is simply too much.
I tried wrapping org-annotate-file, setting org-annotate-file-storage-file
and taking advantage of elisp's dynamic binding. However, it opens the
annotation file in the current window, and I'd really like to split the window
and open the annotations the right. Rather than trying to sort of "work it out
backwards" I decided to write a small package and use as much of the
functionality in org-annotate-file.el as possible.
First off I decided that I want the annotation file to be called
projectile-annotations.org.
(defvarorg-projectile-annotate-file-name"projectile-annotations.org""The name of the file to store project annotations.")
Then I wanted a slightly modified version of org-annotate-file-show-section, I
wanted it to respect the root of the project.
(defunorg-projectile-annotate--file-show-section(storage-file)"Add or show annotation entry in STORAGE-FILE and return the buffer.";; modified version of org-annotate-file-show-section(let*((proj-root (projectile-project-root))(filename (file-relative-name buffer-file-name proj-root))(line (buffer-substring-no-properties (point-at-bol)(point-at-eol)))(annotation-buffer (find-file-noselect storage-file)))(with-current-buffer annotation-buffer
(org-annotate-file-annotate filename line))
annotation-buffer))
The main function can then simply work out where the file with annotations
should be located and call org-projectile-annotate--file-show-section.
When testing it all out I noticed that org-store-link makes a link with a
search text. In my case it would be much better to have links with line numbers.
I found there's a hook to modify the behaviour of org-store-link,
org-create-file-search-functions. So I wrote a function to get the kind of
links I want, but only when the project annotation file is open in a buffer.
(defunorg-projectile-annotate-file-search-func()"A function returning the current line number when called in aproject while the project annotation file is open.This function is designed for use in the hook'org-create-file-search-functions'. It changes the behaviour of'org-store-link' so it constructs a link with a line numberinstead of a search string.";; TODO: find a way to make the link description nicer(when(and(projectile-project-p)(get-buffer-window org-projectile-annotate-file-name))(number-to-string (line-number-at-pos))))
That's it, now I only have to wait until the next time I want to comment on a
project to see if it improves my way of working.
Have an Org link type for Youtube videos that opened the video in mpv instead of the browwser
When exporting to HTML the link should result in an embedded video rather than a link to Youtube
Most folks probably aren’t going to have those requirements, of course, but Singh’s post is still useful because it’s a great go-by for how to define and implement special links in Org-mode. The TL;DR is that you define a link type and two actions associated with it. The first action is what to do when the link is followed (Ctrl+cCtrl+o). The second is how to export the link (Ctrl+cCtrl+e).
In Singh’s case, the follow action is to display the video with mpv unless the follow is invoked with the universal argument in which case the browser is used. For export, Singh cares only about HTML for which the necessary markup for an embedded video is output.
The code is easy to follow so if you have a case for a special Org link, it’s worthwhile taking a look at Singh’s post to see how things are done.
One Emacs package that has been with me for a very long time is diff-hl1,
and the reason is not its on-the-fly coloured fringe markers, but the fact that
colours stay there when I visit the same buffer later. This is useful since more
often than not I end my work day with something still in progress, so the next
morning it’s easier to use diff-hl-next-hunk and diff-hl-previous-hunk to
move around my unfinished edits.
However, I have put diff-hl aside because there have been some welcome
improvements lately on the built-in diff-mode, especially the possibility to
edit its buffer contents and commit straight from it2. I now find myself
using C-x v D (vc-root-diff) many times a day, and by using
diff-mode more, I have started to appreciate one simple thing that was already
available to me but have always ignored, that is the navigation among hunks with
diff-hunk-next (n) and diff-hunk-prev (p).
The pattern, already become muscle memory, is the following:
C-x p p to enter the project I am working on
Visit the file I am interested in
Hit C-x v =
Move with either n or p to the desired hunk
Hit RET to jump to the hunk
Hit C-x 1 to hide the diff-mode buffer
Easy and quick. I guess one could even speed up the process by using
something like recentf-mode, for instance, but I’ll leave that to you wild
ELisp explorers.
By the way, after months with VC instead of Magit3, the combination of
vc-dir, vc-git, diff-mode, and shell-command has resulted in one of the
most dreaded command any serious Emacs user can think of, one that I cannot even
type out of fear of mystical forces coming after me. Let’s just say it involves
package-delete and… Dear GNU, they’re already here.
The ef-themes is a collection of light and dark themes for GNU Emacs
whose goal is to provide colourful (“pretty”) yet legible options for
users who want something with a bit more flair than the modus-themes
(also designed by me). Watch the presentation of the original version,
which demonstrates the first eight themes in the collection and explains
a few technical points: https://protesilaos.com/codelog/2022-08-18-ef-themes-demo/.
The collection now includes two themes which apply shades of magenta,
blue, and teal in most contexts. They are named ef-trio-dark and
ef-trio-light. I think some of you will like their aesthetics.
As part of the development, I initially forgot to register the “trio”
themes as part of the collection. Thanks to Sven Seebeck for informing
me about it. (This is shared with permission, as it was done via a
private channel.)
Changes to faces or face groups
Removed the override for the org-modern-label face. We used to
affect its properties, which had the unintended effect of breaking the
functionality of the user option org-modern-label-border. Users of
the org-modern package may thus notice a difference in the effective
typography that org-modern-mode produces.
For the alignment of tables with timestamps (e.g. clocktables), it is
recommended to set the user option org-modern-timestamp to nil. The
manual covers this information in the section titled “Tweak
org-modern timestamps”.
Users who still need help with this are welcome to contact me in
private or via the development channels of the Ef themes (mailing list
or GitHub/GitLab mirrors).
Refined the backgrounds of regexp groupings. Commands such as
re-builder and isearch-forward-regexp apply distinct colours to
matching regexp groups. Those are now optimised to stand out more
when seen side-by-side.
Part of this work involved a thorough review of the applicable hues
used by the ef-deuteranopia-dark and ef-deuteranopia-light (the
two themes which are designed for users with red-green colour
deficiency). The announcement on my website shows screenshots,
including those which simulate deuteranopia:
https://protesilaos.com/codelog/2022-09-18-ef-themes-deuteranopia-regexp/.
Added support for display-fill-column-indicator-mode. Thanks to
Daniel Mendler for informing me about it (this is shared with
permission, as it was done via a private channel).
Covered two faces that are available on Emacs 29 (current development
target) for Version Control: vc-git-log-edit-summary-max-warning,
and vc-git-log-edit-summary-target-warning.
Making use of ef-themes-select in init files
The manual includes improved language on how to use the function
ef-themes-select in user init files. This is for users who need to
leverage the ef-themes-post-load-hook at startup (using that hook is
also explained in the manual). Basically, one loads a theme in their
init file with something like:
;; like `load-theme' but also call `ef-themes-post-load-hook'(ef-themes-select'ef-summer)
I could not use seq-union because it introduces a dependency on
Emacs 28, whereas we support Emacs 27. I went with append instead.
Ensured that the background colour of matching delimiters in
show-paren-mode is no longer red-tinted. We thus avoid the
potential problem of mistaking those highlights for errors of some
sort. This affects the themes ef-autumn, ~ef-light, and ef-night.
Recorded the colour distance and colour contrast between the base
background values across all themes. The data is incorporated in the
file contrast-ratios.org, which is part of the Git repository and is
basically intended for my own use as part of this project’s
development (though you are welcome to consult it).
What you do not see but still need to know about
I worked on two major changes but refrained from implementing them in
this version. Whether I will do so in the future remains to be
determined. The first is an option to apply “intense” colouration to
the region face. The second pertains to a review of the base
backgrounds across all dark themes in order to improve their contrast
relative to the main background.
The following sections delve into the specifics. To cut the long story
short: changing colours is not trivial work.
Considerations for the “intense” region
The following patch is deceptively simple. It defines some new colour
values, adds a tiny function, and a user option. Why not add this to
the themes, then? The reason is that colours are never that simple.
Any new value for the region must (i) work with hl-line-mode, (ii)
respect the highlights of show-paren-mode, (iii) complement or
otherwise not interfere with isearch and its lazy highlights or any
other search utility that can extend the active region highlight, (iv)
keep the cursor visible, and (v) remain thematically consistent with the
rest of the theme. Running those checks for 14 themes is no mean feat
and there is always the chance that the new colours will still have a
negative effect in places that are not expected. Furthermore, there is
no guarantee that the number of Ef themes will stay at 14 (I have some
more ideas, yes).
It is for such reasons that one of the principles of this project is to
NOT offer customisation options that influence colours. They do not
scale and will make things unmaintainable.
As with the “intense” region, any change to the base backgrounds has
far-reaching implications. The following patch is, again, a matter of
making small tweaks to colours values whose effect is far greater than
what meets the eye. I mean, what can possibly go wrong by changing the
colour #1a1a1a to #232323, right? This marginal adjustment
requires, among others, that we also adjust (i) the foregrounds in
header lines, (ii) the background colours of added and removed lines in
Magit focused diff hunks as well as the backgrounds of word-wise, aka
“refined”, diff highlights, (iii) the foregrounds of inactive mode
lines, (iv) the legibility of inactive tabs in tab-bar-mode,
tab-line-mode, (v) the legibility of elements such as the
#+begin_src line in Org buffers, and probably many others. A change
to one background necessarily needs a change to all others.
Over at the Emacs subreddit, analysis230 has a sort of confession. He had long considered the phrase “Emacs is not just a text editor” to be something geezer developers said as they clung desperately to an aging technology. He says he didn’t even know what it meant.
Then one day for unspecified reasons he decided to move from VS Code to Emacs. He was already familiar with the Vim keybindings so he was up and running (with Doom Emacs) in short order. He really liked modal editing and found himself wishing for a keyboard-driven file manager. That’s when he discovered dired and, as he put it, the penny dropped. He finally understood what everyone meant when they said that Emacs is not just a text editor.
He’s since moved on to installing Mu4e but his story makes an important point: it can be hard to understand and appreciate the power of Emacs until you’ve learned some basics and used it for a while. Lots of worthwhile things in life are like that.
Speaking of the “not just a text editor” quote, analysis230 says,
I know I heard people say that but I always thought of them as denial-filled ramblings of people who have sunk a decade into learning a tool that’s slowly fading. Apparently, not the case at all.
His post is, it seems to me, the perfect answer to those who complain that Emacs has a steep learning curve. It may have but the it’s worth the climb.
You gotta try out using describe-symbol because it is usually what you really want from describe-function and describe-variable. The most useful part is that it instantly teaches you when there are both a variable and a function with the same name. Sometimes it is surprising and better to know right away. For example M-x describe-symbol … Continue reading "You Gotta Try Using ~describe-symbol~"
Time moves on and things you thought you knew turn out to be not as accurate as you hoped. This happened to me recently in regard to using the Webster 1913 dictionary in Emacs. I recently posted about James Somers’ article on Webster’s 1913 and how to use it from withn Emacs. In it I repeated my advice to follow Marcin Borkowski’s recipe for making this wonderful resource available from within Emacs.
In the comments to that post, acdw and Brian Green note that the dictionary is now available from dict.org and that—as of Emacs 28—you can access it from the built-in dictionary-search. That means that any Emacs user can take advantage of this splendid resource without downloading extra packages or data.
If you call dictionary-search without configuring anything, it will prompt you for the dictionary source with a default of dict.org. As Green says, you can avoid that by simply adding
(setq dictionary-server "dict.org")
to your init.el.
That will give you all the definitions from Weber’s 1913 as well as the other dictionaries located at dict.org. If you’re coming to this post without the benefit of reading the backstory, you should definitely read Somers’ post, You’re probably using the wrong dictionary to see why you should bother with Webster’s 1913 to begin with. It is not, after all, the most modern dictionary but as Somers explains, it is the best if you’re looking for just the right word.
This is a simple package that renders an indicator with an email count
of the notmuch index on the Emacs mode line. The underlying mechanism
is that of notmuch-count(1), which is used to find the number of items
that match the given search terms. In practice, the user can define one
or more searches and display their counters. These form a string which
realistically is like: @50 😱1000 💕0 for unread messages, bills, and
love letters, respectively.
Backronym: notmuch-… Increasingly in Need of Displaying
Inconsequential Counters Alongside Trivia that Obscure Reality.
The GNU ELPA package will be built by the server in a few hours from
now. Local time is 2022-09-21 07:43 +0300 and I expect it to be done by
noon.
Below are the release notes, which are just the contents of the README,
given that this is the first stable version.
This is a simple package that renders an indicator with an email count
of the notmuch index on the Emacs mode line. The underlying mechanism
is that of notmuch-count(1), which is used to find the number of items
that match the given search terms.
The indicator is enabled when notmuch-indicator-mode is on.
The user option notmuch-indicator-args provides the means to define
search terms and associate them with a given label. The label is purely
cosmetic, though it helps characterise the resulting counter.
The value of notmuch-indicator-args is a list of plists (property
lists). Each plist consists of one mandarory property and two optional
ones:
The :terms, which is required, is a string that holds the
command-line arguments passed to notmuch-count(1) (read the Notmuch
documentation for the technicalities).
The :label, which is optional, is an arbitrary string that is
prepended to the return value of the above. If nil or omitted, no
label is displayed.
The face, which is optional, is the symbol of a face that is
applied to the :label. It should not be quoted, so like :face
bold. Good candidates are bold, italic, success, warning,
error, though anything will do. If nil or omitted, no face is
used.
Multiple plist lists represent separate notmuch-count(1) queries.
These are run sequentially. Their return values are joined into a
single string.
For instance, a value like the following defines three searches:
(setqnotmuch-indicator-args'((:terms"tag:unread and tag:inbox":label"@")(:terms"from:bank and tag:bills":label"😱")(:terms"--output threads tag:loveletter":label"💕")))
These form a string which realistically is like: @50 😱1000 💕0.
The user option notmuch-indicator-refresh-count determines how often
the indicator will be refreshed. It accepts a numeric argument which
represents seconds.
The user option notmuch-indicator-force-refresh-commands accepts as
its value a list of symbols. Those are commands that will forcefully
update the indicator after they are invoked.
The user option notmuch-indicator-hide-empty-counters hides zero
counters from the indicator, when it is set to a non-nil value.
For example, in addition to backlinks, Young implemented a database that linked a person in his database to the any headlines that involved them. That allowed him to answer question like, “Who did I discuss [some topic] with?”
His setup is very idiosyncratic but finely tuned to work exactly the way he finds most useful. Others who don’t want the heavy machinery of things like Org-roam may find his system useful.
Regardless, the main takeaway for me is that his workflow is yet another example of how flexible Emacs is. You can bend it in almost any direction to get just the workflow you want.
It feels like I did one of these posts just the other day, but it was a month ago? Time sure does fly…
Since there’s a round number in the title of this blog post, perhaps I should natter on a bit more than usual? Sure! If you insist!
So: This is part of a series of posts where I bloviate on how Emacs development is going, partially through gamification of the Emacs bug tracker. This round, 10% was 205 bugs, so we started at 2050 open bugs, and after closing 10% of those, we’re now at…
Drum roll…
1966 open bugs! Well, that’s a decrease, at least — we had an increase in the previous stretch.
But as you can see, I got my act together and did some actual work.
Most of it was just the normal, eh, whatever, but I also went through all the bugs that were tagged as having a patch, and…
… applied a bunch of those. (But a surprising number, perhaps a quarter of those closed, had already actually been applied, but then discussion had just gone on to other things and nobody remembered to close the door after they left.)
As you can see, it’s been almost a year since the last time somebody took the time to do some triage on the patch reports, and that’s really too long — I found stuff in there that should have been applied a lot speedier, but…
Hm… I wonder how many bugs I’ve closed since I started this silly project back in 2019…
As you can clearly see, by using quadratic linear regression we will be at negative 500 in 2026, and to achieve that at that point, I’ll have to start opening bug reports instead of closing them.
That’s mathematics for you!
Anyway — has Emacs gained any new and exciting functionality over the last month? Er… Let’s look at the NEWS file.
Oh, yeah, there’s new branching commands for VC mode under C-x v b. But more significantly, there’s C-x v v in diff buffers (courtesy of Juri Linkov), which allows you to selectively commit things. It’s very convenient — for instance, if you’re working on something bigger in a file, and then see an unrelated typo in that file, you can now commit that unrelated thing in a separate commit without having to stash anything first. It’s very convenient for us that futz around a lot.
We now interpret OSC escape sequence in compilation buffers (courtesy of Matthias Meulien), which makes output from some newer compilers more pleasant to read.
We have a new package for setting wallpapers on desktops directly from Emacs and image-mode (courtesy of Stefan Kangas), which is quite convenient.
Aaand…
I finally incorporated the image cropping/cutting code I wrote a few years back.
Tada!
I know, right?
But since this is a round-numbered 10% post, let’s look at more stats. Let’s see… Oops! Found a bug in the stats generator, so if I’ve posted charts like this before, they’ve been er wrong.
But here’s the full overview of contributors per month, going all the way back to 1985:
Which is misleading as ever, since the VC (ahem) didn’t really keep that much track of things back in the 80s. But the last few years should be reasonably accurate:
And… It’s looking OK. We’re up from about 45 to about 65 per month over the last five years. (Note: Expert cherry-picking of dates; I’m an ex stock broker after all.)
But what about the number of commits instead?
Yowza. People have been busy. Let’s zoom in:
700 commits per month? We seem to have more than doubled the er development er velocity? I didn’t really know that, actually…
Let’s see… anything more? Oh yeah:
A couple old Emacs stats posts went to HackerNews and reddit, which totally makes the WordPress stats unreadable for normal days for a month. Fie!
function, but we can plot any other, like 
:
:
using the 
like this: 
