[Bug: 21.4.16] make-glyph doc-string missing essential information
dak at gnu.org
Thu Feb 10 04:58:56 EST 2005
"Ben Wing" <ben at 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
> 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
> `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:
(list (preview-filter-specs preview-tb-icon-specs))
"Preview on/off at point")))
;;; [Courtesy Stephen J. Turnbull, with some modifications
;;; Message-ID: <87el9fglsj.fsf at 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)
(append tb (list preview-icon-toolbar-button))
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
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
David Kastrup, Kriemhildstr. 15, 44793 Bochum
More information about the XEmacs-Beta