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

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

[Robert Pluim]

(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:

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

For comparison, when I do have a font:

(char-displayable-p #x2502) => <font-object
"-*-Menlo-normal-normal-normal-*-12-*-*-*-m-0-iso10646-1">

The question is: what should the docstring/manual say? The original
intent of char-displayable-p seems to be as a wrapper around
internal-char-font to allow asking "do I have a glyph for this
character", but thatʼs not what it does today.

Robert

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

[Eli Zaretskii]

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

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

[Robert Pluim]

>>>>> On Fri, 12 Apr 2019 15:51:48 +0300, Eli Zaretskii <eliz@gnu.org> said:

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

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

That I can do easily enough in emacs-26

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

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

    Eli> Perhaps mentioning this caveat in the manual would be good.

Iʼve made an attempt below. Do we want a cross reference to 'Glyphless
Chars' as well?

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index b07999432c..fac883ae16 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -3507,12 +3507,16 @@ Fontsets
 @end defun
 
 @defun char-displayable-p char
-This function returns @code{t} if Emacs ought to be able to display
-@var{char}.  More precisely, if the selected frame's fontset has a
-font to display the character set that @var{char} belongs to.
+This function returns non-@code{nil} if Emacs ought to be able to
+display @var{char}.  More precisely, if the selected frame's fontset
+has a font to display the character set that @var{char} belongs to.
 
 Fontsets can specify a font on a per-character basis; when the fontset
 does that, this function's value may not be accurate.
+
+This function may return non-@code{nil} even when there is no font
+available, since it also checks if the coding system for the text
+terminal can encode the character.
 @end defun
 
 @node Low-Level Font

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

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: 35230@debbugs.gnu.org
> Date: Sun, 14 Apr 2019 11:51:36 +0200
> 
>  @defun char-displayable-p char
> -This function returns @code{t} if Emacs ought to be able to display
> -@var{char}.  More precisely, if the selected frame's fontset has a
> -font to display the character set that @var{char} belongs to.
> +This function returns non-@code{nil} if Emacs ought to be able to
> +display @var{char}.  More precisely, if the selected frame's fontset
> +has a font to display the character set that @var{char} belongs to.
>  
>  Fontsets can specify a font on a per-character basis; when the fontset
>  does that, this function's value may not be accurate.
> +
> +This function may return non-@code{nil} even when there is no font
> +available, since it also checks if the coding system for the text
> +terminal can encode the character.
>  @end defun

Thanks.  I think we should tell more about the testing of text
terminal capabilities, because otherwise the reference to terminal
encoding comes out of the blue without being mentioned anywhere else,
since the preceding text talks only about fonts and fontsets,
i.e. only about GUI frames.

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

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> +This function may return non-@code{nil} even when there is no font
>> +available, since it also checks if the coding system for the text
>> +terminal can encode the character.
>>  @end defun
>
> Thanks.  I think we should tell more about the testing of text
> terminal capabilities, because otherwise the reference to terminal
> encoding comes out of the blue without being mentioned anywhere else,
> since the preceding text talks only about fonts and fontsets,
> i.e. only about GUI frames.

Robert, this was over a year ago -- the documentation fix is an
improvement, but did you look into also saying some words about text
terminal capabilities?

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

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

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Robert, this was over a year ago -- the documentation fix is an
> improvement, but did you look into also saying some words about text
> terminal capabilities?

I've now applied Robert's patch, and added a reference to the terminal
coding system node.

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