GNU bug report logs - #59266
29.0.50; [PATCH] Add flat-button to set-face-attribute docstring

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 59266 in the body.
You can then email your comments to 59266 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Gabriel <gabriel376 <at> hotmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.0.50; [PATCH] Add flat-button to set-face-attribute docstring
Date: Mon, 14 Nov 2022 11:48:23 -0300

[Message part 1 (text/plain, inline)]

Description:
The docstring of `set-face-attribute' does not mention the new
`flat-button' STYLE in BOX section.

See commit 13bd909591e9c1cf0228750b2d4a9e4364f61cc9 and
(info "(elisp)Face Attributes").

Patch:

[0001-Add-flat-button-to-set-face-attribute-docstring.patch (text/x-diff, attachment)]

[Message part 3 (text/plain, inline)]

---
Gabriel

Message #8 received at 59266 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Gabriel <gabriel376 <at> hotmail.com>, 59266 <at> debbugs.gnu.org
Subject: Re: bug#59266: 29.0.50;
 [PATCH] Add flat-button to set-face-attribute docstring
Date: Mon, 14 Nov 2022 20:01:10 -0800

Gabriel <gabriel376 <at> hotmail.com> writes:

> From fed6c0773f152ff795115b1a6c1a7855b3b99f54 Mon Sep 17 00:00:00 2001
> From: Gabriel do Nascimento Ribeiro <gabriel376 <at> hotmail.com>
> Date: Mon, 14 Nov 2022 11:36:59 -0300
> Subject: [PATCH 1/1] Add flat-button to set-face-attribute docstring
>
> * lisp/faces.el (set-face-attribute): Add `flat-button' to STYLE
>   section of docstring.
> ---
>  lisp/faces.el | 5 ++---
>  1 file changed, 2 insertions(+), 3 deletions(-)
>
> diff --git a/lisp/faces.el b/lisp/faces.el
> index 09e8110449..4088f4be8a 100644
> --- a/lisp/faces.el
> +++ b/lisp/faces.el
> @@ -791,9 +791,8 @@ set-face-attribute
>  color of the face for 3D boxes.  STYLE specifies whether a 3D box
>  should be draw.  If STYLE is `released-button', draw a box looking
>  like a released 3D button.  If STYLE is `pressed-button' draw a box
> -that appears like a pressed button.  If STYLE is nil, the default if
> -the property list doesn't contain a style specification, draw a 2D
> -box.
> +that appears like a pressed button.  If STYLE is nil, `flat-button'
> +or omitted, draw a 2D box.

Thanks for the patch.  It copies the text from (info "(elisp)Face
Attributes") and in that sense looks good.  But shouldn't we keep the
part saying that nil is "the default if the property list doesn't
contain a style specification"?

Message #11 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Gabriel <gabriel376 <at> hotmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#59266: 29.0.50; [PATCH] Add flat-button to
 set-face-attribute docstring
Date: Tue, 15 Nov 2022 02:23:14 -0300

Stefan Kangas <stefankangas <at> gmail.com> writes:

> Thanks for the patch.  It copies the text from (info "(elisp)Face
> Attributes") and in that sense looks good.  But shouldn't we keep the
> part saying that nil is "the default if the property list doesn't
> contain a style specification"?

Hi Stefan,

I think the word "omitted" makes it clear that "nil is the default if
the property list doesn't contain a STYLE specification", similar to how
it's phrased in (info "(elisp)Face Attributes"). WDYT?

"[...] If STYLE is nil, `flat-button' or omitted, draw a 2D box."

---
Gabriel

Message #14 received at 59266 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Gabriel <gabriel376 <at> hotmail.com>, 59266 <at> debbugs.gnu.org
Subject: Re: bug#59266: 29.0.50;
 [PATCH] Add flat-button to set-face-attribute docstring
Date: Mon, 14 Nov 2022 22:56:15 -0800

Gabriel <gabriel376 <at> hotmail.com> writes:

>> Thanks for the patch.  It copies the text from (info "(elisp)Face
>> Attributes") and in that sense looks good.  But shouldn't we keep the
>> part saying that nil is "the default if the property list doesn't
>> contain a style specification"?
>
> I think the word "omitted" makes it clear that "nil is the default if
> the property list doesn't contain a STYLE specification", similar to how
> it's phrased in (info "(elisp)Face Attributes"). WDYT?
>
> "[...] If STYLE is nil, `flat-button' or omitted, draw a 2D box."

Ah, right.  Yes, I agree.  I think this could go in, but let's see if
anyone else has any comments first.  Thanks.

Message #17 received at 59266 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Gabriel <gabriel376 <at> hotmail.com>
Cc: 59266 <at> debbugs.gnu.org
Subject: Re: bug#59266: 29.0.50;
 [PATCH] Add flat-button to set-face-attribute docstring
Date: Tue, 15 Nov 2022 14:34:21 +0200

> From: Gabriel <gabriel376 <at> hotmail.com>
> Date: Mon, 14 Nov 2022 11:48:23 -0300
> 
> diff --git a/lisp/faces.el b/lisp/faces.el
> index 09e8110449..4088f4be8a 100644
> --- a/lisp/faces.el
> +++ b/lisp/faces.el
> @@ -791,9 +791,8 @@ set-face-attribute
>  color of the face for 3D boxes.  STYLE specifies whether a 3D box
>  should be draw.  If STYLE is `released-button', draw a box looking
>  like a released 3D button.  If STYLE is `pressed-button' draw a box
> -that appears like a pressed button.  If STYLE is nil, the default if
> -the property list doesn't contain a style specification, draw a 2D
> -box.
> +that appears like a pressed button.  If STYLE is nil, `flat-button'
> +or omitted, draw a 2D box.

Thanks, but can you rephrase so that `flat-button' appeared as one of
the values for STYLE, with an explicit (not implied) description of
what it does?  For example, how does `flat-button' affect what COLOR
does for the button isn't clear from your suggested text.

IOW, what I see in NEWS about this doesn't follow from the text you
propose, at least not easily.

Message #20 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Gabriel <gabriel376 <at> hotmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#59266: 29.0.50; [PATCH] Add flat-button to
 set-face-attribute docstring
Date: Tue, 15 Nov 2022 19:49:29 -0300

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:
>
> Thanks, but can you rephrase so that `flat-button' appeared as one of
> the values for STYLE, with an explicit (not implied) description of
> what it does?  For example, how does `flat-button' affect what COLOR
> does for the button isn't clear from your suggested text.
>
> IOW, what I see in NEWS about this doesn't follow from the text you
> propose, at least not easily.

Hi Eli,

Makes sense, thank you for pointing it out. I took another look at NEWS
and display.texi, and rephrased the docstring to also mention the
flat-button in the COLOR section.

Here is a new patch.

[0001-Add-flat-button-to-set-face-attribute-docstring.patch (text/x-diff, attachment)]

[Message part 3 (text/plain, inline)]

---
Gabriel

Message #25 received at 59266-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Gabriel <gabriel376 <at> hotmail.com>
Cc: 59266-done <at> debbugs.gnu.org
Subject: Re: bug#59266: 29.0.50;
 [PATCH] Add flat-button to set-face-attribute docstring
Date: Wed, 16 Nov 2022 16:45:17 +0200

> From: Gabriel <gabriel376 <at> hotmail.com>
> Date: Tue, 15 Nov 2022 19:49:29 -0300
> 
> Makes sense, thank you for pointing it out. I took another look at NEWS
> and display.texi, and rephrased the docstring to also mention the
> flat-button in the COLOR section.
> 
> Here is a new patch.

Thanks, installed, and closing the bug.

P.S. There were minor issues with the commit log message, in
particular with our quoting style.  Please examine the commit I
actually push and try to follow this example in the future.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.