bug#67713: [PATCH] 30.0.50; Small change to display.texi

bug#67713: [PATCH] 30.0.50; Small change to display.texi

[Arash Esbati]

Hi all,

I'd like to suggest a small change to display.texi where the text
follows the code in line 2725 (line break added for legibility):

  @item @code{(:line-width (@var{vwidth} . @var{hwidth})
               :color @var{color} :style @var{style})}

--8<---------------cut here---------------start------------->8---
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 4dbb4afb20d..2056b8552da 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2735,16 +2735,16 @@ Face Attributes
 single number @var{n} instead of a list, such case is equivalent to
 @code{((abs @var{n}) . @var{n})}.

+The value @var{color} specifies the color to draw with.  The default
+is the background color of the face for 3D boxes and
+@code{flat-button}, and the foreground color of the face for other
+boxes.
+
 The value @var{style} specifies whether to draw a 3D box.  If it is
 @code{released-button}, the box looks like a 3D button that is not
 being pressed.  If it is @code{pressed-button}, the box looks like a
 3D button that is being pressed.  If it is @code{nil},
 @code{flat-button} or omitted, a plain 2D box is used.
-
-The value @var{color} specifies the color to draw with.  The default
-is the background color of the face for 3D boxes and
-@code{flat-button}, and the foreground color of the face for other
-boxes.
 @end table

 @item :inverse-video
--8<---------------cut here---------------end--------------->8---

Best, Arash

bug#67713: [PATCH] 30.0.50; Small change to display.texi

[Eli Zaretskii]

> From: Arash Esbati <arash@gnu.org>
> Date: Fri, 08 Dec 2023 17:03:03 +0100
> 
> I'd like to suggest a small change to display.texi where the text
> follows the code in line 2725 (line break added for legibility):
> 
>   @item @code{(:line-width (@var{vwidth} . @var{hwidth})
>                :color @var{color} :style @var{style})}

Thanks, but why is it so important to follow the order in the @item?

bug#67713: [PATCH] 30.0.50; Small change to display.texi

[Arash Esbati]

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks, but why is it so important to follow the order in the @item?

One point (which is minor) is that my brain can parse that information
easier if they are in order.  The major point is that couple of lines
above in display.texi (and also in other places in the manual), the
information is provided in that order:

@item @code{(:color @var{color} :style @var{style} :position @var{position})}
@var{color} is either a string, or the symbol @code{foreground-color},
meaning the foreground color of the face.  Omitting the attribute
@code{:color} means to use the foreground color of the face.
@var{style} should be a symbol @code{line} or @code{wave}, meaning to
use a straight or wavy line.  Omitting the attribute @code{:style}
means to use a straight line.  @var{position}, if non-@code{nil}, means to
display the underline at the descent of the text, instead of at the
baseline level.  If it is a number, then it specifies the amount of
pixels above the descent to display the underline.

But I'm easy, feel free to reject; it is really a minor issue.

Best, Arash

bug#67713: [PATCH] 30.0.50; Small change to display.texi

[Eli Zaretskii]

> From: Arash Esbati <arash@gnu.org>
> Cc: 67713@debbugs.gnu.org
> Date: Fri, 08 Dec 2023 17:43:09 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Thanks, but why is it so important to follow the order in the @item?
> 
> One point (which is minor) is that my brain can parse that information
> easier if they are in order.  The major point is that couple of lines
> above in display.texi (and also in other places in the manual), the
> information is provided in that order:
> 
> @item @code{(:color @var{color} :style @var{style} :position @var{position})}
> @var{color} is either a string, or the symbol @code{foreground-color},
> meaning the foreground color of the face.  Omitting the attribute
> @code{:color} means to use the foreground color of the face.
> @var{style} should be a symbol @code{line} or @code{wave}, meaning to
> use a straight or wavy line.  Omitting the attribute @code{:style}
> means to use a straight line.  @var{position}, if non-@code{nil}, means to
> display the underline at the descent of the text, instead of at the
> baseline level.  If it is a number, then it specifies the amount of
> pixels above the descent to display the underline.
> 
> But I'm easy, feel free to reject; it is really a minor issue.

I installed this on the emacs-29 branch, and I'm closing this bug.

Thanks.

bug#67713: [PATCH] 30.0.50; Small change to display.texi

[Arash Esbati]

Eli Zaretskii <eliz@gnu.org> writes:

> I installed this on the emacs-29 branch, and I'm closing this bug.

Thanks.  Best, Arash