Nicolas Martyanoff – Brain dump

Controlling link opening in Emacs

nicolas@n16f.net (Nicolas Martyanoff) — Sun, 11 Aug 2024 18:00:00 +0000

Multiple Emacs modes recognize URIs so that you can follow them in a web browser, usually with a mouse left click. In modes that do not support it, one can still call browse-url-at-point interactively with the cursor positioned on a URI.

I wanted to make link handling more convenient for some time; this is what I ended up with.

Key bindings

There is no global Emacs concept of following links, so modes deal with them differently. I wanted to use the same key binding everywhere; I went for C-o (“o” for “open”) since I never use open-line. I also wanted the ability to use Eww —the Emacs builtin web browser— when it is convenient. So I added a function to select the secondary browser when the prefix is set. This way C-o opens Firefox, and C-u C-o opens Eww.

(setq browse-url-secondary-browser-function 'eww-browse-url)

(defun g-browse-url-at-point (arg)
  (interactive "P")
  (let ((browse-url-browser-function
         (if arg
             browse-url-secondary-browser-function
           browse-url-browser-function)))
    (browse-url-at-point)))

(keymap-global-set "C-o" 'g-browse-url-at-point)

Ultimately the function calls browse-url-at-point which identifies the URI under the cursor (i.e. at the current point) and calls browse-url.

Selecting a web browser

The browse-url function is fully configurable; two mechanisms are used to select a web browser for each link:

the browse-url-handlers and browse-url-default-handlers association lists, used to match specific URIs using predicates or regular expression;
the browse-url-browser-function variable (by default browser-url-default-browser) referencing a function which looks for available web browsers on the current machine.

Since I use multiple Firefox profiles, I needed the ability to open URIs in the right profile depending of the context. For example links in a professional email read in Gnus should be open in my work context.

The following function returns a handler that can be used in browse-url-handlers or as value for browse-url-browser-function:

(defun g-browse-url-firefox-function (profile)
  (lambda (uri &rest args)
    (let ((process-environment (browse-url-process-environment))
          (process-name (concat "firefox " uri))
          (process-args `("--new-tab" ,uri
                          ,@(if profile (list "-P" profile)))))
      (apply #'start-process process-name nil "firefox" process-args))))

For example, (g-browse-url-firefox-function "test") returns a browse function that will open the link in a new tab of a Firefox window associated with the “test” profile.

To change the logic deciding how to handle links in a buffer with a specific major mode, all you have to do is to add a hook to set browse-url-browser-function in a way that only affects the current buffer. Since this variable is not buffer-local by default, you have to take care to use setq-local when changing it.

Links in Gnus messages

Gnus messages are displayed using the gnus-article-mode major mode.

We first write a function to identify the account associated with the current group (assuming you are using nnimap for your email accounts as I do):

(defun g-current-gnus-account ()
  (let ((group gnus-newsgroup-name))
    (when (string-match "^nnimap\\+\\([^:]+\\):" group)
      (match-string 1 group))))

Then we define the actual browse function:

(defun g-gnus-browse-url (url &rest args)
  (let ((profile
         (pcase (g-current-gnus-account)
           ("my-company"
            "my-company-profile")
           ("a-client"
            "the-client-profile")
           (_
            "default"))))
    (apply (g-browse-url-firefox-function profile) url args)))

And the hook function:

(defun g-gnus-set-browser-function ()
  (setq-local browse-url-browser-function 'g-gnus-browse-url))

Finally we update the hook:

(use-package gnus-art
  :hook
  ((gnus-article-mode-hook . g-gnus-set-browser-function)))

Links in emails are now open in the right Firefox profile!

Links in the Circe IRC client

Same idea for Circe, select the right Firefox profile based on the network and channel of the current channel buffer.

We define the function to be called during the initialization of each channel buffer:

(defun g-circe-set-browser-function ()
  (let* ((network (with-circe-server-buffer
                    circe-network))
         (channel circe-chat-target)
         (profile (cond
                   ((and (equal network "my-network")
                         (equal channel "#my-channel"))
                    "the-right-profile")
                   (t
                    "default"))))
    (setq-local browse-url-browser-function
                (g-browse-url-firefox-function profile))))

And add it as a hook:

(use-package circe
  :hook
  ((circe-channel-mode-hook . g-circe-set-browser-function))

Making IELM More Comfortable

nicolas@n16f.net (Nicolas Martyanoff) — Sat, 08 Apr 2023 18:00:00 +0000

IELM is the Emacs Lisp REPL. It lets you evaluate any Elisp expression, prints the output and keeps track of previous commands. While it is a serious step-up from the humble eval-expression, it can be uncomfortable on several aspects. Let us improve it.

Adding Eldoc hints

Eldoc is a generic module used to display realtime documentation hints while you type. For Emacs Lisp, it means displaying docstrings when your cursor is over a symbol or when you start writing a function call.

When calling a function, you often need a quick remainder about the arguments. Having Eldoc means you do not have to call C-h f and deal with the documentation buffer, and can just glance at the echo area.

To enable Eldoc in IELM, let us add it to the initialization hook:

(add-hook 'ielm-mode-hook 'eldoc-mode)

Using Paredit

Paredit is an essential minor mode that lets you manipulate Lisp code as expressions and not as simple text. If you are not using it and think that editing all these parentheses is annoying, you are missing out. Give it a try, you will not be disappointed.

To use Paredit in IELM, we add it to the initialization hook:

(add-hook 'ielm-mode-hook 'paredit-mode)

Infortunately there is a key conflict between Paredit and IELM. Paredit overrides return to execute paredit-RET, meaning that the original ielm-return is not called.

The simplest way to fix it is to alter the Paredit keymap:

(define-key paredit-mode-map (kbd "RET") nil)
(define-key paredit-mode-map (kbd "C-j") 'paredit-newline)

We remove the entry associated with return and use C-j to insert a newline character, useful to write a multiline expression.

Making the command history persistent

The most annoying part of IELM is that it does not have persistent history. I expect any interactive command system to store past entries since they can always be useful again. ZSH has persistence, so does the SLIME Common Lisp REPL. IELM does not, even though Comint (the mode IELM derives from) can handle it.

Let us add it. First we will write a function to configure Comint and load any entry stored in the history file if it exists:

(defun g-ielm-init-history ()
  (let ((path (expand-file-name "ielm/history" user-emacs-directory)))
    (make-directory (file-name-directory path) t)
    (setq-local comint-input-ring-file-name path))
  (setq-local comint-input-ring-size 10000)
  (setq-local comint-input-ignoredups t)
  (comint-read-input-ring))

We store the history in the ielm/history file in the user Emacs directory, mimicking the eshell/history file used by Eshell.

Nothing complicated: we increase the number of entries stored in the history file, and tell Comint to drop duplicate entries. We also are careful and use setq-local to make sure Comint settings are only modified for the current buffer and not globally, since other buffers using different Comint-based modes could have different requirements.

We want to call this function when IELM start:

(add-hook 'ielm-mode-hook 'g-ielm-init-history)

Reading the history is one thing. We need a way to add all expressions we evaluate to it. It would have been nice to have a hook called everytime an expression is entered, but we have to do without it. We are going to use Elisp advices to evaluate code each time a specific function is called. We want to write the history file when ielm-send-input returns:

(defun g-ielm-write-history (&rest _args)
  (with-file-modes #o600
    (comint-write-input-ring)))
  
(advice-add 'ielm-send-input :after 'g-ielm-write-history)

Advising functions are called with the same arguments as the advised function. We do not care about them, so we use the &rest keyword to match all arguments passed to g-ielm-write-history.

We are careful to use with-file-modes to make sure the file is always created as only readable by the user, since it may contain private information.

This was not easy, but persistent history is worth it!

Useful key bindings

Finally we will bind two key combinations.

First the very common C-l to clear the buffer. All modes deriving from Comint have C-c M-o, but it is awkward to type and C-l is very common in various applications.

(define-key inferior-emacs-lisp-mode-map (kbd "C-l")
            'comint-clear-buffer)

Then we want a way to search through old expressions. Comint has comint-history-isearch-backward-regexp which is incredibly primitive. We can get a far better experience with Helm. The helm-comint-input-ring function lets us browse among old expressions and select one through incremental search. We bind it to C-r:

(define-key inferior-emacs-lisp-mode-map (kbd "C-r")
            'helm-comint-input-ring)

IELM is so much more comfortable to use now!

Custom Font Lock configuration in Emacs

nicolas@n16f.net (Nicolas Martyanoff) — Fri, 24 Feb 2023 18:00:00 +0000

Font Lock is the builtin Emacs minor mode used to highlight textual elements in buffers. Major modes usually configure it to detect various syntaxic constructions and attach faces to them.

The reason I ended up deep into Font Lock is because I was not satisfied with the way it is configured for lisp-mode, the major mode used for both Common Lisp and Emacs Lisp code. This forced me to get acquainted with various aspects of Font Lock in order to change its configuration. If you want to change highlighting for your favourite major mode, you will find this article useful.

Common Lisp highlighting done wrong

The core issue of Common Lisp highlighting in Emacs is that a lot of it is arbitrary and inconsistent:

The mode highlights what it calls “definers” and “keywords”, but it does not really make sense in Common Lisp. Why would WITH-OUTPUT-TO-STRING be listed as a keyword, but not CLASS-OF?
SIGNAL uses font-lock-warning-face. Why would it be a warning? Even stranger, why would you use this warning face for CHECK-TYPE?
Keywords and uninterned symbols are all highlighted with font-lock-builtin-face. But they are not functions or variables. They are not even special in any way, and their syntax already indicates clearly their nature. Having so many yellow symbols everywhere is really distracting.
All symbols starting with & are highlighted using font-lock-type-face. But lambda list arguments are not types, and symbols starting with & are not always lambda list arguments.
All symbols preceded by ( whose name starts with DO- or WITH- are highlighted as keywords. There is even a comment by RMS stating that it is too general. He is right.

Beyond these issues, the mode sadly uses default Font Lock faces instead of defining semantically appropriate faces and mapping them to existing ones as default values.

The chances of successfully driving this kind of large and disruptive change directly into Emacs are incredibly low. Even if it was to be accepted, the result would not be available until the next release, which could mean months. Fortunately, Emacs is incredibly flexible and we can change all of this ourselves.

Note that you may not agree with the list of issues above, and this is fine. The point of this article is to show you how you can change the way Emacs highlights content in order to match your preferences. And you can do that for all major modes!

Font Lock configuration

Font Lock always felt a bit magic and it took me some time to find the motivation to read the documentation. As is turned out, it can be used for very complex highlighting schemes, but basic features are not that hard to use.

The main configuration of Font Lock is stored in the font-lock-defaults buffer-local variable. It is a simple list containing the following entries:

A list of symbols containing the value to use for font-lock-keywords at each level, the first symbol being the default value.
The value used for font-lock-keywords-only. If it is nil, it enables syntaxic highlighting (strings and comments) in addition of search-based (keywords) highlighting.
The value used for font-lock-keywords-case-fold-search. If true, highlighting is case insensitive.
The value used for font-lock-syntax-table, the association list controlling syntaxic highlighting. If it is nil, Font Lock uses the syntax table configured with set-syntax-table. In lisp-mode this would mean lisp-mode-syntax-table.
All remaining values are bindings using the form (VARIABLE-NAME . VALUE) used to set buffer-local values for other Font Lock variables.

The part we are interested about is search-based highlighting which uses regular expressions to find specific text fragments and attach faces to them.

Values used for font-lock-keywords are also lists. Each element is a construct used to specify one or more keywords to highlight. While these constructs can have multiple forms for more complex use cases, we will only use the two simplest ones:

(REGEXP . FACE) tells Font Lock to use FACE for text fragments which match REGEXP. For example, you could use ("\\_<-?[0-9]+\\_>" . font-lock-constant-face) to highlight integers as constants (note the use of \_< and \_> to match the start and end of a symbol; see the regexp documentation for more information).
(REGEXP (GROUP FACE)…) is a bit more advanced. When REGEXP matches a subset of the buffer, Font Lock assigns faces to the capture group identified by their number. You could use this construction to detect a complex syntaxic element and highlight some of its parts with different faces.

Simplified Common Lisp highlighting

We are going to configure keyword highlighting for the following types of values:

Character literals, e.g. #\Space.
Function names in the context of a function call for standard Common lisp functions.
Standard Common Lisp values such as *STANDARD-OUTPUT* or PI.

Additionally, we want to keep the default syntaxic highlighting configuration which recognizes character strings, documentation strings and comments.

Faces

Let us start by defining new faces for the different values we are going to match:

(defface g-cl-character-face
  '((default :inherit font-lock-constant-face))
  "The face used to highlight Common Lisp character literals.")

(defface g-cl-standard-function-face
  '((default :inherit font-lock-keyword-face))
  "The face used to highlight standard Common Lisp function symbols.")

(defface g-cl-standard-value-face
  '((default :inherit font-lock-variable-name-face))
  "The face used to highlight standard Common Lisp value symbols.")

Nothing complicated here, we simply inherit from default Font Lock faces. You can then configure these faces in your color theme without affecting other modes using Font Lock.

Keywords

To detect standard Common Lisp functions and values, we are going to need a regular expression. The first step is to build a list of strings for both functions and values. Easy to do with a bit of Common Lisp code!

(defun standard-symbol-names (predicate)
  (let ((symbols nil))
    (do-external-symbols (symbol :common-lisp)
      (when (funcall predicate symbol)
        (push (string-downcase (symbol-name symbol)) symbols)))
    (sort symbols #'string<)))
    
(standard-symbol-names #'fboundp)
(standard-symbol-names #'boundp)

The STANDARD-SYMBOL-NAMES build a list of symbols exported from the :COMMON-LISP package which satisfy a predicate. The first call gives us the name of all symbols bound to a function, and the second all which are bound to a value.

The astute reader will immediately wonder about symbols which are bound both a function and a value. They are easy to find by calling INTERSECTION on both sets of names: +, /, *, -. It is not really a problem: we can highlight function calls by matching function names preceded by (, making sure that these symbols will be correctly identified as either function symbols or value symbols depending on the context.

We store these lists of strings in the g-cl-function-names and g-cl-value-names (the associated code is not reproduced here: these lists are quite long; but I posted them as a Gist).

With this lists, we can use the regexp-opt Emacs Lisp function to build optimized regular expressions matching them:

(defvar g-cl-font-lock-keywords
  (let* ((character-re (concat "#\\\\" lisp-mode-symbol-regexp "\\_>"))
         (function-re (concat "(" (regexp-opt g-cl-function-names t) "\\_>"))
         (value-re (regexp-opt g-cl-value-names 'symbols)))
    `((,character-re . 'g-cl-character-face)
      (,function-re
       (1 'g-cl-standard-function-face))
      (,value-re . 'g-cl-standard-value-face))))

Characters literals are reasonably easy to match.

Functions are a bit more complicated since we want to match the function name when it is preceded by an opening parenthesis. We use a capture capture (see the last argument of regexp-opt) for the function name and highlight it separately.

Values are always matched as full symbols: we do not want to highlight parts of a symbol, for example MAP in a symbol named MAPPING.

Final configuration

Finally we can define the variable which will be used for font-lock-defaults in the initialization hook; we copy the original value from lisp-mode, and change the keyword list for what is going to be our own configuration:

(defvar g-cl-font-lock-defaults
  '((g-cl-font-lock-keywords)
    nil                                 ; enable syntaxic highlighting
    t                                   ; case insensitive highlighting
    nil                                 ; use the lisp-mode syntax table
    (font-lock-mark-block-function . mark-defun)
    (font-lock-extra-managed-props help-echo)
	(font-lock-syntactic-face-function
	 . lisp-font-lock-syntactic-face-function)))

To configure font-lock-defaults, we simply set it in the initialization hook of lisp-mode:

(defun g-init-lisp-font-lock ()
  (setq font-lock-defaults g-cl-font-lock-defaults))
  
(add-hook 'lisp-mode-hook 'g-init-lisp-font-lock)

Comparison

Let us compare highlighting for a fragment of code before and after our changes:

The differences are subtle but important:

All standard functions are highlighted, helping to distinguish them from user-defined functions.
Standard values such as *ERROR-OUTPUT* are highlighted.
Character literals are highlighted the same way as character strings.
Keywords are not highlighted anymore, avoiding the confusion with function names.

Conclusion

That was not easy; but as always, the effort of going through the documentation and experimenting with different Emacs components was very rewarding. Font Lock does not feel like a black box anymore, opening the road for the customization of other major modes.

In the future, I will work on a custom color scheme to use more subtle colors, with the hope of reducing the rainbow effect of so many major modes, including lisp-mode.

Templating in Emacs with Tempo

nicolas@n16f.net (Nicolas Martyanoff) — Sun, 12 Feb 2023 18:00:00 +0000

I have used text editors for more than 20 years; in all that time, I have never used a templating system to generate content because copy pasting and replacing always felt good enough. I recently decided to give it a try.

In Emacs it is hard to talk about templating without mentionning YASnippet. Developped by the prolific João Távora, who also developped Eglot, YASnippet lets you write templates as text documents.

But while I was researching the subject, I found out that Emacs already had two builtin templating modules: Skeleton and Tempo.

Tempo looked simpler, so I decided to give it a chance.

Using Tempo

Tempo templates are functions defined with tempo-define-template. The content to be inserted is a S-expression containing various kinds of elements which control the insertion process.

As an example, let us define a template to insert a HTML figure.

First we define a variable to store a list of templates. When using html-mode, we instruct Tempo to use it.

(defvar g-html-tempo-tags nil)

(defun g-init-html-tempo-templates ()
  (tempo-use-tag-list 'g-html-tempo-tags))

(add-hook 'html-mode-hook 'g-init-html-tempo-templates)

Then we define the template itself:

(tempo-define-template
 "g-html-figure"
 '("<figure>" n
   > "<img src=\"" (p "URI: ") "\">" n
   > "<figcaption>" (p "Caption: ") "</figcaption>" n
   "</figure>")
 "figure"
 "a figure containing an image and caption"
 'g-html-tempo-tags)

This form creates a function named tempo-template-g-html-figure. When it is called, Tempo processes elements of the template:

Strings are inserted in the buffer.
The n symbol causes the insertion of a new line character
The > symbol tells Emacs to indent the current line according to the rules of the major mode of the buffer.
The p forms cause Tempo to ask the user for values to insert. Note that you need to set tempo-interative to t.

Note that Tempo supports more elements; refer to the documentation string of tempo-define-template for more information.

The template is associated to the figure text tag which will be used for completion. We also add a description, and finally add the template to the g-html-tempo-tags list. Note that these three last arguments are optional.

Tag matching

Of course we do not have to call the template manually. When we call tempo-complete-tag, Tempo uses the string before the cursor to decide which template to insert. Open a HTML buffer, type figure and execute tempo-complete-tag (I bind it to M-S-<tab>): Tempo will automatically insert our template.

Tempo will handle the case where there is partial match for multiple templates and will spawn a completion buffer.

Now it would make sense to use <figure> as tag. To do so, update the g-init-html-tempo-templates function to set the local variable that Tempo uses to detect a tag:

(setq tempo-match-finder "\\(<[a-z]+>\\)\\=")

Doing so will use HTML tags as Tempo tags. We can then alter the call to tempo-define-template to use <figure> as tag, and from now on use it for template insertion.

Of course this means we can customize it to allow different formats of Tempo tags depending on the major mode we are in. Handy.

Writing a template selector

Calling template functions manually is unpractical and tag completion requires remembering which tags have been defined. My interface of choice would be a simple key spawning an incremental completion buffer (Helm in my case) to let me select a template to insert.

As it turns out, it is not that hard:

(defun g-insert-tempo-template ()
  (interactive)
  (let* ((tags-data
          (mapcar (lambda (entry)
                    (let ((function (cdr entry)))
                      (list function (documentation function))))
                  (tempo-build-collection)))
         (completion-extra-properties
          `(:annotation-function
            (lambda (string)
              (let* ((data (alist-get string minibuffer-completion-table
                                      nil nil #'string=))
                     (description (car data)))
                (format "  %s" description)))))
         (function-name (completing-read "Template: " tags-data))
         (function (intern function-name)))
    (funcall function)))

As we have already seen in a previous post, completing-read is quite limited in terms of presentation. I will probably spend some time switching from Helm to a mix of Vertico and Marginalia which apparently offers more options.

This will do the job in the mean time.

Conclusion

Tempo is reasonably satisfying. While it is a very simple module, it lets me define templates as Emacs Lisp expressions, associate them to tags and store them in tag lists which can be used in the major modes of my choice.

I do not expect to start using dozens of tiny templates for the simplest constructions, but Tempo is going to help with recurrent complex constructions such as Emacs module skeletons or Common Lisp system definitions.

Decluttering Dired for peace of mind

nicolas@n16f.net (Nicolas Martyanoff) — Fri, 03 Feb 2023 18:00:00 +0000

Dired is an Emacs mode providing an interactive interface to navigate and manipulate files. It took me a while to start using it, but it is so efficient that I now spend more time in it than in my usual shell.

However I am no fond of the way files are listed. Dired displays a lot of information which is — at least for me — rarely used. As a result the important content (the name of the file) is flushed to the right of the window, often leading to unpractical line wrapping.

It is hard to find what you are searching for in this kind of interface:

So I decided to spend some time improving my Dired experience.

Configuring a simpler view

Dired comes with the dired-hide-details-mode minor mode which hides extra information. By default it is activated with the ( key.

It has two drawbacks:

First it also hides the display of symbolic link target while still showing the -> marker after the link. This behaviour can be changed by setting the dired-hide-details-hide-symlink-targets variable to nil.
Second, Dired disables this minor mode each time you move to a different directory, which is really annoying

We create a g-dired-minimal-view variable to store the current state. When then write two functions: one to either enable or disable the minor mode depending on the state, called by the dired-mode-hook, and one to switch between simple and extended view bound to the more accessible <tab> key.

(setq g-dired-minimal-view t)

(defun g-dired-setup-view ()
  (dired-hide-details-mode (if g-dired-minimal-view 1 -1)))

(defun g-dired-switch-view ()
  (interactive)
  (setq g-dired-minimal-view (not g-dired-minimal-view))
  (g-dired-setup-view))

(use-package dired
  :config
  (setq dired-hide-details-hide-symlink-targets nil)

  :hook
  ((dired-mode-hook . g-dired-setup-view))

  :bind
  (:map dired-mode-map
        ("<tab>" . g-dired-switch-view)))

A better extended view

While I prefer the simple view by default, the extended view still has its use; but I find it hard to read:

The traditional representations of permissions takes a lot of horizontal space, the 4 digit octal value would be shorter.
The number of links is not really useful.
The size of the file would be more convenient in a human readable format.
The date and time uses an irregular US-style format which is either “month day year” or “month day hour:minute”.

To list files, Dired call the ls program with a list of options (defined by the dired-listing-switches variable), insert the output in the buffer and rely on regular expressions to extract information. This means that we have very little control on formatting. We can change the options passed to ls, but we have to be careful not to break Dired features. For example, Dired can highlight files with specific permissions, but rely on a regular expression based on the format used by ls, so we cannot change the permission column.

First we use dired-listing-switches to add the -h (for human-readable sizes) and --time-style=long-iso option. Since these options are only available for the GNU version of ls, I will have to add platform detection for FreeBSD support in a way that works when Dired is running with TRAMP. Something for another day.

Then we add a dired-after-readin-hook hook which is called by Dired after the output of ls has been collected and inserted in the buffer. In this hook, we iterate on lines and process them. We highlight metadata with the shadow face to keep them visually distinct from the filename, and we hide the link count column using the invisible text property so that the text stays in the buffer, making sure not to break Dired features.

Finally we disable wrapping with a hook.

(defun g-dired-postprocess-ls-output ()
  "Postprocess the list of files printed by the ls program when
executed by Dired."
  (save-excursion
    (goto-char (point-min))
    (while (not (eobp))
      ;; Go to the beginning of the next line representing a file
      (while (null (dired-get-filename nil t))
        (dired-next-line 1))
      (beginning-of-line)
      ;; Narrow to the line and process it
      (let ((start (line-beginning-position))
            (end (line-end-position)))
        (save-restriction
          (narrow-to-region start end)
          (setq inhibit-read-only t)
          (unwind-protect
              (g-dired-postprocess-ls-line)
            (setq inhibit-read-only nil))))
      ;; Next line
      (dired-next-line 1))))

(defun g-dired-disable-line-wrapping ()
  (setq truncate-lines t))

(defun g-dired-postprocess-ls-line ()
  "Postprocess a single line in the ls output, i.e. the information
about a single file. This function is called with the buffer
narrowed to the line."
  ;; Highlight everything but the filename
  (when (re-search-forward directory-listing-before-filename-regexp nil t 1)
    (add-text-properties (point-min) (match-end 0) '(font-lock-face shadow)))
  ;; Hide the link count
  (beginning-of-line)
  (when (re-search-forward " +[0-9]+" nil t 1)
    (add-text-properties (match-beginning 0) (match-end 0) '(invisible t))))

(use-package dired
  :config
  (setq dired-listing-switches "-alh --time-style=long-iso")

  :hook
  ((dired-mode-hook . g-dired-disable-line-wrapping)
   (dired-after-readin-hook . g-dired-postprocess-ls-output)))

Much better now!

Using units in Emacs Calc

nicolas@n16f.net (Nicolas Martyanoff) — Sat, 28 Jan 2023 18:00:00 +0000

I was recently reminded of the ability of Emacs Calc to perform computations on values with units. Like so many Emacs features, it was on the list of the things I wanted to explore. Today is the day to do so!

Basic operations with units

The Emacs Calc manual presents a lot of features but makes it hard to understand how to start. You cannot just enter an expression such as “25mm” in calc-mode: 25 will be correctly interpreted as a number, but “mm” will be used to trigger the m m key binding which executes calc-save-modes. Not what you had in mind.

To enter a value with a unit, use the ' (apostrophe) key to enter an algebraic expression and hit return to push it on the stack. You can now use this value for your computations.

Note that after hitting ', you can use it a second time to recall the expression on the stack and edit it.

To remove the unit associated with a value. Simply hit u r, for “unit remove”.

Simplifying expressions

Expressions containing multiple units can be simplified. For example, enter two values, 2m and 50cm and add them with +. The resulting expression is 2 m + 50 cm. Hit u s, for “unit simplify”, to have Calc simplify it to 2.5 m.

Converting units

Unit conversion is of course possible. Use u c, for “unit convert”, at any moment: Calc will ask for a unit and will try to convert the value at the top of the stack into this unit. For example, entering 1.5mi (mi being the unit for miles) and typing u c km <return> will correctly yield 2.414016 km.

You will quickly discover that Calc tries way too hard to convert units and will produce really strange results when types are not compatible. For example, trying to convert 250mA into kilometers will produce 0.25A which is clearly incorrect. I have no idea what causes this behaviour. Fortunately you can use u n, bound to calc-convert-exact-units, which will check that the unit you required is compatible with the unit of the expression on the stack. To minimize the risk of producing incorrect results by mistake, I replace the calc-convert-units function by calc-convert-exact-units. I would prefer to remap u c, but Calc has a strange way to handle key bindings that prevent doing this kind of remapping.

(use-package calc
  :config
  (require 'calc-units)

  (setf (symbol-function 'calc-convert-units)
        (symbol-function 'calc-convert-exact-units)))

As a shortcut, u b, where b stands for “base”, will convert the value to its base unit. For example, it will automatically convert 250mA to 0.25A.

Defining custom units

Calc comes by default with more than 170 units (type u v to list them all), but none of them are about standard data size units. This is disappointing given that Emacs is a software primarily used for programming. But we can add new units, so it is not that much of a problem.

New units can be defined with the math-additional-units variable. Its format is the same as math-standard-units: each entry is a list of three elements:

A symbol identifying the unit.
An expression indicating the value of the unit, or nil for fundamental units.
A textual description.

Let us add data sizes. We need two units, bits and bytes, with bytes being defined as 8 bits. Note that using the b symbol for the bit unit will override the internal “Barn” unit; not a problem to me, I do not expect to use it any time soon. Feel free to use bit instead.

(setq math-additional-units
      '((b nil "Bit")
        (B "8 * b" "Byte")))

(setq math-units-table nil)

We need to set math-units-table to nil after defining new units to force Calc to recompute its internal table.

These new units can of course be used with standard SI prefixes defined in Calc. For example, 25kB will correctly be converted to 25000 B. And asking for a convertion to the base unit will yield 200000 b.

A limitation of Calc is its inability to handle unit prefixes of more than one character, so we cannot define ki as being a prefix with a multiplicative value of 1024, which would for example allow us to manipulate kibibytes.

A workaround is to define these power-of-two binary units with the prefix included:

(setq math-additional-units
      '((b nil "Bit")
        (B "8 * b" "Byte")

        (kiB "2^10 * B" "Kibibyte")
        (MiB "2^20 * B" "Mebibyte")
        (GiB "2^30 * B" "Gibibyte")
        (TiB "2^40 * B" "Tebibyte")
        (PiB "2^50 * B" "Pebibyte")
        (EiB "2^60 * B" "Exbibyte")))

(setq math-units-table nil)

Very helpful for data size conversion.

Going farther with Calc

Writing this post has been an interesting experience: it forced me to read various parts of the Calc manual and some of its source files. It made me realize that this package is full of useful features. I hope to find the time to experiment with Calc features in the future.

Taking code screenshots in Emacs

nicolas@n16f.net (Nicolas Martyanoff) — Wed, 18 Jan 2023 18:00:00 +0000

My friend Rémi found an Emacs package developed by Tecosaur to take screenshots of your code. I usually do it with scrot, but it always requires spending some time cropping the result with Gimp. A bit annoying.

Installation

Let us give it a try. The screenshot package is not available on MELPA due to cosmetic issues, so we have two options.

The first one would be to clone the repository, add its location to load-path, and use require to load the module. But doing so means having to explicitely install its dependencies, transient and posframe.

The second option is to rely on use-package and straight.el. With straight.el, you can load packages from various sources, including Git repositories.

(use-package screenshot
  :straight (:type git :host github :repo "tecosaur/screenshot"))

Evaluate the form with C-x C-e, and straight.el will clone the repository and load the screenshot package.

Usage

Simply run M-x screenshot to take a screenshot. If you are currently selecting a region, it will screenshot this part only. If not, it will use the entire buffer.

Since Screenshot uses the transient library, it has the same well designed interface system as Magit:

I really like the ability to adjust the font size just for the screenshot. By default, the save action will save the image in the same directory as the buffer which was selected when screenshot was executed.

Customization

Screenshot lets you change the default value of each setting. This is not obvious when reading the code, because the variables used are defined programmatically through two layers of macros: first screenshot--define-infix then transient-define-infix.

It is too bad these values are not defined as proper settings using defcustom, but we can still set them.

This is a list of available settings:

Variable	Description
`screenshot-line-numbers-p`	Whether to display line numbers or not.
`screenshot-relative-line-numbers-p`	Whether to use relative line numbers or not.
`screenshot-text-only-p`	Whether to show code as simple text or not.
`screenshot-truncate-lines-p`	Whether to truncate long lines instead of wrapping them.
`screenshot-font-family`	The name of the font to use.
`screenshot-font-size`	The size of the font to use.
`screenshot-border-width`	The width of the border.
`screenshot-radius`	The corner radius of the border.
`screenshot-min-width`	The minimal width of the screenshot as a number of characters.
`screenshot-max-width`	The maximal width of the screenshot as a number of characters.
`screenshot-shadow-radius`	The corner radius of the shadow.
`screenshot-shadow-intensity`	The intensity of the shadow.
`screenshot-shadow-color`	The hexadecimal code of the shadow.
`screenshot-shadow-offset-horizontal`	The horizontal offset of the shadow in pixels.
`screenshot-shadow-offset-vertical`	The vertical offset of the shadow in pixels.

Another nice feature is the presence of a hook executed in the temporary buffer used for the screenshot, allowing to execute code affecting this buffer just before the actual screenshot is being taken.

In my case, I use it to disable the fill column indicator and to remove the additional line spacing added by default by Screenshot.

This is my configuration:

(defun g-screenshot-on-buffer-creation ()
  (setq display-fill-column-indicator-column nil)
  (setq line-spacing nil))

(use-package screenshot
  :straight (:type git :host github :repo "tecosaur/screenshot")

  :config
  (setq screenshot-line-numbers-p nil)

  (setq screenshot-min-width 80)
  (setq screenshot-max-width 80)
  (setq screenshot-truncate-lines-p nil)

  (setq screenshot-text-only-p nil)

  (setq screenshot-font-family "Berkeley Mono")
  (setq screenshot-font-size 10)

  (setq screenshot-border-width 16)
  (setq screenshot-radius 0)

  (setq screenshot-shadow-radius 0)
  (setq screenshot-shadow-offset-horizontal 0)
  (setq screenshot-shadow-offset-vertical 0)

  :hook
  ((screenshot-buffer-creation-hook . g-screenshot-on-buffer-creation)))

All in all a very useful package!

Improving Git diffs for Lisp

nicolas@n16f.net (Nicolas Martyanoff) — Sun, 08 Jan 2023 18:00:00 +0000

All my code is stored in various Git repositories. When Git formats a diff between two objects, it generates a list of hunks, or groups of changes.

Each hunk can be displayed with a title which is automatically extracted. Git ships with support for multiple languages, but Lisp dialects are not part of it. Fortunately Git lets users configure their own extraction.

The first step is to identify the language using a pattern applied to the filename. Edit your Git attribute file at $HOME/.gitattributes and add entries for both Emacs Lisp and Common Lisp:

*.lisp diff=common-lisp
*.el diff=elisp

Then edit your Git configuration file at $HOME/.gitconfig and configure the path of the Git attribute file:

[core]
    attributesfile = ~/.gitattributes

Finally, set the regular expression used to match a top-level function name:

[diff "common-lisp"]
    xfuncname="^\\((def\\S+\\s+\\S+)"
    
[diff "elisp"]
    xfuncname="^\\((((def\\S+)|use-package)\\s+\\S+)"

For Lisp dialects, we do not just identify function names: it is convenient to identify hunks for all sorts of top-level definitions. We use a regular expression which captures the first symbol of the form and the name that follows.

Of course you can modifiy these expressions to identify more complex top-level forms. For example, for Emacs Lisp, I also want to identify use-package expressions.

You can see the result in all tools displaying Git diffs, for example in Magit with Common Lisp code:

Or for my Emacs configuration file:

Hunk titles, highlighted in blue, now contain the type and name of the top-level construction the changes are associated with.

A simple change, but one which really helps reading diffs.

Eshell key bindings and completion

nicolas@n16f.net (Nicolas Martyanoff) — Fri, 06 Jan 2023 18:00:00 +0000

I have been having completion issues in Eshell for some time, and I decided to fix it. Of course the yak shaving is always strong with Emacs, so it ended up being a bit more complicated than expected.

Defining keys with use-package

Eshell key bindings are stored in eshell-mode-map. For quite some time, Eshell has been initializing this value to nil, making it impossible to define keys before Eshell has been started. As initially reported, the workaround was to call define-key in a hook, eshell-mode-hook to be precise.

Apparently Emacs 28.1 fixed it. However to be able to use the key binding mechanism of use-package, eshell-mode-map must actually be defined. The solution is to load the right module before use-package configures key bindings, therefore using :init and not :config.

For example:

(use-package eshell
  :init
  (require 'esh-mode) ; eshell-mode-map

  :bind
  (("C-x s" . g-eshell)
   :map eshell-mode-map
   (("C-l" . 'g-eshell-clear)
    ("C-r" . helm-eshell-history))))

Configuring Company for completion

Eshell supports the standard completion-at-point completion system, the function being bound to <tab> by default. If you are using Helm, it will be automatically used to present the list of possible completions. This is a bit cumbersome: I want completion to be inline, not in a separate buffer in the bottom of the screen.

Since I use Company, I can instead bind <tab> to company-complete:

(define-key eshell-mode-map (kbd "<tab>") 'company-complete)

Fixing completion of commands in subdirectories

As it turns out, completion works as intended for global commands, but fails when calling a command in a subdirectory. For example, when completing ./utils/create-blog-post, completion-at-point will replace the line by create-blog-post, which is of course incorrect. This bug is also present when completing the absolute path of an executable.

After spending way too much time on Google and in the em-cmpl module, which handles completion for Eshell, it turned out to be a known bug, introduced almost two years ago.

The workaround is to redefine eshell--complete-commands-list as it was before the commit:

(defun eshell--complete-commands-list ()
  "Generate list of applicable, visible commands."
  (let ((filename (pcomplete-arg)) glob-name)
    (if (file-name-directory filename)
        (if eshell-force-execution
            (pcomplete-dirs-or-entries nil #'file-readable-p)
          (pcomplete-executables))
      (if (and (> (length filename) 0)
               (eq (aref filename 0) eshell-explicit-command-char))
          (setq filename (substring filename 1)
                pcomplete-stub filename
                glob-name t))
      (let* ((paths (eshell-get-path))
             (cwd (file-name-as-directory
                   (expand-file-name default-directory)))
             (path "") (comps-in-path ())
             (file "") (filepath "") (completions ()))
        ;; Go thru each path in the search path, finding completions.
        (while paths
          (setq path (file-name-as-directory
                      (expand-file-name (or (car paths) ".")))
                comps-in-path
                (and (file-accessible-directory-p path)
                     (file-name-all-completions filename path)))
          ;; Go thru each completion found, to see whether it should
          ;; be used.
          (while comps-in-path
            (setq file (car comps-in-path)
                  filepath (concat path file))
            (if (and (not (member file completions)) ;
                     (or (string-equal path cwd)
                         (not (file-directory-p filepath)))
                     (if eshell-force-execution
                         (file-readable-p filepath)
                       (file-executable-p filepath)))
                (setq completions (cons file completions)))
            (setq comps-in-path (cdr comps-in-path)))
          (setq paths (cdr paths)))
        ;; Add aliases which are currently visible, and Lisp functions.
        (pcomplete-uniquify-list
         (if glob-name
             completions
           (setq completions
                 (append (if (fboundp 'eshell-alias-completions)
                             (eshell-alias-completions filename))
                         (eshell-winnow-list
                          (mapcar
                           (lambda (name)
                             (substring name 7))
                           (all-completions (concat "eshell/" filename)
                                            obarray #'functionp))
                          nil '(eshell-find-alias-function))
                         completions))
           (append (and (or eshell-show-lisp-completions
                            (and eshell-show-lisp-alternatives
                                 (null completions)))
                        (all-completions filename obarray #'functionp))
                   completions)))))))

I have no idea what is wrong in the new implementation of the function, but hopefully someone can find a fix to be merged before Emacs 29 is released.

Org-mode headline tips

nicolas@n16f.net (Nicolas Martyanoff) — Mon, 02 Jan 2023 18:00:00 +0000

Org-mode is what got me into Emacs in the first place. I use it to take notes, keep track of what I have to do and plan projects.

An Org file is a tree of elements, each one starting with a headline. Manipulating headlines can be confusing; here are a few tips that you may find helpful.

Do not split lines when adding headlines

At any point, you can insert a new headline below the current one using the C-<return> shortcut, which calls org-insert-heading. However if the cursor is at the middle of a line (headline or content), Org will split it and add the end of the line to the new headline.

~~Quite annoying, really. Fortunately there is a function to add a headline without splitting the currentline, org-insert-heading-respect-content. I simply bind it to C-<return>:~~

~~Obviously I want the same behaviour for C-M-<return> which inserts a TODO headline:~~

Edit (2023-01-07)
As it turns out, a simpler way to do that is to set org-insert-heading-respect-content:

(setq org-insert-heading-respect-content t)

No need to rebind keys.

Jump quickly to the right headline

Some of my Org files are quite long. For example, my main development tracking file contains more than 700 lines.

I never really thought about navigation, and usually either search for elements by title with C-s or move between folded items manually (I use org-startup-folded so that all items are folded by default).

As it turns out, Org has a buitin navigation system triggered by C-c C-j. At first I could not see how it could help; but then I realized that this feature can use native Emacs completion. This is incredibly useful when combined with a vertical completion framework such as Helm, making it easy to jump to any headline just by typing a couple characters.

In order to do that, we enable completion with org-goto-interface, disable the multi-steps navigation system, and set the maximum depth level used to select headlines which will be listed during completion.

(setq org-goto-interface 'outline-path-completion)
(setq org-outline-path-complete-in-steps nil)
(setq org-goto-max-level 2)

Stop highlighting TODO headlines

By default, Org highlights the entire headline for TODO items, not just the TODO or DONE keyword.

I believe this is a mistake: headlines mark the hierarchy of items, and having multiple red or green headlines is confusing. This behaviour can be configured with two settings:

(setq org-fontify-todo-headline nil)
(setq org-fontify-done-headline nil)

This way, headlines keep their original color (defined by org-level-* faces), and keywords only are highlighted with the org-todo and org-done faces.

Replacing Projectile by Project

nicolas@n16f.net (Nicolas Martyanoff) — Tue, 27 Dec 2022 18:00:00 +0000

I have been using Projectile for years, and it served me well. While Projectile is really useful, it is a third party package made of more than 8000 lines of code. Since the built-in Project module has received lots of improvements since Emacs 28.1, I decided to give it a try and see if I could remove Projectile from my Emacs setup.

Key binding

The Project keymap is bound to C-x p by default, but I am used to C-c p. This is easy to change, for example with use-package:

(use-package project
  :bind-keymap
  (("C-c p" . project-prefix-map)))

Switching between projects

By default, the project switching command uses a prompt letting you select a command to run for the selected project. If you always use the same command, you can configure it, allowing to switch project without any prompt.

For example, to always display the project directory with Dired:

(setq project-switch-commands 'project-dired)

Search using Helm and AG

The Projectile feature I used the most is incremental project search using helm-projectile and helm-ag.

Adding this feature to Project is not that hard. Let us write the search function:

(defun g-project-search ()
  (interactive)
  (let ((project (project-current t)))
    (helm-do-ag (project-root project))))

And bind it to C-c p s (replacing project-shell, a command I do not use):

(use-package project
  :bind
  (:map project-prefix-map
        (("s" . 'g-project-search))))

One thing to be aware of: helm-ag does not take patterns returned by project-ignores into consideration when filtering results. It is not that much of a problem to me, since ag already supports .gitignore files

But it would be an improvement to use project-ignores and pass the pattern list to ag.

In the mean time, I can also remove the helm-projectile dependency.

Starting Eshell

While both Projectile and Project can run Eshell in the current project, I want the ability to start it the same way whether I am in a project or not. Therefore I have a small function looking for a current project and running Eshell the right way. Migrating to Project is easy:

(defun g-eshell ()
  "Start eshell at the root of the current project, or in the
current directory if the current buffer is not part of a
project."
  (interactive)
  (if (project-current)
      (project-eshell)
    (eshell)))

I bind it to C-x s (“s” being for “shell”):

(global-set-key (kbd "C-x s") 'g-eshell)

Conclusion

The result is quite satisfying. It may not do everything Projectile supports, but the features I use are all implemented. As a result, my Emacs setup is simpler and lighter, relying on one less external dependency.

Clearing the Eshell Buffer

nicolas@n16f.net (Nicolas Martyanoff) — Sat, 24 Dec 2022 18:00:00 +0000

I have used the C-l shortcut in ZSH to clear the screen for as long as I can remember. When I started using Eshell, one of the first problems I encountered was the inability to clear the buffer. I like to remove the output of previous commands to be able to focus on the current one, so let us script Emacs once again.

After a quick look to the eshell module, it seems we can do that in two steps:

Clear the entire buffer with (eshell/clear t).
Recreate the prompt with (eshell-emit-prompt).

A non-obvious edge case is that it should be possible to hit C-l while typing a command without losing what was typed. For that, we have to keep a copy of the input content before clearing the screen and reinsert it after.

The result is the following function:

(defun g-eshell-clear ()
  (interactive)
  (let ((input (eshell-get-old-input)))
    (eshell/clear t)
    (eshell-emit-prompt)
    (insert input)))

We then write a hook which binds the function to C-l:

(defun g-eshell-init-keys ()
  (define-key eshell-mode-map (kbd "C-l") 'g-eshell-clear))

And register the hook:

(add-hook 'eshell-mode-hook 'g-eshell-init-keys)

Note that clearing the screen means removing shell history from the buffer. Not really an issue: instead of looking in the buffer, I use helm-eshell-history which is much more convenient.

Investigating a FFAP issue in Emacs

nicolas@n16f.net (Nicolas Martyanoff) — Thu, 22 Dec 2022 18:00:00 +0000

I just encountered the strangest behaviour in Emacs. I was editing a shell script, hit C-x b to switch to another buffer, and Emacs suddenly froze with the following message:

Pinging <hostname> (Commercial)...

Where <hostname was the hostname of a server used in the script.

I really do not like the idea of my text editor pinging random servers just because their name appears in a buffer, so I went to the bottom of it.

Since I had no idea what caused this behaviour, I simply ran grep for the “Pinging” message in the Emacs source repository and found it in the ffap-machine-p function. To find out how it was called, I enabled tracing, making sure to print the current backtrace for each trace:

(trace-function 'ffap-machine-p nil 'backtrace)

This yielded the following (truncated) trace:

ffap-machine-p("pkg.exograd.com")
ffap-machine-at-point()
ffap-guesser()
ffap-guess-file-name-at-point()
run-hook-with-args-until-success(ffap-guess-file-name-at-point)
helm-guess-filename-at-point()
helm-fuzzy-highlight-matches(…)
helm--collect-matches(…)
helm-update(nil)
helm-read-from-minibuffer(nil nil nil nil nil nil nil)
helm-internal(…)
apply(helm-internal (…))
helm((helm-source-buffers-list helm-source-buffer-not-found) …)
apply(helm ((helm-source-buffers-list helm-source-buffer-not-found) …)
helm(…)
helm-buffers-list()
funcall-interactively(helm-buffers-list)
call-interactively(helm-buffers-list nil nil)
command-execute(helm-buffers-list)

Apparently, Helm tries to guess if the cursor is pointing to a filename using the ffap (for “find file at point”) module. For some reason, it does not just identify paths, but also URLs and machine names. And the default strategy to check if a machine is “real” and “reachable” (as documented in ffap-machine-p is to ping it.

This kind is insanity is really disappointing from Emacs: a text editor should absolutely not use the network in such a hidden way by default.

The behaviour of ffap-machine-p depends on three settings:

ffap-machine-p-local: what to do if the hostname does not have a domain.
ffap-machine-p-known: what to do if the hostname has a known domain.
ffap-machine-p-unknown: what to do if the hostname has an unknown domain.

For all these variables, the value is either accept, to indicate that the hostname is a valid hostname, reject to indicate it is not, or ping to check by sending a ping message.

The way to fix this mess is to accept local and known hostnames while rejecting unknown ones:

(setq ffap-machine-p-local 'accept)
(setq ffap-machine-p-known 'accept)
(setq ffap-machine-p-unknown 'reject)

If you are curious, ffap uses mail-extr-all-top-level-domains in the mail-extr module to assess if a domain is “known”. This function will identify most common TLDs, but has never been updated for modern TLDs. Something to keep in mind if you want to use it.

Fixing unquote-splicing behaviour with Paredit

nicolas@n16f.net (Nicolas Martyanoff) — Tue, 13 Dec 2022 18:00:00 +0000

Paredit is an Emacs package for structural editing. It is particularly useful in Lisp languages to manipulate expressions instead of just characters.

One of the numerous little features of Paredit is the automatic insertion of a space character before a delimiting pair. For example, if you are typing (length, typing ( will have Paredit automatically insert a space character before the opening parenthesis, to produce the expected (length ( content.

Paredit is smart enough to avoid doing so after quote, backquote or comma characters, but not after an unquote-splicing sequence (,@) which is quite annoying in languages such as Scheme or Common Lisp. As almost always in Emacs, this behaviour can be customized.

Paredit decides whether to add a space or not using the paredit-space-for-delimiter-p function, ending up with applying a list of predicates from paredit-space-for-delimiter-predicates.

Let us add our own. For more flexibility, we will start by defining a list of prefixes which are not to be followed by a space:

(defvar g-paredit-no-space-prefixes (list ",@"))

We then write our predicate which simply checks if we are right after one of these prefixes:

(defun g-paredit-space-for-delimiter (endp delimiter)
  (let ((point (point)))
    (or endp
        (seq-every-p
         (lambda (prefix)
           (and (> point (length prefix))
                (let ((start (- point (length prefix)))
                      (end point))
                  (not (string= (buffer-substring start end) prefix)))))
         g-paredit-no-space-prefixes))))

Finally we add a Paredit hook to append our predicate to the list:

(defun g-init-paredit-space-for-delimiter ()
  (add-to-list 'paredit-space-for-delimiter-predicates
               'g-paredit-space-for-delimiter))

(add-hook 'paredit-mode-hook 'g-init-paredit-space-for-delimiter)

Not only does it fix the problem for unquote-slicing, but it makes it easy to add new prefixes. For example I immediately added #p (used for pathnames in Common Lisp, e.g. #p"/usr/bin/") to the list.

Eye level window centering in Emacs

nicolas@n16f.net (Nicolas Martyanoff) — Sun, 30 Oct 2022 18:00:00 +0000

In the default Emacs configuration, C-l is bound to recenter-top-bottom. This function has an interesting behaviour: when called once, it scrolls the current window so that the current line appears at the middle of the screen. When called several times in a row, it cycles through three scrolling position: middle, top and bottom.

This has always bugged me because I only need one of the three behaviours, and none of these positions are useful to me. In pratice, I want to focus on the line I am working on, which means putting it at eye level. In my case at roughly 20% of the top of the window.

Fortunately Emacs is easy to customize. As it turns out, recenter-top-bottom is based on recenter which is easy to use:

(defcustom g-recenter-window-eye-level 0.2
  "The relative position of the line considered as eye level in the
current window, as a ratio between 0 and 1.")

(defun g-recenter-window ()
  "Scroll the window so that the current line is at eye level."
  (interactive)
  (let ((line (round (* (window-height) g-recenter-window-eye-level))))
    (recenter line)))

(global-set-key (kbd "C-l") 'g-recenter-window)

Local CLHS access in Emacs

nicolas@n16f.net (Nicolas Martyanoff) — Wed, 01 Jan 2020 18:00:00 +0000

The CLHS, or Common Lisp HyperSpec, is one of the most important resource for any Common Lisp developer. It is derived from the official Common Lisp standard, and contains documentation for every aspect of the language.

While it is currently made available online by LispWorks, it can be useful to be able to access it locally, for example when you do not have any internet connection available.

For this purpose, LispWorks provides an archive which can be downloaded and browsed offline.

While the HyperSpec is valuable on its own, the SLIME Emacs mode provides various functions to make it even more useful.

I have found the following functions particularily useful:

slime-documentation-lookup, or C-c C-d h to browse the documentation associated with a symbol.
common-lisp-hyperspec-format, or C-c C-d ~, to lookup format control characters.
common-lisp-hyperspec-glossary-term, or C-c C-d g, to access terms in the glossary.

With the default configuration, Emacs will use the online HyperSpec. You can have it use a local copy by setting common-lisp-hyperspec-root to a file URI. For example, if you downloaded the content of the CLHS archive to ~/common-lisp/:

(setq common-lisp-hyperspec-root
  (concat "file://" (expand-file-name "~/common-lisp/HyperSpec/")))

And if you configure Emacs to use the EWW web browser, you can work with the CLHS without leaving your editor.

Reading RFC documents in Emacs

nicolas@n16f.net (Nicolas Martyanoff) — Sun, 02 Jun 2019 18:00:00 +0000

I am used to read RFC documents in Emacs by opening them as simple text files. But I was always annoyed by the impossibility to follow references to other documents. Additionally, searching for the right RFC usually involve going back to the web browser and Google while I would prefer staying in Emacs.

Since I enjoy Helm so much, I thought it would be easy to parse the index of all RFC documents, and create a browser allowing me to pick a RFC. And since I was writing some elisp, I ended up writing a major mode to highlight parts of RFC documents, including adding links when another RFC is mentioned.

So here is rfc-mode. It is quite simple for the time being, and I have a few ideas for more features, but it is already quite useful.

It is also available on MELPA.

Buffer ordering with Helm

nicolas@n16f.net (Nicolas Martyanoff) — Sun, 21 Oct 2018 18:00:00 +0000

I have been using Emacs for some time, and ido has always been my favourite way to switch buffers.

But recently I discovered and started using Helm, a package based on incremental completion which can provide lots of interesting features. One of them being buffer switching.

The simplest way to use Helm to switch buffers is helm-buffers-list. Personally I use C-x b:

(global-set-key (kbd "C-x b") 'helm-buffers-list)

I really like that helm-buffer-list orders buffers using the last time they were used. However as soon as I start typing something to narrow the selection, Helm switches to a different ordering based on the length of buffer names. A bug report was submitted, but apparently, this is the intended behaviour.

Fortunately, it is possible to override this behaviour, as suggested in another Github issue. Ordering is done in the helm-buffers-sort-transformer function; we could replace it, but it is cleaner to advise it.

(defun nm-around-helm-buffers-sort-transformer (candidates source)
  candidates)

(advice-add 'helm-buffers-sort-transformer
            :override #'nm-around-helm-buffers-sort-transformer)

This way we keep the LRU-style ordering even when narrowing the selection.