Alignment in Emacs

Suppose that you have some code that looks like this:

b->pt = BEG;
b->begv = BEG;
b->zv = BEG;
b->pt_byte = BEG_BYTE;
b->begv_byte = BEG_BYTE;
b->zv_byte = BEG_BYTE;

But really, you want it to look like that:

b->pt        = BEG;
b->begv      = BEG;
b->zv        = BEG;
b->pt_byte   = BEG_BYTE;
b->begv_byte = BEG_BYTE;
b->zv_byte   = BEG_BYTE;

See? Nice and tidy. Something about putting similar things on the same column of consecutive lines just feels… right. I think it has something to do with clarifying the meaning of the code by visually identifying parallel constructs. It’s like putting these lines into a little table that we mentally annotate with column names. Anyway, this business of adding meaningless whitespace to make things pretty is called alignment, because we align parts of different lines to the same column. But aligning code manually can be quite a hassle.

How do I align stuff without breaking the spacebar?

This question bothered many a-tinkerer throughout the years. I’m sure you too wondered about just that, once or twice. For over two decades now, Emacs has an answer. Authored by John Wiegley in 1999, align.el is an Emacs Lisp library that includes M-x align and several related commands. This library was added to Emacs in the year 2000, and not a lot have changed since then in terms of its functionality.

Personally, I knew that M-x align existed somewhere in the back of my head, but I guess I never really internalized it and adopted it into my workflows. I certainly didn’t know exactly how it works. I’m not going to tell you about it here, either. Not another word. Because last week, more than twenty years after the debut of this alignment facility in Emacs 21, it has finally been documented in the Emacs manual.

And so it came to be, that after aligning some Prolog code by hand one too many times, I decided to learn to utilize this M-x align command. (I’ve tried it in the past, but for some reason it didn’t stick.) I started by typing C-h f align RET and reading the command’s docstring. That gives a good idea of what M-x align does, but I wanted to dig deeper. So I hit i to invoke help-goto-info, and to my surprise Emacs replied with:

Not documented as a symbol: align

A follow up examination of the manual confirmed what this message seemed to suggest–the documentation of M-x align just wasn’t there. My reaction was, of course, to submit a bug report to Emacs, requesting that M-x align would be documented, and suggesting a draft patch for adding such documentation. At first, Eli Zaretskii didn’t seem that enthusiastic about documenting M-x align in the manual. Instead, he suggested to expand some of the docstrings in align.el to cover more ground. I argued that documenting this facility in the manual brings certain benefits that docstrings alone can never replace. For one, the manuals of other programs and Emacs packages can link to nodes in the Emacs manual, but not to docstrings. That did not convince Eli, but we were able to agree to disagree about the principle while moving forward with the specific case at hand of documenting M-x align in the Emacs manual. So, after honing the text through a few more patch revisions, the new manual section landed in the emacs-29 branch, that will soon become Emacs version 29.2.

So if you want to know how to align stuff in Emacs, wait for Emacs 29.2 to come out and do C-h r m alignment RET. If you can’t wait, build Emacs from the Git repository, or just stick to the docstrings.