Re: master 270ca8c: Fix internal-lisp-face-attributes to match face.

Re: master 270ca8c: Fix internal-lisp-face-attributes to match face.

[Stephen Berman]

On Sun, 20 Oct 2019 10:46:10 -0400 (EDT) ergus@savannah.gnu.org (Jimmy Aguilar Mena) wrote:

> branch: master
> commit 270ca8c2735cfc7935b9e4d0b770a55138493ef3
> Author: Jimmy Aguilar Mena <spacibba@aol.com>
> Commit: Jimmy Aguilar Mena <spacibba@aol.com>
>
>     Fix internal-lisp-face-attributes to match face.
>
>     * lisp/face-remap.el (internal-lisp-face-attributes): Updated the
                                                            ^^^^^^^

The conventional practice is to use the imperative form of verbs in
commit messages (so here "Update").  (I couldn't find documentation of
this practice -- unlike for doc strings in (info "(elisp) Documentation
Tips") -- but you'll see it in most commit messages.)

>     vector members to match the real member names. (Bug#37806) (Bug#37824)
> ---
>  lisp/face-remap.el | 8 +++++---
>  1 file changed, 5 insertions(+), 3 deletions(-)
>
> diff --git a/lisp/face-remap.el b/lisp/face-remap.el
> index 5cdecb9..f2ff2ec 100644
> --- a/lisp/face-remap.el
> +++ b/lisp/face-remap.el
> @@ -64,12 +64,14 @@
>  ;; Names of face attributes corresponding to lisp face-vector positions.
>  ;; This variable should probably be defined in C code where the actual
>  ;; definitions are available.
> +;; :vector must be always at the end as a guard

I don't think this is true for this vector, since it's only the length
that's used here.  (It is of course true for the enum
LFACE_ATTRIBUTE_INDEX, which internal-lisp-face-attributes is meant to
mirror, even though it doesn't use its content.)

>  ;;
>  (defvar internal-lisp-face-attributes
>    [nil
> -   :family :foundry :swidth :height :weight :slant :underline :inverse
> -   :foreground :background :stipple :overline :strike :box
> -   :font :inherit :fontset :vector])
> +   :family :foundry :width :height :weight :slant :underline
> +   :inverse-video
> +   :foreground :background :stipple :overline :strike-through :box
> +   :font :inherit :fontset :distant-foreground :extend :vector])

For the same reason the attribute names here are not important (that's
why :swidth and :inverse, and the absence of :distant(-foreground),
didn't matter before).  Indeed, I think :swidth was used instead of
:width because the model for internal-lisp-face-attributes was the enum
LFACE_ATTRIBUTE_INDEX, not the Lisp face attribute keywords defined in
xfaces.c.  I think that's also why internal-lisp-face-attributes begins
with nil, so that the indices of the remaining elements match those of
LFACE_ATTRIBUTE_INDEX; for it's use in face-remap.el, that element is
superfluous.

These remarks will probably become irrelevant when you replace
internal-lisp-face-attributes with a vector defined in C in terms of the
attribute keywords in xfaces.c.

Steve Berman

Re: master 270ca8c: Fix internal-lisp-face-attributes to match face.

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Date: Sun, 20 Oct 2019 17:44:06 +0200
> Cc: Jimmy Aguilar Mena <spacibba@aol.com>
> 
> >     * lisp/face-remap.el (internal-lisp-face-attributes): Updated the
>                                                             ^^^^^^^
> 
> The conventional practice is to use the imperative form of verbs in
> commit messages (so here "Update").  (I couldn't find documentation of
> this practice

Because there's nothing wrong with "Updated", IMO.  You will find, for
example, "Function removed" and the likes in the logs.

Re: master 270ca8c: Fix internal-lisp-face-attributes to match face.

[Stefan Monnier]

>> >     * lisp/face-remap.el (internal-lisp-face-attributes): Updated the
>>                                                             ^^^^^^^
>> The conventional practice is to use the imperative form of verbs in
>> commit messages (so here "Update").

Indeed.  The comment should describe what the change does rather than
what it did.

>> (I couldn't find documentation of this practice

It comes from the GNU Coding Standards
(https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs),
where it's not described in the text but can be seen in the example.

> Because there's nothing wrong with "Updated", IMO.

It's less consistent with the rest of our changelogs, and it wastes
a precious byte (and sometimes an even more precious column).

> You will find, for example, "Function removed" and the likes in
> the logs.

That's a passive form, and I prefer the active form.

This said, it's clearly much less important than the actual content of
the description.


        Stefan