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

["Drew Adams" <drew.adams@oracle.com>]

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