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

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

[Drew Adams]

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 rgm@gnu.org-20140628015517-eku6hj8mpgcvfnso
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''

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

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

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

I don't know what the doc string said at the time you filed the report
(it would be helpful if you included that in your reports), but
currently it says:

---

Customize loaded options, faces and groups matching PATTERN.
PATTERN can be a word, a list of words (separated by spaces),
or a regexp (using some regexp special characters).  If it is a word,
search for matches for that word as a substring.  If it is a list of
words, search for matches for any two (or more) of those words.

---

That seems quite clear to me, and I'm closing this bug report.

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

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

[Drew Adams]

> >  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 substrings.
> 
> I don't know what the doc string said at the time you filed the report
> (it would be helpful if you included that in your reports),

The build reported is the one the report is about.
(That's why build info is included.)  And yes, that
was 5 years ago...

A guess is that it said the same thing that is said
in Emacs 23.4 - just this:

customize-apropos is an interactive autoloaded Lisp function in
`cus-edit.el'.

It is bound to <menu-bar> <options> <customize> <customize-apropos>.

(customize-apropos REGEXP &optional ALL)

Customize all loaded options, faces and groups matching REGEXP.
If ALL is `options', include only options.
If ALL is `faces', include only faces.
If ALL is `groups', include only groups.
If ALL is t (interactively, with prefix arg), include variables
that are not customizable options, as well as faces and groups
(but we recommend using `apropos-variable' instead).

> but currently it says:
> 
> Customize loaded options, faces and groups matching PATTERN.
> PATTERN can be a word, a list of words (separated by spaces),
> or a regexp (using some regexp special characters).  If it is a word,
> search for matches for that word as a substring.  If it is a list of
> words, search for matches for any two (or more) of those words.

Good.