Protesilaos Stavrou

My packages and/or custom code for GNU Emacs

Emacs Lisp Elements

A book that provides big picture view of the Emacs Lisp programming language by combining prose with code. The goal is to give readers an idea of how Elisp works by showing some of the main concepts or patterns discernible in everyday code.

Some chapters are beginner-friendly, while others dive into deeper waters. Though I think everything is still approachable, as I try to explain basic concepts and take things one step at a time.

The book is not meant to be a replacement for the built-in Emacs Lisp Reference Manual. It simply gives you enough information to reason about Elisp. Once you start extending Emacs, the rest will follow naturally.

I hope you enjoy it and continue to have fun with Emacs.

Denote

Denote is a simple note-taking tool for Emacs. It is based on the idea that notes should follow a predictable and descriptive file-naming scheme. The file name must offer a clear indication of what the note is about, without reference to any other metadata. Denote basically streamlines the creation of such files while providing facilities to link between them.

Denote’s file-naming scheme is not limited to “notes”. It can be used for all types of file, including those that are not editable in Emacs, such as videos. Naming files in a consistent way makes their filtering and retrieval considerably easier. Denote provides relevant facilities to rename files, regardless of file type.

[ Further down on this list I include more of my Denote-related packages. ]

Modus themes

Highly accessible themes, conforming with the highest standard for colour contrast between background and foreground values (WCAG AAA). They also are optimised for users with red-green or blue-yellow colour deficiency.

The themes are very customisable and provide support for a wide range of packages. Their manual is detailed so that new users can get started, while it also provides custom code for all sorts of more advanced customisations.

Since August 2020, the original Modus themes (modus-operandi, modus-vivendi) are built into Emacs version 28 or higher. Emacs 28 ships with modus-themes version 1.6.0. Emacs 29 includes version 3.0.0. Emacs 30 provides version 4.4.0. Version 4 is a major refactoring of how the themes are implemented and customized. Such major versions are not backward-compatible due to the limited resources at my disposal to support multiple versions of Emacs and of the themes across the years.

Ef (εὖ) themes

The ef-themes are a collection of light and dark themes for GNU Emacs that provide colourful (“pretty”) yet legible options for users who want something with a bit more flair than the modus-themes (also designed by me).

Doric themes

These are my minimalist themes. They use few colours and will appear mostly monochromatic in many contexts. Styles involve the careful use of typography, such as italics and bold italics.

If you want maximalist themes in terms of colour, check my ef-themes package. For something in-between, which I would consider the best “default theme” for a text editor, opt for my modus-themes.

Fontaine

Fontaine allows the user to define detailed font configurations and set them on demand. For example, one can have a regular-editing preset and another for presentation-mode (these are arbitrary, user-defined symbols): the former uses small fonts which are optimised for writing, while the latter applies typefaces that are pleasant to read at comfortable point sizes.

spacious-padding

This package provides a global minor mode to increase the spacing/padding of Emacs windows and frames. The idea is to make editing and reading feel more comfortable. Enable the mode with M-x spacious-padding-mode. Adjust the exact spacing values by modifying the user option spacious-padding-widths.

Inspiration for this package comes from Nicolas Rougier’s impressive designs and Daniel Mendler’s org-modern package.

Beframe

beframe enables a frame-oriented Emacs workflow where each frame has access only to the list of buffers visited therein. In the interest of brevity, we call buffers that belong to frames “beframed”.

Substitute

Efficiently replace targets in the buffer or context.

Substitute is a set of commands that perform text replacement (i) throughout the buffer, (ii) limited to the current definition (per narrow-to-defun), (iii) from point to the end of the buffer, and (iv) from point to the beginning of the buffer.

These substitutions are meant to be as quick as possible and, as such, differ from the standard query-replace (which I still use when necessary). The provided commands prompt for substitute text and perform the substitution outright, without moving the point.

TMR

TMR is an Emacs package that provides facilities for setting timers using a convenient notation. Lots of commands are available to operate on timers, while there also exists a tabulated view to display all timers in a nice grid.

aLtCaPs

The altcaps package is a small, focused-in-scope tool that helps users communicate mockery or sarcasm effectively. It does this by alternating the letter casing of characters in the words it affects.

show-font

This package lets you preview a font inside of Emacs. It does so in three ways:

  • Prompt for a font on the system and display it in a buffer.
  • List all known fonts in a buffer, with a short preview for each.
  • Provide a major mode to preview a font whose file is among the installed ones.

Check out its sources:

Logos

This package provides a simple approach to setting up a “focus mode”. It uses the page-delimiter (typically ^L) or the outline together with some commands to move between pages whether narrowing is in effect or not. It also provides some optional aesthetic tweaks which come into effect when the buffer-local logos-focus-mode is enabled. The manual shows how to extend the code to achieve the desired result.

(all my videos since early 2022 use logos).

Pulsar

This is a small package that temporarily highlights the current line or region after a given function is invoked. Several user options control the exact behaviour. Watch the original demo.

Lin

Lin is a stylistic enhancement for Emacs’ built-in hl-line-mode. It remaps the hl-line face (or equivalent) buffer-locally to a style that is optimal for major modes where line selection is the primary mode of interaction.

The idea is that hl-line-mode cannot work equally well for contexts with competing priorities: (i) line selection, or (ii) simple line highlight. In the former case, the current line needs to be made prominent because it carries a specific meaning of some significance in the given context: the user has to select a line. Whereas in the latter case, the primary mode of interaction does not revolve around the line highlight itself: it may be because the focus is on editing text or reading through the buffer’s contents, so the current line highlight is more of a reminder of the point’s location on the vertical axis.

Cursory

Cursory provides a thin wrapper around built-in variables that affect the style of the Emacs cursor on graphical terminals. The intent is to allow the user to define preset configurations such as “block with slow blinking” or “bar with fast blinking” and set them on demand. The use-case for such presets is to adapt to evolving interface requirements and concomitant levels of expected comfort, such as in the difference between writing and reading.

Notmuch Indicator

This is a simple package that renders an indicator with an email count of the notmuch index on the Emacs mode line. The underlying mechanism is that of notmuch-count(1), which is used to find the number of items that match the given search terms. In practice, the user can define one or more searches and display their counters. These form a listing which realistically is like: @50 😱1000 💕0 for unread messages, bills, and love letters, respectively.

Dired Preview

This is a simple and robust package to automatically preview in a side window the file at point in Dired buffers. Preview windows are closed when they are no longer relevant, while preview buffers are killed if they have not been used for other purposes beside previewing. The package provides several customisation options to control its behaviour.

Standard themes

The standard-themes are a collection of light and dark themes for GNU Emacs. The standard-light and standard-dark emulate the out-of-the-box looks of Emacs (which technically do NOT constitute a theme) while bringing to them thematic consistency, customizability, and extensibility. Other themes are stylistic variations of those.

In practice, the Standard themes take the default style of the font-lock and Org faces, complement it with a wider and harmonious colour palette, address many inconsistencies, and apply established semantic patterns across all interfaces by supporting a large number of packages.

Minibuffer Confines Transcended (mct.el)

Enhancements for the default minibuffer completion UI of Emacs. In essence, MCT is (i) a very thin layer of interactivity on top of the out-of-the-box completion experience, and (ii) glue code that combines built-in functionalities to make the default completion framework work like that of more featureful third-party options.

Consult-Denote

Glue code to integrate my denote package with Daniel Mendler’s consult. The idea is to enhance minibuffer interactions, such as by providing a preview of the file-to-linked/opened and by adding more sources to the consult-buffer command.

Denote Org (extras for integrating Denote with Org)

The denote-org package contains extra features that better integrate Denote with Org mode. These used to be available as part of the main denote package in a file called denote-org-extras.el, but now live in this standalone package to main things easier to maintain and understand.

With denote-org, users have Org-specific extensions such as dynamic blocks, links to headings, and splitting an Org subtree into its own standalone file. This package’s official manual covers the technicalities.

Denote Sequence (Sequence notes or Folgezettel with Denote)

The denote-sequence package provides an optional extension to ~denote~ for naming files with a sequencing scheme. The idea is to establish hiearchical relationships between files, such that the contents of one logically follow or complement those of another.

Denote Silo

The denote-silo package makes it easier to work with multiple “silos”, as explained in the Denote manual. In short, a “silo” is a localised denote-directory that is not connected to the default/global denote-directory and other silos.

The code of denote-silo used to be bundled up with the denote package before version 4.0.0 of the latter and was available in the file denote-silo-extras.el. Users of the old code will need to adapt their setup to use the denote-silo package. This can be done by replacing all instances of denote-silo-extras with denote-silo across their configuration.

Denote Journal (extras for dailies)

The denote-journal package makes it easier to use Denote for journaling. While it is possible to use the generic denote command (and related) to maintain a journal, this package defines extra functionality to streamline the journaling workflow.

The code of denote-journal used to be bundled up with the denote package before version 4.0.0 of the latter and was available in the file denote-journal-extras.el. Users of the old code will need to adapt their setup to use the denote-journal package. This can be done by replacing all instances of denote-journal-extras with denote-journal across their configuration.

Denote Markdown

The denote-markdown package provides some convenience functions to better integrate Markdown with Deonte. This is mostly about converting links from one type to another so that they can work in different applications (because Markdown does not have a standardised way to define custom link types).

The code of denote-markdown used to be bundled up with the denote package before version 4.0.0 of the latter and was available in the file denote-md-extras.el. Users of the old code will need to adapt their setup to use the denote-markdown package. This can be done by replacing all instances of denote-md-extras with denote-markdown across their configuration.

sxhkdrc-mode

This is a major mode for editing sxhkdrc files. SXHKD is the Simple X Hot Key Daemon which is commonly used in minimalist desktop sessions on Xorg (I use it with bspwm, herbstluftwm, and i3wm). The sxhkdrc file configures key chords, binding them to commands. For the technicalities, read the man page sxhkd(1).

The official Emacs TUTORIAL in Greek

I am the author and maintainer of the TUTORIAL.el_GR file that is part of Emacs 29 since 2022-05-08. You can find it in the Emacs source code inside the etc/tutorials/ directory. If you report a bug about it with M-x report-emacs-bug, consider adding me in carbon copy (Cc). The etc/tutorials/TUTORIAL.translators file mentions the email address you should use.

Dotemacs

My personal Emacs configuration. It is comprehensive, both in terms of the [custom] code it contains as well as the documentation on what each piece of functionality does.

Theme buffet

The theme-buffet package arranges to automatically change themes during specific times of the day or at fixed intervals. The collection of themes is customisable, with the default options covering the built-in Emacs themes as well as my modus-themes and ef-themes.

Bruno Boal is the lead developer and I am a co-maintainer.

Aporetic

This is not an “Emacs package” per se though I use it full time in my Emacs setup (it complements my work on Emacs themes and fontaine, for example).

Customised build of the Iosevka typeface, with a consistent rounded style and overrides for almost all individual glyphs in both upright (roman) and slanted (italic) variants. This is the successor to my now-discontinued “Iosevka Comfy” fonts.

Iosevka Comfy

[ As of 2025-02-04, the Iosevka Comfy project is discontinued: https://protesilaos.com/codelog/2025-02-04-aporetic-fonts-1-0-0/. The main reason is that “Iosevka” is a reserved name. See my Aporetic fonts instead. ]

This is not an “Emacs package” per se though I use it full time in my Emacs setup (it complements my work on Emacs themes and fontaine, for example).

Iosevka Comfy is a customised build of the Iosevka typeface, with a consistent rounded style and overrides for almost all individual glyphs in both roman (upright) and italic (slanted) variants. Many font families are available, covering a broad range of typographic weights. The README file in the git repository covers all the technicalities.

Mandoura

⚠️ WORK-IN-PROGRESS

Use MPV to play media files via Dired.

The name of this package is a reference to a Greek musical instrument from the island of Crete. Though according to the Oracle of Delphi, it is a cryptic message for future generations: “MPV Access Needs Dired to Output User’s Requested Audio”.

Research (research.el)

⚠️ WORK-IN-PROGRESS

Run shell searches and store them reproducibly in buffers.

The goal of research.el (“re-search” is a shorthand for “repeatable search”) is to provide a thin wrapper for shell invocations that search for file names or file contents. The output is stored in an Emacs buffer which retains the parameters that generated it. This buffer can then repeat the command that created it by means of revert-buffer (bound to g by default). File paths are automatically buttonised so that they can be used as links to the file they reference.

RESEARCH provides the means to write the Emacs Lisp that wraps around the desired shell invocation. We call the resulting commands and the buffers they generate “re-searchable”.

Agitate (experimental)

Agitate is a collection of commands or potentially useful functions that expand on the available version control features of Emacs. Those are meant to complement a workflow that relies on the built-in Version Control framework and its accoutrements (diff-mode.el, log-view.el, log-edit.el, vc-git.el, and potentially others).

Custom Emacs build for Arch Linux (PKGBUILD)

This is just like every other package recipe for Arch. We provide a PKGBUILD and then pacman does the rest. The project’s README file describes the procedure. ⛔ For experts only!

For more on my Emacs-related contributions, check my coding blog which includes lots of videos and written publications on the topic.