Using face names as FACESPEC in font-lock-keywords does not work

[jan . synacek]

Hello!

I have the following piece of code that is supposed to add highlighting 
for CPP-like conditionals in my mode:

(setq-local font-lock-defaults
            (let* ((cpp-rx (rx line-start
                               "#" (or "if" "ifdef" "else" "elif" 
"endif")
                               word-boundary))
                   (keywords
                    `((,cpp-rx . xref-file-header))))
              (list keywords)))

This piece of code does not work and does not use the 'xref-file-header' 
face.


In the Elisp manual (24.6.2 Search-based Fontification) it says:
"
  -- Variable: font-lock-keywords
  ...

...
Each element of ‘font-lock-keywords’ should have one of these forms:
...
‘(MATCHER . FACESPEC)’
     In this kind of element, FACESPEC is an expression whose value
     specifies the face to use for highlighting.  In the simplest case,
     FACESPEC is a Lisp variable (a symbol) whose value is a face name.
...
"

I find the language here quite confusing. 'xref-file-header' is a symbol 
that evaluates to itself, which also happens to be the face name, and is 
technically an expression. But apparently, that's not enough, as it 
seems that the symbol itself has to have a value cell in this particular 
case.

Also, in 40.12.2 Defining Faces, it says:
"
   People are sometimes tempted to create a variable whose value is a
face name.  In the vast majority of cases, this is not necessary; the
usual procedure is to define a face with ‘defface’, and then use its
name directly.
"

This piece of documentation doesn't really help, too. It seems that my 
case is exactly the minority case where it's actually needed. Using 
faces like 'font-lock-string-face' works, because they are defined 
exactly as the documentation says is not necessary. And evaluating 
"(defvar xref-file-header 'xref-file-header)" fixes the highlighting, 
too.

So my question is: Am I doing something wrong? Or does this case 
(setting font-lock-keywords) really
require a variable which holds the face name instead of using the face 
name directly?

In any case, I think that the documentation deserves a bit of 
sharpening.

Regards,
Jan Synáček