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

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

[Drew Adams]

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'
 

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

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@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