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

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Eshel Yaron <me <at> eshelyaron.com>
Cc: 66303 <at> debbugs.gnu.org
Subject: bug#66303: [PATCH] Document 'M-x align' in the Emacs manual
Date: Sat, 14 Oct 2023 11:00:50 +0300

> From: Eshel Yaron <me <at> eshelyaron.com>
> Cc: 66303 <at> 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:

> +@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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.