Re: Using more and/or better icons in Emacs

[Eli Zaretskii]

> Date: Tue, 13 Apr 2021 20:50:12 +0100
> From: Alan Third <alan@idiocy.org>
> Cc: emacs-devel@gnu.org, Dmitry Gutov <dgutov@yandex.ru>
> 
> > Your patch LGTM, but I guess it would need documentation and a NEWS entry.
> > Thanks again for working on this!
> 
> Thanks. I've attached a version with documentation. I think it's good
> enough but would appreciate someone else double checking it makes sense.

Thanks, a few minor nits below.

> --- a/doc/lispref/display.texi
> +++ b/doc/lispref/display.texi
> @@ -5289,6 +5289,13 @@ Image Descriptors
>  and values, including at least the pair @code{:type @var{type}} that
>  specifies the image type.
>  
> +  Image descriptors which define image dimensions, i.e. @code{:width},
> +@code{:height}, @code{:max-width} and @code{:max-height}, may take
> +either a number, which represents the dimension in pixels, or a pair
> +@code{(@var{value} . 'em)}, where @var{value} is the dimension's
> +length in ``ems''.  One ``em'' is equivalent to the height of the
> +font.

I would use @dfn{em} the first time, and thereafter just em, without
quotes.  It would also be good to have a @footnote explaining the
source of the name "em".

Also, VALUE can be a float, and that should be documented.

> +/* Return a size in pixels either directly from the value specified by
> +   SYMBOL, or from a CONS of the form (VALUE . UNITS).  If the value
> +   doesn't exist in the image spec, or is invalid, return -1.  */
> +static int
> +image_get_length (struct image *img, Lisp_Object symbol)

The "length" part of the name defeats its mnemonic value.  I suggest
image_get_dimension instead.

Also, I think the commentary is inaccurate or at least confusing (is
it from some earlier version of the code, perhaps?).