[Bug: 21.4.16] make-glyph doc-string missing essential information

[David Kastrup]

"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
> `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 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)
      (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