Elisp manual: Note that created faces cannot be removed.

Elisp manual: Note that created faces cannot be removed.

[Alan Mackenzie]

Hello, Emacs.

It transpires that once a face has been created by defface, it cannot
then be removed.  This is not mentioned in the Elisp manual, despite this
non removeability being exceptionally rare in Emacs.

So I propose the following patch, which is surely(?) uncontroversial:


diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 276d60b21a..22b7eb0bd1 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2476,6 +2476,9 @@ Defining Faces
 usual procedure is to define a face with @code{defface}, and then use
 its name directly.
 
+Note that once you have defined a face with @code{defface}, you cannot
+later remove this face except by restarting Emacs.
+
 @defmac defface face spec doc [keyword value]@dots{}
 This macro declares @var{face} as a named face whose default face spec
 is given by @var{spec}.  You should not quote the symbol @var{face},


.  Is it too late to push this patch to Emacs 26, or does the rule about
documentation changes being OK still hold?

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Elisp manual: Note that created faces cannot be removed.

[Eli Zaretskii]

> Date: Sat, 20 Jul 2019 18:37:15 +0000
> From: Alan Mackenzie <acm@muc.de>
> 
> So I propose the following patch, which is surely(?) uncontroversial:
> 
> 
> diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
> index 276d60b21a..22b7eb0bd1 100644
> --- a/doc/lispref/display.texi
> +++ b/doc/lispref/display.texi
> @@ -2476,6 +2476,9 @@ Defining Faces
>  usual procedure is to define a face with @code{defface}, and then use
>  its name directly.
>  
> +Note that once you have defined a face with @code{defface}, you cannot
> +later remove this face except by restarting Emacs.

I think without some index entries leading to it, this sentence will
be lost in the ocean of the information in the manual.

Re: Elisp manual: Note that created faces cannot be removed.

[Eli Zaretskii]

> Date: Sat, 20 Jul 2019 21:39:31 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: emacs-devel@gnu.org
> 
> > +Note that once you have defined a face with @code{defface}, you cannot
> > +later remove this face except by restarting Emacs.
> 
> I think without some index entries leading to it, this sentence will
> be lost in the ocean of the information in the manual.

Also, defface is not the only way of defining a face, unlike what the
proposed text seems to imply.

Re: Elisp manual: Note that created faces cannot be removed.

[Alan Mackenzie]

Hello, Eli.

On Sat, Jul 20, 2019 at 21:41:20 +0300, Eli Zaretskii wrote:
> > Date: Sat, 20 Jul 2019 21:39:31 +0300
> > From: Eli Zaretskii <eliz@gnu.org>
> > Cc: emacs-devel@gnu.org

> > > +Note that once you have defined a face with @code{defface}, you cannot
> > > +later remove this face except by restarting Emacs.

> > I think without some index entries leading to it, this sentence will
> > be lost in the ocean of the information in the manual.

Well, this page was the first one I scanned whilst seeking a remove-face
function.

> Also, defface is not the only way of defining a face, unlike what the
> proposed text seems to imply.

OK.  How about this slightly amended patch?



diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 276d60b21a..4ae0bba723 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2476,6 +2476,10 @@ Defining Faces
 usual procedure is to define a face with @code{defface}, and then use
 its name directly.
 
+@cindex face (non-removability of)
+Note that once you have defined a face (usually with @code{defface}),
+you cannot later remove this face except by restarting Emacs.
+
 @defmac defface face spec doc [keyword value]@dots{}
 This macro declares @var{face} as a named face whose default face spec
 is given by @var{spec}.  You should not quote the symbol @var{face},


-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Elisp manual: Note that created faces cannot be removed.

[Eli Zaretskii]

> Date: Sat, 20 Jul 2019 20:26:08 +0000
> Cc: emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > > I think without some index entries leading to it, this sentence will
> > > be lost in the ocean of the information in the manual.
> 
> Well, this page was the first one I scanned whilst seeking a remove-face
> function.
> 
> > Also, defface is not the only way of defining a face, unlike what the
> > proposed text seems to imply.
> 
> OK.  How about this slightly amended patch?

Fine with me, thanks.

Re: Elisp manual: Note that created faces cannot be removed.

[Alan Mackenzie]

Hello, Eli.

On Sun, Jul 21, 2019 at 05:28:33 +0300, Eli Zaretskii wrote:
> > Date: Sat, 20 Jul 2019 20:26:08 +0000
> > Cc: emacs-devel@gnu.org
> > From: Alan Mackenzie <acm@muc.de>

> > > > I think without some index entries leading to it, this sentence will
> > > > be lost in the ocean of the information in the manual.

> > Well, this page was the first one I scanned whilst seeking a remove-face
> > function.

> > > Also, defface is not the only way of defining a face, unlike what the
> > > proposed text seems to imply.

> > OK.  How about this slightly amended patch?

> Fine with me, thanks.

Sorry to go on about this (trivial) point, but I'm not happy about my
proposed text any more.  With the mechanism pointed out by Noam, it
clearly _is_ possible to undefine a face, but it's unsafe.

So, using "undefine" rather than "remove" (suggested to me by private
email), and inserting the word "safely", I now propose this:

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 276d60b21a..4ae0bba723 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2476,6 +2476,10 @@ Defining Faces
 usual procedure is to define a face with @code{defface}, and then use
 its name directly.

+@cindex face (non-removability of)
+Note that once you have defined a face (usually with @code{defface}),
+you cannot later undefine this face safely, except by restarting Emacs.
+
 @defmac defface face spec doc [keyword value]@dots{}
 This macro declares @var{face} as a named face whose default face spec
 is given by @var{spec}.  You should not quote the symbol @var{face},

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Elisp manual: Note that created faces cannot be removed.

[Eli Zaretskii]

> Date: Mon, 22 Jul 2019 10:02:09 +0000
> Cc: emacs-devel@gnu.org, Noam Postavsky <npostavs@gmail.com>
> From: Alan Mackenzie <acm@muc.de>
> 
> Sorry to go on about this (trivial) point, but I'm not happy about my
> proposed text any more.  With the mechanism pointed out by Noam, it
> clearly _is_ possible to undefine a face, but it's unsafe.
> 
> So, using "undefine" rather than "remove" (suggested to me by private
> email), and inserting the word "safely", I now propose this:
> 
> diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
> index 276d60b21a..4ae0bba723 100644
> --- a/doc/lispref/display.texi
> +++ b/doc/lispref/display.texi
> @@ -2476,6 +2476,10 @@ Defining Faces
>  usual procedure is to define a face with @code{defface}, and then use
>  its name directly.
> 
> +@cindex face (non-removability of)
> +Note that once you have defined a face (usually with @code{defface}),
> +you cannot later undefine this face safely, except by restarting Emacs.

That's fine with me, but unlike you, I don't really see a difference:
for the reader of the ELisp manual "cannot undefine safely" and
"cannot remove" are identical for all practical purposes.  Moreover,
"undefine a face" is not really well-defined.

Re: Elisp manual: Note that created faces cannot be removed.

[Alan Mackenzie]

Hello, Eli.

On Mon, Jul 22, 2019 at 17:33:40 +0300, Eli Zaretskii wrote:
> > Date: Mon, 22 Jul 2019 10:02:09 +0000
> > Cc: emacs-devel@gnu.org, Noam Postavsky <npostavs@gmail.com>
> > From: Alan Mackenzie <acm@muc.de>

> > Sorry to go on about this (trivial) point, but I'm not happy about my
> > proposed text any more.  With the mechanism pointed out by Noam, it
> > clearly _is_ possible to undefine a face, but it's unsafe.

> > So, using "undefine" rather than "remove" (suggested to me by private
> > email), and inserting the word "safely", I now propose this:

> > diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
> > index 276d60b21a..4ae0bba723 100644
> > --- a/doc/lispref/display.texi
> > +++ b/doc/lispref/display.texi
> > @@ -2476,6 +2476,10 @@ Defining Faces
> >  usual procedure is to define a face with @code{defface}, and then use
> >  its name directly.

> > +@cindex face (non-removability of)
> > +Note that once you have defined a face (usually with @code{defface}),
> > +you cannot later undefine this face safely, except by restarting Emacs.

> That's fine with me, but unlike you, I don't really see a difference:
> for the reader of the ELisp manual "cannot undefine safely" and
> "cannot remove" are identical for all practical purposes.  Moreover,
> "undefine a face" is not really well-defined.

Well, I've just committed the change.  Maybe there's only a slight
difference between "cannot remove" and "cannot undefine safely", but
there actually is a difference - the latter is closer to the truth.

"undefine a face" might not be well-defined, but since we can't do it
anyway (at least, not safely), that surely doesn't matter too much.
Stefan has suggested we hack such a facility, but ...  Well somebody
would have to do it, and the benefit of it would not be great.

Anyway, I think we've talked around this enough already, so let's just
close the conversation.  :-)

-- 
Alan Mackenzie (Nuremberg, Germany).