From a5a4ab4a25cfee7c9b13b73a8a2db29cf0ca195a Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Mon, 16 Oct 2023 20:28:35 +0200 Subject: [PATCH] New post about "Alignment in Emacs" --- source/notes/john-wiegley.org | 13 +++ .../posts/2023-10-16-alignment-in-emacs.org | 91 +++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 source/notes/john-wiegley.org create mode 100644 source/posts/2023-10-16-alignment-in-emacs.org diff --git a/source/notes/john-wiegley.org b/source/notes/john-wiegley.org new file mode 100644 index 0000000..d500ef5 --- /dev/null +++ b/source/notes/john-wiegley.org @@ -0,0 +1,13 @@ +#+TITLE: John Wiegley +#+SUBTITLE: Former Emacs maintainer +#+DESCRIPTION: Eshel Yaron's notes about John Wiegley +#+KEYWORDS: emacs +#+DATE: 2023-10-16 + + +* References in published posts +#+BEGIN: links-to-note :dir "/Users/eshelyaron/checkouts/esy-publish/source/posts/" +#+END: +* References in other notes +#+BEGIN: links-to-note :dir "/Users/eshelyaron/checkouts/esy-publish/source/notes/" +#+END: diff --git a/source/posts/2023-10-16-alignment-in-emacs.org b/source/posts/2023-10-16-alignment-in-emacs.org new file mode 100644 index 0000000..add983a --- /dev/null +++ b/source/posts/2023-10-16-alignment-in-emacs.org @@ -0,0 +1,91 @@ +#+TITLE: Alignment in Emacs +#+SUBTITLE: Sheding some light on a decades old Emacs command +#+DESCRIPTION: Post from Eshel Yaron sheding some light on a decades old Emacs command +#+KEYWORDS: emacs,lisp +#+DATE: 2023-10-16 + +@@html:
@@Created on [{{{date}}}], last updated [{{{modification-time(%Y-%m-%d, t)}}}]@@html:
@@ + +Suppose that you have some code that looks like this: + +#+begin_src c-ts + b->pt = BEG; + b->begv = BEG; + b->zv = BEG; + b->pt_byte = BEG_BYTE; + b->begv_byte = BEG_BYTE; + b->zv_byte = BEG_BYTE; +#+end_src + +But really, you want it to look like that: + +#+begin_src c-ts + b->pt = BEG; + b->begv = BEG; + b->zv = BEG; + b->pt_byte = BEG_BYTE; + b->begv_byte = BEG_BYTE; + b->zv_byte = BEG_BYTE; +#+end_src + +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. + +#+begin_quote +How do I align stuff without breaking the spacebar? +#+end_quote + +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, [[note:emacs][Emacs]] has an answer. Authored by [[note:john-wiegley][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: + +#+begin_quote +Not documented as a symbol: align +#+end_quote + +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 [[https://debbugs.gnu.org/cgi/bugreport.cgi?bug=66303][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, [[note:eli-zaretskii][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. -- 2.39.2