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

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

[Drew Adams]

The doc string should say explicitly what the args are. In particular,
it should say that FACE can be a string or a symbol.
 

In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'
 

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

[Lars Magne Ingebrigtsen]

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

> The doc string should say explicitly what the args are. In particular,
> it should say that FACE can be a string or a symbol.

What does FACE mean if FACE is a string?

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

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

[Drew Adams]

> > The doc string should say explicitly what the args are. In 
> > particular, it should say that FACE can be a string or a symbol.
> 
> What does FACE mean if FACE is a string?

You tell me.  And other users.

The answer is apparently...the face name.
E.g., you can use the symbol `bold' or the string "bold".

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

[Lars Magne Ingebrigtsen]

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

>> > The doc string should say explicitly what the args are. In 
>> > particular, it should say that FACE can be a string or a symbol.
>> 
>> What does FACE mean if FACE is a string?
>
> You tell me.  And other users.
>
> The answer is apparently...the face name.
> E.g., you can use the symbol `bold' or the string "bold".

Then I think it should be left undocumented.  That the command takes a
string sounds like an historical artifact and should not be encouraged.

I'm closing this report.

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

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

[Drew Adams]

> >> > The doc string should say explicitly what the args are. In 
> >> > particular, it should say that FACE can be a string or a symbol.
> >> 
> >> What does FACE mean if FACE is a string?
> >
> > You tell me.  And other users.
> >
> > The answer is apparently...the face name.
> > E.g., you can use the symbol `bold' or the string "bold".
> 
> Then I think it should be left undocumented.  That the command takes a
> string sounds like an historical artifact and should not be 
> encouraged.
> 
> I'm closing this report.

What?  Why are you arbitrarily deciding that?  Why not assume that allowing a
string is a good thing, a purposeful design decision?  What makes you conclude
that this is not something to be encouraged?

We have many places in Emacs where we allow an arg to be either a thing or its
name.  Think of all of the BUFFER args that can be a buffer or a buffer name.

Recently some code has been changed to name such parameters BLAH-OR-NAME instead
of BLAH.  An example is the bookmark.el code.  (I personally think that's a
mistake - the doc string still needs to say that BLAH-OR-NAME can be a BLAH or
its name.)

But the point here is that allowing FACE to be a string is a *feature*, not a
"historical artifact".  There is no reason to lose this feature, and no reason
it should not be documented.

You should not be designing on the fly that way.  This is a doc bug.  The doc
should mention that FACE can be a face or its name.  Nothing new about this.

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

[Stefan Monnier]

> What?  Why are you arbitrarily deciding that?  Why not assume that
> allowing a string is a good thing, a purposeful design decision?

Because a good programmer knows that it's obviously not a good idea to
encourage the caller to use a string here.


        Stefan

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

[Drew Adams]

> > What?  Why are you arbitrarily deciding that?  Why not assume that
> > allowing a string is a good thing, a purposeful design decision?
> 
> Because a good programmer knows that it's obviously not a good idea to
> encourage the caller to use a string here.

It might be obvious to what you call good programmers, but how about giving a
_reason_, for us mere mortals?

And what about all of the other places where we accept a string in place of the
object named by the string?  As I said:

>> We have many places in Emacs where we allow an arg to be
>> either a thing or its name.  Think of all of the BUFFER args
>> that can be a buffer or a buffer name.

What do the "good programmers" say about the design in those cases?  Is it
"obviously not a good idea" also?

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

[Stefan Monnier]

>> > What?  Why are you arbitrarily deciding that?  Why not assume that
>> > allowing a string is a good thing, a purposeful design decision?
>> Because a good programmer knows that it's obviously not a good idea to
>> encourage the caller to use a string here.
> It might be obvious to what you call good programmers, but how about giving a
> _reason_, for us mere mortals?

How 'bout the other way around: give me a reason to accept strings.

>>> We have many places in Emacs where we allow an arg to be
>>> either a thing or its name.  Think of all of the BUFFER args
>>> that can be a buffer or a buffer name.
> What do the "good programmers" say about the design in those cases?  Is it
> "obviously not a good idea" also?

Very often, yes it's also a bad idea.  At least for buffers we have
a guarantee that there is a one-to-one mapping between (live) buffers
and buffer names, so for buffers it's a bit less bad.


        Stefan

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

[Drew Adams]

> >> > What?  Why are you arbitrarily deciding that?  Why not 
> >> > assume that allowing a string is a good thing, a
> >> > purposeful design decision?
> >>
> >> Because a good programmer knows that it's obviously not a 
> >> good idea to encourage the caller to use a string here.
> >
> > It might be obvious to what you call good programmers, but 
> > how about giving a _reason_, for us mere mortals?
> 
> How 'bout the other way around: give me a reason to accept strings.

You're the one claiming that there is a good (even _obvious_) reason not to.
What's the reason, if it's so obvious?

> >>> We have many places in Emacs where we allow an arg to be
> >>> either a thing or its name.  Think of all of the BUFFER args
> >>> that can be a buffer or a buffer name.
> >
> > What do the "good programmers" say about the design in 
> > those cases?  Is it "obviously not a good idea" also?
> 
> Very often, yes it's also a bad idea.

Why?  And when? ("Very often" doesn't say much - how about a specific context
where it is a bad idea, since there are supposedly so many.)

How about a reason or two to back up all the hand-waving claims about "good" and
"bad"?

> At least for buffers we have a guarantee that there is a
> one-to-one mapping between (live) buffers and buffer names,
> so for buffers it's a bit less bad.

"Less bad"?  You haven't said what is bad about it.

And what about faces?  Can a given face have two different names?  We have
`face-name' the same way we have `buffer-name'.  At least there is nothing
documented AFAICT about `face-name' being a relation and not a function.

If F is a face, under what circumstances will (face-name F) give different names
at different times?

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

[Lars Ingebrigtsen]

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

> You're the one claiming that there is a good (even _obvious_) reason not to.
> What's the reason, if it's so obvious?

Using the name of something isn't as good as using the thing itself, in
general.  For buffers it's usually handy to use the name and the buffer
object itself interchangeably, but I don't see any reason to do the same
with faces.

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

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 

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

[Stefan Monnier]

> general.  For buffers it's usually handy to use the name and the buffer
> object itself interchangeably, but I don't see any reason to do the same

Actually, that's also a source of subtle issues.  In Emacs, we sometimes
use the distinction between names and buffers so that M-x
rename-uniquely can be used (together with some other command) to create
a new buffer.
And indeed, the difference between names and buffers is still relevant
when we rename buffers.


        Stefan

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

[Stefan Monnier]

>> How 'bout the other way around: give me a reason to accept strings.
> You're the one claiming that there is a good (even _obvious_) reason not to.
> What's the reason, if it's so obvious?

I'm not here to give software engineering courses, sorry.
But if you want, we can start from the very simplest: choice implies
performance and conceptual costs, so unless it's justified by actual
needs it's bad.
So we're back to "why do you think we should also accept strings?".

> And what about faces?  Can a given face have two different names?  We have

No, but two faces can have the same name.
And there can even be a face which has a unique name and yet `intern'
does not return the corresponding face.


        Stefan

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

[Drew Adams]

> No, but two faces can have the same name.

In the same obarray?

> And there can even be a face which has a unique name and yet `intern'
> does not return the corresponding face.

In the same obarray?

Anyway, a good reason (finally).  And not so obvious.

Faces are symbols, and I agree that it is generally not good to accept a symbol
name in place of a symbol as arg.  I retract the request, based on your
argument.

In practice, 99% of the faces passed as args will be interned in `obarray' (not
in some other obarray), so there is still some argument for the convenience of
accepting a string name.

But to avoid confusion and explicitly documenting which obarray would be used if
a string is passed, I agree with you after all.

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

[Lars Magne Ingebrigtsen]

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

> Anyway, a good reason (finally).  And not so obvious.

Closing this report.

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