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

* doc/emacs/indent.texi (Alignment): New section.
* doc/emacs/emacs.texi: Update menu.
---
 doc/emacs/emacs.texi  |  1 +
 doc/emacs/indent.texi | 79 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 7a21eb49e24..3f122107392 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -595,6 +595,7 @@ Top
 * Tab Stops::             Stop points for indentation in Text modes.
 * Just Spaces::           Using only space characters for indentation.
 * Indent Convenience::    Optional indentation features.
+* Alignment::             Making common parts of lines start at the same column.
 
 Commands for Human Languages
 
diff --git a/doc/emacs/indent.texi b/doc/emacs/indent.texi
index 17b663d22e1..e6d0246720f 100644
--- a/doc/emacs/indent.texi
+++ b/doc/emacs/indent.texi
@@ -55,6 +55,7 @@ Indentation
 * Tab Stops::             Stop points for indentation in Text modes.
 * Just Spaces::           Using only space characters for indentation.
 * Indent Convenience::    Optional indentation features.
+* Alignment::             Making common parts of lines start at the same column.
 @end menu
 
 @node Indentation Commands
@@ -265,3 +266,81 @@ Indent Convenience
 by default.  To toggle this minor mode, type @kbd{M-x
 electric-indent-mode}.  To toggle the mode in a single buffer,
 use @kbd{M-x electric-indent-local-mode}.
+
+@node Alignment
+@section 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
+
+@findex align-current
+@findex align-entire
+  The command @kbd{M-x align-current} is similar to to @kbd{M-x
+align}, except that it operates only on the section that contains
+point, regardless of the current region.  @kbd{M-x align-entire} is
+another variant of @kbd{M-x align}, that aligns the entire region as a
+single alignment section with consistent alignment, disregarding blank
+lines and similar hints that @kbd{M-x align} uses to separate the
+region into multiple alignment sections.
+
+@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.
-- 
2.42.0