Subject: bug#18281: 24.4.50; doc of `customize-apropos*'

From: Drew Adams <[email-masked]>
Date: Sat, 16 Aug 2014 11:11:05 -0700 (PDT)

This applies to `customize-apropos' and its related commands.

1. The doc is not clear wrt what happens when you provide a list of
"words" as the input, instead of a regexp.

It is very easily to misunderstand the inadequate description as saying
that the words you enter are matched, not together sequentially against
a single customize target, but individually against multiple customize
targets.

This is all the more true, since this command has as its aim to match
any number of targets: it constructs a Customize buffer for all targets
matched.

Both the doc at (emacs) `Specific Customization' and the doc string are
defective (misleading and incomplete) in this regard.

The doc should say something like this:

 If you provide a list of words then all possible pairs of the words are
 matched together, in both orders, against the name of each Customize
 object of TYPE.  That is, the object name must contain both words as
 sbubstrings.

2. The doc should also say that in this context a "word" is any string
of characters that does not contain special regexp constructs.  That is,
the string is the same as `regexp-quote' applied to the string.  This
lets users know that the "words" can contain more than word-constituent
chars.

In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-06-28 on ODIEONE
Bzr revision: 117431 [email-masked]
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/snapshot/trunk
 --enable-checking=yes,glyphs 'CFLAGS=-O0 -g3'
 LDFLAGS=-Lc:/Devel/emacs/lib 'CPPFLAGS=-DGC_MCHECK=1
 -Ic:/Devel/emacs/include''