GNU bug report logs - #8287
24.0.50; regexp-builder, rx, sregex: (a) in manuals, (b) in action

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 8287 in the body.
You can then email your comments to 8287 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; regexp-builder, rx, sregex: (a) in manuals, (b) in action
Date: Fri, 18 Mar 2011 11:14:23 -0700

1. Only `re-builder', not `regexp-builder', is indexed in the Elisp
manual.  This is incomplete and backwards - users will look for "regexp"
before "re-" when looking for help with regexps.
 
2. There is no explanation of this command in either manual.  Node
`Regular Expressions' of Elisp just mentions it in passing, with no
help.  It says that the command provides "a convenient interface"
without providing any explanation of that nifty interface or how to use
it.  The Emacs manual doesn't even mention the command.
 
See also bug #8286, about the hopeless doc string.
 
3. There is no real doc for `re-builder' - no help for users, including
after they actually try to use the command.  `C-h m' in buffer
*RE-Builder* simply lists the key bindings.  To understand anything
about this "convenient interface" users will need to drill down from the
list of key bindings and check the doc for each command.  And even then
they will discover nothing of any real help AFAICT.
 
If this is a "builder" with a "convenient interface", then it should
assist users.
 
4. The comments in `re-builder.el' are of some help.  But even there
things are unclear and incomplete.  It refers to "`rx' syntax".  What is
that?  Try to find `rx' in the index of either Emacs manual - nothing.
 
5. Consider mentioning `rx' features in the manuals.  The only mention
is of Gerd's contribution of `rx.el' to Emacs.  Sheesh.
 
6. In the Commentary of `rx.el' we find mention of "the Sregex package
coming with Emacs" and a comparison of rx with sregex.  Again, there is
nothing about sregex in either manual, except for an acknowledgement to
Bob Glickstein for contributing it.  Sheesh.
 
 
 
In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-03-07 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/imagesupport/include'
 

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8287 <at> debbugs.gnu.org
Subject: Re: bug#8287: 24.0.50;
 regexp-builder, rx, sregex: (a) in manuals, (b) in action
Date: Thu, 28 Apr 2016 12:21:56 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> 1. Only `re-builder', not `regexp-builder', is indexed in the Elisp
> manual.  This is incomplete and backwards - users will look for "regexp"
> before "re-" when looking for help with regexps.

There's already a @cindex to "regexp" in the same node, so that seems
unnecessary.

> 2. There is no explanation of this command in either manual.  Node
> `Regular Expressions' of Elisp just mentions it in passing, with no
> help.  It says that the command provides "a convenient interface"
> without providing any explanation of that nifty interface or how to use
> it.  The Emacs manual doesn't even mention the command.

@findex re-builder
@cindex regular expressions, developing
  For interactive development of regular expressions, you
can use the @kbd{M-x re-builder} command.  It provides a convenient
interface for creating regular expressions, by giving immediate visual
feedback in a separate buffer.  As you edit the regexp, all its
matches in the target buffer are highlighted.  Each parenthesized
sub-expression of the regexp is shown in a distinct face, which makes
it easier to verify even very complex regexps.

Looks fine now, at least...

> See also bug #8286, about the hopeless doc string.
>
> 3. There is no real doc for `re-builder' - no help for users, including
> after they actually try to use the command.  `C-h m' in buffer
> *RE-Builder* simply lists the key bindings.  To understand anything
> about this "convenient interface" users will need to drill down from the
> list of key bindings and check the doc for each command.  And even then
> they will discover nothing of any real help AFAICT.

Chong fixed this in 2011, apparently.  Closing.

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

Previous Next

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