Re: master a739cab6637 2/2: ; * doc/lispref/display.texi (Image Descriptors): Insert missing text.

Re: master a739cab6637 2/2: ; * doc/lispref/display.texi (Image Descriptors): Insert missing text.

[Robert Pluim]

>>>>> On Mon,  3 Jun 2024 04:36:43 -0400 (EDT), Po Lu via Mailing list for Emacs changes <emacs-diffs@gnu.org> said:

    Po Lu> branch: master
    Po Lu> commit a739cab66378a367cef8fa3a59f7ccb70a56bbb4
    Po Lu> Author: Po Lu <luangruo@yahoo.com>
    Po Lu> Commit: Po Lu <luangruo@yahoo.com>


The text now reads

    @vindex image-scaling-factor
    Alternatively, the symbol @code{default} may be specified, indicating
    that the image should be scaled according as the value of the
    @code{image-scaling-factor} variable is the default @code{auto} or a
    number, which by default scales the image in proportion to the average
    widths (@pxref{Low-Level Font}) of the default faces of frames on which
    it happens to be displayed, if such widths should exceed @code{10}
    pixels.  If no other value is provided, @code{create-image} will specify
    this value in image specifications it creates.

which apart from saying 'according as' rather than 'according to' is
completely incomprehensible to me.

Robert
-- 

Re: master a739cab6637 2/2: ; * doc/lispref/display.texi (Image Descriptors): Insert missing text.

[Eli Zaretskii]

> From: Robert Pluim <rpluim@gmail.com>
> Cc: Po Lu <luangruo@yahoo.com>
> Date: Mon, 03 Jun 2024 13:27:22 +0200
> 
> >>>>> On Mon,  3 Jun 2024 04:36:43 -0400 (EDT), Po Lu via Mailing list for Emacs changes <emacs-diffs@gnu.org> said:
> 
>     Po Lu> branch: master
>     Po Lu> commit a739cab66378a367cef8fa3a59f7ccb70a56bbb4
>     Po Lu> Author: Po Lu <luangruo@yahoo.com>
>     Po Lu> Commit: Po Lu <luangruo@yahoo.com>
> 
> 
> The text now reads
> 
>     @vindex image-scaling-factor
>     Alternatively, the symbol @code{default} may be specified, indicating
>     that the image should be scaled according as the value of the
>     @code{image-scaling-factor} variable is the default @code{auto} or a
>     number, which by default scales the image in proportion to the average
>     widths (@pxref{Low-Level Font}) of the default faces of frames on which
>     it happens to be displayed, if such widths should exceed @code{10}
>     pixels.  If no other value is provided, @code{create-image} will specify
>     this value in image specifications it creates.
> 
> which apart from saying 'according as' rather than 'according to' is
> completely incomprehensible to me.

Agreed.  Po Lu, can you please fix that text?

Re: master a739cab6637 2/2: ; * doc/lispref/display.texi (Image Descriptors): Insert missing text.

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Robert Pluim <rpluim@gmail.com>
>> Cc: Po Lu <luangruo@yahoo.com>
>> Date: Mon, 03 Jun 2024 13:27:22 +0200
>> 
>> >>>>> On Mon, 3 Jun 2024 04:36:43 -0400 (EDT), Po Lu via Mailing
>> list for Emacs changes <emacs-diffs@gnu.org> said:
>> 
>>     Po Lu> branch: master
>>     Po Lu> commit a739cab66378a367cef8fa3a59f7ccb70a56bbb4
>>     Po Lu> Author: Po Lu <luangruo@yahoo.com>
>>     Po Lu> Commit: Po Lu <luangruo@yahoo.com>
>> 
>> 
>> The text now reads
>> 
>>     @vindex image-scaling-factor
>>     Alternatively, the symbol @code{default} may be specified, indicating
>>     that the image should be scaled according as the value of the
>>     @code{image-scaling-factor} variable is the default @code{auto} or a
>>     number, which by default scales the image in proportion to the average
>>     widths (@pxref{Low-Level Font}) of the default faces of frames on which
>>     it happens to be displayed, if such widths should exceed @code{10}
>>     pixels.  If no other value is provided, @code{create-image} will specify
>>     this value in image specifications it creates.
>> 
>> which apart from saying 'according as' rather than 'according to' is
>> completely incomprehensible to me.
>
> Agreed.  Po Lu, can you please fix that text?

Is it "according as XXX or YYY" that is incomprehensible to both of you,
or just the punctuation?  "According to whether XXX or YYY" is not
appropriate in this context, I think, as it implies that the choice
between the two options is the only factor that affects the image's
scaling, while there is really also the value of the variable that the
latter option refers to, whose values and their effects are elaborated
immediately afterwards.

Re: master a739cab6637 2/2: ; * doc/lispref/display.texi (Image Descriptors): Insert missing text.

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: Robert Pluim <rpluim@gmail.com>,  emacs-devel@gnu.org
> Date: Thu, 06 Jun 2024 21:18:44 +0800
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >>     @vindex image-scaling-factor
> >>     Alternatively, the symbol @code{default} may be specified, indicating
> >>     that the image should be scaled according as the value of the
> >>     @code{image-scaling-factor} variable is the default @code{auto} or a
> >>     number, which by default scales the image in proportion to the average
> >>     widths (@pxref{Low-Level Font}) of the default faces of frames on which
> >>     it happens to be displayed, if such widths should exceed @code{10}
> >>     pixels.  If no other value is provided, @code{create-image} will specify
> >>     this value in image specifications it creates.
> >> 
> >> which apart from saying 'according as' rather than 'according to' is
> >> completely incomprehensible to me.
> >
> > Agreed.  Po Lu, can you please fix that text?
> 
> Is it "according as XXX or YYY" that is incomprehensible to both of you,
> or just the punctuation?

The entire paragraph is incomprehensible.  I simply don't understand
what you wanted to say there.  Perhaps explain it in simple words, and
then I will be able to suggest how to rephrase.

Re: master a739cab6637 2/2: ; * doc/lispref/display.texi (Image Descriptors): Insert missing text.

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Po Lu <luangruo@yahoo.com>
>> Cc: Robert Pluim <rpluim@gmail.com>,  emacs-devel@gnu.org
>> Date: Thu, 06 Jun 2024 21:18:44 +0800
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >>     @vindex image-scaling-factor
>> >>     Alternatively, the symbol @code{default} may be specified, indicating
>> >>     that the image should be scaled according as the value of the
>> >>     @code{image-scaling-factor} variable is the default @code{auto} or a
>> >>     number, which by default scales the image in proportion to the average
>> >>     widths (@pxref{Low-Level Font}) of the default faces of frames on which
>> >>     it happens to be displayed, if such widths should exceed @code{10}
>> >>     pixels.  If no other value is provided, @code{create-image} will specify
>> >>     this value in image specifications it creates.
>> >> 
>> >> which apart from saying 'according as' rather than 'according to' is
>> >> completely incomprehensible to me.
>> >
>> > Agreed.  Po Lu, can you please fix that text?
>> 
>> Is it "according as XXX or YYY" that is incomprehensible to both of you,
>> or just the punctuation?
>
> The entire paragraph is incomprehensible.  I simply don't understand
> what you wanted to say there.  Perhaps explain it in simple words, and
> then I will be able to suggest how to rephrase.

How's this?

Alternatively, the symbol @code{default} may be specified, indicating
that the image should be scaled in one of two ways, selected by the
value of the @code{image-scaling-factor} variable.  This value is either
a number providing a constant scale factor, or the default, @code{auto},
in which case the image will be scaled in proportion to the average
widths (@pxref{Low-Level Font}) of the default faces of frames on which
it is displayed and where this default width exceeds @code{10} pixels.
If no other value is provided, @code{create-image} will specify
@code{default} in image specifications it creates.

Re: master a739cab6637 2/2: ; * doc/lispref/display.texi (Image Descriptors): Insert missing text.

[Robert Pluim]

>>>>> On Thu, 06 Jun 2024 21:58:20 +0800, Po Lu <luangruo@yahoo.com> said:

    Po Lu> Eli Zaretskii <eliz@gnu.org> writes:
    >>> From: Po Lu <luangruo@yahoo.com>
    >>> Cc: Robert Pluim <rpluim@gmail.com>,  emacs-devel@gnu.org
    >>> Date: Thu, 06 Jun 2024 21:18:44 +0800
    >>> 
    >>> Eli Zaretskii <eliz@gnu.org> writes:
    >>> 
    >>> >>     @vindex image-scaling-factor
    >>> >>     Alternatively, the symbol @code{default} may be specified, indicating
    >>> >>     that the image should be scaled according as the value of the
    >>> >>     @code{image-scaling-factor} variable is the default @code{auto} or a
    >>> >>     number, which by default scales the image in proportion to the average
    >>> >>     widths (@pxref{Low-Level Font}) of the default faces of frames on which
    >>> >>     it happens to be displayed, if such widths should exceed @code{10}
    >>> >>     pixels.  If no other value is provided, @code{create-image} will specify
    >>> >>     this value in image specifications it creates.
    >>> >> 
    >>> >> which apart from saying 'according as' rather than 'according to' is
    >>> >> completely incomprehensible to me.
    >>> >
    >>> > Agreed.  Po Lu, can you please fix that text?
    >>> 
    >>> Is it "according as XXX or YYY" that is incomprehensible to both of you,
    >>> or just the punctuation?
    >> 
    >> The entire paragraph is incomprehensible.  I simply don't understand
    >> what you wanted to say there.  Perhaps explain it in simple words, and
    >> then I will be able to suggest how to rephrase.

    Po Lu> How's this?

    Po Lu> Alternatively, the symbol @code{default} may be specified, indicating
    Po Lu> that the image should be scaled in one of two ways, selected by the
    Po Lu> value of the @code{image-scaling-factor} variable.  This value is either
    Po Lu> a number providing a constant scale factor, or the default, @code{auto},
    Po Lu> in which case the image will be scaled in proportion to the average
    Po Lu> widths (@pxref{Low-Level Font}) of the default faces of frames on which
    Po Lu> it is displayed and where this default width exceeds @code{10} pixels.
    Po Lu> If no other value is provided, @code{create-image} will specify
    Po Lu> @code{default} in image specifications it creates.

That reads a lot better, thanks.

Robert
-- 

Re: master a739cab6637 2/2: ; * doc/lispref/display.texi (Image Descriptors): Insert missing text.

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: rpluim@gmail.com,  emacs-devel@gnu.org
> Date: Thu, 06 Jun 2024 21:58:20 +0800
> 
> How's this?
> 
> Alternatively, the symbol @code{default} may be specified, indicating
> that the image should be scaled in one of two ways, selected by the
> value of the @code{image-scaling-factor} variable.  This value is either
> a number providing a constant scale factor, or the default, @code{auto},
> in which case the image will be scaled in proportion to the average
> widths (@pxref{Low-Level Font}) of the default faces of frames on which
> it is displayed and where this default width exceeds @code{10} pixels.
> If no other value is provided, @code{create-image} will specify
> @code{default} in image specifications it creates.

Better, but still "needs work".  Here's my suggestion:

  @var{scale} can also be the symbol @code{default}, which means to
  use the value of @code{image-scaling-factor}.  If that value is a
  number, it is the scale factor to use; if it is @code{auto} (the
  default), it means to compute the scaling factor based on pixel size
  of the font used by the frame's default face (@pxref{Low-Level
  Font}).

And I would like to explain more about "computing the scaling factor
based on pixel size of the font used by the frame's default face", and
what happens if the default font's width is 10 pixels or below, but
your text doesn't really tell that story.  I think it should.  (Btw,
the default width of the font in "emacs -Q" on Windows is 8, so it
will always hit the case which was left unexplained.)

Thanks.

Re: master a739cab6637 2/2: ; * doc/lispref/display.texi (Image Descriptors): Insert missing text.

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> And I would like to explain more about "computing the scaling factor
> based on pixel size of the font used by the frame's default face", and
> what happens if the default font's width is 10 pixels or below, but
> your text doesn't really tell that story.  I think it should.  (Btw,
> the default width of the font in "emacs -Q" on Windows is 8, so it
> will always hit the case which was left unexplained.)

Below 10 pixels, the image is not scaled unless a numeric scale be
provided in image-scaling-factor.  As for the reasoning behind this
arbitrary value, you'll need to ask Lars, whose code I've merely
reproduced in C.

Thanks.

Re: master a739cab6637 2/2: ; * doc/lispref/display.texi (Image Descriptors): Insert missing text.

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: rpluim@gmail.com,  emacs-devel@gnu.org
> Date: Fri, 07 Jun 2024 08:14:36 +0800
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > And I would like to explain more about "computing the scaling factor
> > based on pixel size of the font used by the frame's default face", and
> > what happens if the default font's width is 10 pixels or below, but
> > your text doesn't really tell that story.  I think it should.  (Btw,
> > the default width of the font in "emacs -Q" on Windows is 8, so it
> > will always hit the case which was left unexplained.)
> 
> Below 10 pixels, the image is not scaled unless a numeric scale be
> provided in image-scaling-factor.  As for the reasoning behind this
> arbitrary value, you'll need to ask Lars, whose code I've merely
> reproduced in C.

So this means at least on Windows, where the default font's width is
8, the image will never be scaled in "emacs -Q", am I right?

I think on macOS the default width is 7, so the same will happen there
as well?

What is the default width of the font on GNU/Linux?

And finally, can you tell more about how the scale factor is computed
"based on the font's pixel size"?  Or point me to the code which does
that?  I think some of that should be in the manual, to give the users
some idea of what will happen.

Thanks.

Re: master a739cab6637 2/2: ; * doc/lispref/display.texi (Image Descriptors): Insert missing text.

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> So this means at least on Windows, where the default font's width is
> 8, the image will never be scaled in "emacs -Q", am I right?
>
> I think on macOS the default width is 7, so the same will happen there
> as well?
>
> What is the default width of the font on GNU/Linux?

8, though all this is only true when there is no display scale
configured, even on MS-Windows, correct?  This code isn't supposed to
activate when the display density isn't so high as to require font
scaling, and in the other case the default font width will be scaled
beyond 10 pixels.

> And finally, can you tell more about how the scale factor is computed
> "based on the font's pixel size"?  Or point me to the code which does
> that?  I think some of that should be in the manual, to give the users
> some idea of what will happen.

See line 2699 of image.c.

Re: master a739cab6637 2/2: ; * doc/lispref/display.texi (Image Descriptors): Insert missing text.

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: rpluim@gmail.com,  emacs-devel@gnu.org
> Date: Fri, 07 Jun 2024 16:50:55 +0800
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > So this means at least on Windows, where the default font's width is
> > 8, the image will never be scaled in "emacs -Q", am I right?
> >
> > I think on macOS the default width is 7, so the same will happen there
> > as well?
> >
> > What is the default width of the font on GNU/Linux?
> 
> 8, though all this is only true when there is no display scale
> configured, even on MS-Windows, correct?  This code isn't supposed to
> activate when the display density isn't so high as to require font
> scaling, and in the other case the default font width will be scaled
> beyond 10 pixels.
> 
> > And finally, can you tell more about how the scale factor is computed
> > "based on the font's pixel size"?  Or point me to the code which does
> > that?  I think some of that should be in the manual, to give the users
> > some idea of what will happen.
> 
> See line 2699 of image.c.

Thanks, I installed some clarifications of this text.

Re: master a739cab6637 2/2: ; * doc/lispref/display.texi (Image Descriptors): Insert missing text.

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks, I installed some clarifications of this text.

Thanks.