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

From: Eli Zaretskii <[email-masked]>
Date: Sat, 14 Oct 2023 11:00:50 +0300

> From: Eshel Yaron <[email-masked]>
> Cc: [email-masked]
> 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.