GNU bug report logs - #54114
26.3; Doc of `face-remap-add-relative' in (elisp) `Face Remapping'

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 54114 in the body.
You can then email your comments to 54114 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: Drew Adams <drew.adams <at> oracle.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 26.3; Doc of `face-remap-add-relative' in (elisp) `Face Remapping'
Date: Tue, 22 Feb 2022 17:22:32 +0000

In this text:

 -- Function: face-remap-add-relative face &rest specs
     This function adds the face spec in SPECS as relative remappings
     for face FACE in the current buffer.  The remaining arguments,
     SPECS, should form either a list of face names, or a property list
     of attribute/value pairs.

please consider removing this: "The remaining arguments,".
This should just say "SPECS should form...".

SPECS and FACE were already introduced in the first sentence.  And the
`&rest' makes clear that SPECS is the remaining args _after argument
FACE_.  Talking about "remaining arguments out of the blue, without
saying they are what come ("remain") _after FACE_, is not
comprehensible.

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.19043
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 54114 <at> debbugs.gnu.org
Subject: Re: bug#54114: 26.3;
 Doc of `face-remap-add-relative' in (elisp) `Face Remapping'
Date: Tue, 22 Feb 2022 19:45:26 +0200

> From: Drew Adams <drew.adams <at> oracle.com>
> Date: Tue, 22 Feb 2022 17:22:32 +0000
> 
> In this text:
> 
>  -- Function: face-remap-add-relative face &rest specs
>      This function adds the face spec in SPECS as relative remappings
>      for face FACE in the current buffer.  The remaining arguments,
>      SPECS, should form either a list of face names, or a property list
>      of attribute/value pairs.
> 
> please consider removing this: "The remaining arguments,".
> This should just say "SPECS should form...".

I don't see any reason to make such a change, FWIW.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "54114 <at> debbugs.gnu.org" <54114 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#54114: 26.3; Doc of
 `face-remap-add-relative' in (elisp) `Face Remapping'
Date: Tue, 22 Feb 2022 18:32:35 +0000

> I don't see any reason to make such a change, FWIW.

English.  That's the reason.  There's no clear
antecedent to "the remaining arguments".  And
SPECS is already identified.
___

This is also poor: "the face spec in SPECS".

Presumably you want to say "each face spec in
SPECS" or "the face specs in SPECS".  The
current text suggests that there's exactly
one face spec in SPECS, in spite of the
plural name.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 54114 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#54114: 26.3; Doc of `face-remap-add-relative' in (elisp)
 `Face Remapping'
Date: Wed, 23 Feb 2022 12:59:25 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

> I don't see any reason to make such a change, FWIW.

The entry seems somewhat hard to parse, so I've now reworded it in the
emacs-28 manual.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Eli Zaretskii <eliz <at> gnu.org>
Cc: "54114 <at> debbugs.gnu.org" <54114 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#54114: 26.3; Doc of
 `face-remap-add-relative' in (elisp) `Face Remapping'
Date: Wed, 23 Feb 2022 16:10:06 +0000

> > I don't see any reason to make such a change, FWIW.
> 
> The entry seems somewhat hard to parse, so I've now reworded it in the
> emacs-28 manual.

Yes, the improvement helps.  Thx.

Previous Next

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