bug#33541: 26; Doc string of `align-regexp'

[Drew Adams <drew.adams@oracle.com>]

These two paragraphs seem to contradict each other:

 There is no predefined rule to handle this, but you could easily do it
 using a REGEXP like "(".  Interactively, all you would have to do is
 to mark the region, call 'align-regexp' and enter that regular expression.

 REGEXP must contain at least one parenthesized subexpression, typically
 whitespace of the form "\\(\\s-*\\)".  In normal interactive use,
 this is automatically added to the start of your regular expression after
 you enter it.  You only need to supply the characters to be lined up, and
 any preceding whitespace is replaced.

It cannot be the case that both (1) all you have to input as regexp is
"(" and (2) the input regexp must contain a group subexpression.

It's also unclear to say that REGEXP must contain... and also say that
something gets added automatically to it.

Yes, it's correct, provided a user interprets "REGEXP" only as the Lisp
argument and not directly as the regexp she enters.  Clearer wording
would be welcome, distinguishing (1) what you have to input (do you need
to include a group subexpression?  even if it is the whitespace prefix
"\\(\\s-*\\)"?) from what is required as the REGEXP argument to the
function.

In particular (minimum fix), it is incorrect to say 'you could easily do
it using a REGEXP like "("'.  There, REGEXP clearly must be the Lisp
argument, not what you type interactively.  REGEXP presumably always
requires a group subexpression.


In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.16299
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''