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

[Eshel Yaron]

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

v4-0001-Document-M-x-align-in-the-Emacs-manual.patch
Description: Text Data