5:13 a.m.
> Namely: what happens if the specifier refers to image files
> that are not existent, that are broken, or that are in a
> format that XEmacs does not support? Does make-glyph return
> nil? Does it return a glyph that later triggers some error
> when being used? Does make-glyph throw an error itself? At
> what point of time do :file ... and similar properties
> actually get evaluated?
>
> In short: what does make-glyph return or throw under what
> basic error conditions?
File data is loaded at the time that the spec is added to the
specifier, and the inline data is substituted. If an error
occurs or the file can't be found, XEmacs simply proceeds to
the next spec -- as a backup you will ultimately get a
"nothing" instantiator, I think -- i.e. you'll go ahead and
get a glyph back but it just won't show anything.
Actually, this info is documented too. It's at the bottom of
`make-image-specifier', which documents the format of the instantiator to
`make-glyph':
-------------
If the instantiator specifies data from a file, the data will be read
in at the time that the instantiator is added to the image (which may
be well before when the image is actually displayed), and the
instantiator will be converted into one of the inline-data forms, with
the filename retained using a :file keyword. This implies that the
file must exist when the instantiator is added to the image, but does
not need to exist at any other time (e.g. it may safely be a temporary
file).
-------------
`make-image-specifier' is specifically referred to by `make-glyph', so this
cannot be said to be totally obscure.
However, it's true that it's easy to miss among all the other docs.
Where exactly would you prefer that I put these two paragraphs? (i.e. if in
the docs for `make-glyph', where?)
9:58 a.m.
New subject: [Bug: 21.4.16] make-glyph doc-string missing essential information
"Ben Wing" <ben(a)666.com> writes:
Actually, this info is documented too. It's at the bottom of
`make-image-specifier', which documents the format of the instantiator to
`make-glyph':
-------------
If the instantiator specifies data from a file, the data will be read
in at the time that the instantiator is added to the image (which may
be well before when the image is actually displayed), and the
instantiator will be converted into one of the inline-data forms, with
the filename retained using a :file keyword. This implies that the
file must exist when the instantiator is added to the image, but does
not need to exist at any other time (e.g. it may safely be a temporary
file).
-------------
`make-image-specifier' is specifically referred to by `make-glyph',
so this cannot be said to be totally obscure.
Call me dense, but guessing the semantics of the return value of
make-glyph by following a link to a different function and then seeing
how this function may deal with certain conditions possibly arising
from completely different functions, making it somewhat probably that
make-glyph might be passing them on in some manner, or not detect
them, or whatever, is not _exactly_ what I'd call totally obvious.
And in fact, I have something like the following in preview-latex:
(unless preview-icon-toolbar-button
(setq preview-icon-toolbar-button
(vector
(list (preview-filter-specs preview-tb-icon-specs))
#'preview-at-point
t
"Preview on/off at point")))
;;; [Courtesy Stephen J. Turnbull, with some modifications
;;; Message-ID: <87el9fglsj.fsf(a)tleepslib.sk.tsukuba.ac.jp>
;;; I could not have figured this out for the world]
;;; Hm, there really ought to be a way to get the spec that would be
;;; instantiated in a given domain
(let ((tb (cdadar (or (specifier-spec-list default-toolbar (current-buffer))
(specifier-spec-list default-toolbar 'global)))))
(unless (member preview-icon-toolbar-button tb)
(set-specifier default-toolbar
(append tb (list preview-icon-toolbar-button))
(current-buffer))))
When the icon is missing, I currently get an absolutely weird error
message, but that is probably my fault since I then have
(vector (list nil) ...
I am going to try what happens with other approaches, but let me tell
you one thing: guessing this sort of stuff from the documentation is
impossible for me.
However, it's true that it's easy to miss among all the other
docs.
Where exactly would you prefer that I put these two paragraphs? (i.e. if in
the docs for `make-glyph', where?)
`make-glyph' checks only the structural validity of its
specifiers/instant whatevers, but not even whether referenced files
exist. Sorting out instantiable from non-instantiable glyphs for a
particular local/domain/whatever is only done by whatever.
make-glyph never returns nil, but rather throws an error for invalid
data/invalid data makes make-glyph return nil.
It is all fine and nice that you'll probably use the return value of
make-glyph in some other function, but that still does not tell me
whether the return value can always passed on and with what
consequences.
And the return behavior of make-glyph should be documented in the
documentation to make-glyph. If you want to, you can write then
something in a referenced function that says "a return value from
make-glyph is always valid input for
do-what-you-want-with-this-instantiator/specifier/whatever".
--
David Kastrup, Kriemhildstr. 15, 44793 Bochum
10:07 a.m.
New subject: [Bug: 21.4.16] make-glyph doc-string missing essential information
Call me dense, but guessing the semantics of the return value
of make-glyph by following a link to a different function and
then seeing how this function may deal with certain
conditions possibly arising from completely different
functions, making it somewhat probably that make-glyph might
be passing them on in some manner, or not detect them, or
whatever, is not _exactly_ what I'd call totally obvious.
Well, if you actually read the docs you see that in the second paragraph of
`make-glyph' it tells you that if you want to understand the format of the
SPEC parameter to `make-glyph', go see `make-image-specifier'. Since your
initial question was about the behavior of different kinds of SPEC
parameters, it doesn't take an einstein to figure out that the place that
describes spec parameters in detail might say something about their
behavior.
Ben
10:36 a.m.
New subject: [Bug: 21.4.16] make-glyph doc-string missing essential information
"Ben Wing" <ben(a)666.com> writes:
> Call me dense, but guessing the semantics of the return value of
> make-glyph by following a link to a different function and then
> seeing how this function may deal with certain conditions possibly
> arising from completely different functions, making it somewhat
> probably that make-glyph might be passing them on in some manner,
> or not detect them, or whatever, is not _exactly_ what I'd call
> totally obvious.
Well, if you actually read the docs you see that in the second
paragraph of `make-glyph' it tells you that if you want to
understand the format of the SPEC parameter to `make-glyph', go see
`make-image-specifier'. Since your initial question was about the
behavior of different kinds of SPEC parameters, it doesn't take an
einstein to figure out that the place that describes spec parameters
in detail might say something about their behavior.
And that is supposed to tell me the set of return semantics of
make-glyph? But of course I am no Einstein.
I apologize profusely for not having the necessary mental capacity to
be allowed reporting problems I encountered with understanding your
documentation without having my inferiority pointed out as the
principal problem in return.
It is always a joy helping you improve XEmacs.
--
David Kastrup, Kriemhildstr. 15, 44793 Bochum
7225
days inactive
7225
days old
3 comments
2 participants
participants (2)
-
Ben Wing -
David Kastrup