Re: read-face-name doc string incorrect

[Richard Stallman]

     > Would you like to check the Lisp Manual files that still need to be
     > checked?

    I find it hard to find much that needs improving.

The main checking that is needed here is accuracy checking.  Is the
information correct?  Have the changes in etc/NEWS made it wrong?
So you need to reread NEWS, then read the text, and check the facts
it states.

Improvements in the writing are also welcome, even though that is not
the main issue.  Your proposed changes are good, except for the second
hunk.  I would modify your first hunk as follows.

    ! @item @code{defer}
    ! This value states that the character's @code{face} property is invalid
      and marks it for deferred fontification.

For better parallelism: "The character's @code{face} property is
invalid and it needs deferred fontification."

      @item @code{t}
    ! The character's @code{face} property, if any, is currently valid.

Clearer would be "The character's @code{face} property value (or
absence of one) is valid..."

The second hunk is very problematical, and the old text is better:

    ! If the value of the @code{help-echo} property is a function that
    ! should return a help string or @code{nil} for none, and which is
    ! called with three arguments, @var{window}, @var{object} and @var{pos}.
    ! The first argument, @var{window} is the window in which the character
    ! is located; the second, @var{object}, is the buffer, overlay or
    ! string associated with the character; and the third, @var{pos}, is
    ! the associated position of the character:

That first sentence is garbled, and the old version is generally
better.

    ! The first argument, @var{window} is the window in which the character
    ! is located; the second, @var{object}, is the buffer, overlay or
    ! string associated with the character;

It is strange to say "window in which the character is located".
Displayed characters are located in buffers, or occasionally strings
that are properties in the buffers.  "Associated with" is a vague
relationship; the old text is much clearer.

      @itemize @bullet{}
      @item
    ! If @var{object} is a buffer, @var{pos} is the position in the buffer.
      @item
      If @var{object} is an overlay, that overlay has a @code{help-echo}
    ! property, and @var{pos} is the position in the overlay's buffer.
      @item
      If @var{object} is a string (an overlay string or a string displayed
      with the @code{display} property), @var{pos} is the position in that
    ! string.
      @end itemize

Those changes are good.