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" <bug-gnu-emacs@gnu.org>]

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