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

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

> I think the docstring is clear, provided that you read all of it; but
> it could undoubtedly be improved, especially as this is a slightly
> fiddly command to get to grips with.

I don't think so.

> Perhaps your concern could be addressed by tweaking the paragraph
> starting "REGEXP must contain at least one parenthesized subexpression"
> so that it says:
> 
> "Non-interactively, REGEXP must contain at least one parenthesized...."
> 
> (which strictly speaking is perhaps less correct than what it says now,
> yet I think in practice would make things slightly clearer.)

That's in fact worse, as you say.

The argument to the function is REGEXP.  Just what
REGEXP needs to be must be specified accurately.
And what REGEXP needs to be has nothing to do with
whether the function is invoked interactively.

However, in addition to REGEXP needing to be specified
precisely, we need to tell users what they need to
input, to provide arg REGEXP to the function.

Those are two different descriptions.

Usually we describe a command first in terms of
interactive use.  In this case, that means in terms
of describing what you need to input.  Call it a
pattern or whatever, or don't call it anything, but
in any case don't call it REGEXP (the arg name) -
what you input is not arg REGEXP.

We can then say that from your input is constructed
arg REGEXP, which is what is matched against...
And there we can specify both REGEXP and how it is
constructed from your input.

The main problem is conflating arg REGEXP with the
user input, which is a suffix of REGEXP.