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

From: Gabriel <[email-masked]>
Date: Tue, 15 Nov 2022 19:49:29 -0300

Eli Zaretskii <[email-masked]> 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.

>From 5456fbba9cfd3cd27dfc4db60f0729d7a79578c5 Mon Sep 17 00:00:00 2001
From: Gabriel do Nascimento Ribeiro <[email-masked]>
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

---
Gabriel