Subject: bug#66303: closed (Re: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual)

From: [email-masked] (GNU bug Tracking System)
Date: Sat, 14 Oct 2023 11:18:02 +0000

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
66303: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=66303
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual
From: Eli Zaretskii <[email-masked]>
To: Eshel Yaron <[email-masked]>
Cc: [email-masked]
Date: Sat, 14 Oct 2023 14:17:10 +0300
List-Id: <debbugs-submit.debbugs.gnu.org>

> From: Eshel Yaron <[email-masked]>
> Cc: [email-masked]
> Date: Sat, 14 Oct 2023 12:47:05 +0200
> 
> Eli Zaretskii <[email-masked]> writes:
> 
> >> From: Eshel Yaron <[email-masked]>
> >> Cc: [email-masked]
> >> 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.

Subject: [PATCH] Document 'M-x align' in the Emacs manual
From: Eshel Yaron <[email-masked]>
To: [email-masked]
Date: Mon, 02 Oct 2023 10:21:58 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

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

>From 20fa3ea348617350fa8a437fad75aa9e9a9a620f Mon Sep 17 00:00:00 2001
From: Eshel Yaron <[email-masked]>
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