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