* bug#35230: char-displayable-p return code is conflictingly documented
@ 2019-04-11 14:49 Robert Pluim
2019-04-12 12:51 ` Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Robert Pluim @ 2019-04-11 14:49 UTC (permalink / raw)
To: 35230
(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
^ permalink raw reply [flat|nested] 6+ messages in thread* bug#35230: char-displayable-p return code is conflictingly documented 2019-04-11 14:49 bug#35230: char-displayable-p return code is conflictingly documented Robert Pluim @ 2019-04-12 12:51 ` Eli Zaretskii 2019-04-14 9:51 ` Robert Pluim 0 siblings, 1 reply; 6+ messages in thread From: Eli Zaretskii @ 2019-04-12 12:51 UTC (permalink / raw) To: Robert Pluim; +Cc: 35230 > 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. ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#35230: char-displayable-p return code is conflictingly documented 2019-04-12 12:51 ` Eli Zaretskii @ 2019-04-14 9:51 ` Robert Pluim 2019-04-14 14:10 ` Eli Zaretskii 0 siblings, 1 reply; 6+ messages in thread From: Robert Pluim @ 2019-04-14 9:51 UTC (permalink / raw) To: Eli Zaretskii; +Cc: 35230 >>>>> 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 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* bug#35230: char-displayable-p return code is conflictingly documented 2019-04-14 9:51 ` Robert Pluim @ 2019-04-14 14:10 ` Eli Zaretskii 2020-08-21 15:09 ` Lars Ingebrigtsen 0 siblings, 1 reply; 6+ messages in thread From: Eli Zaretskii @ 2019-04-14 14:10 UTC (permalink / raw) To: Robert Pluim; +Cc: 35230 > 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. ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#35230: char-displayable-p return code is conflictingly documented 2019-04-14 14:10 ` Eli Zaretskii @ 2020-08-21 15:09 ` Lars Ingebrigtsen 2020-10-11 1:50 ` Lars Ingebrigtsen 0 siblings, 1 reply; 6+ messages in thread From: Lars Ingebrigtsen @ 2020-08-21 15:09 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Robert Pluim, 35230 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#35230: char-displayable-p return code is conflictingly documented 2020-08-21 15:09 ` Lars Ingebrigtsen @ 2020-10-11 1:50 ` Lars Ingebrigtsen 0 siblings, 0 replies; 6+ messages in thread From: Lars Ingebrigtsen @ 2020-10-11 1:50 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Robert Pluim, 35230 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2020-10-11 1:50 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2019-04-11 14:49 bug#35230: char-displayable-p return code is conflictingly documented Robert Pluim 2019-04-12 12:51 ` Eli Zaretskii 2019-04-14 9:51 ` Robert Pluim 2019-04-14 14:10 ` Eli Zaretskii 2020-08-21 15:09 ` Lars Ingebrigtsen 2020-10-11 1:50 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).