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

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

[Drew Adams]

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''

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

[Phil Sainty]

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.

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

I would also change "automatically added" to "automatically prefixed".


-Phil



On 2018-11-29 06:26, Drew Adams wrote:
> 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.

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

[Drew Adams]

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

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

[Eli Zaretskii]

> Date: Wed, 28 Nov 2018 15:46:09 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 33541@debbugs.gnu.org
> 
> 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.

I don't see how this doc string could be improved by just discussing
it.  Someone who understands well enough what the feature does should
sit down and prepare more clear and coherent text, and then submit a
patch.  FWIW, I tried and didn't succeed too well.  (Which should not
discourage others from trying, of course.)

TIA

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> I don't see how this doc string could be improved by just discussing
> it.  Someone who understands well enough what the feature does should
> sit down and prepare more clear and coherent text, and then submit a
> patch. 

I've now tried to make the doc string more coherent by emphasising
what's being added interactively, and what REGEXP has to actually
contain in Emacs 28.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Eli Zaretskii]

> Date: Thu, 29 Nov 2018 12:22:18 +1300
> From: Phil Sainty <psainty@orcon.net.nz>
> Cc: 33541@debbugs.gnu.org
> 
> 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.
> 
> 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.)
> 
> I would also change "automatically added" to "automatically prefixed".

Patches to improve that doc string are welcome.