RE: [Bug: 21.4.16] make-glyph doc-string missing essential information
> 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?)