Eli Zaretskii <eliz@gnu.org> writes:

>> From: Robert Pluim <rpluim@gmail.com>
>> Date: Fri, 09 Mar 2018 16:53:26 +0100
>> Cc: 30757@debbugs.gnu.org
>> 
>> Here's what I've got so far. Suggestions welcome for wording, style
>> changes, etc.
>
> Thanks.
>
>> --- a/etc/NEWS
>> +++ b/etc/NEWS
>> @@ -71,6 +71,12 @@ moved to the early init file (see above).
>>  
>>  * Changes in Emacs 27.1
>>  
>> ++++
>
> "+++" means this change was documented in the manual(s), but this
> change wasn't, AFAIU.  Shkuld this be documented in the ELisp manual?
>

etc/NEWS says:

  +++ indicates that all necessary documentation updates are complete.
      (This means all relevant manuals in doc/ AND lisp doc-strings.)

I'd looked through the manuals and couldn't see anywhere where I
thought it should be documented, hence I only changed the
doc-string. We can go for '---' in that case.

>> +** Warning types can now be disabled from the warning buffer.
>> +For each warning 'display-warning' now adds buttons to the buffer it
>> +uses to allow permanent suppression of the warning popup or of the
>> +warning itself.
>
> This entry should be made more clear.  "Warning types" is never
> explained, the reference to 'display-warning' is confusing (this is a
> user-level feature, so why mention the function which is involved?),
> it is unclear what buffer is alluded to by "the buffer it uses", and
> the difference between "warning popup" and "warning itself" is left
> unexplained.

I've rewritten it. See attached.

>> +(define-button-type 'warning-suppress-warning
>> +  'action #'warning-suppress-action
>> +  'help-echo "mouse-2, RET: Permanently disable popping up this warning")
>> +(defun warning-suppress-action (button)
>> +  (customize-save-variable 'warning-suppress-types
>> +                           (cons (list (button-get button 'warning-type))
>> +                                 warning-suppress-types)))
>> +(define-button-type 'warning-suppress-log-warning
>> +  'action #'warning-suppress-log-action
>> +  'help-echo "mouse-2, RET: Never generate this warning")
>
> Likewise here: the difference between "disable popping up" and "never
> generate" is unclear.  maybe a different wording will clarify that,
> but I cannot suggest one because frankly I don't understand well
> enough what each one does.

Yes. I'm stuck between being precise but verbose, and more general and
succinct, and expressing the permanence of the resulting change. I've
make another attempt, although I'm still not entirely happy with it,
especially since the button texts are now quite long (I thought about
using the verb 'hide', but that's not accurate either).

Robert