Use The Right Tool
September 30, 2025
Do not pound nails with a dish-rag, nor wash dishes with a hammer.
My father, a civil engineer and carpenter (among his other callings), often said to me, Use the right tool for the job.
The job I had in mind involved making a table of contents for a web page, such as the following.
For good and sufficient reasons today, I concluded that Emacs Lisp cannot be my first choice of programming language for searching and selecting certain bits of text out of an html file, such as the one I wrote for this blog post.
PLEASE NOTE: I subsequently resolved the issues I describe in this article. For more information see the next post: Automate html Links with Emacs Lisp.
The headline that follows here can give an illustration of my goal and of the problem I encountered.
The Contents of an <h2> Tag
The html code for the headline looks like this:
<h2 id="the-contents-of-an-h2-tag">The Contents of an <h2> Tag</h2>
"<h2>" indicates a kind of sub-heading, the title of a section in an article. This section concerns itself with its own sub-heading.
Notice that the <h2> tag expands to include an id attribute, a string of words separated by hyphens enclosed within its pair of '<' and '>' brackets. This string of words uniquely identifies the tag.
Html code elsewhere on the page, or anywhere in the whole wide world for that matter, can use that id attribute as a navigation landmark.
Unfortunately, I found that searching to select the text of the id-attribute can leave the Emacs Lisp language tongue-tied. Save that thought. The next section deals with it.
Above here, this web page precedes all of the <h2> tags with a table of contents listing links to their navigational landmarks. It even includes a link to this section. I repeat the link below, for illustration.
To see how the link works, first scroll this page up until the sub-heading disappears above the top of the display window but the link is still visible. Then click the link. If all goes well, the page will scroll back to where the heading is again visible.
The html code for the link takes the id attribute of the sub-heading as its landmark, preceding it with a "#" character because that is how html recognizes landmarks like these. The rest of the anchor tag gives the text to be displayed for the link. It makes sense to repeat the sub-heading here. The complete html code for the link becomes:
<a href="#the-contents-of-an-h2-tag">The Contents of an <h2> Tag</a>
I reasoned: how convenient! The <h2> and the <a> tags can incorporate the same, two strings of words and special characters. Why write them twice?
Emacs prides itself on being a programmable text editor. Surely it can be programmed to extract the strings from the <h2> tag and use them to automate writing the <a> tag?
But hold on.
Emacs Lisp Struggles with the <h2> Tag
My friend Roger Wagner likes to say, With computers, the answer is always yes but not always easy.
As my Dad would add, it goes best when you use the right tool.
(And I must add here, you have to learn to use the tool! Which I did, after writing this article, and now I have it working in Emacs Lisp.)
I spent the past two days prior to writing this entry unsuccessfully trying to write Lisp code to formulate those <a> tags. Lisp language appears to make several different approaches possible, using so-called regular expressions to extract chunks of text at one step and then to concatenate them into other, different text during subsequent steps.
Many hours reading many pages of the Emacs Lisp Programming Manual later, and after experimenting with Lisp statements such as (re-search-forward) and (match-string), I concluded that Emacs Lisp struggles with regular expressions targeting the text between the '>' and '<' characters in an html tag.
Sometimes, the Emacs Lisp search statements either do not find or skip over the character. Sometimes when editing an html file, Lisp mistakes one of the characters for an "unbalanced parenthesis" and, for that reason, refuses to evaluate the expression.
(This remains true but is not a problem because it happened only when writing search functions in an HTML buffer, as explained in the next article.)
A Better Tool Comes to the Rescue!
I had already written a nice, simple solution using a standard, Linux program named sed. A single line of code combines both copying selected text from the <h2> tags and pasting it into the <a> tags. It is, in fact, a regular expression:
sed -n 's/^.*<h[1-6].*id="\(.*\)".*>\(.*\)<\/h2>.*$/<li><a href="#\1">\2<\/a><\/li>/p'
The code line is fed into sed along with a text file, such as the html file for this page. Almost immediately, sed outputs a list of <a> tags corresponding to the <h2> tags it encounters in the file.
A few keystrokes suffice to copy that list and paste it into the html file. Done!
Emacs Lisp provides no ready-made list of instructions to evaluate that regular expression. In all of its voluminous documentation, I cannot find any such single-line solution. Instead, Lisp apportions the different steps to different instructions. And then, sadly, those instructions do not always work as consistently as the documentation supposes they do.
As surely as a dish-rag can drive a nail if you pound it long enough, I have no doubt Lisp could make those <a> tags if only I could ever figure out how to amalgamate enough of its special search-related instructions.
Meanwhile, Time marches on and sed does the job in a heartbeat.
Choose the Right Tool
Given choice, the better tool is the right tool to use.
Emacs serves very well for writing and editing the text and html codes for a web page. sed is not a text editor in that way; however, (my conclusion when I wrote this art5icle was that) sed beats Emacs for sifting out the key text fragments of <h2> tags and generating navigational <a> tags for them.
Musical ensembles sound better together than any instrument does playing by itself, and web page authors do well to harmonize their tools. Use each one for the part it does best.
A quick web search will unearth enthusiastic endorsements of Emacs for Everything
. To be sure, Emacs is a mighty hammer; however, not every line of code is a nail.