bug#19722: 25.0.50; (elisp) `Tool Bar': Add xref to doc for image specifications

bug#19722: 25.0.50; (elisp) `Tool Bar': Add xref to doc for image specifications

[Drew Adams]

The doc here describes `:image' in terms of "image specifications".
It should cross-reference the part of the manual that describes the
latter.  Otherwise, there is no way to understand what IMAGE means
in `:image IMAGE'.

Also, there is a typo:

   `:image IMAGE'
      IMAGES is either...

IMAGE or IMAGES?


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

bug#19722: 25.0.50; (elisp) `Tool Bar': Add xref to doc for image specifications

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 380 bytes --]

I note too that neither ":image" nor "image spec" has a substring match
for `i'.  (Yes, I know that you will reply that the former cannot be
indexed - dommage.)

FWIW, these (attached) are the only index entries I see when matching
"image" as a substring.  Dunno where to find the info about "image
specifications."  (Even searching for ":image" did not seem to help.)



[-- Attachment #2: throw-elisp-manual-index--image.png --]
[-- Type: image/png, Size: 24748 bytes --]

bug#19722: 25.0.50; (elisp) `Tool Bar': Add xref to doc for image specifications

[Eli Zaretskii]

> Date: Thu, 29 Jan 2015 08:50:47 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> I note too that neither ":image" nor "image spec" has a substring match
> for `i'.  (Yes, I know that you will reply that the former cannot be
> indexed - dommage.)
> 
> FWIW, these (attached) are the only index entries I see when matching
> "image" as a substring.  Dunno where to find the info about "image
> specifications."  (Even searching for ":image" did not seem to help.)

Please tell what information you were looking for, and which phrases
went through your head when you looked for that.

bug#19722: 25.0.50; (elisp) `Tool Bar': Add xref to doc for image specifications

[Drew Adams]

> > I note too that neither ":image" nor "image spec" has a substring match
> > for `i'.  (Yes, I know that you will reply that the former cannot be
> > indexed - dommage.)
> >
> > FWIW, these (attached) are the only index entries I see when matching
> > "image" as a substring.  Dunno where to find the info about "image
> > specifications."  (Even searching for ":image" did not seem to help.)
> 
> Please tell what information you were looking for, and which phrases
> went through your head when you looked for that.

I was trying to find what an "image specification" is - its
format/structure etc.  One cannot understand the doc for `:image' in
that node without knowing what "image specification" amounts to.

Perhaps "image format" or "image descriptor" is the same thing? If so
then it could help to use the same terminology throughout, but an xref
is still needed here, IMO.  Perhaps it should go to node `Image Formats'
or to node `Image Descriptors'.  Dunno.

The term "image specification" is used in the manual in many places,
but none of those places seem to define/describe what it is.  Perhaps
each of those occurrences should be changed to a different term (?).
And perhaps each of those occurrences should have an xref to wherever
this thingie is described.

bug#19722: 25.0.50; (elisp) `Tool Bar': Add xref to doc for image specifications

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> The doc here describes `:image' in terms of "image specifications".
> It should cross-reference the part of the manual that describes the
> latter.  Otherwise, there is no way to understand what IMAGE means
> in `:image IMAGE'.

I've now added a link.

> Also, there is a typo:
>
>    `:image IMAGE'
>       IMAGES is either...
>
> IMAGE or IMAGES?

Fixed.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no