Thomas Letan's Blog - emacs

What happened since December 2022?

May 18, 2023

What happened since December 2022?

Initially, I started this “What happened” series as an exercise to publish more regularly on this website. Suffice to say, I haven’t done a particularly impressive job in that regard, which only means I have a lot of room for improvement.

Anyway, if the first few months of 2023 has been mostly $WORK focus, the same cannot be said for April and May. For one, I have started running again. But this is only the tip of the iceberg.

Spatial Shell got its first releases

Spatial Shell is probably my hobby project I am most excited about. The “call for testers” article I have published recently managed to catch the attention of a few folksYou want to hear a lesson I learned the hard way just after publishing it? Before calling for testers, it is better to be sure your project can actually be compiled easily by the potential volunteers . . The perspective to publish such a write-up was a very strong source of motivation for me to clean up a project I was using daily for several months now, and I am very satisfied with the result.

Mass adoption is still a distant horizon, but still, the project is now mainstream enough that it has already been mentioned in a random topic on the OCaml discourse by someone who isn’t me . 🎉

This led me to formally release a first version of Spatial Shell in the end of April, and a second today. For the first time, I have also published an Archlinux package , to make the life of potential early adopters even easier. Do not hesitate to upvote it so that it can find its way to the extra repository some day.

Goodbye Emacs! Remember me, Neovim?

In 2015, I started using Coq for my PhD thesis and at the time, there was no real support for (Neo)vimThe situation later improved. Nowadays, you can implement your theories using Coqtail , and Coq LSP will probably become a viable and interesting setup in a near future. . Everyone was using Proof General and Emacs, so I was left with little choice but to follow through. With only my courage and the good advice of a fellow “vimer” who had also made a similar journey , I started using Emacs.

Fast forward 8 years later, and my Emacs configuration has become a project of its own. Overall, I was pretty happy with my setup, but in the same time, I always remained a bit nostalgic of my Neovim days. This is probably why I decided to give this old friend a try when my company bought me a new laptop. I also used this as an opportunity to try out this LSP-thing everyone was talking about.

It has been a month now, and I do not plan to come back to my previous habits. There are still some few edges here and there, I still need to get my head around lua, but LSP is nice, and plugins like telescope are simply too beautiful.

That being said, there was one aspect of moving from Emacs to Neovim I had not anticipated: Org mode. Which constitutes a perfect transition to the next session.

Website redesign, again

Did you notice this website has been revamping recently? The changes are actually deeper than “just” a redesign, to a point where I had to port all my write-ups to a different markup languageAre you starting to understand why “Org mode” was the perfect transition to move on to this section? .

Why, you ask? Well, it’s actually pretty simple: as time goes, I’ve grown lazier.

Let me give you some context. Until very recently, my website was built around the idea to have literate programming as a first-class citizen of my author tools. For instance, you can have a look at what used to be the literate program which was responsible for generating the website. Similarly, most of my write-ups about Coq were actually Coq documents. Literate programming is actually a very nice paradigm for authoring technical contents, because it gives you the tools to keep said contents accurate and up-to-date. In a nutshell, you cannot have a typo in one of your code snippets which would prevent it from compiling, because you actually compile the snippet and catch the typo when you try to generate your website. Or at least, it is what I used to do.

I decided to stop because, for all its benefits, this approach has one major drawback: it is hard to maintain. I had invested quite some time and efforts to keep my website sources under control, but it really was an everyday fight. There are some strange things which start happening when you fully commit to this, as I think I did. For instance, software dependencies tie your article together. Suddenly, you cannot talk about this new fancy feature of the latest Coq release without upgrading all your write-ups implemented as Coq documentsWell, in theory you can. Just have each Coq document specifies the Coq version it requires, and support this level of customization in your build toolchain. But then, your blog takes forever to build from a cold repository. .

That being said, most of the work had already been done. This website was a collection of literate programs, and I was pretty proud of the state of things. I could deal with the annoyancesLike using Coqdoc syntax to write my articles, for instance. I could write about how the Coqdoc syntax irks me for ages. . But then, as I explained in the previous section, I decided to move away from Emacs. The first time I tried to start a new write-up, it hit me.

I used to write most of my contents using Org mode. Org mode, also known as the Emacs markup language.

I know of at least one “Org plugin” for Neovim , but instead of giving it a try, I decided to use this opportunity to tackle my “maintenance problem” once and for all. I gave up on literate programming for this website. As a result, this website is now generated from Markdown files only (using markdown-it with many plugins). As a consequence, the generated HTML is way more “predictable.” This was enough to motivate me at giving a try at Soupault’s indexes , which are way more powerful than I anticipated. Now, this website has

Tags. Each write-up can be labeled with as many tags as I want, there is a page which lists all the tags used in the website, and each tag has its own page (for instance, the coq tag.
A RSS feed. It was actually one of the main features I really wanted to get with this revamp.
Automatically generated list of articles in the home page, for each series (see the Ltac series for instance). Before, I was publishing “curated indexes,” or put in other words: I was writing these indexes myself, by hand. And again, I’ve grown lazier.

It took me a week to go through this rework. Translating manually every write-up was tedious, to say the least, as was implementing the Lua plugins for Soupault since I have neither proficiency nor tooling to help me write Lua code. But I am very glad for the final result.

Also, I have invested in an Antidote license, so hopefully, this website will have fewer typos and English butchering as of now. A clean text, delivered with a nice and simple design, from a sane and maintainable Git repository .

What happened in August 2022?

August 15, 2022

What happened in August 2022?

emacs meta

Without further ado, let’s take a look at what was achieved for the last thirty days or so.

Emacs

I have started tweaking and improving my Emacs configuration againAfter having used Emacs for seven years now, I am nowhere close to consider my configuration as a done project. I really envy developers who are using their editor with little to no customization. .

Theme Selection Menu

The change I am the most excited about is that I have finally reduced the boilerplate in need to write to use a new theme. I am very indecisive when it comes to theming. I like to have my choices, and I get tired of any color scheme pretty quickly. As a consequence, I introduced a customizable variable to let me select a theme dynamically, and have this choice persist across Emacs session.

I have a Hydra menu that allows me to select which theme I want to use for the time being. It looks like this.

A Hydra menu for selecting a theme.

But adding new entries to this menu was very cumbersome, and mostly boilerplate that I know a good macro could abstract away. And I can finally report that I was right all along. I have my macros now, and they allow me to have the Hydra menu above generated with these simple lines of code.

(use-theme ancientless "a" :straight nil :load-path "~/.emacs.d/lisp")
(use-theme darkless "d" :straight nil :load-path "~/.emacs.d/lisp")
(use-theme brightless "b" :straight nil :load-path "~/.emacs.d/lisp")
(use-theme monotropic "m")
(use-theme monokai "M")
(use-theme nothing "n")
(use-theme eink "e")
(use-theme dracula "D")
(use-theme chocolate "c")
(use-themes-from tao-theme
                 '(("tl" . tao-yang)
                   ("td" . tao-yin)))

Eldoc and Flycheck Popups

I have been experimenting with several combinations of packages to have Eldoc and Flycheck using pop-up-like mechanisms to report things to me, instead of the echo area.

The winning setup for now is the one that uses the quick-peek package . That is, flycheck-inline (customized to use quick-peek, as suggested in their README), and eldoc-overlay . This works well enough, so the pop-ups of eldoc are maybe a bit too distracting.

#flycheck-inline in action with an OCaml compilation error.

In my quest for pop-ups, I ran into several issues with the packages I tried out. For instance, eldoc-box was very nice, but also very slow for some reason. It turns out there was an issue about that slowness, wherein the culprit was identified. This allowed me to submit a pull request that got merged rather quickly .

Similarly, after a packages update, I discovered flycheck-ocaml was no longer working, and submit a patch to fix the issue .

This Website

I have not been investing a lot of time in this website for the past six years or so. This month, things change a bit on that side too.

New Contents

First, I have published a (short) article on higher-order polymorphism in OCaml. The goal was for me to log somewhere the solution for an odd problem I was confronted to at $WORK, but the resulting article was not doing a great job as conveying this. In particular, two comments on Reddit motivated me to rework it, and I am glad I did. I hope you enjoy the retake.

Once this was out of the way, I decided that generating this website was taking way too much time for no good enough reason. The culprit was cleopatra, a toolchain I had developed in 2020 to integrate the build process of this website as additional contents that I thought might interest people. The sad things were: cleopatra was adding a significant overhead, and I never take the time to actually document them properly.

Under the Hood

Overall, the cost of using cleopatra was not worth the burden, and so I got rid of it. Fortunately, it was not very difficult, since the job of cleopatra was to extracting the generation processes from org files; I just add to implement a small makefile to make use of these files, without having to rely on cleopatra anymore.

This was something I was pondering to do for a long time, and as often in these circumstances, this gave me the extra motivation I needed to tackle other ideas I had in mind for this website. This is why now, rather than starting one Emacs process per Org file I have to process, my build toolchain starts one Emacs server, and later uses emacsclient.

Now, most of the build time is spent by soupault . I guess I will have to spend some time on the Lua plugins I have developed for it at some point.

A New Mailing List

Finally, I have created a public mailing list that is available if you want to start a discussion on one of my articles. Don’t hesitate to use it, or to register to it!

A Literate Toolchain To Build This Website

February 4, 2020

A Literate Toolchain To Build This Website

meta literate-programming emacs

Important

What you are reading is actually the rendered version of a Markdown document that was manually “translated” from the Org original document, named Bootstrap.org. Bootstrap.org was probably complete gibberish for anyone who isn’t me. This version was actually heavily reworked to try to fix that.

In any case, the tool-suite described here has not been used to generate this website for a while now.

A literate program is a particular type of software program where code is not directly written in source files, but rather in a text document as code snippets. In essence, literate programming allows for writing in the same place both the software program and its technical documentation.

cleopatra is a “literate toolchain” I have implemented to build this website, and you are currently reading itThis sentence was true when this article was published, but things have changed since then. . That is, cleopatra is both the build system and an article of this website! To achieve this, cleopatra has been written as a collection of org files which can be either “tangled” using Babel or “exported” as a HTML document. Tangling here refers to extract marked code blocks into files.

The page you are currently reading is cleopatra entry point. Its primary purpose is to define two Makefiles —makefile and bootstrap.mk— and the necessary emacs-lisp script to tangle this document.

On the one hand, makefile is the main entrypoint of cleopatra. It serves two purposes:

It initiates a few global variables, and
It provides a rule to tangle this document, that is to update itself and bootstrap.mk.

On the other hand, bootstrap.mk is used to declare the various “generation processes” used to generate this website.

makefile and the emacs-lisp scripts are versioned, because they are necessary to bootstrap cleopatra; but since they are also defined in this document, it means cleopatra can update itself, in some sense. This is to be kept in mind when modifying this document to hastily.

Global Constants and Variables

First, makefile defines several global “constants”As far as I know, make does not support true constant values, It is assumed generation processes will not modify them. . In a nutshell,

$ROOT tells Emacs where the root of your website sources is, so that tangled output filenames can be given relative to it rather than the org files. So for instance, the block_src tangle parameter for Makefile looks like :tangle Makefile, instead of :tangle ../../Makefile.
$CLEODIR tells cleopatra where its sources live. If you place it inside the site/ directory (as it is intended), and you enable the use of org files to author your contents, then cleopatra documents will be part of your website. If you don’t want that, just move the directory outside the site/ directory, and update the $CLEODIR variable accordingly.

For this website, these constants are defined as followsI will use a comment in the first line to recall to which file a given block code is expected to be tangled. .

# makefile:
ROOT := $(shell pwd)
CLEODIR := site/cleopatra

We then introduce two variables to list the output of the generation processes, with two purposes in mind: keeping the .gitignore up-to-date automatically, and providing rules to remove them.

$ARTIFACTS lists the short-term artifacts which can be removed frequently without too much hassle. They will be removed by make clean.
$CONFIGURE lists the long-term artifacts whose generation can be time consuming. They will only be removed by~make cleanall.

# makefile:
ARTIFACTS := build.log
CONFIGURE :=

clean :
	@rm -rf ${ARTIFACTS}

cleanall : clean
	@rm -rf ${CONFIGURE}

Generation processes can declare new build outputs using the += assignement operators. Using another operator will likely provoke an undesirable result.

Tangling Org Documents

cleopatra is a literate program implemented with Org mode, an Emacs major editing mode. We provide the necessary bits to easily tangle Org documents.

The configuration of Babel is done using an emacs lisp script called tangle-org.el whose status is similar to Makefile. It is part of the bootstrap process, and therefore lives “outside” of cleopatra (it is not deleted with make clean for instance). However, it is overwritten when this file is tangled. If you try to modify it and find that cleopatra does not work properly, you should restore it.

;;; tangle-org.el:
(require 'org)
(cd (getenv "ROOT"))
(setq org-confirm-babel-evaluate nil)
(setq org-src-preserve-indentation t)
(add-to-list 'org-babel-default-header-args
             '(:mkdirp . "yes"))
(org-babel-do-load-languages
 'org-babel-load-languages
 '((shell . t)))
(org-babel-tangle)

We define variables that ensure that the $ROOT environment variable is set and tangle-org.el is loaded when using Emacs.

# makefile:
EMACSBIN := emacs
EMACS := ROOT="${ROOT}" ${EMACSBIN}
TANGLE := --batch \
          --load="${ROOT}/scripts/tangle-org.el" \
          2>> build.log

Finally, we introduce a canned recipe to seamlessly tangle a given fileIt was the first time I had used canned recipes, and I don’t think I had the opportunity to re-use it ever again. .

# makefile:
define emacs-tangle =
echo "  tangle  $<"
${EMACS} $< ${TANGLE}
endef

Updating `.gitignore` Automatically

Assuming each generation process correctly defines its $ARTIFACTS and $CONFIGURE variables, we have all the information we need to update .gitignore automatically.

This is done by adding markers in .gitignore to define a region under the control of cleopatra, and writing a script to update said region after each build.

# update-gitignore.sh:
BEGIN_MARKER="# begin generated files"
END_MARKER="# begin generated files"

# remove the previous list of generated files to ignore
sed -i -e "/${BEGIN_MARKER}/,/${END_MARKER}/d" .gitignore
# remove trailing empty lines
sed -i -e :a -e '/^\n*$/{$d;N;};/\n$/ba' .gitignore

# output the list of files to ignore
echo "" >> .gitignore
echo ${BEGIN_MARKER} >> .gitignore
for f in $@; do
    echo "${f}" >> .gitignore
done
echo ${END_MARKER} >> .gitignore

The ignore rule of makefile is defined as follows.

# makefile:
ignore :
	@echo "  update  gitignore"
	@scripts/update-gitignore.sh \
	   ${ARTIFACTS} \
	   ${CONFIGURE}

Bootstrapping

The core purpose of makefile remains to bootstrap the chain of generation processes. This chain is divided into three stages: prebuild, build, and postbuild.

This translates as follows in makefile.

# makefile:
default : postbuild ignore

init :
	@rm -f build.log

prebuild : init

build : prebuild

postbuild : build

.PHONY : init prebuild build postbuild ignore

A generation process in cleopatra is a Makefile which provides rules for these three stages, along with the utilities used by these rules. More precisely, a generation process proc is defined in proc.mk. The rules of proc.mk for each stage are expected to be prefixed by proc-, e.g., proc-prebuild for the prebuild stage.

Eventually, the following dependencies are expected between within the chain of generation processes for every generation process.

prebuild : proc-prebuild
build : proc-build
postbuild : proc-postbuild

proc-build : proc-prebuild
proc-postbuild : proc build

cleopatra is a literate toolchain whose main purpose is to allow me to turn the scripts I wrote to generate my website into blogposts of said website. As such, it allows me to implement the generation processes using Org mode, which means that before being able to start generating HTML files, cleopatra has to tangle the generation processes.

To achieve this, cleopatra relies on a particular behavior of make regarding the include directive. If there exists a rule to generate a Makefile used as an operand of include, make will use this rule to update (if necessary) said Makefile before actually including it.

Therefore, the rules of the following form achieve our ambition of extensibility.

include ${PROC}.mk

prebuild : ${PROC}-prebuild
build : ${PROC}-build
postbuild : ${PROC}-postbuild

${PROC}-prebuild : ${PROC}.mk ${AUX}
${PROC}-build : ${PROC}-prebuild
${PROC}-postbuild : ${PROC}-build

${PROC}.mk ${AUX} &:\
   ${CLEODIR}/${IN}
	@$(emacs-tangle)

CONFIGURE += ${PROC}.mk ${AUX}

.PHONY : ${PROC}-prebuild \
         ${PROC}-build \
         ${PROC}-postbuild

where

$IN is the Org document which contains the generation process code
$PROC is the name of the generation process
$AUX lists the utilities of the generation process tangled from $IN with $PROC.mk

We use &: is used in place of : to separate the target from its dependencies in the “tangle rule.”Yet another obscure Makefile trick I have never encountered again. This tells make that the recipe of this rule generates all these files.

Rather than writing these rules manually for each generation process we want to define, we rely on to noweb of Babel . We call extends the primitive to generate new generation processes.

We derive the rule to tangle bootstrap.mk using extends, using the following Org mode syntax.

#+BEGIN_SRC makefile :noweb yes
# makefile:
<<extends(IN="Bootstrap.org", PROC="bootstrap", AUX="scripts/update-gitignore.sh")>>
#+END_SRC

which gives the following result.

include bootstrap.mk

prebuild : bootstrap-prebuild
build : bootstrap-build
postbuild : bootstrap-postbuild

bootstrap-prebuild : bootstrap.mk scripts/update-gitignore.sh
bootstrap-build : bootstrap-prebuild
bootstrap-postbuild : bootstrap-build

bootstrap.mk scripts/update-gitignore.sh &:\
   ${CLEODIR}/Bootstrap.org
	@$(emacs-tangle)

CONFIGURE += bootstrap.mk scripts/update-gitignore.sh

.PHONY : bootstrap-prebuild \
         bootstrap-build \
         bootstrap-postbuild

These are the last lines of makefile. The rest of the generation processes will be declared in bootstrap.mk.

Generation Processes

In this section, we construct bootstrap.mk by enumerating the generation processes that are currently used to generate the website you are reading.

We recall that each generation process shall

Define proc-prebuild, proc-build, and proc-postbuild
Declare dependencies between stages of generation processes
Declare build outputs (see ARTIFACTS and CONFIGURE)

Theming and Templating

The theme generation process controls the general appearance of the website. More precisely, it introduces the main template used by soupault (main/templates.html), and the main SASS sheet used by this template.

If a generation process produces a set of styles within a specific SASS files, the current approach is

To make this file a dependency of theme-build
To modify style/main.sass in theme to import this file

Eventually, the second step will be automated, but, in the meantime, this customization is mandatory.

Configuring Soupault

The soupault generation configures and run soupault, in order to generate a static website.

If a generation process proc produces files that will eventually be integrated to your website, its proc-build recipe needs to be executed before the soupault-build recipe. This can be enforced by making the dependency explicit to make, i.e.,

soupault-build : proc-build

Eventually, generation processes shall be allowed to produce specific soupault widgets to be integrated into soupault.conf.

Authoring Contents

The fact that cleopatra is a literate program which gradually generates itself was not intended: it is a consequence of my desire to be able to easily use whatever format I so desire for writing my contents, and Org documents in particular.

In the present website, contents can be written in the following format:

HTML Files: This requires no particular set-up, since HTML is the lingua franca of soupault.
Regular Coq files: Coq is a system which allows writing machine-checked proofs, and it comes with a source “prettifier” called coqdoc. Learn more about the generation process for Coq files .
Org documents: Emacs comes with a powerful editing mode called Org mode , and Org documents are really pleasant to work with. Learn more about the generation process for Org documents

Thomas Letan's Blog - emacs

What happened since December 2022?

What happened since December 2022?

Spatial Shell got its first releases

Goodbye Emacs! Remember me, Neovim?

Website redesign, again

What happened in August 2022?

What happened in August 2022?

Emacs

Theme Selection Menu

Eldoc and Flycheck Popups

This Website

New Contents

Under the Hood

A New Mailing List

A Literate Toolchain To Build This Website

A Literate Toolchain To Build This Website

Global Constants and Variables

Tangling Org Documents

Updating .gitignore Automatically

Bootstrapping

Generation Processes

Theming and Templating

Configuring Soupault

Authoring Contents

Updating `.gitignore` Automatically