From 20fa3ea348617350fa8a437fad75aa9e9a9a620f Mon Sep 17 00:00:00 2001
From: Eshel Yaron <me@eshelyaron.com>
Date: Mon, 2 Oct 2023 10:02:46 +0200
Subject: [PATCH] Document 'M-x align' in the Emacs manual

* doc/emacs/align.texi: New file.
* doc/emacs/emacs.texi: Include it and update menu.
---
 doc/emacs/align.texi | 70 ++++++++++++++++++++++++++++++++++++++++++++
 doc/emacs/emacs.texi |  2 ++
 2 files changed, 72 insertions(+)
 create mode 100644 doc/emacs/align.texi

diff --git a/doc/emacs/align.texi b/doc/emacs/align.texi
new file mode 100644
index 00000000000..c7e48890695
--- /dev/null
+++ b/doc/emacs/align.texi
@@ -0,0 +1,70 @@
+@c This is part of the Emacs manual.
+@c Copyright (C) 2023 Free Software Foundation, Inc.
+@c See file emacs.texi for copying conditions.
+@node Alignment
+@chapter Alignment
+@cindex alignment
+
+  @dfn{Alignment} is the process of adjusting whitespace in a sequence
+of lines such that in all lines certain parts begin at the same
+column.  This is usually done to enhance readability of a piece of
+text or code.  The classic example is aligning a series of assignments
+in C-like programming languages:
+
+@example
+int a = 1;
+short foo = 2;
+double blah = 4;
+@end example
+
+Is commonly aligned to:
+
+@example
+int    a    = 1;
+short  foo  = 2;
+double blah = 4;
+@end example
+
+@findex align
+  You can use the command @kbd{M-x align} to align lines in the
+current region.  This command knows about common alignment patterns
+across many markup and programming languages.  It encodes these
+patterns as a set of @dfn{alignment rules}, that say how to align
+different kinds of text in different contexts.
+
+@kbd{M-x align} splits the region into a series of @dfn{sections},
+usually sequences of non-blank lines, and aligns each section
+according to a matching alignment rule by expanding or contracting
+stretches of whitespace.  If you call this command with a prefix
+argument (@kbd{C-u M-x align}), it enables more alignment rules that
+are often useful but may sometimes be too intrusive.  For example, in
+a Lisp buffer with the following form:
+
+@lisp
+(set-face-attribute 'mode-line-inactive nil
+                    :box nil
+                    :background nil
+                    :underline "black")
+@end lisp
+
+Typing (@kbd{C-u M-x align}) yields:
+
+@lisp
+(set-face-attribute 'mode-line-inactive nil
+                    :box                nil
+                    :background         nil
+                    :underline          "black")
+@end lisp
+
+@vindex align-indent-before-aligning
+  If the user option @code{align-indent-before-aligning} is
+non-@code{nil}, Emacs indents the region before aligning it with
+@kbd{M-x align}.  @xref{Indentation}.
+
+@vindex align-to-tab-stop
+  The user option @code{align-to-tab-stop} says whether aligned parts
+should start at a tab stop (@pxref{Tab Stops}).  If this option is
+@code{nil}, @kbd{M-x align} uses just enough whitespace for alignment,
+disregarding tab stops.  If this is a non-@code{nil} symbol, @kbd{M-x
+align} checks the value of that symbol, and if this value is
+non-@code{nil}, @kbd{M-x align} aligns to tab stops.
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 7a21eb49e24..c4ed9a6ae93 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -178,6 +178,7 @@ Top
 Advanced Features
 * Modes::               Major and minor modes alter Emacs's basic behavior.
 * Indentation::         Editing the white space at the beginnings of lines.
+* Alignment::           Making common parts of lines start at the same column.
 * Text::                Commands and modes for editing human languages.
 * Programs::            Commands and modes for editing programs.
 * Building::            Compiling, running and debugging programs.
@@ -1616,6 +1617,7 @@ Intro
 @include mule.texi
 @include modes.texi
 @include indent.texi
+@include align.texi
 @include text.texi
 @c Includes fortran-xtra.
 @include programs.texi
-- 
2.42.0