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

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

[Drew Adams]

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''

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@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.

bug#54114: [External] : Re: bug#54114: 26.3; Doc of `face-remap-add-relative' in (elisp) `Face Remapping'

[Drew Adams]

> 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.

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

[Lars Ingebrigtsen]

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

bug#54114: [External] : Re: bug#54114: 26.3; Doc of `face-remap-add-relative' in (elisp) `Face Remapping'

[Drew Adams]

> > 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.