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

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

[Gabriel]

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

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:

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-flat-button-to-set-face-attribute-docstring.patch --]
[-- Type: text/x-diff, Size: 1045 bytes --]

From fed6c0773f152ff795115b1a6c1a7855b3b99f54 Mon Sep 17 00:00:00 2001
From: Gabriel do Nascimento Ribeiro <gabriel376@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.
 
 `:inverse-video'
 
-- 
2.34.1


[-- Attachment #3: Type: text/plain, Size: 16 bytes --]


---
Gabriel

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

[Stefan Kangas]

Gabriel <gabriel376@hotmail.com> writes:

> From fed6c0773f152ff795115b1a6c1a7855b3b99f54 Mon Sep 17 00:00:00 2001
> From: Gabriel do Nascimento Ribeiro <gabriel376@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"?

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

[Gabriel]

Stefan Kangas <stefankangas@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

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

[Stefan Kangas]

Gabriel <gabriel376@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.

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

[Eli Zaretskii]

> From: Gabriel <gabriel376@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.

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

[Gabriel]

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

Eli Zaretskii <eliz@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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-flat-button-to-set-face-attribute-docstring.patch --]
[-- Type: text/x-diff, Size: 1641 bytes --]

From 5456fbba9cfd3cd27dfc4db60f0729d7a79578c5 Mon Sep 17 00:00:00 2001
From: Gabriel do Nascimento Ribeiro <gabriel376@hotmail.com>
Date: Tue, 15 Nov 2022 19:42:01 -0300
Subject: [PATCH 1/1] Add flat-button to set-face-attribute docstring

* lisp/faces.el (set-face-attribute): Add `flat-button' to COLOR and
  STYLE sections of docstring.
---
 lisp/faces.el | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/lisp/faces.el b/lisp/faces.el
index 09e8110449..5ae1c65a4d 100644
--- a/lisp/faces.el
+++ b/lisp/faces.el
@@ -787,13 +787,12 @@ set-face-attribute
 defaults to 1.  If WIDTH is negative, the absolute value is the width
 of the lines, and draw top/bottom lines inside the characters area,
 not around it.  COLOR is the name of the color to draw in, default is
-the foreground color of the face for simple boxes, and the background
-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.
+the background color of the face for 3D boxes and `flat-button', and
+the foreground color of the face for other 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,
+`flat-button' or omitted, draw a 2D box.
 
 `:inverse-video'
 
-- 
2.34.1


[-- Attachment #3: Type: text/plain, Size: 13 bytes --]


---
Gabriel

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

[Eli Zaretskii]

> From: Gabriel <gabriel376@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.