bug#35230: char-displayable-p return code is conflictingly documented

[Eli Zaretskii <eliz@gnu.org>]

> From: Robert Pluim <rpluim@gmail.com>
> Date: Thu, 11 Apr 2019 16:49:29 +0200
> 
> (This comes as a result of the stackexchange question at
> https://emacs.stackexchange.com/questions/48810)
> 
> char-displayable-p docstring says
> 
>      Return non-nil if we should be able to display CHAR.
> 
> The elisp manual says something subtly different:
> 
>      This function returns ‘t’ if Emacs ought to be able to display
>      CHAR.  More precisely, if the selected frame’s fontset has a font
>      to display the character set that CHAR belongs to.
> 
> The function itself is more in line with the docstring:

Yes, the manual is wrong and should be fixed.  Non-nil is exactly
right, and callers should not depend on any finer definition of the
return value, as it could be many different non-nil objects.

> (char-displayable-p #xE01EF) => unicode
> 
> since I donʼt have a font with a glyph for that character, so it ends
> up displayed as a box with the unicode code point inside it. The code
> that results in 'unicode has the comment 	     
> 
>     ;; On a text terminal without glyph codes, CHAR is displayable
>     ;; if the coding system for the terminal can encode it.
> 
> but Iʼm very much on a graphical terminal here, not a text terminal.

This is a (known) deficiency in char-displayable-p, but one which is
not easy to fix: no one says that every call to this function asks
about the selected frame, so we cannot unconditionally disable the TTY
branch when on GUI frames.  Perhaps an optional argument could be
added for that purpose, which is the frame for which to make the test.
At least some, if not most, of the calls will still need to omit that
argument, though, because we currently need to know that up front to
set up the quote-style, for example.

Perhaps mentioning this caveat in the manual would be good.

Thanks.