bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 154 bytes --]

Tags: patch

Hi,

This is a request for documenting `M-x align` in the Emacs manual, along
with a suggested draft for such documentation.


Best,

Eshel


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Document-M-x-align-in-the-Emacs-manual.patch --]
[-- Type: text/patch, Size: 3987 bytes --]

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

bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

[Eli Zaretskii]

> Date: Mon, 02 Oct 2023 10:21:58 +0200
> From:  Eshel Yaron via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> This is a request for documenting `M-x align` in the Emacs manual, along
> with a suggested draft for such documentation.

Thanks, but it seems to me we will be better off expanding the doc
string(s) of the respective functions and variables.  The text you
suggest to add documents one command and 2 user options, and provides
an example of the usage.  I think adding the example to the doc string
of 'align' and mentioning the two options in its doc string, as well
as expanding the doc strings of those two options, would give us the
same benefits without the downsides (extra *.texi file, a larger
manual, etc.)

WDYT?

bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Hi,

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Mon, 02 Oct 2023 10:21:58 +0200
>> From:  Eshel Yaron via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>>
>> This is a request for documenting `M-x align` in the Emacs manual, along
>> with a suggested draft for such documentation.
>
> Thanks, but it seems to me we will be better off expanding the doc
> string(s) of the respective functions and variables.  The text you
> suggest to add documents one command and 2 user options, and provides
> an example of the usage.  I think adding the example to the doc string
> of 'align' and mentioning the two options in its doc string, as well
> as expanding the doc strings of those two options, would give us the
> same benefits without the downsides (extra *.texi file, a larger
> manual, etc.)
>
> WDYT?

Thanks for taking a look.  I think that documenting `M-x align` in the
manual has some benefits that aren't completely covered by enhancing
docstrings.  Namely, you can link to the Info from other manuals, such
as manuals of packages that extend/integrate with `align.el`.  I also
think it helps with discoverability.  (For instance, you can skim the
manual online even without using Emacs.)

How would you feel about a new section in indent.texi instead of a new
.texi file?

bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

[Eli Zaretskii]

> From: Eshel Yaron <me@eshelyaron.com>
> Cc: 66303@debbugs.gnu.org
> Date: Mon, 02 Oct 2023 21:30:59 +0200
> 
> > Thanks, but it seems to me we will be better off expanding the doc
> > string(s) of the respective functions and variables.  The text you
> > suggest to add documents one command and 2 user options, and provides
> > an example of the usage.  I think adding the example to the doc string
> > of 'align' and mentioning the two options in its doc string, as well
> > as expanding the doc strings of those two options, would give us the
> > same benefits without the downsides (extra *.texi file, a larger
> > manual, etc.)
> >
> > WDYT?
> 
> Thanks for taking a look.  I think that documenting `M-x align` in the
> manual has some benefits that aren't completely covered by enhancing
> docstrings.  Namely, you can link to the Info from other manuals, such
> as manuals of packages that extend/integrate with `align.el`.  I also
> think it helps with discoverability.  (For instance, you can skim the
> manual online even without using Emacs.)
> 
> How would you feel about a new section in indent.texi instead of a new
> .texi file?

That's better.  But the text should be more than just mentioning a
couple of variables, or else addition to the manual is not justified.

The basic question to ask yourself is: are the doc strings in align.el
enough to allow users to use this feature, or will they need some
"glue" and auxiliary explanations that provide a clearer picture?  If
the latter is needed, that's the stuff to put in the manual.

bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 2915 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Eshel Yaron <me@eshelyaron.com>
>> Cc: 66303@debbugs.gnu.org
>> Date: Mon, 02 Oct 2023 21:30:59 +0200
>>
>> > Thanks, but it seems to me we will be better off expanding the doc
>> > string(s) of the respective functions and variables.  The text you
>> > suggest to add documents one command and 2 user options, and provides
>> > an example of the usage.  I think adding the example to the doc string
>> > of 'align' and mentioning the two options in its doc string, as well
>> > as expanding the doc strings of those two options, would give us the
>> > same benefits without the downsides (extra *.texi file, a larger
>> > manual, etc.)
>> >
>> > WDYT?
>>
>> Thanks for taking a look.  I think that documenting `M-x align` in the
>> manual has some benefits that aren't completely covered by enhancing
>> docstrings.  Namely, you can link to the Info from other manuals, such
>> as manuals of packages that extend/integrate with `align.el`.  I also
>> think it helps with discoverability.  (For instance, you can skim the
>> manual online even without using Emacs.)
>>
>> How would you feel about a new section in indent.texi instead of a new
>> .texi file?
>
> That's better.

Alright, I'm attaching an updated patch below.

> But the text should be more than just mentioning a couple of
> variables, or else addition to the manual is not justified.

In this v2 patch I've also described `M-x align-current`
and `M-x align-entire`.  Are there any further details that should be
mentioned?

I think that documentation in the manual provides a more authoritative
answer for users to the question "how do you do alignment with Emacs?"
than the docstrings of `M-x align` and friends can, since those
docstrings mostly concern with their respective commands and variables.
This can also point you to `M-x align` in the first place.  Also, as I
mentioned above, describing this command in the manual allows other
manuals to link to this description instead of having to describe it
themselves.  The AUCTeX manual, for example, mentions `align-current`
without providing a relevant reference.

> The basic question to ask yourself is: are the doc strings in align.el
> enough to allow users to use this feature, or will they need some
> "glue" and auxiliary explanations that provide a clearer picture?  If
> the latter is needed, that's the stuff to put in the manual.

Basically, ISTM that this feature is important enough to be mentioned in
the manual, regardless of the clarity of the docstrings in align.el.
Many commands in Emacs have perfectly clear docstrings that give you the
full picture, but that doesn't preclude them from being documented in
the manual.  I don't find that redundant because I think the manual
serves a somewhat different purpose (with some different upsides that I
mentioned above).  Does that make sense?


Anyhow, here's the updated patch:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v2-0001-Document-M-x-align-in-the-Emacs-manual.patch --]
[-- Type: text/x-patch, Size: 4527 bytes --]

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

bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

[Eli Zaretskii]

> From: Eshel Yaron <me@eshelyaron.com>
> Cc: 66303@debbugs.gnu.org
> Date: Thu, 05 Oct 2023 12:46:24 +0200
> 
> > But the text should be more than just mentioning a couple of
> > variables, or else addition to the manual is not justified.
> 
> In this v2 patch I've also described `M-x align-current`
> and `M-x align-entire`.  Are there any further details that should be
> mentioned?

I think we need more, see below.

> I think that documentation in the manual provides a more authoritative
> answer for users to the question "how do you do alignment with Emacs?"
> than the docstrings of `M-x align` and friends can, since those
> docstrings mostly concern with their respective commands and variables.

That is not the correct view, IMO.  Both the doc strings and the
manual are equally "authoritative".  It's just that the doc strings
have a narrow focus and scope, whereas the manual can easily present a
more general view.

> This can also point you to `M-x align` in the first place.  Also, as I
> mentioned above, describing this command in the manual allows other
> manuals to link to this description instead of having to describe it
> themselves.  The AUCTeX manual, for example, mentions `align-current`
> without providing a relevant reference.

That's not our problem, quite bluntly.  Let the authors of those other
manuals get their act together and provide whatever missing
information we don't provide.  They should not expect us to document
everything they need for the purposes of the use of their packages.

> > The basic question to ask yourself is: are the doc strings in align.el
> > enough to allow users to use this feature, or will they need some
> > "glue" and auxiliary explanations that provide a clearer picture?  If
> > the latter is needed, that's the stuff to put in the manual.
> 
> Basically, ISTM that this feature is important enough to be mentioned in
> the manual, regardless of the clarity of the docstrings in align.el.

That's not what I said, and not how we consider the issue of
documenting features in the manual.  Once again, the doc strings and
the apropos commands are an integral part of the Emacs documentation
system, so not every important command or function or variable must be
in the manuals.

> Many commands in Emacs have perfectly clear docstrings that give you the
> full picture, but that doesn't preclude them from being documented in
> the manual.  I don't find that redundant because I think the manual
> serves a somewhat different purpose (with some different upsides that I
> mentioned above).  Does that make sense?

Your views are different from the project's views in this matter.  We
look at this differently.

> Anyhow, here's the updated patch:

Thanks, some comments below.

> +@node Alignment
> +@section Alignment
> +@cindex alignment

The section and the index entry, and possibly also the node, should be
"Code Alignment" or maybe "Source Code Alignment", not just
"Alignment", which is too general/generic.

> +  @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.

I think this should say "lines in the region", rather than just
"series of lines", since the commands work on the region.

>          This is usually done to enhance readability of a piece of
> +text or code.

Passive tense alert!

>                   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:

You want @outdent before the last line, and maybe also start it from a
non-capital letter (as it is a continuation of the previous sentence).

> +  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.

Saying this without documenting align-rules-list makes the manual much
less useful, IMO.

> +@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.

And here, I would at least mention align-region-separate.

>                               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

This should probably be followed by advice to try "M-x align" first,
and if that doesn't produce the desirable result, follow up with C-/
and "C-u M-x align", right?  Otherwise the above text looks incomplete
to me.

> +@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.

This should define "section", and tell something about how to identify
where the point's section begins and ends.  Probably related to the
description of align-region-separate above.

>                                             @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.

An example of how the results are different is in order here, I think.

> +@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}.

We usually document in the manual the default value of each option.

> +@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.

This is incomplete without describing the default value of the option.

Should we also document align-highlight-rule, together with when it is
useful?

Thanks.

bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 7997 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Eshel Yaron <me@eshelyaron.com>
>> Cc: 66303@debbugs.gnu.org
>> Date: Thu, 05 Oct 2023 12:46:24 +0200
>>
>> In this v2 patch I've also described `M-x align-current`
>> and `M-x align-entire`.  Are there any further details that should be
>> mentioned?
>
> I think we need more, see below.
>

Thanks, I'm attaching an updated patch (v3) following your comments.

>> I think that documentation in the manual provides a more authoritative
>> answer for users to the question "how do you do alignment with Emacs?"
>> than the docstrings of `M-x align` and friends can, since those
>> docstrings mostly concern with their respective commands and variables.
>
> That is not the correct view, IMO.  Both the doc strings and the
> manual are equally "authoritative".  It's just that the doc strings
> have a narrow focus and scope, whereas the manual can easily present a
> more general view.
>
>> This can also point you to `M-x align` in the first place.  Also, as I
>> mentioned above, describing this command in the manual allows other
>> manuals to link to this description instead of having to describe it
>> themselves.  The AUCTeX manual, for example, mentions `align-current`
>> without providing a relevant reference.
>
> That's not our problem, quite bluntly.  Let the authors of those other
> manuals get their act together and provide whatever missing
> information we don't provide.  They should not expect us to document
> everything they need for the purposes of the use of their packages.
>
>> > The basic question to ask yourself is: are the doc strings in align.el
>> > enough to allow users to use this feature, or will they need some
>> > "glue" and auxiliary explanations that provide a clearer picture?  If
>> > the latter is needed, that's the stuff to put in the manual.
>>
>> Basically, ISTM that this feature is important enough to be mentioned in
>> the manual, regardless of the clarity of the docstrings in align.el.
>
> That's not what I said, and not how we consider the issue of
> documenting features in the manual.  Once again, the doc strings and
> the apropos commands are an integral part of the Emacs documentation
> system, so not every important command or function or variable must be
> in the manuals.
>
>> Many commands in Emacs have perfectly clear docstrings that give you the
>> full picture, but that doesn't preclude them from being documented in
>> the manual.  I don't find that redundant because I think the manual
>> serves a somewhat different purpose (with some different upsides that I
>> mentioned above).  Does that make sense?
>
> Your views are different from the project's views in this matter.  We
> look at this differently.
>

So it seems.  That's fine, of course.

>> Anyhow, here's the updated patch:
>
> Thanks, some comments below.
>

Thanks.

>> +@node Alignment
>> +@section Alignment
>> +@cindex alignment
>
> The section and the index entry, and possibly also the node, should be
> "Code Alignment" or maybe "Source Code Alignment", not just
> "Alignment", which is too general/generic.
>

Alright, updated to "Code 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.
>
> I think this should say "lines in the region", rather than just
> "series of lines", since the commands work on the region.
>

Done.

>>          This is usually done to enhance readability of a piece of
>> +text or code.
>
> Passive tense alert!
>

Updated.

>>                   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:
>
> You want @outdent before the last line, and maybe also start it from a
> non-capital letter (as it is a continuation of the previous sentence).
>

Thanks, I've added @noindent.

>> +  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.
>
> Saying this without documenting align-rules-list makes the manual much
> less useful, IMO.
>

Yes, I wasn't really sure about documenting `align-rules-list` here,
I've now added a description in the updated patch.

>> +@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.
>
> And here, I would at least mention align-region-separate.
>

Done.

>>                               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
>
> This should probably be followed by advice to try "M-x align" first,
> and if that doesn't produce the desirable result, follow up with C-/
> and "C-u M-x align", right?  Otherwise the above text looks incomplete
> to me.
>

Sure, that makes sense.  I've added some words along these lines.

>> +@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.
>
> This should define "section", and tell something about how to identify
> where the point's section begins and ends.  Probably related to the
> description of align-region-separate above.
>

Alright, I've elaborated about "sections", mostly in the description of
`align-region-separate`.

>>                                             @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.
>
> An example of how the results are different is in order here, I think.
>

Done.

>> +@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}.
>
> We usually document in the manual the default value of each option.
>

Alright, I've mentioned the default value in the updated patch.

>> +@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.
>
> This is incomplete without describing the default value of the option.
>

Updated with an explanation of the default value.

> Should we also document align-highlight-rule, together with when it is
> useful?

Sure, in the updated patch I've described `align-highlight-rule` and
`align-unhighlight-rule`.  I've also documented `align-regexp` and
`align-default-spacing`.

New patch:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v3-0001-Document-M-x-align-in-the-Emacs-manual.patch --]
[-- Type: text/x-patch, Size: 11913 bytes --]

From 92bf5e98a119d72de9f7b3b06db0d209bed33b26 Mon Sep 17 00:00:00 2001
From: Eshel Yaron <me@eshelyaron.com>
Date: Mon, 2 Oct 2023 10:02:46 +0200
Subject: [PATCH v3] 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 | 230 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 231 insertions(+)

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index f9096557c24..da9696dfa4b 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -594,6 +594,7 @@ Top
 * Tab Stops::             Stop points for indentation in Text modes.
 * Just Spaces::           Using only space characters for indentation.
 * Indent Convenience::    Optional indentation features.
+* Code 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..4d149c903c2 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.
+* Code Alignment::        Making common parts of lines start at the same column.
 @end menu
 
 @node Indentation Commands
@@ -265,3 +266,232 @@ 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 Code Alignment
+@section Code Alignment
+@cindex code alignment
+@cindex aligning code
+
+  @dfn{Alignment} is the process of adjusting whitespace in a sequence
+of lines in the region such that in all lines certain parts begin at
+the same column.  This is usually something you do 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
+
+@noindent
+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.
+
+@vindex align-rules-list
+@vindex align-mode-rules-list
+The user option @code{align-rules-list} says which alignment rules
+@kbd{M-x align} should consult.  The value of this option is a list
+with elements describing alignment rules.  Each element is a cons cell
+@code{(@var{title} . @var{attributes})}, where @var{title} is the name
+of the alignment rule as a symbol, and @var{attributes} is a list of
+rule attributes that define when the rule should apply and how it
+partitions and aligns lines.  Each rule attribute is a cons cell
+@code{(@var{attribute} . @var{value})}, where @var{attribute} is the
+name of attribute and @var{value} is its value.  The only required
+attribute is @code{regexp}, whose value is a regular expression with
+sub-expressions matching the parts of each line where @kbd{M-x align}
+should expand or contract whitespace.  See the documentation string of
+@code{align-rules-list} (@kbd{C-h v align-rules-list @key{RET}}) for a
+full description of possible alignment rule attributes.  By default,
+this option is set to a long list of alignment rules for many
+languages that Emacs supports.  The default rules use the @code{modes}
+rule attribute to specify major modes in which @kbd{M-x align} should
+apply them.  Major modes can also override @code{align-rules-list} by
+setting the buffer-local variable @code{align-mode-rules-list} to a
+non-@code{nil} list of alignment rules.  When
+@code{align-mode-rules-list} is non-@code{nil}, @kbd{M-x align}
+consults it instead of @code{align-rules-list}.
+
+@vindex align-exclude-rules-list
+@vindex align-mode-exclude-rules-list
+Besides alignment rules, @kbd{M-x align} uses another kind of rules
+called @dfn{exclusion rules}.  The exclusion rules say which parts in
+the region @kbd{M-x align} should not align and instead leave them
+intact.  The user option @code{align-exclude-rules-list} specifies
+these exclusion rules.  Similarly to @code{align-rules-list}, the
+value of @code{align-exclude-rules-list} is also a list of cons cells
+that describe the exclusion rules.  By default,
+@code{align-exclude-rules-list} includes rules that exclude alignment
+in quoted strings and comments in Lisp, C and other languages.  Beyond
+the default exclusion rules in @code{align-exclude-rules-list}, major
+modes can define bespoke exclusion rules by setting
+@code{align-mode-exclude-rules-list} to a non-@code{nil} list of
+rules, this overrides @code{align-exclude-rules-list} just like
+@code{align-mode-rules-list} overrides @code{align-rules-list}.
+
+@vindex align-region-separate
+@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 all matching alignment rule by expanding or contracting
+stretches of whitespace.  @kbd{M-x align} consistently aligns all
+lines inside a single section, but it may align different sections in
+the region differently.  The user option @code{align-region-separate}
+specifies how @kbd{M-x align} separates the region to sections.  This
+option can be one of the symbols @code{entire}, @code{group}, or a
+regular expression.  If @code{align-region-separate} is @code{entire},
+Emacs aligns the entire region as a single section.  If this option is
+@code{group}, Emacs aligns each group of consecutive non-blank lines
+in the region as a separate section.  If @code{align-region-separate}
+is a regular expression, @kbd{M-x align} scans the region for matches
+to that regular expression and treats them as section separators.  By
+default @code{align-region-separate} is set to a regular expression
+that matches blank lines and lines that contains only whitespace and a
+single curly brace (@samp{@{} or @samp{@}}).  For special cases where
+regular expressions are not accurate enough, you can also set
+@code{align-region-separate} to a function that says how to separate
+the region to alignment sections.  See the documentation string of
+@code{align-region-separate} for more details.  Specific alignment
+rules can override the value of @code{align-region-separate} and
+define their own section separator by specifying the @code{separate}
+rule attribute.
+
+If you call @kbd{M-x align} with a prefix argument (@kbd{C-u}), 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
+
+@noindent
+Typing (@kbd{C-u M-x align}) yields:
+
+@lisp
+(set-face-attribute 'mode-line-inactive nil
+                    :box                nil
+                    :background         nil
+                    :underline          "black")
+@end lisp
+
+In most cases, you should try @kbd{M-x align} without a prefix
+argument first, and if that doesn't produce the right result you can
+undo with @kbd{C-/} and try again with @kbd{C-u M-x align}.
+
+@findex align-highlight-rule
+@findex align-unhighlight-rule
+You can use the command @kbd{M-x align-highlight-rule} to visualize
+the effect of a specific alignment or exclusion rule in the current
+region.  This command prompts you for the title of a rule and
+highlights the parts on the region that this rule affects.  For
+alignment rules, this command highlights the whitespace that @kbd{M-x
+align} would expand or contract, and for exclusion this command
+highlights the parts that @kbd{M-x align} would exclude from
+alignment.  To remove the highlighting that this command creates, type
+@kbd{M-x align-unhighlight-rule}.
+
+@findex align-current
+@findex align-entire
+  The command @kbd{M-x align-current} is similar to @kbd{M-x align},
+except that it operates only on the alignment section that contains
+point regardless of the current region.  This command determines the
+boundaries of the current section according to the section separators
+that @code{align-region-separate} define.  @kbd{M-x align-entire} is
+another variant of @kbd{M-x align}, that disregards
+@code{align-region-separate} and aligns the entire region as a single
+alignment section with consistent alignment.  If you set
+@code{align-region-separate} to @code{entire}, @kbd{M-x align} behaves
+like @kbd{M-x align-entire} by default.  To illustrate the effect of
+aligning the entire region as a single alignment section, consider the
+following code:
+
+@example
+one = 1;
+foobarbaz = 2;
+
+spam = 3;
+emacs = 4;
+@end example
+
+@noindent
+when the region covers all of these lines, typing @kbd{M-x align}
+yields:
+
+@example
+one       = 1;
+foobarbaz = 2;
+
+spam  = 3;
+emacs = 4;
+@end example
+
+@noindent
+On the other hand, @kbd{M-x align-entire} aligns all of the lines as a
+single section, so the @samp{=} appears at the same column in all
+lines:
+
+@example
+one       = 1;
+foobarbaz = 2;
+
+spam      = 3;
+emacs     = 4;
+@end example
+
+@findex align-regexp
+  The command @kbd{M-x align-regexp} lets you align the current region
+with an alignment rule that you define ad-hoc, instead of using the
+predefined rules in @code{align-rules-list}.  @kbd{M-x align-regexp}
+prompts you for a regular expression and uses that expression as the
+@code{regexp} attribute for an ad-hoc alignment rule that this command
+uses to align the current region.  By default, this command adjusts
+the whitespace that matches the first sub-expression of the regular
+expression you specify.  If you call @kbd{M-x align-regexp} with a
+prefix argument, it also prompts you for the sub-expression to use and
+lets you specify the amount of whitespace to use as padding, as well
+as whether to apply the rule repeatedly to all matches of the regular
+expression in each line.
+
+@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}.  By default
+@code{align-indent-before-aligning} is set to @code{nil}.
+
+@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.  By default, this
+option is set to @code{indent-tabs-mode}, so alignment respects tab
+stops in buffers that use tabs for indentation.  @xref{Just Spaces}.
+
+@vindex align-default-spacing
+  The user option @code{align-default-spacing} specifies the default
+amount of whitespace that @kbd{M-x align} and its related commands use
+for padding between the different parts of each line when aligning it.
+When @code{align-to-tab-stop} is @code{nil}, the value of
+@code{align-default-spacing} is the number of spaces to use for
+padding; when @code{align-to-tab-stop} is non-@code{nil}, the value of
+@code{align-default-spacing} is instead the number of tab stops to
+use.  Each alignment rule can override the default that
+@code{align-default-spacing} specifies with the @code{spacing}
+attribute rule.
-- 
2.42.0

bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

[Eli Zaretskii]

> From: Eshel Yaron <me@eshelyaron.com>
> Cc: 66303@debbugs.gnu.org
> Date: Sat, 07 Oct 2023 21:02:19 +0200
> 
> New patch:

Thanks.  I have a couple of minor issues, and then we can install
this:

> +@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.

Whenever you use @dfn, you introduce new terminology.  New terminology
should always be indexed, so that readers could easily find its
description.  So for the above paragraph there should be

  @cindex alignment rules.

> +@vindex align-exclude-rules-list
> +@vindex align-mode-exclude-rules-list
> +Besides alignment rules, @kbd{M-x align} uses another kind of rules
> +called @dfn{exclusion rules}.  The exclusion rules say which parts in
> +the region @kbd{M-x align} should not align and instead leave them
> +intact.  The user option @code{align-exclude-rules-list} specifies

And here we should have

  @cindex align exclusion rules

> +@findex align-regexp
> +  The command @kbd{M-x align-regexp} lets you align the current region
> +with an alignment rule that you define ad-hoc, instead of using the
> +predefined rules in @code{align-rules-list}.  @kbd{M-x align-regexp}
> +prompts you for a regular expression and uses that expression as the
> +@code{regexp} attribute for an ad-hoc alignment rule that this command
> +uses to align the current region.  By default, this command adjusts
> +the whitespace that matches the first sub-expression of the regular
> +expression you specify.  If you call @kbd{M-x align-regexp} with a

Here and elsewhere you mention regexp sub-expressions.  Please add in
those places a cross-reference to where sub-expressions are described
in the manual, since this is an advanced aspect of regexps with which
some readers might not be well acquainted.

bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 2437 bytes --]

Hi Eli,

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Eshel Yaron <me@eshelyaron.com>
>> Cc: 66303@debbugs.gnu.org
>> Date: Sat, 07 Oct 2023 21:02:19 +0200
>>
>> New patch:
>
> Thanks.  I have a couple of minor issues, and then we can install
> this:
>

Great.

>> +@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.
>
> Whenever you use @dfn, you introduce new terminology.  New terminology
> should always be indexed, so that readers could easily find its
> description.  So for the above paragraph there should be
>
>   @cindex alignment rules.
>

Alright, thanks for the explanation, that makes sense.

>> +@vindex align-exclude-rules-list
>> +@vindex align-mode-exclude-rules-list
>> +Besides alignment rules, @kbd{M-x align} uses another kind of rules
>> +called @dfn{exclusion rules}.  The exclusion rules say which parts in
>> +the region @kbd{M-x align} should not align and instead leave them
>> +intact.  The user option @code{align-exclude-rules-list} specifies
>
> And here we should have
>
>   @cindex align exclusion rules
>

Done.

>> +@findex align-regexp
>> +  The command @kbd{M-x align-regexp} lets you align the current region
>> +with an alignment rule that you define ad-hoc, instead of using the
>> +predefined rules in @code{align-rules-list}.  @kbd{M-x align-regexp}
>> +prompts you for a regular expression and uses that expression as the
>> +@code{regexp} attribute for an ad-hoc alignment rule that this command
>> +uses to align the current region.  By default, this command adjusts
>> +the whitespace that matches the first sub-expression of the regular
>> +expression you specify.  If you call @kbd{M-x align-regexp} with a
>
> Here and elsewhere you mention regexp sub-expressions.  Please add in
> those places a cross-reference to where sub-expressions are described
> in the manual, since this is an advanced aspect of regexps with which
> some readers might not be well acquainted.

Sure, I've added cross-references to the "Regular Expressions" node in
the Elisp manual.  Alternatively, we could link to "Regexp Backslash" in
the Emacs manual, if you think that's preferable.

Here's the new patch (v4):


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v4-0001-Document-M-x-align-in-the-Emacs-manual.patch --]
[-- Type: text/x-patch, Size: 12213 bytes --]

From 42de6a2816dc629198ede4b622eb47c6748437bf Mon Sep 17 00:00:00 2001
From: Eshel Yaron <me@eshelyaron.com>
Date: Mon, 2 Oct 2023 10:02:46 +0200
Subject: [PATCH v4] 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 | 236 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 237 insertions(+)

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index f9096557c24..da9696dfa4b 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -594,6 +594,7 @@ Top
 * Tab Stops::             Stop points for indentation in Text modes.
 * Just Spaces::           Using only space characters for indentation.
 * Indent Convenience::    Optional indentation features.
+* Code 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..a3ac5676829 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.
+* Code Alignment::        Making common parts of lines start at the same column.
 @end menu
 
 @node Indentation Commands
@@ -265,3 +266,238 @@ 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 Code Alignment
+@section Code Alignment
+@cindex code alignment
+@cindex aligning code
+
+  @dfn{Alignment} is the process of adjusting whitespace in a sequence
+of lines in the region such that in all lines certain parts begin at
+the same column.  This is usually something you do 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
+
+@noindent
+is commonly aligned to:
+
+@example
+int    a    = 1;
+short  foo  = 2;
+double blah = 4;
+@end example
+
+@cindex alignment rules
+@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.
+
+@vindex align-rules-list
+@vindex align-mode-rules-list
+The user option @code{align-rules-list} says which alignment rules
+@kbd{M-x align} should consult.  The value of this option is a list
+with elements describing alignment rules.  Each element is a cons cell
+@code{(@var{title} . @var{attributes})}, where @var{title} is the name
+of the alignment rule as a symbol, and @var{attributes} is a list of
+rule attributes that define when the rule should apply and how it
+partitions and aligns lines.  Each rule attribute is a cons cell
+@code{(@var{attribute} . @var{value})}, where @var{attribute} is the
+name of attribute and @var{value} is its value.  The only required
+attribute is @code{regexp}, whose value is a regular expression
+(@pxref{Regular Expressions,,,elisp,The Emacs Lisp Reference Manual})
+with sub-expressions matching the parts of each line where @kbd{M-x
+align} should expand or contract whitespace.  See the documentation
+string of @code{align-rules-list} (@kbd{C-h v align-rules-list
+@key{RET}}) for a full description of possible alignment rule
+attributes.  By default, this option is set to a long list of
+alignment rules for many languages that Emacs supports.  The default
+rules use the @code{modes} rule attribute to specify major modes in
+which @kbd{M-x align} should apply them.  Major modes can also
+override @code{align-rules-list} by setting the buffer-local variable
+@code{align-mode-rules-list} to a non-@code{nil} list of alignment
+rules.  When @code{align-mode-rules-list} is non-@code{nil}, @kbd{M-x
+align} consults it instead of @code{align-rules-list}.
+
+@cindex align exclusion rules
+@vindex align-exclude-rules-list
+@vindex align-mode-exclude-rules-list
+Besides alignment rules, @kbd{M-x align} uses another kind of rules
+called @dfn{exclusion rules}.  The exclusion rules say which parts in
+the region @kbd{M-x align} should not align and instead leave them
+intact.  The user option @code{align-exclude-rules-list} specifies
+these exclusion rules.  Similarly to @code{align-rules-list}, the
+value of @code{align-exclude-rules-list} is also a list of cons cells
+that describe the exclusion rules.  By default,
+@code{align-exclude-rules-list} includes rules that exclude alignment
+in quoted strings and comments in Lisp, C and other languages.  Beyond
+the default exclusion rules in @code{align-exclude-rules-list}, major
+modes can define bespoke exclusion rules by setting
+@code{align-mode-exclude-rules-list} to a non-@code{nil} list of
+rules, this overrides @code{align-exclude-rules-list} just like
+@code{align-mode-rules-list} overrides @code{align-rules-list}.
+
+@cindex alignment sections
+@vindex align-region-separate
+@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 all matching alignment rule by expanding or contracting
+stretches of whitespace.  @kbd{M-x align} consistently aligns all
+lines inside a single section, but it may align different sections in
+the region differently.  The user option @code{align-region-separate}
+specifies how @kbd{M-x align} separates the region to sections.  This
+option can be one of the symbols @code{entire}, @code{group}, or a
+regular expression.  If @code{align-region-separate} is @code{entire},
+Emacs aligns the entire region as a single section.  If this option is
+@code{group}, Emacs aligns each group of consecutive non-blank lines
+in the region as a separate section.  If @code{align-region-separate}
+is a regular expression, @kbd{M-x align} scans the region for matches
+to that regular expression and treats them as section separators.  By
+default @code{align-region-separate} is set to a regular expression
+that matches blank lines and lines that contains only whitespace and a
+single curly brace (@samp{@{} or @samp{@}}).  For special cases where
+regular expressions are not accurate enough, you can also set
+@code{align-region-separate} to a function that says how to separate
+the region to alignment sections.  See the documentation string of
+@code{align-region-separate} for more details.  Specific alignment
+rules can override the value of @code{align-region-separate} and
+define their own section separator by specifying the @code{separate}
+rule attribute.
+
+If you call @kbd{M-x align} with a prefix argument (@kbd{C-u}), 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
+
+@noindent
+Typing (@kbd{C-u M-x align}) yields:
+
+@lisp
+(set-face-attribute 'mode-line-inactive nil
+                    :box                nil
+                    :background         nil
+                    :underline          "black")
+@end lisp
+
+In most cases, you should try @kbd{M-x align} without a prefix
+argument first, and if that doesn't produce the right result you can
+undo with @kbd{C-/} and try again with @kbd{C-u M-x align}.
+
+@findex align-highlight-rule
+@findex align-unhighlight-rule
+You can use the command @kbd{M-x align-highlight-rule} to visualize
+the effect of a specific alignment or exclusion rule in the current
+region.  This command prompts you for the title of a rule and
+highlights the parts on the region that this rule affects.  For
+alignment rules, this command highlights the whitespace that @kbd{M-x
+align} would expand or contract, and for exclusion this command
+highlights the parts that @kbd{M-x align} would exclude from
+alignment.  To remove the highlighting that this command creates, type
+@kbd{M-x align-unhighlight-rule}.
+
+@findex align-current
+@findex align-entire
+  The command @kbd{M-x align-current} is similar to @kbd{M-x align},
+except that it operates only on the alignment section that contains
+point regardless of the current region.  This command determines the
+boundaries of the current section according to the section separators
+that @code{align-region-separate} define.  @kbd{M-x align-entire} is
+another variant of @kbd{M-x align}, that disregards
+@code{align-region-separate} and aligns the entire region as a single
+alignment section with consistent alignment.  If you set
+@code{align-region-separate} to @code{entire}, @kbd{M-x align} behaves
+like @kbd{M-x align-entire} by default.  To illustrate the effect of
+aligning the entire region as a single alignment section, consider the
+following code:
+
+@example
+one = 1;
+foobarbaz = 2;
+
+spam = 3;
+emacs = 4;
+@end example
+
+@noindent
+when the region covers all of these lines, typing @kbd{M-x align}
+yields:
+
+@example
+one       = 1;
+foobarbaz = 2;
+
+spam  = 3;
+emacs = 4;
+@end example
+
+@noindent
+On the other hand, @kbd{M-x align-entire} aligns all of the lines as a
+single section, so the @samp{=} appears at the same column in all
+lines:
+
+@example
+one       = 1;
+foobarbaz = 2;
+
+spam      = 3;
+emacs     = 4;
+@end example
+
+@findex align-regexp
+  The command @kbd{M-x align-regexp} lets you align the current region
+with an alignment rule that you define ad-hoc, instead of using the
+predefined rules in @code{align-rules-list}.  @kbd{M-x align-regexp}
+prompts you for a regular expression and uses that expression as the
+@code{regexp} attribute for an ad-hoc alignment rule that this command
+uses to align the current region.  By default, this command adjusts
+the whitespace that matches the first sub-expression of the regular
+expression you specify.  If you call @kbd{M-x align-regexp} with a
+prefix argument, it also prompts you for the sub-expression to use and
+lets you specify the amount of whitespace to use as padding, as well
+as whether to apply the rule repeatedly to all matches of the regular
+expression in each line.  @xref{Regular Expressions,,,elisp,The Emacs
+Lisp Reference Manual}, for more information about regular expressions
+and their sub-expressions.
+
+@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}.  By default
+@code{align-indent-before-aligning} is set to @code{nil}.
+
+@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.  By default, this
+option is set to @code{indent-tabs-mode}, so alignment respects tab
+stops in buffers that use tabs for indentation.  @xref{Just Spaces}.
+
+@vindex align-default-spacing
+  The user option @code{align-default-spacing} specifies the default
+amount of whitespace that @kbd{M-x align} and its related commands use
+for padding between the different parts of each line when aligning it.
+When @code{align-to-tab-stop} is @code{nil}, the value of
+@code{align-default-spacing} is the number of spaces to use for
+padding; when @code{align-to-tab-stop} is non-@code{nil}, the value of
+@code{align-default-spacing} is instead the number of tab stops to
+use.  Each alignment rule can override the default that
+@code{align-default-spacing} specifies with the @code{spacing}
+attribute rule.
-- 
2.42.0

bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

[Eli Zaretskii]

> From: Eshel Yaron <me@eshelyaron.com>
> Cc: 66303@debbugs.gnu.org
> Date: Sat, 14 Oct 2023 12:02:20 +0200
> 
> > Here and elsewhere you mention regexp sub-expressions.  Please add in
> > those places a cross-reference to where sub-expressions are described
> > in the manual, since this is an advanced aspect of regexps with which
> > some readers might not be well acquainted.
> 
> Sure, I've added cross-references to the "Regular Expressions" node in
> the Elisp manual.  Alternatively, we could link to "Regexp Backslash" in
> the Emacs manual, if you think that's preferable.

It is better to cross-reference to the same manual, assuming it does
document the sub-expressions.  Only if it doesn't document them well
enough should we cross-reference to ELisp.

bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

[Eshel Yaron via Bug reports for GNU Emacs, the Swiss army knife of text editors]

[-- Attachment #1: Type: text/plain, Size: 1235 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Eshel Yaron <me@eshelyaron.com>
>> Cc: 66303@debbugs.gnu.org
>> Date: Sat, 14 Oct 2023 12:02:20 +0200
>>
>> > Here and elsewhere you mention regexp sub-expressions.  Please add in
>> > those places a cross-reference to where sub-expressions are described
>> > in the manual, since this is an advanced aspect of regexps with which
>> > some readers might not be well acquainted.
>>
>> Sure, I've added cross-references to the "Regular Expressions" node in
>> the Elisp manual.  Alternatively, we could link to "Regexp Backslash" in
>> the Emacs manual, if you think that's preferable.
>
> It is better to cross-reference to the same manual, assuming it does
> document the sub-expressions.  Only if it doesn't document them well
> enough should we cross-reference to ELisp.

Neither manual documents the concept of sub-expressions in detail
AFAICT, both only describe the relevant syntax.  The text in the Elisp
manual seems a bit more relevant to me, but I can see how sticking to
the Emacs manual may be preferable.  I'm attaching a revised (v5) patch
that refers to "Regexp Backslash" in the Emacs manual instead.  I've
also added a reference to this bug number in the commit message:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v5-0001-Document-M-x-align-in-the-Emacs-manual.patch --]
[-- Type: text/x-patch, Size: 12137 bytes --]

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

* doc/emacs/indent.texi (Alignment): New section.
* doc/emacs/emacs.texi: Update menu. (Bug#66303)
---
 doc/emacs/emacs.texi  |   1 +
 doc/emacs/indent.texi | 234 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 235 insertions(+)

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index f9096557c24..da9696dfa4b 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -594,6 +594,7 @@ Top
 * Tab Stops::             Stop points for indentation in Text modes.
 * Just Spaces::           Using only space characters for indentation.
 * Indent Convenience::    Optional indentation features.
+* Code 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..0df973c1dd0 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.
+* Code Alignment::        Making common parts of lines start at the same column.
 @end menu
 
 @node Indentation Commands
@@ -265,3 +266,236 @@ 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 Code Alignment
+@section Code Alignment
+@cindex code alignment
+@cindex aligning code
+
+  @dfn{Alignment} is the process of adjusting whitespace in a sequence
+of lines in the region such that in all lines certain parts begin at
+the same column.  This is usually something you do 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
+
+@noindent
+is commonly aligned to:
+
+@example
+int    a    = 1;
+short  foo  = 2;
+double blah = 4;
+@end example
+
+@cindex alignment rules
+@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.
+
+@vindex align-rules-list
+@vindex align-mode-rules-list
+The user option @code{align-rules-list} says which alignment rules
+@kbd{M-x align} should consult.  The value of this option is a list
+with elements describing alignment rules.  Each element is a cons cell
+@code{(@var{title} . @var{attributes})}, where @var{title} is the name
+of the alignment rule as a symbol, and @var{attributes} is a list of
+rule attributes that define when the rule should apply and how it
+partitions and aligns lines.  Each rule attribute is a cons cell
+@code{(@var{attribute} . @var{value})}, where @var{attribute} is the
+name of attribute and @var{value} is its value.  The only required
+attribute is @code{regexp}, whose value is a regular expression with
+sub-expressions matching the parts of each line where @kbd{M-x align}
+should expand or contract whitespace (@pxref{Regexp Backslash}).  See
+the documentation string of @code{align-rules-list} (@kbd{C-h v
+align-rules-list @key{RET}}) for a full description of possible
+alignment rule attributes.  By default, this option is set to a long
+list of alignment rules for many languages that Emacs supports.  The
+default rules use the @code{modes} rule attribute to specify major
+modes in which @kbd{M-x align} should apply them.  Major modes can
+also override @code{align-rules-list} by setting the buffer-local
+variable @code{align-mode-rules-list} to a non-@code{nil} list of
+alignment rules.  When @code{align-mode-rules-list} is non-@code{nil},
+@kbd{M-x align} consults it instead of @code{align-rules-list}.
+
+@cindex align exclusion rules
+@vindex align-exclude-rules-list
+@vindex align-mode-exclude-rules-list
+Besides alignment rules, @kbd{M-x align} uses another kind of rules
+called @dfn{exclusion rules}.  The exclusion rules say which parts in
+the region @kbd{M-x align} should not align and instead leave them
+intact.  The user option @code{align-exclude-rules-list} specifies
+these exclusion rules.  Similarly to @code{align-rules-list}, the
+value of @code{align-exclude-rules-list} is also a list of cons cells
+that describe the exclusion rules.  By default,
+@code{align-exclude-rules-list} includes rules that exclude alignment
+in quoted strings and comments in Lisp, C and other languages.  Beyond
+the default exclusion rules in @code{align-exclude-rules-list}, major
+modes can define bespoke exclusion rules by setting
+@code{align-mode-exclude-rules-list} to a non-@code{nil} list of
+rules, this overrides @code{align-exclude-rules-list} just like
+@code{align-mode-rules-list} overrides @code{align-rules-list}.
+
+@cindex alignment sections
+@vindex align-region-separate
+@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 all matching alignment rule by expanding or contracting
+stretches of whitespace.  @kbd{M-x align} consistently aligns all
+lines inside a single section, but it may align different sections in
+the region differently.  The user option @code{align-region-separate}
+specifies how @kbd{M-x align} separates the region to sections.  This
+option can be one of the symbols @code{entire}, @code{group}, or a
+regular expression.  If @code{align-region-separate} is @code{entire},
+Emacs aligns the entire region as a single section.  If this option is
+@code{group}, Emacs aligns each group of consecutive non-blank lines
+in the region as a separate section.  If @code{align-region-separate}
+is a regular expression, @kbd{M-x align} scans the region for matches
+to that regular expression and treats them as section separators.  By
+default @code{align-region-separate} is set to a regular expression
+that matches blank lines and lines that contains only whitespace and a
+single curly brace (@samp{@{} or @samp{@}}).  For special cases where
+regular expressions are not accurate enough, you can also set
+@code{align-region-separate} to a function that says how to separate
+the region to alignment sections.  See the documentation string of
+@code{align-region-separate} for more details.  Specific alignment
+rules can override the value of @code{align-region-separate} and
+define their own section separator by specifying the @code{separate}
+rule attribute.
+
+If you call @kbd{M-x align} with a prefix argument (@kbd{C-u}), 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
+
+@noindent
+Typing (@kbd{C-u M-x align}) yields:
+
+@lisp
+(set-face-attribute 'mode-line-inactive nil
+                    :box                nil
+                    :background         nil
+                    :underline          "black")
+@end lisp
+
+In most cases, you should try @kbd{M-x align} without a prefix
+argument first, and if that doesn't produce the right result you can
+undo with @kbd{C-/} and try again with @kbd{C-u M-x align}.
+
+@findex align-highlight-rule
+@findex align-unhighlight-rule
+You can use the command @kbd{M-x align-highlight-rule} to visualize
+the effect of a specific alignment or exclusion rule in the current
+region.  This command prompts you for the title of a rule and
+highlights the parts on the region that this rule affects.  For
+alignment rules, this command highlights the whitespace that @kbd{M-x
+align} would expand or contract, and for exclusion this command
+highlights the parts that @kbd{M-x align} would exclude from
+alignment.  To remove the highlighting that this command creates, type
+@kbd{M-x align-unhighlight-rule}.
+
+@findex align-current
+@findex align-entire
+  The command @kbd{M-x align-current} is similar to @kbd{M-x align},
+except that it operates only on the alignment section that contains
+point regardless of the current region.  This command determines the
+boundaries of the current section according to the section separators
+that @code{align-region-separate} define.  @kbd{M-x align-entire} is
+another variant of @kbd{M-x align}, that disregards
+@code{align-region-separate} and aligns the entire region as a single
+alignment section with consistent alignment.  If you set
+@code{align-region-separate} to @code{entire}, @kbd{M-x align} behaves
+like @kbd{M-x align-entire} by default.  To illustrate the effect of
+aligning the entire region as a single alignment section, consider the
+following code:
+
+@example
+one = 1;
+foobarbaz = 2;
+
+spam = 3;
+emacs = 4;
+@end example
+
+@noindent
+when the region covers all of these lines, typing @kbd{M-x align}
+yields:
+
+@example
+one       = 1;
+foobarbaz = 2;
+
+spam  = 3;
+emacs = 4;
+@end example
+
+@noindent
+On the other hand, @kbd{M-x align-entire} aligns all of the lines as a
+single section, so the @samp{=} appears at the same column in all
+lines:
+
+@example
+one       = 1;
+foobarbaz = 2;
+
+spam      = 3;
+emacs     = 4;
+@end example
+
+@findex align-regexp
+  The command @kbd{M-x align-regexp} lets you align the current region
+with an alignment rule that you define ad-hoc, instead of using the
+predefined rules in @code{align-rules-list}.  @kbd{M-x align-regexp}
+prompts you for a regular expression and uses that expression as the
+@code{regexp} attribute for an ad-hoc alignment rule that this command
+uses to align the current region.  By default, this command adjusts
+the whitespace that matches the first sub-expression of the regular
+expression you specify.  If you call @kbd{M-x align-regexp} with a
+prefix argument, it also prompts you for the sub-expression to use and
+lets you specify the amount of whitespace to use as padding, as well
+as whether to apply the rule repeatedly to all matches of the regular
+expression in each line.  @xref{Regexp Backslash}, for more
+information about regular expressions and their sub-expressions.
+
+@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}.  By default
+@code{align-indent-before-aligning} is set to @code{nil}.
+
+@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.  By default, this
+option is set to @code{indent-tabs-mode}, so alignment respects tab
+stops in buffers that use tabs for indentation.  @xref{Just Spaces}.
+
+@vindex align-default-spacing
+  The user option @code{align-default-spacing} specifies the default
+amount of whitespace that @kbd{M-x align} and its related commands use
+for padding between the different parts of each line when aligning it.
+When @code{align-to-tab-stop} is @code{nil}, the value of
+@code{align-default-spacing} is the number of spaces to use for
+padding; when @code{align-to-tab-stop} is non-@code{nil}, the value of
+@code{align-default-spacing} is instead the number of tab stops to
+use.  Each alignment rule can override the default that
+@code{align-default-spacing} specifies with the @code{spacing}
+attribute rule.
-- 
2.42.0

bug#66303: [PATCH] Document 'M-x align' in the Emacs manual

[Eli Zaretskii]

> From: Eshel Yaron <me@eshelyaron.com>
> Cc: 66303@debbugs.gnu.org
> Date: Sat, 14 Oct 2023 12:47:05 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Eshel Yaron <me@eshelyaron.com>
> >> Cc: 66303@debbugs.gnu.org
> >> Date: Sat, 14 Oct 2023 12:02:20 +0200
> >>
> >> > Here and elsewhere you mention regexp sub-expressions.  Please add in
> >> > those places a cross-reference to where sub-expressions are described
> >> > in the manual, since this is an advanced aspect of regexps with which
> >> > some readers might not be well acquainted.
> >>
> >> Sure, I've added cross-references to the "Regular Expressions" node in
> >> the Elisp manual.  Alternatively, we could link to "Regexp Backslash" in
> >> the Emacs manual, if you think that's preferable.
> >
> > It is better to cross-reference to the same manual, assuming it does
> > document the sub-expressions.  Only if it doesn't document them well
> > enough should we cross-reference to ELisp.
> 
> Neither manual documents the concept of sub-expressions in detail
> AFAICT, both only describe the relevant syntax.  The text in the Elisp
> manual seems a bit more relevant to me, but I can see how sticking to
> the Emacs manual may be preferable.  I'm attaching a revised (v5) patch
> that refers to "Regexp Backslash" in the Emacs manual instead.  I've
> also added a reference to this bug number in the commit message:

Thanks, installed on the emacs-29 branch, and closing the bug.