New post about "Alignment in Emacs"

diff --git a/source/notes/john-wiegley.org b/source/notes/john-wiegley.org
new file mode 100644 (file)
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 (file)
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:<div class="metadata">@@Created on [{{{date}}}], last updated [{{{modification-time(%Y-%m-%d, t)}}}]@@html:</div>@@
+
+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.