bug#47105: defface docs

bug#47105: defface docs

[Reza Nikoopour]

[-- Attachment #1: Type: text/plain, Size: 1056 bytes --]

Hello,

I've been reading the docs in the emacs manual about defface:

https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Faces.html

I had a question about the following two conventions

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.


You should not quote the symbol face, and it should not end in ‘-face’
> (that would be redundant).


I see both of these conventions in font-lock.el.

https://github.com/emacs-mirror/emacs/blob/master/lisp/font-lock.el#L318-L319
https://github.com/emacs-mirror/emacs/blob/master/lisp/font-lock.el#L1976-L1979

Could the docs be updated to reflect what's happening in font-lock.el?  I'd
be happy to make the contribution, but I don't know the proper way to
suggest an update to the manual.

Alternatively, could it be explained why font-lock.el doesn't follow these
conventions?

Cheers,
Reza

[-- Attachment #2: Type: text/html, Size: 1782 bytes --]

bug#47105: defface docs

[Lars Ingebrigtsen]

Reza Nikoopour <rnikoopour@gmail.com> writes:

> Alternatively, could it be explained why font-lock.el doesn't follow these
> conventions?

Much of font-lock.el was written before the conventions were in place,
and it hasn't been converted to use them because that would be too
disruptive.

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

bug#47105: defface docs

[Eli Zaretskii]

> From: Reza Nikoopour <rnikoopour@gmail.com>
> Date: Fri, 12 Mar 2021 08:53:18 -0800
> 
>  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. 
> 
>  You should not quote the symbol face, and it should not end in ‘-face’ (that would be redundant).
> 
> I see both of these conventions in font-lock.el. 
> 
> https://github.com/emacs-mirror/emacs/blob/master/lisp/font-lock.el#L318-L319
> https://github.com/emacs-mirror/emacs/blob/master/lisp/font-lock.el#L1976-L1979
> 
> Could the docs be updated to reflect what's happening in font-lock.el?  I'd be happy to make the contribution,
> but I don't know the proper way to suggest an update to the manual.
> 
> Alternatively, could it be explained why font-lock.el doesn't follow these conventions?

It's the case of "do as I say, not as I do".  We cannot always follow
our own recommendations for some historical reasons.

bug#47105: defface docs

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> It's the case of "do as I say, not as I do".  We cannot always follow
> our own recommendations for some historical reasons.

So I don't think there's anything to fix here, and I'm closing this bug
report.

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