bug#5105: 23.1; doc string of facemenu-set-face

[Drew Adams]

> Using the name of something isn't as good as using the thing 
> itself, in general.

Depends what you cover by "in general".  In general, it's a _good thing_ when
functions let you use a buffer name in place of a buffer object.

An object is not its name, and no one is arguing the contrary, but referring to
an argument unambiguously by its name is no no-no.

> For buffers it's usually handy to use the name and the buffer
> object itself interchangeably, 

Oh really?  Why is that, do you suppose?

> but I don't see any reason to do the same with faces.

Same reason, _exactly_.  Convenience.
There is nothing special about buffers in this regard.

Yes, you can always do `(get-buffer bname)' to get the buffer object from its
name, just as you can do `(face-name fname)' to get the face object from its
name.

But, as you say, it can be a lot handier not to have to do that each time.  Code
is littered enough with calls to `get-buffer' where the arg might be a string.
Thank goodness (not badness) many functions are reasonable in this regard.

Same exact reasoning holds for faces and their names.  Convenience.

FYI, below is a list of just those vanilla functions that actually declare in
their doc strings that the arg can be a buffer or its name by naming it
explicitly `BUFFER-OR-NAME'.  As you can see, there are quite a few..., and many
of them are very recent additions.  There are no doubt other functions and
macros that accept a buffer name but whose doc strings don't name the parameter
`BUFFER-OR-NAME'.

Why do you suppose so many functions do this?  "Bad programmers" designed them?
A little less hubris, please.

bury-buffer
delete-windows-on 
display-buffer 
display-buffer-normalize-options 
display-buffer-other-frame 
display-buffer-other-window 
display-buffer-same-frame 
display-buffer-same-frame-other-window 
display-buffer-same-window 
get-buffer 
get-buffer-create 
get-buffer-window 
get-buffer-window-list 
kill-buffer 
normalize-buffer-to-display 
normalize-buffer-to-switch-to 
normalize-live-buffer 
pop-to-buffer 
pop-to-buffer-other-frame 
pop-to-buffer-other-window 
pop-to-buffer-same-frame 
pop-to-buffer-same-frame-other-window 
pop-to-buffer-same-window 
replace-buffer-in-windows 
set-buffer 
set-window-buffer 
show-buffer 
switch-to-buffer 
switch-to-buffer-other-frame 
switch-to-buffer-other-window 
switch-to-buffer-same-frame 
with-current-buffer