bug#13686: hi-yellow vs. hi-lock-1

[Drew Adams]

The face name should not reflect any particular face attributes - not, that is,
unless the attributes are somehow made to remain relatively constant (e.g.
always some shade of yellow).

Or if there is only one face for a given feature/library, and there is no more
appropriate name, then it can make sense to name the face after the
feature/library, for purposes of discoverability etc.

The main point is that it makes little sense for a face, which is a variable
thingy (changeable, customizable), to have a name that suggests otherwise, i.e.,
suggests that it has some _particular_, constant quality.

The face name should reflect what the face is for - the kind of highlighting or
whatever that it does.  Is this all we can say about the purpose of this face?

  > The user's goal is to highlight something

That's pretty vague, but at least "highlight" presumably belongs in the name.
(No, not all faces are for highlighting.)  And if you can narrow down the kind
of "something" or the use of the highlghting, then that info too can help.

Presumably, this highlighting of something is hi-lock highlighting.  That
already makes it a specific kind of highlighting.  There is a specific way to
turn it on/off etc.

The manual says that hi-lock-mode highlights text that matches a regexp you
provide.  Is this face used for that highlighting?

If so, and if there is not some other hi-lock face that it could be confused
with, then "hi-lock" in the face name is the best identification of what it is
for: it is the face for hi-lock highlighting.

If hi-lock uses other faces that are not for highlighting, then add "highlight"
to the name.  If hi-lock has multiple faces used for highlighting in essentially
the same way, i.e., there is nothing other than their separateness that
distinguishes them, then yes, "hi-lock-1", "hi-lock-2", etc. are the best names.

IOW, if you cannot be more specific than to say that this is for hi-lock
highlighting, then hi-lock highlighting is what the name should reflect.

It certainly should not reflect the face's particular default attributes,
whether they be underlining, boxing, or a yellow background.

> the user can go through face choices until he or she finds
> a suitable color (if the first one does not satisfy)

By that I guess you mean choosing among the available hi-lock faces, e.g., by
cycling.  Nothing wrong with that.

But the current appearance of each of those faces has nothing to do with the
face names you currently use: "hi-green" etc.  Face `hi-green' might well mean
italic blue text on a pink background and wrapped in a box.

You seem to be arguing that a name like "hi-green" helps the user by suggesting
the appearance (e.g. green background or foreground) s?he will get.  Nothing
could be farther from the truth.  It misleads the user into thinking precisely
that.

If you want to give the user names that describe appearance, then you don't want
faces, which are variable, you want constants - e.g., symbols or strings.

In that case, let users choose a _color name_ for each kind of highlighting that
you make available, and set the color of the face for that highlighting to the
chosen color.  Simple.  The user sees color names as the choices (and all
available color names, not just 5 or 6).

In that case, you need to decide which attribute(s) of the face to use that
color for: foreground, background, underline, box.  Or you need to somehow let
users choose the attribute(s) too.