completing-read-multiple and read-face-name are not in Elisp manual

completing-read-multiple and read-face-name are not in Elisp manual

[Drew Adams]

(Yes, I realize that not every function needs to be documented in the
manual - please don't bother with such a general reminder.) I think
`completing-read-multiple' and `read-face-name' should be documented.

Is `completing-read-multiple' not in the manual because `crm.el' is somehow
considered optional? `completing-read-multiple' is used in `read-face-name'
(where there is also a `require' of crm).

The doc string of `read-face-name' says nothing about the fact that you can
input and complete multiple face names. And nothing indicates to a user,
when `read-face-name' is called, that s?he can input and complete multiple
names, separating them with a comma. (Sure, a programmer can mention that in
the prompt, but s?he might not, especially since there is no info about this
in the doc string.) The doc string of read-face-name mentions the optional
MULTIPLE argument, but that is only for output, not input.

I find nothing about this behavior described anywhere in the Emacs manual or
the Elisp manual. How will users understand the UI? How will programmers
understand how these functions work (without examining the code in detail)?

Re: completing-read-multiple and read-face-name are not in Elisp manual

[Juri Linkov]

> I find nothing about this behavior described anywhere in the Emacs manual or
> the Elisp manual. How will users understand the UI? How will programmers
> understand how these functions work (without examining the code in detail)?

This is an optional feature that users can encounter only when running
`describe-face' on the face name in the `defface' definition (where one face
gets picked from the face name, and another from the face used to highlight
it by font-lock mode - font-lock-variable-name).

However, this feature could be documented and developed further to e.g.
allowing selecting multiple faces from the *Completions* buffer, inserting
them into the minibuffer separated by a comma, and calling a multi-command
on them.

-- 
Juri Linkov
http://www.jurta.org/emacs/

RE: completing-read-multiple and read-face-name are not in Elisp manual

[Drew Adams]

> > I find nothing about this behavior described anywhere in the
> > Emacs manual or the Elisp manual. How will users understand
> > the UI? How will programmers understand how these functions
> > work (without examining the code in detail)?
>
> This is an optional feature

What is? Do you mean completing multiple face names? My question was more
general. `completing-read-multiple' is presumably not tied to face-name
completion - it too should be documented, IMO.

> that users can encounter only when running
> `describe-face' on the face name in the `defface' definition
> (where one face gets picked from the face name, and another
> from the face used to highlight
> it by font-lock mode - font-lock-variable-name).
>
> However, this feature could be documented and developed further to e.g.
> allowing selecting multiple faces from the *Completions* buffer, inserting
> them into the minibuffer separated by a comma, and calling a multi-command
> on them.

Not sure I understand you well, but I think there is no need to insert the
selected faces in the minibuffer all at once separated by commas. When you
say "calling a multi-command on them", do you mean calling it on each of
them individually or acting on the set of them collectively?

If you're talking about an Icicles multi-command that would act on multiple
faces individually, the way to do that is to define an Icicles
(multi-)command that acts on a single face.

(icicle-define-command my-cmd
  "Do `something' to one or more faces"
  something
  "Choose a face: "
  (mapcar #'icicle-make-face-candidate (face-list))
  (not (wholenump icicle-WYSIWYG-Completions-flag)))

Function `something' is the action function here. Users can apply it to any
number of faces during completion, using `C-RET'.

Or, if you mean to act on a set of chosen faces collectively (as a set, not
individually), then you would call `icicle-face-list' in some function and
act on the list of faces that the user chose:

(icicle-define-command icicle-face-list
  "Choose a list of face names.  The list of names is returned."
  (lambda (name) (push name face-names))
  "Choose face (`RET' when done): "
  (mapcar #'icicle-make-face-candidate (face-list))
  nil t nil 'face-name-history
  nil nil
  ((face-names nil)                     ; Additional bindings
   (icicle-use-candidates-only-once-flag t))
  nil nil                               ; First code, undo code
  (prog1 (setq face-names (delete "" face-names)) ; Return list
   (when (interactive-p) (message "Faces: %S" face-names))))

Commands such as `icicle-face-list' are handy to use as functions in, say,
the interactive spec of other commands. You can, for instance, define a
command that lets users pick a list of faces to act on, and then does
something with that combination (e.g. merge or whatever). Other commands
that return a list of items that a user picks include: `icicle-buffer-list'
and `icicle-file-list'.

Re: completing-read-multiple and read-face-name are not in Elisp manual

[Richard Stallman]

We must restrain the growth of the Lisp manual, and these functions
seem rather obscure.

RE: completing-read-multiple and read-face-name are not in Elisp manual

[Drew Adams]

> We must restrain the growth of the Lisp manual, and these functions
> seem rather obscure.

Your call, of course. I'd say that functions that you use to prompt the user
for input are not obscure and should be documented for Emacs-Lisp
programmers.

Re: completing-read-multiple and read-face-name are not in Elisp manual

[Juri Linkov]

>> This is an optional feature
>
> What is? Do you mean completing multiple face names? My question was more
> general. `completing-read-multiple' is presumably not tied to face-name
> completion - it too should be documented, IMO.

Both are optional so far (completing multiple items in general and
completing multiple face names).

>> However, this feature could be documented and developed further to e.g.
>> allowing selecting multiple faces from the *Completions* buffer, inserting
>> them into the minibuffer separated by a comma, and calling a multi-command
>> on them.
>
> Not sure I understand you well, but I think there is no need to insert the
> selected faces in the minibuffer all at once separated by commas. When you
> say "calling a multi-command on them", do you mean calling it on each of
> them individually or acting on the set of them collectively?

In Dired, after selecting several files, you can run a command once on all
of them when the command contains `*' surrounded by whitespace, and run for
each file when the command doesn't contain it.

In crm, we could use different separators, e.g. to use `,' to call the
action on all completion candidates, and to use `;' as a separator to call
the action on each of them.

-- 
Juri Linkov
http://www.jurta.org/emacs/