GNU bug report logs - #33541
26; Doc string of `align-regexp'

Previous Next

Full log

Message #17 received at 33541 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: psainty <at> orcon.net.nz, 33541 <at> debbugs.gnu.org
Subject: Re: bug#33541: 26; Doc string of `align-regexp'
Date: Thu, 29 Nov 2018 09:25:49 +0200

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

Previous Next

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