emacs on A Scripter's Notes

Using Git Delta with Magit

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Wed, 06 Jul 2022 22:04:00 -0400

Git Delta is a command line utility that beautifies git diffs in the terminal. But did you know that it can do the same in Magit too?

Table of Contents

Installing delta
Installing magit-delta
Configuring delta

Delta is a highly configurable I am not kidding. Check out the output of delta --help. command line utility that makes the git diffs look better, while also syntax-highlighting Difftastic is another popular diff tool which compares files based on their syntax. I like reviewing git diffs from within Emacs (Magit). But difftastic does not support Magit. the code in the diffs.

When I first heard of “syntax highlighted diffs”, I wasn’t sure what that meant. If you are in the same boat, here’s a screenshot that shows that.

Figure 1: Example of how delta renders a git diff for an ox-hugo commit

But I do most of my git operations including viewing of diffs from within Emacs, using Magit.

.. and thankfully delta works with Magit!

Below screenshot shows how the same diff looks like in Magit.

Figure 2: Example of how magit-delta renders a git diff for an ox-hugo commit

The magit-delta Emacs package makes this possible, which is also developed by the delta author Dan Davison.

Caveat: If the line numbers are enabled in delta, they mess up the interactive expanding and collapsing of diffs in Magit. See Magit Delta Issue # 13 for more details.

Now, I am alright with not seeing the line numbers in Magit. But I really liked to see the line numbers in the side-by-side view in the terminal. Luckily, if disabled the line-numbers feature but enabled the side-by-side view, I got what I wanted!

Line numbers are disabled in Magit and expanding/collapsing of diffs works correctly. I am also really glad that I don’t see the side-by-side view in Magit diffs even when I enable that feature in delta, because I like to have my Emacs buffers only about 90 characters wide.
Line numbers and side-by-side view are enabled in the terminal.

I’ll end this post with pointers to installing delta and magit-delta and how to configure them.

Installing `delta` #

You can install delta (it’s called git-delta in some package managers) using one of the methods listed in its manual, or you can download → extract its statically compiled binary for your OS from its GitHub Releases page.

Installing `magit-delta` #

Once you put this snippet in your Emacs config and evaluate it, it will install this package and enable the magit-delta-mode in the Magit buffers.

(use-package magit-delta
 :ensure t
 :hook (magit-mode . magit-delta-mode))

Code Snippet 1: Installing and enabling magit-delta using use-package

Configuring `delta` #

Here’s a snippet for delta configuration from my .gitconfig. It’s mostly the same as the one in delta’s the Getting Started guide. The main difference in my workaround for the magit-delta issue.

[core]
 pager = delta

[interactive]
 diffFilter = delta --color-only
[add.interactive]
 useBuiltin = false # required for git 2.37.0

[diff]
 colorMoved = default

[delta]
 # https://github.com/dandavison/magit-delta/issues/13
 # line-numbers = true # Don't do this.. messes up diffs in magit
 #
 side-by-side = true # Display a side-by-side diff view instead of the traditional view
 # navigate = true # Activate diff navigation: use n to jump forwards and N to jump backwards
 relative-paths = true # Output all file paths relative to the current directory
 file-style = yellow
 hunk-header-style = line-number syntax

Code Snippet 2: My configuration for delta in .gitconfig

Gujarati Transliteration

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Mon, 27 Jun 2022 18:43:00 -0400

You can phonetically write a non-English language on an English keyword in Emacs, and that transforms into that non-English script. This is called transliteration, and I demonstrate that for the Gujarati language in this post.

Table of Contents

Enabling transliteration
Toggling the input method
Caveats with Gujarati and other Indic language transliteration
“Input method” cheat sheet
Closing
References

Emacs provides the transliteration feature using the set-input-method command. I’ll introduce that and few related functions in this post to get to help get started with transliteration quickly.

Enabling transliteration #

Emacs uses the “input method” feature to do character conversion from ASCII to the target language or script. The “input method”, stored in current-input-method, is nil by default. In this state, you see the exact ASCII in Emacs buffer, that you typed on the keyboard¹.

In this post, my target non-English language is Gujarati. So I want to type on my English keyboard and have Gujarati script letters show up in the buffer.

Emacs provides the set-input-method command to change the current input method. This command is bound to C-x RET C-\ by default. Pick the new input method after calling that command.

To see the available input methods, do M-x list-input-methods.

As I want to do Gujarati transliteration, I pick the gujarati-itrans method.

If you don’t know Gujarati, don’t fret! The commands shown here will work when transliterating to other languages too — only the Gujarati-specific input method gujarati-itrans will change to the input method of your choice.

Toggling the input method #

I often need to switch between the Gujarati and English languages in the same document. You can see me doing that in this post next section onwards. The toggle-input-method command bound by default to C-\ is helpful here.

So if I am already in the “Gujarati transliteration mode” calling this command will set current-input-method back to nil. Repeating that same call will again set current-input-method to gujarati-itrans, and I will once again be in the “Gujarati transliteration mode”.

Caveats with Gujarati and other Indic language transliteration #

Apologies, but this section is meaningful only if you know how to read Gujarati. So you can safely skip to the next section.

Below table is a quick glimpse of some nuances in Gujarati transliteration. I will save my explanation and instead show some of the mistakes I made in transliteration using examples.

ASCII input	Gujarati Transliteration	Rough Translation
ram	રમ્	(incorrect spelling, no meaning)
rama	રમ	play
raama	રામ	a popular name Raama (as in Lord Raama)
angreji	અન્ગ્રેજિ	(incorrect spelling)
hu.n	હું	I
chhu.n	છું	am
a.ngrejii	અંગ્રેજી²	English (language)
Ime.cksa	ઈમૅક્સ	this literally reads “Emacs”

“Input method” cheat sheet #

Thankfully Emacs provides full help through the describe-input-method command bound to C-h C-\ If you haven’t already noticed the consistency in these bindings, the default bindings with C-\ in them are related to “input method” commands. by default.

For example, M-x describe-input-method gujarati-itrans gives this:

Figure 1: Partial screen capture of Gujarati transliteration cheat sheet C-h C- gujarati-itrans

The ∗Help∗ that shows up looks formidable at the first glance. Though, I found comfort in the fact that roughly half of the key sequences were obvious and roughly half resulted in Gujarati characters that I have never found the need of! 😃

Closing #

Typing this in the “transliteration mode”:

maaru naama kaushala chhe. mane e jaaNii ne aana.nda thaaya chhe ke hu.n aa sahelaaI thI lakhI shaku chhu.n. (joDanI-bhula maapha.)

will result in:

મારુ નામ કૌશલ છે. મને એ જાણી ને આનંદ થાય છે કે હું આ સહેલાઈ થી લખી શકુ છું. (જોડણી-ભુલ માફ.)

Translation: My name is Kaushal. I am happy knowing that I can write this easily.

References #

Emacs Info: Input Methods
- Emacs Info: Select Input Method
M-x describe-input-method gujarati-itrans

I am assuming an English keyboard here. ↩︎
This spelling might still render incorrectly on your browser depending on the unicode character set available for Gujarati on your system. ↩︎

View GitHub Pull Requests in Magit

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Thu, 23 Jun 2022 17:51:00 -0400

How to view GitHub Pull Request branches locally in the cloned repo, and more importantly, how to do that automatically from within Emacs.

Table of Contents

Locally creating a branch for a PR
Getting references to all Pull Requests
Automatically adding PR refs
Summary
References

I have a few public projects in git repos, but I don’t get that much traffic in Pull Requests (PR) Gitlab calls these Merge Requests or MRs. . So when I need to add additional commits to a PR, I would just add the PR author’s remote to my local repo, check out their PR branch, add my own commits and then merge that to my project’s main branch.

As these occurrences were few and far apart, I didn’t have a need to view the PR branches directly from within Emacs/Magit. Though, I somehow knew that each GitHub Pull Request’s HEAD got assigned a git reference. But I didn’t need to use that knowledge until today 😃.

Today, when discussing PR # 20 on Prot’s Denote package’s GitHub mirror Prot uses SourceHut as the primary git forge for his Emacs packages. But I am glad that he doesn’t mind the activity in Issues and Pull Requests on the GitHub mirror. , he wrote this comment:

Now I just need to figure out how best to incorporate your changes into the org-id branch so I can add the final bits. I am not too familiar with the PR workflow …

.. and that inspired this post today.

Locally creating a branch for a PR #

From the GitHub docs, the git command to create a local branch for a PR is this:

git fetch origin pull/ID/head:BRANCHNAME

I have the denote package cloned from its GitHub mirror. So the origin remote’s url is https://github.com/protesilaos/denote.

Make sure that the remote name used in this command is pointing to a GitHub repo, and not a mirror forge like GitLab or SourceHut.

When I ran the below command, I got a new branch pr-20 pointing to the latest commit of that PR:

git fetch origin pull/20/head:pr-20

Awesome!

.. But that wasn’t good enough
.. Now I wanted more
.. I didn’t want to manually create a branch for each PR.

Getting references to all Pull Requests #

Now that I was on that quest of “I want more”, it didn’t take me long to re-discover this 7-year old nugget by Oleh Krehel. Here are the relevant bits from that post:

Open the local repo’s .git/config file.
Find the [remote "origin"] section

Modify it by adding this one line with pull refs. This is the same for all GitHub repositories.

[remote "origin"]
 url = https://github.com/USER/REPO.git
 fetch = +refs/heads/*:refs/remotes/origin/*
 fetch = +refs/pull/*/head:refs/pull/origin/*

With that edit in place, when I did l a (show the log for all git references), followed by f a (fetch all the remotes) in the Magit, I could see the references to the denote repo’s PRs!

Figure 1: Viewing PR references from denote package’s GitHub repo

.. But that still wasn’t good enough
.. I didn’t want to manually edit the .git/config in each repo.

Automatically adding PR refs #

Of course, I wasn’t the first one to think of this!

Another Emacs veteran Artur Malabarba had already had this covered also around 7 years back. Coincidentally, that post was written as a response to that same blog post by Oleh where he shared the above .git/config tip.

In that post, Artur shares an Emacs Lisp function that uses Magit functions like magit-get, magit-get-all and magit-git-string to auto-add the fetch = +refs/pull/*/head:refs/pull/origin/* line in the .git/config. This magic happens after checking that the origin remote points to a GitHub repo, and if that line doesn’t already exist.

Here, I am lightly modifying the function shared in that post so that the origin remote name is not hard-coded The reason is that sometimes, I name the original remote as upstream and my fork as fork, and I might have no remote named origin. . Credit for the main logic in this code still goes to Artur.

(defun modi/add-PR-fetch-ref (&optional remote-name)
 "If refs/pull is not defined on a GH repo, define it.

If REMOTE-NAME is not specified, it defaults to the `remote' set
for the \"main\" or \"master\" branch."
 (let* ((remote-name (or remote-name
 (magit-get "branch" "main" "remote")
 (magit-get "branch" "master" "remote")))
 (remote-url (magit-get "remote" remote-name "url"))
 (fetch-refs (and (stringp remote-url)
 (string-match "github" remote-url)
 (magit-get-all "remote" remote-name "fetch")))
 ;; https://oremacs.com/2015/03/11/git-tricks/
 (fetch-address (format "+refs/pull/*/head:refs/pull/%s/*" remote-name)))
 (when fetch-refs
 (unless (member fetch-address fetch-refs)
 (magit-git-string "config"
 "--add"
 (format "remote.%s.fetch" remote-name)
 fetch-address)))))
(add-hook 'magit-mode-hook #'modi/add-PR-fetch-ref)

Code Snippet 1: Function to auto-add GitHub PR references to the repo's .git/config

Summary #

With the above snippet added to your Emacs config and evaluated, each time you visit a repo cloned from GitHub in the Magit Status buffer (M-x magit-status), the PR refs will get auto-added to that repo’s .git/config if needed.

After that, you can easily view the commits from all the PRs by doing l a f a.

References #

Gujarati fonts in Emacs

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Sun, 19 Jun 2022 01:31:00 -0400

Setting a different font for a specific script or language in Emacs.

Table of Contents

Setting a “fontset” font
Gujarati fonts

All Emacs versions ship with a nifty HELLO file that you can quickly open using M-x view-hello-file or its default binding C-h h. This file lists “Hello” written in dozens of languages to demonstrate some of the character sets supported by Emacs.

Figure 1: “Hello” buffer in Emacs

Born and raised in the Gujarat state in India, I grew up speaking the Gujarati (ગુજરાતી) language India officially recognizes 22 languages (as of <2022-06-19 Sun>) and Gujarati is one of them. and so it’s also the language closest to my heart. So I was pleasantly surprised to see a representation of Gujarati in the “Hello” buffer! In the above screenshot, in the “South Asia” section, the script after the yellow cursor is Gujarati, and it reads namaste.

Setting a “fontset” font #

It was on <2018-08-13 Mon> that I discovered the presence of Gujarati script in that “Hello” buffer, and the reason I know that exact date is because I had asked a question regarding that on the help-gnu-emacs mailing list 😃.

This was the time when Emacs was using the m17n library for multi-lingual font rendering by default. The question was regarding a font rendering issue I was seeing. As I learn later in that thread, it was because I didn’t have the m17n database installed on my machine At least in 2022, the harfbuzz library is the recommended library for text shaping and font rendering. Someone please correct me if that’s wrong. In any case, I have switched to using harfbuzz instead of m17n for a while now and haven’t found any font-rendering issues with non-English scripts. . But it’s in that support thread that, thanks to Andy Moreton, I learned that you can change the font for the Gujarati script using set-fontset-font.

This applies in general to any script. You can read more details about this function in Emacs Info: Modifying Fontsets, but here’s the gist:

(set-fontset-font "fontset-default" 'gujarati "<FONT NAME>")

Code Snippet 1: Setting default font for Gujarati script using set-fontset-font

That led me down the path of exploring the available Gujarati fonts out there ..

Gujarati fonts #

After looking around for a bit, I found a wonderful collection of Gujarati fonts in this GitHub repository: github.com/samyakbhuta/chhapkaam The repo name is chhapkaam (I would have spelled it as chhaapkaam) which is the Gujarati word છાપકામ, meaning “printing”. .

Below is my further curated list of fonts from the above list:

Table 1: Gujarati Fonts

Font Name	Category	Homepage	Download
Shruti	serif		wfonts.com
Mukta Vaani	serif	Ek Type – Mukta Vaani	GitHub
Lohit Gujarati	sans serif	Pagure – Lohit	pagure releases

To use these fonts, after downloading and installing them on your system, evaluate Code Snippet 1 above with the correct “FONT NAME”. For example, to set the Gujarati text to use the Shruti font, evaluate (set-fontset-font "fontset-default" 'gujarati "Shruti").

Thanks for reading (વાંચવા બદલ આભાર) 🙏!

Emacs Lisp: Advice Combinators

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Fri, 17 Jun 2022 21:30:00 -0400

My diagrammatic take on summarizing all the Emacs advice combinators.

Table of Contents

Overview on using advices
1 :before
2 :after
3 :override
4 :around
5 :before-while
6 :before-until
7 :after-while
8 :after-until
9 :filter-args
10 :filter-return
Summary
References

If you have read some of my earlier posts, you would know that I really enjoy using the Emacs Advice system 😃.

The “advice” feature lets you add to the existing definition of a function, by advising the function. This is a cleaner method than redefining the whole function, because it’s easier to debug and if you don’t need it, you can just remove the advice.

You can jump to the References section below if you need to look at the related sections in the Emacs Lisp Manual.

Overview on using advices #

I do not plan to write a tutorial on how to write advices in Emacs-Lisp, but here’s a 3-second primer:

To add an advice: (advice-add 'original-fn <combinator> #'advising-fn)
To remove an advice: (advice-remove 'original-fn #'advising-fn)

This article attempts to briefly describe different ways of advising a function, using 10 different combinators. If you have never used advices in your Emacs config, don’t worry. I am hopeful that the diagrams in this post and the examples linked for some of the combinators in the Summary section makes this concept a bit easier to assimilate.

Diagram Legend

Initial black circle: Original Fn input arguments
Yellow box: Original Fn
Gray box: Advising Fn
Black circle inside a white circle: Return values

1 `:before` #

Figure 1: :before advice

2 `:after` #

Figure 2: :after advice

3 `:override` #

Figure 3: :override advice

4 `:around` #

Figure 4: :around advice

5 `:before-while` #

Figure 5: :before-while advice

6 `:before-until` #

Figure 6: :before-until advice

7 `:after-while` #

Figure 7: :after-while advice

8 `:after-until` #

Figure 8: :after-until advice

9 `:filter-args` #

Figure 9: :filter-args advice

10 `:filter-return` #

Figure 10: :filter-return advice

Summary #

Here’s a concise summary of what each advice combinator does. For brevity, the advising function is called A and the original function is called O.

Once you click on any of the example posts, search for advice-add on that page to find the code example.

Table 1: Summary of what each advice combinator means

Combinator	Description	Example
`:before`	A is called before O. O args and return values are not modified.
`:after`	A is called after O. O args and return values are not modified.
`:override`	A is called in lieu of O. A gets the same args as O.	Zero HTML Validation Errors!
`:around`	A is called in lieu of O. A gets O fn + O args as args.	Using Emacs advice to silence messages from functions
`:before-while`	A is called first. If it returns non-nil, O is called.
`:before-until`	A is called first. If it returns nil, O is called.	Org: Show only Post subtree headings
`:after-while`	O is called first. If it returns non-nil, A is called.
`:after-until`	O is called first. If it returns nil, A is called.
`:filter-args`	A is called first. O is called next with return value from A as input.	Narrowing the Author column in Magit
`:filter-return`	O is called first. A is called next with return value from O as input.	Zero HTML Validation Errors!

If you have any feedback on how these diagrams can be made easier to understand, please let me know.

References #

Elisp Info: Advising Functions
- Elisp Info: Advice Combinators

Org: Show only Post subtree headings

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Thu, 16 Jun 2022 00:21:00 -0400

How to define a custom org-global-cycle-like command that collapses only the Org subtrees with specific properties.

Table of Contents

Org Global Cycle
Skeleton of only Post headings
The “Collapse All Posts” function
Binding with C-u C-c TAB
Result

I start this post by introducing what the Org mode global cycling command does, what kind of subtree folding I actually need, and then share the solution with code snippets.

Org Global Cycle #

Org mode has a built-in org-global-cycle command that you might be familiar with. It’s bound by default to the S-TAB key. Each time this command is called, the Org buffer will cycle through these states:

Overview: Show only the Level 1 headings and collapse everything underneath.
Contents: Show only the Org headings and collapse all the content.
Show All: Expand all the headings and show their contents too.

If a numeric prefix N is used with this command, it will show only the Org headings up to Level N. For example, C-2 S-TAB will show only the headings up to Level 2.

This is a really helpful command, but I needed something different ..

Skeleton of only Post headings #

I maintain most of this website’s content in a single Org file. I have dozens of blog posts organized in Org subtrees, which I further organize under “category” headings .. It kind of looks like the below mock-up: It’s amazing how many features PlantUML has. If you are interested in creating diagrams like these, check out the PlantUML Salt syntax.

Figure 1: Post Subtrees at arbitrary heading levels

As we can see,

All the post subtrees are not at Level 1 headings.
They are also not at a fixed Level N.
The heading level of the post depends on how many parent categories that post has (and that will also change over time).

I needed to basically show everything leading up to a post subtree heading, and then collapse all the content under that post; even the sub-headings.

The “Collapse All Posts” function #

The modi/org-hugo-collapse-all-posts function defined below meets the above requirement:

It first widens the whole buffer and expands all the headings.
Then it loops through all the headings and collapses all the post subtrees i.e. all the subtrees that have the EXPORT_FILE_NAME property set. This is where I use the org-map-entries magic.
Finally it looks for Org headings that begin with “Footnotes” or “COMMENT” and collapses them as well.

I am using the development version of Org mode (version 9.6, yet to be released as of <2022-06-15 Wed>) which has the new org-fold library. This library obsoletes the use of outline.el library and other code-folding related functions in Org mode. So cl-flet is used to create function symbol aliases that use the org-fold-* functions if available, otherwise they fall back to the legacy functions.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


(defun modi/org-hugo-collapse-all-posts ()
 "Collapse all post subtrees in the current buffer.
Also collapse the Footnotes subtree and COMMENT subtrees if
present.

A post subtree is one that has the EXPORT_FILE_NAME property
set."
 (interactive)
 (cl-flet ((show-all (if (fboundp 'org-fold-show-all)
 #'org-fold-show-all
 #'org-show-all))
 (hide-subtree (if (fboundp 'org-fold-hide-subtree)
 #'org-fold-hide-subtree
 #'outline-hide-subtree)))
 (widen)
 (show-all '(headings))
 ;; Collapse all the post subtrees (ones with EXPORT_FILE_NAME
 ;; property set).
 (org-map-entries #'hide-subtree "EXPORT_FILE_NAME<>\"\"" 'file)
 ;; Also hide Footnotes and comments.
 (save-excursion
 (goto-char (point-min))
 (while (re-search-forward "^\\(\\* Footnotes\\|\\*+ COMMENT\\)"
 nil :noerror)
 (hide-subtree)))))

Code Snippet 1: Function that collapses all the post subtrees in the current buffer

Binding with `C-u C-c TAB` #

The function is ready, but let’s now add a bit of convenience to it.

If a point is under a subtree, C-c TAB will collapse that subtree while showing only Level 1 headings, and if a numeric prefix is used, it will show only those many levels of headings. I decided to bind the above function to C-u C-c TAB because,

The behavior of modi/org-hugo-collapse-all-posts falls in the same category as that of C-c TAB.
The C-u C-c .. binding rolls off the fingers pretty nicely 😃.

This binding is achieved using one of my favorite Emacs features .. the advice system. The :before-until Advice Combinator is used here, which means that if the advising function (below) returns a nil, the advised or the original function org-ctrl-c-tab is not called.

The advising function below detects if the C-u prefix argument is used. If it is, the modi/org-hugo-collapse-all-posts function is called, otherwise the original org-ctrl-c-tab function is called.

1
2
3
4
5
6
7
8
9


(defun modi/org-ctrl-c-tab-advice (&rest args)
 "Run `modi/org-hugo-collapse-all-posts' when
doing \\[universal-argument] \\[org-ctrl-c-tab]."
 (let ((do-not-run-orig-fn (equal '(4) current-prefix-arg)))
 (when do-not-run-orig-fn
 (modi/org-hugo-collapse-all-posts))
 do-not-run-orig-fn))

(advice-add 'org-ctrl-c-tab :before-until #'modi/org-ctrl-c-tab-advice)

Code Snippet 2: Bind C-u C-c TAB to call modi/org-hugo-collapse-all-posts

Result #

After evaluating the above two snippets, when I do C-u C-c TAB in my “blog posts” Org buffer, I see this:

Figure 2: My “blog posts” Org buffer showing only the Post subtree headings

It matches that earlier mockup — Mission accomplished! 💯

Zero HTML Validation Errors!

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Sun, 05 Jun 2022 17:58:00 -0400

How I fixed my site content and went down from 46 HTML validations errors down to 0!

Table of Contents

1 Avoid duplicate heading id attributes
2 Remove inline <style> elements
3 Ensure that all images have captions or alt attributes
4 Do not have hyperlinks in headings
Validation Ignores
- 5 Ignore errors due to hyperlinks in inline SVG
- 6 Ignore files not expected to serve HTML content
Summary

In my previous HTML5 Validator post, I mentioned:

I was a bit disappointed to see validation errors on my site, but then it wasn’t too bad .. 46 errors.

But they truly say ..

Ignorance is bliss.

So .. once I realized that my site had 46 validation errors, I lost that bliss .. and I couldn’t rest easy — I had to fix them all 😁.

This post summarizes the categories of those errors and how I fixed The fixes mentioned in this post refer to changes in Org mode content. But you should be able to derive equivalent fixes for Markdown too. them all.

1 Avoid duplicate heading `id` attributes #

"file:/public/notes/string-fns-nim-vs-python/index.html":636.34-636.46: error: Duplicate ID "notes".
"file:/public/notes/nim-fmt/index.html":300.34-300.52: error: Duplicate ID "older-issue".
"file:/public/notes/nim-fmt/index.html":306.20-306.33: error: Duplicate ID "floats".
"file:/public/page/6/index.html":29.39-29.54: error: Duplicate ID "fnref:1".

Errors with above kind of signatures were fixed by,

Converting headings to description lists

I had a bunch of generic headings like “Notes” and “Older Issue” in some of my posts. After taking a second look at those, it made more sense to convert those to description lists. So in Org mode, I converted headings like * Notes to description lists - Notes ::.
Setting CUSTOM_ID heading property

For the cases, where the headings needed to be left as so, their IDs were uniquified by setting their CUSTOM_ID property. For example, below fixed the Duplicate ID “floats” errors.
```
 ** Precision
 ..
 *** Floats
+:PROPERTIES:
+:CUSTOM_ID: precision-floats
+:END:
 ..
 ** Type (only for numbers)
 ..
 *** Floats
+:PROPERTIES:
+:CUSTOM_ID: type-floats
+:END:
```
Code Snippet 1: Using CUSTOM_ID property to uniquify heading ID's
Prevent footnote links in post summaries

This issue was due to me not being conscious about how the footnote references work in a post versus on a page outside that post’s context. The issue was caused by footnote references getting into the post summaries parsed by Hugo, which will then show up on the list pages.

The fix was simple — Edit the post summaries so that they don’t contain any footnote references.

2 Remove inline `<style>` elements #

"file:/public/grep-po/index.html":51.139-51.145: error: Element "style" not allowed as child of element "div" in this context. (Suppressing further errors from this subtree.)
"file:/public/how-do-i-write-org-mode/index.html":23.194-23.200: error: Element "style" not allowed as child of element "div" in this context. (Suppressing further errors from this subtree.)

Errors with above kind of signatures were fixed by,

Avoiding export of raw <style> elements in the Markdown content

I figured out which functions were responsible for injecting <style> elements in Markdown content and then advised them to stop that. After applying these advises, I lost the in-content rules for CSS classes .org-center and .csl-entry. So I put those rules directly in this website’s CSS.

(defun modi/org-blackfriday-center-block (_center-block contents info)
 (let* ((class "org-center"))
 (format "<div class=\"%s\">%s\n\n%s\n</div>"
 class (org-blackfriday--extra-div-hack info) contents)))
(advice-add 'org-blackfriday-center-block :override #'modi/org-blackfriday-center-block)

(defun modi/org-cite-csl-render-bibliography (bib-str)
 (replace-regexp-in-string "<style>\\.csl-entry[^<]+</style>" "" bib-str))
(advice-add 'org-cite-csl-render-bibliography :filter-return #'modi/org-cite-csl-render-bibliography)

Code Snippet 2: Emacs-Lisp advices to prevent <style> elements in exports

Removing unnecessary micro-styling

I found a single case, where an inline CSS rule was defined in content for CSS class .repr-type for a table. I just removed that without affecting the looks of that rendered table too much.

3 Ensure that all images have captions or `alt` attributes #

"file:/public/hugo-use-goat-code-blocks-for-ascii-diagrams/index.html":24.130-24.255: error: An "img" element must have an "alt" attribute, except under certain conditions. For details, consult guidance on providing text alternatives for images.

Errors with above kind of signatures were easily fixed by ensuring that all images had captions Thankfully, there were only two images that were missing captions. . The Hugo figure shortcode adds the caption to the alt attribute if the alt is not specified separately.

As an example, here’s how I fixed the above error:

+ #+name: fig__disproportionate_box_drawing
+ #+caption: Disproportionate box drawing characters
[[file:images/hugo-use-goat-code-blocks-for-ascii-diagrams/ascii-diagram-rendered-in-plain-text-code-block.png]]

Code Snippet 3: A git diff showing addition of caption to an image

4 Do not have hyperlinks in headings #

"file:/public/using-emacs-advice-to-silence-messages-from-functions/index.html":151.687-151.732: error: Start tag "a" seen but an element of the same type was already open.
"file:/public/using-emacs-advice-to-silence-messages-from-functions/index.html":151.748-151.751: error: Stray end tag "a".
"file:/public/auto-count-100daystooffload-posts/index.html":114.446-114.475: error: Start tag "a" seen but an element of the same type was already open.
"file:/public/auto-count-100daystooffload-posts/index.html":114.446-114.475: error: End tag "a" violates nesting rules.
"file:/public/auto-count-100daystooffload-posts/index.html":114.526-114.529: error: Stray end tag "a".

While the hyperlinks in headings work well, they created invalid HTML in the Hugo-generated TOC. So while these errors were created technically because of a bug in Hugo It’s really cool when you end up finding a bug in an upstream project while trying to fix the errors in your own thing 😎. , I wanted to fix these errors on my end as soon as I can.

I reviewed the errors, and this is all it took to get rid of them all:

Remove manually inserting hyperlinks in headings

 show two methods of finding sources of any printed messages.
-***** Using plain-old /grep/ or [[https://github.com/BurntSushi/ripgrep][/rg/]]
+***** Using plain-old /grep/ or /ripgrep (rg)/
 This method is pretty easy (but not robust) to use if the search
 ..
 Org source directory and search for the /"org-babel-exp process .."/
-string ..
+string using [[https://github.com/BurntSushi/ripgrep][~rg~]] ..

Code Snippet 4: Removing hyperlink from a heading

Remove Org Radio links that created links in headings

Here, a Org heading happened to contain the string “Day count”, which was also an an Org Radio link in that post. While ideally that shouldn’t have mattered, I removed that radio link to get around this Hugo bug.
```
 .. /Just may be/. But regardless, I am already enjoying writing once
-again, and it's great to see the <<<Day count>>> (counting up to 100)
+again, and it's great to see the Day count (counting up to 100)
 increase with each new post!
```
Code Snippet 5: Removing an Org Radio link

Validation Ignores #

Above fixes fixed 43 out of 46 errors, but the remaining 3 were unfixable.

5 Ignore errors due to hyperlinks in inline SVG #

"file:/public/notes/plantuml/index.html":114.474-114.678: error: Attribute "title" not allowed on element "a" at this point.

This error was caused by hyperlinks in inline SVG elements. These SVG elements are created by PlantUML. The hyperlinks in SVG feature works great, and as these are generated by PlantUML, I chose to just ignore these errors.

I ignored this error by adding the --ignore-re 'notes/plantuml.*Attribute.*title.*not allowed' switch to the html5validator command.

6 Ignore files not expected to serve HTML content #

"file:/public/googleFOO.html":1.1-1.52: error: Non-space characters found without seeing a doctype first. Expected "<!DOCTYPE html>".

The googleFOO.html file here is not a valid HTML file. It’s a just a cookie file that was used by Google to verify that I own this domain.

This error was masked by adding the --ignore 'googleFOO' switch to the html5validator command.

Summary #

Once I fixed the 43 errors by tweaking the Org mode content, and added those two ignores, I had zero validation errors! 🎉

If you are interested in the fix details, here are the commits.

Looping through Org mode headings

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Wed, 18 May 2022 23:29:00 -0400

Using the org-map-entries API to loop through selected or all headings in an Org file.

Table of Contents

org-map-entries API
Example: Modifying a property in all headings
org-map-entries References

Below question on Mastodon by the user @postroutine inspired me to write this post:

I got a lot of Org-Mode headings and I want to modify their properties (add, remove, edit). Is there a function to do the same modifications on each heading?

I think that the best solution to that question is using the org-map-entries function.

But somehow when replying to that question then, that wasn’t what first came to my mind! .. when ironically that function is the main function that enables my preferred subtree-based flow in ox-hugo 😆. So I am writing this post to better ingrain the following concept in myself ..

If you need to loop through headings in an Org buffer, and especially if you need to modify that buffer in the process, use org-map-entries¹.

Next,

I will give a give introduction to the org-map-entries API.
Then provide a super-short solution to the above question.

`org-map-entries` API #

I will give only a broad level overview on how to use this function. I would encourage the reader to refer to the resources at the end of this post to learn more about it.

So let’s start by looking at this function’s signature:

(org-map-entries FUNC &optional MATCH SCOPE &rest SKIP)

Code Snippet 1: Signature of the org-map-entries function

The org-map-entries function iterates through all the headings meeting the MATCH criteria in the determined SCOPE, and then calls the specified function FUNC at each of those headings.

The FUNC function accepts no arguments and is called at the beginning of each Org heading.
The optional second argument MATCH is either nil, t or a search string.
- If MATCH is nil or t, all headings will be visited by the iteration and FUNC will be called on all of them.
- But if MATCH is a string, the headings will first be filtered based on that string and then the FUNC will be called on only those.
For explanations on the optional SCOPE and SKIP arguments, see Org Info: Using the Mapping API or C-h f org-map-entries from within Emacs.

Here’s a typical org-map-entries call that loops through all the headings in the visible buffer: (org-map-entries #'some-function) where all the optional argument values are nil. Next, we’ll see some examples of string-type MATCH arguments used for filtering the headings.

MATCH strings #

Below table shows few examples of match string patterns.

Table 1: String-type MATCH argument examples for org-map-entries

Search string	Description	Example
`"TAG"`	Tag name	`"foo"` matches all headings with that tag
`"{TAG REGEXP}"`	Regexp matching tags	`"{f.*}"` matches all headings whose tags match that regexp
`"TAG1+TAG2+.."`	Tag set intersection	`"foo+bar"` matches all headings with both of those tags
`"TAG1-TAG2+.."`	Tag set difference	`"foo-bar"` matches all headings with `foo` tag but without `bar` tag
`"TAG1`\|`TAG2`\|`.."`	Tag set union or boolean OR	`"foo`\|`bar"` matches all headings with either of those tags
`"TAG1&TAG2&.."`	Tag set intersection or boolean AND	`"foo&bar"` is same as `"foo+bar"`
`"PROP`=`\"STRVAL\""`	Specified property value matching a string	`"color`=`\"blue\""` matches all headings where `color` property is `blue`
`"PROP<>\"STRVAL\""`	Specified property value not matching a string	`"color<>\"blue\""` matches all headings where `color` property is not `blue`
`"PROP`=`{VAL REGEXP}"`	Specified property value matching a regexp	`"color={b.}"` matches all headings where `color` property value matches ‘`b.`’ regexp
`"PROP[OP]NUMVAL"`	Specified property value compared with a numeric value	`"some_num`>=`10"` matches all headings where `some_num` property is >=10
`"LEVEL[OP]VAL"`	Check value of headline’s special property LEVEL	`"level>2"` matches all headlines at levels greater than 2
`"TODO[OP]\"STRVAL\""`	Check value of headline’s TODO state	`"TODO`=`\"DONE\""` matches all headlines with TODO state set to ‘DONE’

Comparison Types #

If the comparison value is a plain number, a numerical comparison is done, and the allowed operators are ‘<’, ‘=’, ‘>’, ‘<=’, ‘>=’, and ‘<>’.
If the comparison value is enclosed in double quotes, a string comparison is done, and the same operators are allowed.
If the comparison value is enclosed in curly braces, a regexp match is performed. For this comparison, only ‘=’ (regexp matches) and ‘<>’ (regexp does not match) operators are allowed.
Comparison with dates and Group Tags is also possible. See Org Info: Matching tags and properties for more details.

Other notes #

The property names are case-insensitive. So these all work the same: "COLOR<>\"blue\"", "color<>\"blue\"", "Color<>\"blue\"".
The “tag” and “property” matches can be mixed up using the boolean ‘&’, ‘|’, ‘+’ and ‘-’ operators. So searching ‘+LEVEL=3+boss-TODO="DONE"’ lists all level three headlines that have the tag ‘boss’ and are not marked with the TODO keyword ‘DONE’.
‘&’ binds more strongly than ‘|’.
Grouping of match expressions using parentheses is not supported.

Example: Modifying a property in all headings #

Below is an example solution to the Mastoson question that I referenced in the beginning of this post.

(defun test/set-property-at-heading ()
 "Function to be called at the beginning of an Org heading."
 (let ((el (org-element-at-point)))
 (org-set-property "foo" (org-element-property :title el))))
(org-map-entries #'test/set-property-at-heading)

Code Snippet 2: Dummy example showing how to set a property for all Org headings using org-map-entries

It defines a function that parses the Org element at point using org-element-at-point, gets the title property of the element This function is designed to be called by org-map-entries and so the point at the time of calling this function will always be on a heading. , and sets that to the headline element’s foo property.
The org-map-entries call now simply calls this function on each heading in the visible scope of the Org buffer.

`org-map-entries` References #

Org mode has another popular mapping/looping API function org-element-map. I won’t go into much detail about that in this post — I’ll just mention that org-element-map is not the best choice if you need to modify the original Org buffer. It’s main use is to loop through a parsed AST of an Org buffer and optional modify those elements in memory. ↩︎

Using Org Logbook Notes to record blog post updates

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Mon, 16 May 2022 00:59:00 -0400

Quick introduction to Org mode’s :LOGBOOK: feature and how I use it to record time-stamped notes for blog post updates.

Table of Contents

Prior forms of adding post updates
Introducing :LOGBOOK:
Adding notes to :LOGBOOK:
:LOGBOOK: Notes Example
References

Most of my blog posts are mainly to serve as documentation for my future self This post will serve to remind me how to get the :LOGBOOK: notes working once again in case I end up with some issue there. . So when I get a chance, I try to fix outdated stuff in my old blog posts. And along with the act of updating things, adding brief notes describing those updates comes naturally to me.

Prior forms of adding post updates #

As I author my posts in Org mode, I can easy enter a date stamp using the org-time-stamp command (bound by default to C-c . RET) and follow that by the update note.

While that worked, that approach bothered me because those notes didn’t have consistent format across multiple posts. For example, I might type the update as “*Update (<time stamp>)*: <note>” in one post, while I might type the same in a description list form in another: “- <time stamp>) :: <note>”.

To solve the consistency problem, I came up with this Org macro:

#+macro: update - $1 :: $2

Code Snippet 1: {{{update(..)}}} Org Macro

This worked mostly … except when the update text needed to be a bit longer, like a paragraph. It didn’t look elegant in that case. Also, if the text had a comma character in there, it needed to be escaped with a backslash (\).

Introducing `:LOGBOOK:` #

So when I learned A little bit of history .. I learned about the :LOGBOOK: drawer when Adam Porter mentioned it in ox-hugo Issue # 203 back in September 2018. I wanted to use that feature, but I didn’t have time and/or know-how on how exactly I would parse those Org Drawers in ox-hugo until very recently (May 2022)! about the Org :LOGBOOK: drawer, it solved all those problems: (i) consistency in adding notes (ii) easy to add update notes – in fact much easier (iii) easy to type long form notes (iv) no comma escaping needed.

Org Drawers look like this:

Content before the drawer
:DRAWERNAME:
Content inside the drawer
:END:
Content after the drawer

Code Snippet 2: Org Drawers

and they can be inserted anywhere in your Org content using the org-insert-drawer command (bound by default to C-c C-x d).

:LOGBOOK: is a special kind of drawer that’s auto-inserted by Org mode when certain actions are detected, like changing the TODO state of a subtree, or adding a note . That latter action is what this blog post is about.

Adding notes to `:LOGBOOK:` #

You need to enable this feature using one of these methods:

Set the org-log-into-drawer variable to a non-nil value (typically t) in your Emacs config, or as a file-local variable, or in your project’s .dir-locals.el (⭐ my preference).
Set #+startup: logdrawer to enable this for the whole Org file.
To enable this feature for only selected subtrees, set the :LOG_INTO_DRAWER: t property in the subtree (or one of its parent subtrees).

Once this is set, call the org-add-note command (bound by default to C-c C-z). That will open a window with ∗Org Note∗ buffer where-in you will type your post update and then C-c C-c to save it to the subtree’s :LOGBOOK: drawer. If that drawer didn’t exist already, it will be created directly under the subtree’s heading.

The note will get recorded in this format by default under the current subtree:

* Subtree title
:LOGBOOK:
- Note taken on <current date and time> \\
 <note text>
:END:

Code Snippet 3: Default format of a :LOGBOOK: note

As you see, you only type the note text, and the time-stamp is inserted automatically.

`:LOGBOOK:` Notes Example #

Here are the update notes from one of my posts:

:LOGBOOK:
- Note taken on <2018-08-26 Sun> \\
 Mention =org-babel-demarcate-block=, tweak the =org-meta-return= advice.
- Note taken on <2018-08-23 Thu> \\
 Use ~M-return~ instead of ~C-return~ for splitting blocks and
 support upper-case blocks (though I [[* Converting Org keywords to lower-case][don't prefer those]]!).
:END:

Code Snippet 4: Examples of post update notes added to the :LOGBOOK: drawer

You can see how they rendered at the top of the Splitting an Org block into two post.

If you are an ox-hugo user following the subtree-based export flow, and would like to export :LOGBOOK: notes in a similar fashion, check out the ox-hugo Manual: Drawers page for details.

References #

Building Org Development version (2022)

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Fri, 13 May 2022 17:01:00 -0400

A guide on how to build Org mode from its main branch and load in Emacs without any path shadowing.

Table of Contents

1 Clone the Org repo
2 Build Setup
- Customizing local.mk (Optional)
3 Build
4 Set the correct paths in your Emacs config
5 Testing that the right Org version got loaded
Future Org development version updates
References

This post is a re-write of an earlier “Building Org Development version” post but minus all the outdated stuff.

I am assuming that you already know what Org mode is and that’s why you are here 😃.

You would want to build Org from its development branch (main branch) to get the latest and greatest goodies plus bug fixes! Go through the ORG-NEWS file to read about what’s new in the main branch.

If you like what you see there, here are the steps for installing the development version of Org.

1 Clone the Org repo #

git clone https://git.savannah.gnu.org/git/emacs/org-mode.git

2 Build Setup #

Copy <REPO_ROOT>/mk/default.mk to <REPO_ROOT>/local.mk
Tweak local.mk (optional)

Customizing `local.mk` (Optional) #

Here are few variables that you might like to change in the local.mk:

prefix

Org installation directory

prefix = /dir/where/you/want/to/install/org # Default: /usr/share

The .el files will go to $(prefix)/emacs/site-lisp/org by default. If you’d like to change that, change the lispdir variable too.

infodir

Org Info installation directory. I like to keep the Info file for development version of Org in a separate directory.

infodir = $(prefix)/org/info # Default: $(prefix)/info

ORG_MAKE_DOC

Types of Org documentation you’d like to build by default. Setting below generates only the Org Info manual.

ORG_MAKE_DOC = info # Default: html pdf

3 Build #

make autoloads
make
make doc
make install

Type make help for help on the Org Makefile. Type make helpall to get a detailed help, or see the Org build system help.

4 Set the correct paths in your Emacs config #

Update load-path to remove the Org version that ships with Emacs. Do the same if you have Org installed via GNU ELPA If you need the latest stable version of Org mode, install it from GNU ELPA. too.
Also remove the associated old Org mode Info manuals from Info-directory-list.
Update the load-path and Info-directory-list variables to point to the Org mode source code and Info manual built using the main branch.

Below code does all that but make sure this code is executed after you do (package-initialize), but before you require the org package . You can use use-package and make sure that this order of code evaluation is always correct — Just put the code from Code Snippet 2 where <HERE> is shown in the below snippet:

(use-package org
 :preface
 <HERE>)

Code Snippet 1: Update load-path and Info-directory-list in use-package :preface

(defvar modi/org-version-select 'dev
 "Variable to choose the version of Org to be loaded.
Valid values are `dev', `elpa' and `emacs'.

When set to `dev', the development version of Org built locally
is loaded.
When set to `elpa', Org is installed and loaded from GNU ELPA.
When set to `emacs', the Org version shipped with Emacs is used.")

(defvar modi/default-lisp-directory "/your/emacs/share/dir/version/lisp/"
 "Directory containing lisp files for the Emacs installation.

This value must match the path to the lisp/ directory of your
Emacs installation.

If Emacs is installed using --prefix=\"${PREFIX_DIR}\" this value
would typically be
\"${PREFIX_DIR}/share/emacs/<VERSION>/lisp/\".")

(defvar org-dev-lisp-directory "/value/of/lispdir/in/local.mk"
 "Directory containing lisp files for dev version of Org.

This value must match the `lispdir' variable in the Org local.mk.
By default the value is \"$prefix/emacs/site-lisp/org\", where
`prefix' must match that in local.mk too.")

(defvar org-dev-info-directory "/value/of/infodir/in/local.mk"
 "Directory containing Info manual file for dev version of Org.

This value must match the `infodir' variable in the Org local.mk.")

(when (and org-dev-lisp-directory
 org-dev-info-directory)
 (with-eval-after-load 'package
 ;; If `modi/org-version-select' is *not* `emacs', remove the Emacs
 ;; version of Org from the `load-path'.
 (unless (eq modi/org-version-select 'emacs)
 ;; Remove Org that ships with Emacs from the `load-path'.
 (let ((default-org-path (expand-file-name "org" modi/default-lisp-directory)))
 (setq load-path (delete default-org-path load-path))))

 ;; If `modi/org-version-select' is *not* `elpa', remove the Elpa
 ;; version of Org from the `load-path'.
 (unless (eq modi/org-version-select 'elpa)
 (dolist (org-elpa-install-path (directory-files-recursively
 package-user-dir
 "\\`org-[0-9.]+\\'"
 :include-directories))
 (setq load-path (delete org-elpa-install-path load-path))
 ;; Also ensure that the associated path is removed from Info
 ;; search list.
 (setq Info-directory-list (delete org-elpa-install-path Info-directory-list))))

 (let ((dev-org-path (directory-file-name org-dev-lisp-directory))
 (dev-org-info (directory-file-name org-dev-info-directory)))
 (if (eq modi/org-version-select 'dev)
 (progn
 (add-to-list 'load-path dev-org-path)
 ;; It's possible that `org-dev-info-directory' is set to
 ;; an unconventional value, in which case, it will not be
 ;; automatically added to `Info-directory-alist'. So add
 ;; it to `Info-directory-alist' manually.
 (add-to-list 'Info-directory-list dev-org-info))

 ;; If `modi/org-version-select' is *not* `dev', remove the
 ;; development version of Org from the `load-path', and its
 ;; Info from the Info search list.
 (setq load-path (delete dev-org-path load-path))
 (with-eval-after-load 'info
 (setq Info-directory-list (delete dev-org-info Info-directory-list)))))))

Code Snippet 2: Emacs config snippet to ensure that load-path and Info-directory-list use the right Org version

Note

Remember that you need to correctly set the values of these 3 variables in the above snippet:

modi/default-lisp-directory
org-dev-lisp-directory
org-dev-info-directory

5 Testing that the right Org version got loaded #

Restart Emacs (Don’t be lazy — do it!)

M-x org-version – That should show something like this in the echo area:

Org mode version 9.5.3 (release_9.5.3-482-gd5a52b @ /home/kmodi/usr_local/apps/7/emacs/emacs-28/share/emacs/site-lisp/org/)

This message format is broken down as:

Org mode version <ORG-VERSION> (release_<ORG-VERSION>-NNN-g<GIT-HASH> @ <PREFIX>/emacs/site-lisp/org/)

If the GIT-HASH and PREFIX above are what you expect, congratulations! You did it! 🎉

Else, let me know in comments if I can help you.

Future Org development version updates #

Below will do git pull and build Org.
```
make update
```
Restart Emacs.

References #

Creating a patch file using Magit

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Sun, 08 May 2022 08:48:00 -0400

Quick tip on how to create git patch files in Emacs using Magit.

Table of Contents

Single-file patch
Multi-file patch
More Resources

Recently I came across few instances where people were asking questions related to creating patches for contributions to Emacs and Org mode repos here and then here. I was in the same shoes back then when I was about to make my first contribution to Emacs. And so I thought of sharing this tip on how to use Magit to create patch files.

If you have been using both Emacs and git, you might have already heard about the awesome Magit package. If you haven’t 😲, check out this screenshot-annotated review of what Magit is. With that out of the way, and assuming that you already have it installed (use-package magit :ensure t) , here’s how to create a patch file using Magit ..

Single-file patch #

Commit your changes to the git repo first.
Bring up the Magit Log view. From the Magit status buffer, you would type l l to show the log of the current branch.
Move the point to the commit that you want to send as a patch file, and hit W c c RET.
- The last RET selects the commit the point is on, in the ∗magit-log∗ buffer.
- If the first line of the commit log of the selected commit is “Update docstrings for shortdoc.el”, you’ll see a patch file named 0001-Update-docstrings-for-shortdoc.el.patch created in your git repo root.
- You can now email this patch file as an attachment to bug-gnu-emacs@gnu.org (if contributing to Emacs) or to emacs-orgmode@gnu.org (if contributing to Org mode).

Multi-file patch #

If you need to create a multi-file patch i.e. patch files for a series of commits, select those commits in the ∗magit-log∗ buffer The commit selection process is the same as how you would select text in any Emacs buffer. For example, if I want to create a series of 5 patches, I would go to the latest commit in the series, hit C-SPC and then C-n 4 times to select 5 rows of commits. , and then use the same W c c binding.

More Resources #

Here are the official contribution guides for Emacs and Org mode:

Here are some more resources that got shared in the Emacsverse recently (within the past year as of writing this):

<2022-04-23 Sat> Contributing patches to Org – Ihor Radchenko
<2022-04-09 Sat> Primer on formatting Git patches with Emacs (Magit) – Protesilaos Stavrou
<2021-08-17 Tue> Contributing to Emacs – Colin Woodbury

Presenting tomelr!

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Wed, 04 May 2022 01:03:00 -0400

In this post, I introduce a little library I created for ox-hugo to have a robust mechanism for generating TOML from any Lisp expression.

Table of Contents

My flow for creating this library
Adapting the library to fit ox-hugo
Changes in ox-hugo tests
What’s next?
- Unblocking some future ox-hugo improvements

In my previous post Defining tomelr, I started toying with the idea of creating a library that would help convert any Lisp expression to a TOML config, and I share my vision (specification) of what this library would look like.

I wasn’t even sure if I would be able to make the tomelr library feature-complete at least to the extent of what ox-hugo was already doing! But to my surprise, the library development snowballed to a completion much earlier than I thought, and additionally it helped fix some inconsistencies that the older TOML generation code had in ox-hugo.

In this post, I start by (i) giving a broad overview of how the development of tomelr happened, then (ii) briefly describe how it got integrated into ox-hugo, and finally (iii) how the use of this library will unblock the path to addition of some cool features to ox-hugo.

My flow for creating this library #

Write the spec for the library.
- List all the formats of Lisp data I would expect it to process.
- List the corresponding TOML data I would expect it to generate.
- Ensure that I am not inventing my own lisp syntax by confirming that the expected TOML output matches the JSON generated from that same lisp form (using the Emacs built-in json.el library).
That helped me write the tests first! – Test Driven Development (TDD).
I started with writing tests for TOML booleans and then implementing that (because that was the simplest and easiest). Of course, I used ert for this! ert helped me quickly create small modular tests Here’s the ert test for booleans as an example. and efficiently iterate through modifications in the library code until I got the tests to pass.
Once that got working, I set up a continuous integration system using GitHub Actions (GHA). I used GHA because I host my library on GitHub. Also I already have a tried and tested setup that I could get up and going in a matter of few seconds. In general, this concept would apply to any Continuous Integration system. The CI setup step should come early in the development of any project so that incremental feature additions don’t start breaking previously added features 😃.
The library development just snowballed after this point .. added support for integers, floats, regular strings, multi-line strings, arrays, TOML tables, arrays of TOML tables. By this time, the library was about 80% finished.
Then came the difficult part .. stabilizing the library to support all the varieties of Lisp data I can think of. I must have put in double the time spent so far to finish the remaining 20% of the planned features for this library 👉 tomelr test suite
Once I had the test suite complete and passing, it was time to do some code cleanup:
- Remove duplicate code and break them off into smaller helper functions.
- See if the function defined in this library is already defined somewhere else (in this case, I was able to use json-plist-p directly from json.el).
- Proof read the code.
- Proof read the docstrings and run M-x checkdoc to fix their formatting.
- Ensure that the code compiles without any warnings.
- Remove unnecessary customization options and case statements from the library (while continuously ensuring that the ert tests still pass).

Adapting the library to fit `ox-hugo` #

After polishing the library by its stand-alone testing, I decided to use it with ox-hugo and see how the test suite in that repo fared.

Of course I saw that a lot of tests failed now 😁.

The main issue was that tomelr was constructing multi-line strings such that the spaces translated exactly from Lisp data to TOML. So (tomelr-encode '((foo . "line1\nline2"))) would generate:

foo = """
line1
line2"""

Code Snippet 1: Multi-line string with same white-space as in original data.. but not that "pretty"

whereas ox-hugo expected the same TOML to look like:

foo = """
 line1
 line2
 """

Code Snippet 2: Pretty multi-line string, but with extra white-space

I had intentionally decided for ox-hugo to have this latter format for multi-line strings because (i) it made it more readable with the triple-quotes out of the way on their own lines, (ii) the indented lines prevented the multi-line string from getting mixed with surrounding TOML parameters, and most importantly (iii) these strings were processed by the Hugo Markdown parser, and so it wasn’t sensitive to horizontal spaces.

And so the tomelr-indent-multi-line-strings feature was born (commit) which optionally made tomelr export multi-line strings as expected by ox-hugo 😎.

Changes in `ox-hugo` tests #

Once I had finalized the integration of tomelr into ox-hugo, I had only about 30 tests change out of roughly 400 tests. These changes were welcome as they fixed all the inconsistencies in the older TOML generation code in ox-hugo. If interested, you can see this commit for the diff and details, but here’s the gist:

Now nil value of a key in Lisp consistently implies that the key should not be exported to TOML. So '((foo . nil)) will result in foo not getting exported to TOML, whether that’s a top-level key or a key in a nested TOML map or array. If you need to set a key to a boolean false, use "false" or any value from tomelr-false.
Earlier empty string value as in '((foo . "")) behaved like the current nil implementation. That’s not the case any more. Now that empty string will export as foo = "" in TOML.
Now if a string has a quote character (") in it, that value will auto-export as TOML multi-line string. I like the readability of this more than that of backslash-escaped double-quotes.
Now the nested tables like [menu."nested menu"] export with their parent table keys like [menu]. As per the TOML spec, this is not required. But now that tomelr has added a generic support for any TOML table, this change happens as a result of consistency 💯.

In summary, the changes in ox-hugo TOML front-matter exports were mostly cosmetic, and if they were not cosmetic, they were consistency fixes.

What’s next? #

tomelr: The library is pretty much feature complete ✨ as many of the examples from TOML v1.0.0 spec have been added to its test suite, and .. it is supporting all the ox-hugo use cases.
The library though has one limitation that I’d like to resolve at some point — Right now, we require the Lisp data to first list all the scalar keys and then list the TOML tables and arrays of tables. But at the moment, I don’t know how to fix that, and also ox-hugo is not affected by that (because it already populates the front-matter alist in the correct order). So fixing this is not urgent, but of course, if someone can help me out with that, I’d welcome that! 🙏.
ox-hugo: Given that tomelr allows robustly exporting any Lisp data expression to TOML, I do not see any value in continuing with YAML generation support using the old custom code.
📢 In near future, I plan to get rid of the org-hugo-front-matter-format customization variable from ox-hugo — thus deprecating YAML export support This change should not functionally affect the YAML front-matter fans out there because the front-matter that ox-hugo is exporting is mainly for Hugo’s consumption. The only scenario where I see that this change can be breaking is if the user is using YAML format extra front-matter blocks. If so, unfortunately, they will need to convert those to TOML manually. and sticking with using just TOML for the front-matter.

Unblocking some future `ox-hugo` improvements #

This decision will open up the doors to add more features to ox-hugo like:

Exporting Org :LOGBOOK: drawers to TOML front-matter (ox-hugo # 504)
Exporting Org Special Blocks to user-configurable front-matter (ox-hugo # 627)
Supporting more complex data in Lisp form using :EXPORT_HUGO_CUSTOM_FRONT_MATTER: which could translate to nested TOML tables or arrays of TOML tables.

Finally, there won’t be a need to use the “Extra front-matter” workaround. For example, it would be possible to represent the data in that first example on that page as :foo ((:bar 1 :zoo "abc") (:bar 2 :zoo "def")) in the :EXPORT_HUGO_CUSTOM_FRONT_MATTER: property.

Defining tomelr – A library for converting Lisp expressions to TOML

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Thu, 28 Apr 2022 00:08:00 -0400

Creating a specification for an Emacs-Lisp library to convert Lisp data expressions into easy-to-read TOML strings.

Table of Contents

Using json-encode as reference
Mapping scalar data to TOML
- About :false
Mapping lists to TOML
Mapping lists of lists to TOML
Mapping other object types
Closing

ox-hugo has some custom code that generates TOML I ❤️ TOML. As the makers of this config format put it.. “it’s a format for humans”! — No need to deal with indentations, weird syntax for multi-line strings, no prohibition on adding comments to the config, or dealing with careful placement of commas and braces. for Hugo front-matter, based on the Org keywords and other meta-data that the user sets in their Org file. But this TOML generation code is not generic enough for any TOML object type.

As I am writing up a definition on how to export :LOGBOOK: drawers, I felt it’s a good time to polish the whole Lisp data → TOML conversion code, and may be package that into a separate library.

It’s kind of an ambitious project — I am calling it tomelr ✨

It’s a big undertaking to create a generic library for this kind of data format conversion. But even before I start coding or think if I can complete this project, I need to spec I am not sure if it’s a widely used verb, but to spec means to write a specification for something. it. I need to understand early-on how the S-exp (Symbolic lisp expression) would needed to look for each kind of generated TOML object — scalars, lists, lists of lists, maps, lists of maps, etc.

Using `json-encode` as reference #

The aim of the tomelr library is to take some (lisp data) and convert that TOML. But I did not want to invent my own lisp data convention for this! So I decided to stick with the lisp expression conventions understood by the json-encode function from the Emacs core library json.el.

Credit for the json.el idea goes to this tweet by Piers Cawley:

I’d suggest that By “that”, he’s referring to adding support for exporting front-matter to JSON in ox-hugo. , since emacs has built in JSON support these days, you don’t really have to worry about the commas and braces, just build the s-exp you want and export, but it’s you that’s writing the code and I’m just delighted that it exists.

Thank you for your efforts.

I am not sold on adding support of yet another front-matter format to ox-hugo. I might not use json.el for that, but it definitely helped me a lot with coming up with this library’s spec 😆.

Mapping scalar data to TOML #

Figuring out the Lisp representation for scalar (plain key-value pairs) TOML objects was easy. json.el helped figure out how to deal with nil and false values.

Table 1: Mapping of scalar Lisp data to TOML

Lisp S-exp	TOML
`'((int_key . 123))`	`int_key = 123`
`'((float_key . 1.23))`	`float_key = 1.23`
`'((date_key . 2022-04-27))`	`date_key = 2022-04-27`
`'((bool_key . t))`	`bool_key = true`
`'((any_key . nil))`	(key removed in TOML)
`'((bool_key . :false))`	`bool_key = false`

About `:false` #

json.el defines a variable json-false that’s set to the value :json-false. This is because in JSON, the null value is different from the boolean false value.

nil in Lisp → null in JSON
:json-false in Lisp → false in JSON

Inspired by that decision of json.el, I am thinking of using :false as the special value that will set the equivalent TOML value to boolean false.

TOML does not define a null value, but if the Lisp value is nil, that key will simply not be translated to TOML.

Mapping lists to TOML #

Mapping lists was simple.. because in Lisp, a list value of course looks like '((foo . (1 2 3 4 5))) 😃.

Table 2: Mapping of list Lisp data to TOML

Lisp S-exp	TOML
`'((list_key1 . (1 2 3)))`	`list_key1 = [1, 2, 3]`
`'((list_key2 . ("a" "b" "c")))`	`list_key2 = ["a", "b", "c"]`

Mapping lists of lists to TOML #

Table 3: Mapping of list of list Lisp data to TOML

Lisp S-exp	TOML
`'((lol_key . [(1 2) (3 4)]))`	`lol_key = [ [1, 2], [3, 4] ]`

I was going to use '((lol_key . ((1 2) (3 4)))) as the reference Lisp expression for lol_key = [ [1, 2], [3, 4] ]. But I found out that json-encode throws an error if you pass it that expression! I don’t understand the reason for that error, and so I have asked for help on the help-gnu-emacs mailing list.

But while that question gets resolved, I wanted to move forward with the spec definition. After some trial-and-error and reverse-engineering json.el I knew how I wanted TOML to look. So I used an online JSON/TOML converter to convert that TOML snippet to JSON, and then used json-read to convert JSON to Lisp expression. , I learned that list of list data needs to be represented using a Vector type, and so '((lol_key . [(1 2) (3 4)])) would be the correct expression – Notice the use of square brackets instead of parentheses for the outer vector.

Mapping other object types #

Once I figured out how to map the above data types, mapping Lisp data to TOML Tables aka dictionaries and arrays of Tables was a breeze Of course, the breeze is referring to the ease of writing the spec for these 😆. Implementation-wise, the tables, arrays of tables, and the especially nested variants of those are going to be the most challenging. .

Closing #

It was fun coming up with an initial draft of the specification for this library. My next steps would be to gradually add TOML generator functions (as I find time) to this library, along with ERT tests! Eventually, I will remove the existing TOML generation code from ox-hugo and depend on this library.

Getting back to my plan for exporting :LOGBOOK: drawers in ox-hugo, based on this spec, I will need to construct this date in Emacs-Lisp:

(org_logbook . (((timestamp . 2022-04-08T14:53:00-04:00)
 (note . "This note addition prompt shows up on typing the `C-c C-z` binding.\nSee [org#Drawers](https://www.gnu.org/software/emacs/manual/html_mono/org.html#Drawers)."))
 ((timestamp . 2018-09-06T11:45:00-04:00)
 (note . "Another note **bold** _italics_."))
 ((timestamp . 2018-09-06T11:37:00-04:00)
 (note . "A note `mono`."))))

Code Snippet 1: Example data from a :LOGBOOK: drawer in Lisp format

.. will translate to this in TOML:

[[org_logbook]]
 timestamp = 2022-04-08T14:53:00-04:00
 note = """This note addition prompt shows up on typing the `C-c C-z` binding.
See [org#Drawers](https://www.gnu.org/software/emacs/manual/html_mono/org.html#Drawers)."""
[[org_logbook]]
 timestamp = 2018-09-06T11:45:00-04:00
 note = """Another note **bold** _italics_."""
[[org_logbook]]
 timestamp = 2018-09-06T11:37:00-04:00
 note = """A note `mono`."""

Code Snippet 2: Same example data from the :LOGBOOK: drawer translated to TOML format

Check out the below link where I have documented the equivalent expressions between Lisp, TOML and JSON for all the object types.

👉 tomelr Specification

Improving ox-hugo exported Org "info:" links

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Fri, 15 Apr 2022 22:50:00 -0400

In my previous post, I talked about how info: Org link export support got added to ox-hugo. This post is about making those exported links a tiny 🤏 bit better.

Table of Contents

💪1: Exported links now point to separate pages in the manual
💪 2: Export Org manual links to orgmode.org URLs
💪 3: Link hover text shows the elisp code for accessing the Info node
Final code in ox-hugo that exports the info: links

After writing my previous post, I had shared its link on the Org mode mailing list For folks who don’t know, you can email the Org mode mailing list (emacs-orgmode@gnu.org) about pretty much anything Org mode related: any help you want, a bug you want to report, a patch you want to submit, or just share your positive or negative experiences with Org mode or thank someone for their awesome work. here, and received some helpful feedback from Max Nikulin.

Thank you Max!

This post is a response to his feedback, and it also describes a few improvements made for info: link exports in ox-hugo based on that.

The commits for this info: link export improvements can be found in ox-hugo PR # 620.

💪¹ 1: Exported links now point to separate pages in the manual #

Feedback

 For <info:emacs#Browse-URL> export to html produces the following link:
 https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Browse_002dURL
 I think, a better variant is
 https://www.gnu.org/software/emacs/manual/html_node/emacs/Browse_002dURL.html
 even though for the Org manual I often prefer single-page HTML version.

I really liked this suggestion!

Earlier, the Info node references were exporting to an anchor on a huge single-page HTML manual e.g. emacs.html#Browse_002dURL
After implementing this fix, the exported link points to a separate HTML page for that node e.g. emacs/Browse_002dURL.html.

Now, [[info:emacs#Screen]] exports and renders to Emacs Info: Screen, and a Top level node like [[info:emacs#Top]] exports and renders to Emacs Info.

For consistency, all info: links will now be exported to URLs pointing to the separate node HTML pages, even for Org manual links.

💪 2: Export Org manual links to `orgmode.org` URLs #

Feedback

(About an example info: link pointing to Org manual: [[info:org#Top]])

And the link target ideally should be https://orgmode.org/manual/index.html

This was another great suggestion!

By default, the Org manual info: links will export to URLs pointing to the Org manual shipped with Emacs. That manual will be associated with the Org mode version that shipped with the last stable version of Emacs. So depending on how long it has been since the last Emacs release, you could be referring to quite an older version of the Org manual.

If you install Org from GNU Elpa, you can get an update of the latest stable Org version every week ! There’s a related post on Org mode’s Release Flow that might interest you. And the manual hosted on https://orgmode.org gets updated every week as well. I would like to always refer to the latest Org manual with the latest fixes and documentation improvements, and so I agree with Max’s suggestion above.

Now [[info:org#Top]] exports and renders as Org Info and the Org manual nodes like [[info:org#Working with Source Code]] also export as a link to a page in that manual: Org Info: Working with Source Code.

💪 3: Link hover text shows the elisp code for accessing the Info node #

Feedback

 I would prefer
 info "(org) Top"
 to
 Org Info: Top
 since the former may be pasted to M-x : or to shell command prompt.

I wanted the link descriptions in the exported markdown to be more “English” and understandable to people not familiar with the Emacs Info interface. So I decided to keep this mostly unchanged ..

I did not change the link description, but I did add a new HTML title attribute to the link. This attribute contains the Emacs Lisp code needed to access the Info manual from Emacs. The user will see the text from this attribute when they hover the mouse over the links. If you haven’t already discovered this feature, try hovering the mouse over that last link above and you should see this 😃 :

Figure 1: Hovering the mouse over the exported info: links will show the Emacs Lisp code for accessing the same node from Emacs

Of course, the user will still not be able to copy that text and paste in Emacs. But it will still provide them enough hint on how to access Info nodes in Emacs.

Final code in `ox-hugo` that exports the `info:` links #

Here’s the version of the org-hugo--org-info-export function that handles the exports of info: links as of today (<2022-04-15 Fri>):

org-hugo--org-info-export function from ox-hugo

888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912


(defun org-hugo--org-info-export (path desc format)
 "Add support for exporting [[info:..]] links for `hugo' format."
 (let* ((parts (split-string path "#\\|::"))
 (manual (car parts))
 (node (or (nth 1 parts) "Top"))
 (title (format "Emacs Lisp: (info \\\"(%s) %s\\\")" manual node))
 (desc (or desc
 (if (string= node "Top")
 (format "%s Info" (capitalize manual))
 (format "%s Info: %s" (capitalize manual) node))))
 ;; `link' below is mostly derived from the code in
 ;; `org-info-map-html-url'.
 (link (cond ((member manual org-info-emacs-documents)
 (let ((manual-url (if (string= (downcase manual) "org")
 "https://orgmode.org/manual"
 (format "https://www.gnu.org/software/emacs/manual/html_node/%s" manual)))
 (node-url (if (string= node "Top")
 "index.html"
 (concat (org-info--expand-node-name node) ".html"))))
 (format "%s/%s" manual-url node-url)))
 ((cdr (assoc manual org-info-other-documents)))
 (t
 (concat manual ".html")))))
 (when (member format '(md hugo))
 (format "[%s](%s \"%s\")" desc link title))))

Code Snippet 1: ox-hugo's version of org-info-export (ol-info.el) function

Link to code in the repo

I will leave it as an exercise for the reader to map the lines in above code snippet to the features described in this post 🍀.

Just for giggles, I am using 💪 as a replacement for “Improvement” ↩︎

Linking and Exporting Org "info:" links

Kaushal.Modi@fakeEmailToMakeValidatorHappy.com (Kaushal Modi) — Tue, 12 Apr 2022 13:51:00 -0400

Journey of Org links from copying (storing) them, inserting them in Org documents and exporting them. The focus of this post is on the info: type Org links, but the same concept would apply to any Org link type.

Table of Contents

1 Storing links to Info nodes
2 Inserting stored links
- Org Link library for info: links (ol-info)
3 Exporting [[info:..]] links using ox-hugo
Summary

This post was inspired out of the exercise of support info: Org link exports in ox-hugo.

There are 3 steps:

Storing a link from any buffer that you want to later document in an Org file.
Inserting that link that you stored earlier.
Exporting the Org document.

I am focusing on the info: Org links in this post, they these steps apply to any Org link type.

1 Storing links to Info nodes #

If you follow the instructions on Org Info: Activation, you’ll see that it is recommended This post assumes that you have actually set this binding. If you haven’t yet, go do it already! (global-set-key (kbd "C-c l") #'org-store-link) to bind the org-store-link command to C-c l in your Emacs global map.

org-store-link stores an Org Mode compatible link based on the context i.e. type of buffer where the point is. Org supports a variety of links as documented in Org Info: External Links.

If the point is in an ∗Info∗ buffer and org-store-link is called, it stores an info: type link that will lead back to the same node where the point was.

Let’s say you have opened the Org Info manual and you hit C-c l. You should then see this in the Echo Area:

Stored: org#Top

The link to Org manual’s Top node is stored by that command, but only temporarily – it isn’t yet saved anywhere.

2 Inserting stored links #

These stored links can now be saved in an Org file. To do that,

Visit an Org file or a buffer and call M-x org-insert-link (bound to C-c C-l by default) and follow the prompts.
An immediate RET after the prompt will select the last stored link to be inserted.
The second prompt allows you to change the link description, and then the link will be inserted.

If I insert the org#Top Info link that I stored earlier over here, and accept the default link description, it will paste as [[info:org#Top][org#Top]].

But .. how did the link description become “org#Top” by default?

The ol-info.el library did that.

Org Link library for `info:` links (`ol-info`) #

The default description for info: type links was set at the time of storing those links, with the help of the org-info-store-link function in ol-info.el. That same description is then suggested at the time of inserting that link.

This library defines these “actions” for [[info:..]] type of links:

:store: Defines when (in which buffer, major mode, etc.) the “store” operation should store to an info: type link, and what metadata should be stored. Some of the stored metadata are: the Info file name, node name, link string and description string.
:follow: Defines what action to perform when org-open-at-point (C-c C-o) is called with point on the link. Hitting this binding with point on an info: link will open or switch to that ∗Info∗ node.
:export: Defines how the link should be exported for various backends. ol-info defines how the info: links should be exported, but only for html and texinfo backends.

3 Exporting `[[info:..]]` links using `ox-hugo` #

ol-info.el defines the :export “action” such that info: links get converted to hyperlinks pointing to online Org manual pages, when exporting using ox-html.

But it didn’t do the same when exporting using ox-hugo. That feature got added recently in this ox-hugo commit. Now ox-hugo exports [[info:org#Top][org#Top]] to org#Top.

I didn’t like the # that org-info-store-link added to the default description (notice that previous link). So I added a tiny little feature to the info: export behavior 😁 — If you leave the info: link descriptions empty when inserting the links, ox-hugo injects its own “auto description” which are better (in my opinion).

Now when that same Info link is inserted description-less as [[info:org#Top]], it renders to: Org Info.

Summary #

Store link (from anywhere in Emacs) : C-c l
Insert link (in an Org file) : C-c C-l
Export the Org file as usual.

emacs on A Scripter's Notes

Using Git Delta with Magit

Installing delta #

Installing magit-delta #

Configuring delta #

Gujarati Transliteration

Enabling transliteration #

Toggling the input method #

Caveats with Gujarati and other Indic language transliteration #

“Input method” cheat sheet #

Closing #

References #

View GitHub Pull Requests in Magit

Locally creating a branch for a PR #

Getting references to all Pull Requests #

Automatically adding PR refs #

Summary #

References #

Gujarati fonts in Emacs

Setting a “fontset” font #

Gujarati fonts #

Emacs Lisp: Advice Combinators

Overview on using advices #

1 :before #

2 :after #

3 :override #

4 :around #

5 :before-while #

6 :before-until #

7 :after-while #

8 :after-until #

9 :filter-args #

10 :filter-return #

Summary #

References #

Org: Show only Post subtree headings

Org Global Cycle #

Skeleton of only Post headings #

The “Collapse All Posts” function #

Binding with C-u C-c TAB #

Result #

Zero HTML Validation Errors!

1 Avoid duplicate heading id attributes #

2 Remove inline <style> elements #

3 Ensure that all images have captions or alt attributes #

4 Do not have hyperlinks in headings #

Validation Ignores #

5 Ignore errors due to hyperlinks in inline SVG #

6 Ignore files not expected to serve HTML content #

Summary #

Looping through Org mode headings

org-map-entries API #

MATCH strings #

Comparison Types #

Other notes #

Example: Modifying a property in all headings #

org-map-entries References #

Using Org Logbook Notes to record blog post updates

Prior forms of adding post updates #

Introducing :LOGBOOK: #

Adding notes to :LOGBOOK: #

:LOGBOOK: Notes Example #

References #

Building Org Development version (2022)

1 Clone the Org repo #

2 Build Setup #

Customizing local.mk (Optional) #

3 Build #

4 Set the correct paths in your Emacs config #

5 Testing that the right Org version got loaded #

Future Org development version updates #

References #

Creating a patch file using Magit

Single-file patch #

Multi-file patch #

More Resources #

Presenting tomelr!

My flow for creating this library #

Adapting the library to fit ox-hugo #

Changes in ox-hugo tests #

Installing `delta` #

Installing `magit-delta` #

Configuring `delta` #

1 `:before` #

2 `:after` #

3 `:override` #

4 `:around` #

5 `:before-while` #

6 `:before-until` #

7 `:after-while` #

8 `:after-until` #

9 `:filter-args` #

10 `:filter-return` #

Binding with `C-u C-c TAB` #

1 Avoid duplicate heading `id` attributes #

2 Remove inline `<style>` elements #

3 Ensure that all images have captions or `alt` attributes #

`org-map-entries` API #

`org-map-entries` References #

Introducing `:LOGBOOK:` #

Adding notes to `:LOGBOOK:` #

`:LOGBOOK:` Notes Example #

Customizing `local.mk` (Optional) #

Adapting the library to fit `ox-hugo` #

Changes in `ox-hugo` tests #

Unblocking some future `ox-hugo` improvements #

Using `json-encode` as reference #

About `:false` #

💪¹ 1: Exported links now point to separate pages in the manual #

💪 2: Export Org manual links to `orgmode.org` URLs #

Final code in `ox-hugo` that exports the `info:` links #

Org Link library for `info:` links (`ol-info`) #

3 Exporting `[[info:..]]` links using `ox-hugo` #