bug#37213: Execute set-window-margins. left-margin-width remains 0.

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[Alan Mackenzie]

Hello, Emacs.

In Emacs-27, recent master branch, do:

emacs -Q
M-: (set-window-margins (selected-window) 2) ; This works.
M-: left-margin-width.

The result is that left-margin-width is still at zero, although the
value should be 2.  This is a bug.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[Eli Zaretskii]

> Date: Wed, 28 Aug 2019 18:53:52 +0000
> From: Alan Mackenzie <acm@muc.de>
> 
> emacs -Q
> M-: (set-window-margins (selected-window) 2) ; This works.
> M-: left-margin-width.
> 
> The result is that left-margin-width is still at zero, although the
> value should be 2.  This is a bug.

I don't think this is a bug.  This variable is for _setting_ the
margin width, not for _returning_ its width as set "by other means".
See its documentation.

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[Alan Mackenzie]

Hello, Eli.

On Wed, Aug 28, 2019 at 22:14:54 +0300, Eli Zaretskii wrote:
> > Date: Wed, 28 Aug 2019 18:53:52 +0000
> > From: Alan Mackenzie <acm@muc.de>

> > emacs -Q
> > M-: (set-window-margins (selected-window) 2) ; This works.
> > M-: left-margin-width.

> > The result is that left-margin-width is still at zero, although the
> > value should be 2.  This is a bug.

> I don't think this is a bug.  This variable is for _setting_ the
> margin width, not for _returning_ its width as set "by other means".
> See its documentation.

The documentation says "This variable specifies the width of the left
margin".  As best, this is unclear.  What you're saying is that the
variable ceases to specify that width, should the margin be altered by
other means.

I maintain that this is either a bug in the documentation, or in the
code.

If the former, it should explicitly state that the variable is
write-only, and its read value is undefined.  It should say that the
function window-margins should be used instead.

But it might be easier just to amend the code.  There appear to be just
two ways to set the width of the left margin (or the right margin), so
if it gets set the second way, why not just set that variable?  Could
this do any harm?  (Note: I haven't looked at the code, yet.)

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[Eli Zaretskii]

> Date: Wed, 28 Aug 2019 19:57:06 +0000
> Cc: 37213@debbugs.gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > I don't think this is a bug.  This variable is for _setting_ the
> > margin width, not for _returning_ its width as set "by other means".
> > See its documentation.
> 
> The documentation says "This variable specifies the width of the left
> margin".  As best, this is unclear.  What you're saying is that the
> variable ceases to specify that width, should the margin be altered by
> other means.
> 
> I maintain that this is either a bug in the documentation, or in the
> code.

I'm okay with clarifying the documentation, but let's first agree what
needs clarifying there.

> If the former, it should explicitly state that the variable is
> write-only, and its read value is undefined.  It should say that the
> function window-margins should be used instead.
> 
> But it might be easier just to amend the code.  There appear to be just
> two ways to set the width of the left margin (or the right margin), so
> if it gets set the second way, why not just set that variable?  Could
> this do any harm?  (Note: I haven't looked at the code, yet.)

Think about it: left-margin-width is a per-buffer variable.  A buffer
can be displayed in zero or more windows, and the margin is a window
property.  How can a single buffer-local variable reflect a value that
can be different in different windows, and can even be meaningless if
the buffer is not displayed in any window?

What happens in the code is that when a buffer is displayed in a
window, this variable is consulted, and the window's margin-width
attribute set accordingly.  The window margins can grow or shrink
thereafter, and the function window-margins then returns this window
attribute's value at any given moment for a specific window.

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[Alan Mackenzie]

Hello, Eli.

On Thu, Aug 29, 2019 at 09:42:17 +0300, Eli Zaretskii wrote:
> > Date: Wed, 28 Aug 2019 19:57:06 +0000
> > Cc: 37213@debbugs.gnu.org
> > From: Alan Mackenzie <acm@muc.de>
 
> > > I don't think this is a bug.  This variable is for _setting_ the
> > > margin width, not for _returning_ its width as set "by other means".
> > > See its documentation.

> > The documentation says "This variable specifies the width of the left
> > margin".  As best, this is unclear.  What you're saying is that the
> > variable ceases to specify that width, should the margin be altered by
> > other means.

> > I maintain that this is either a bug in the documentation, or in the
> > code.

> I'm okay with clarifying the documentation, but let's first agree what
> needs clarifying there.

How about the following, purely pragmatic, patch?


diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 7c0a56dcad..428fe9595a 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -5016,7 +5016,9 @@ Display Margins
   Setting these variables does not immediately affect the window.  These
 variables are checked when a new buffer is displayed in the window.
 Thus, you can make changes take effect by calling
-@code{set-window-buffer}.
+@code{set-window-buffer}.  Do not use these variables to try to
+determine the current width of the left or right margin.  Instead, use
+the function @code{window-margins}.
 
   You can also set the margin widths immediately.
 

With this patch applied, I'd be happy for the bug to be closed.

> > If the former, it should explicitly state that the variable is
> > write-only, and its read value is undefined.  It should say that the
> > function window-margins should be used instead.

> > But it might be easier just to amend the code.  There appear to be just
> > two ways to set the width of the left margin (or the right margin), so
> > if it gets set the second way, why not just set that variable?  Could
> > this do any harm?  (Note: I haven't looked at the code, yet.)

> Think about it: left-margin-width is a per-buffer variable.  A buffer
> can be displayed in zero or more windows, and the margin is a window
> property.  How can a single buffer-local variable reflect a value that
> can be different in different windows, and can even be meaningless if
> the buffer is not displayed in any window?

OK.

> What happens in the code is that when a buffer is displayed in a
> window, this variable is consulted, and the window's margin-width
> attribute set accordingly.  The window margins can grow or shrink
> thereafter, and the function window-margins then returns this window
> attribute's value at any given moment for a specific window.

Thanks for the explanation.

-- 
Alan Mackenzie (Nurermberg, Germany).

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[Eli Zaretskii]

> Date: Sat, 31 Aug 2019 11:59:11 +0000
> Cc: 37213@debbugs.gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> How about the following, purely pragmatic, patch?
> 
> 
> diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
> index 7c0a56dcad..428fe9595a 100644
> --- a/doc/lispref/display.texi
> +++ b/doc/lispref/display.texi
> @@ -5016,7 +5016,9 @@ Display Margins
>    Setting these variables does not immediately affect the window.  These
>  variables are checked when a new buffer is displayed in the window.
>  Thus, you can make changes take effect by calling
> -@code{set-window-buffer}.
> +@code{set-window-buffer}.  Do not use these variables to try to
> +determine the current width of the left or right margin.  Instead, use
> +the function @code{window-margins}.
>  
>    You can also set the margin widths immediately.

Fine with me, thanks.

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[martin rudalics]

 > The documentation says "This variable specifies the width of the left
 > margin".  As best, this is unclear.  What you're saying is that the
 > variable ceases to specify that width, should the margin be altered by
 > other means.

Eli didn't say that.

 > I maintain that this is either a bug in the documentation, or in the
 > code.
 >
 > If the former, it should explicitly state that the variable is
 > write-only, and its read value is undefined.  It should say that the
 > function window-margins should be used instead.

The variable is not write-only and its read value is well-defined.

 > But it might be easier just to amend the code.  There appear to be just
 > two ways to set the width of the left margin (or the right margin), so
 > if it gets set the second way, why not just set that variable?  Could
 > this do any harm?  (Note: I haven't looked at the code, yet.)

Please re-read the documentations of 'left-margin-width' and
'set-window-margins' having in mind that the same buffer may appear in
different windows and the same window may show different buffers all
with differing margins.

Once you've done that, please look at the respective documentations
for fringes and scroll bars which are even more complicated because
they have to obey a frame parameter as well.

Thanks, martin

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[Alan Mackenzie]

Hello, Martin.

On Thu, Aug 29, 2019 at 09:46:54 +0200, martin rudalics wrote:
>  > The documentation says "This variable specifies the width of the left
>  > margin".  As best, this is unclear.  What you're saying is that the
>  > variable ceases to specify that width, should the margin be altered by
>  > other means.

> Eli didn't say that.

>  > I maintain that this is either a bug in the documentation, or in the
>  > code.

>  > If the former, it should explicitly state that the variable is
>  > write-only, and its read value is undefined.  It should say that the
>  > function window-margins should be used instead.

> The variable is not write-only and its read value is well-defined.

Is the read value well-defined?  Never having set it, the value it has
seems always to be 0.  But even if it is well-defined, is it useful for
anything?

>  > But it might be easier just to amend the code.  There appear to be just
>  > two ways to set the width of the left margin (or the right margin), so
>  > if it gets set the second way, why not just set that variable?  Could
>  > this do any harm?  (Note: I haven't looked at the code, yet.)

> Please re-read the documentations of 'left-margin-width' and
> 'set-window-margins' having in mind that the same buffer may appear in
> different windows and the same window may show different buffers all
> with differing margins.

Yes, that's the thing.  We don't have "window local variables" in Emacs,
so anything specific to a window needs a function interface with the
window being one of the parameters.

> Once you've done that, please look at the respective documentations
> for fringes and scroll bars which are even more complicated because
> they have to obey a frame parameter as well.

I've proposed a simple amendment to the "Display Margins" page of the
elisp manual, saying "don't use these variables to ....!".  This would
solve the misunderstanding I experienced earlier.

> Thanks, martin

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[martin rudalics]

 > Is the read value well-defined?  Never having set it, the value it has
 > seems always to be 0.

All margin-related values are zero by default.

 > But even if it is well-defined, is it useful for
 > anything?

To keep you informed about the sizes of the margins of a window
whenever the buffer will be shown in it via 'set-window-buffer'.

 > Yes, that's the thing.  We don't have "window local variables" in Emacs,
 > so anything specific to a window needs a function interface with the
 > window being one of the parameters.

Right.  Windows behave like frames in this regard.

 > I've proposed a simple amendment to the "Display Margins" page of the
 > elisp manual, saying "don't use these variables to ....!".  This would
 > solve the misunderstanding I experienced earlier.

Hmm...  What is the "current width of the left or right margin"?

martin

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[Alan Mackenzie]

Hello, Martin.

On Sun, Sep 01, 2019 at 10:26:35 +0200, martin rudalics wrote:
>  > Is the read value well-defined?  Never having set it, the value it has
>  > seems always to be 0.

> All margin-related values are zero by default.

>  > But even if it is well-defined, is it useful for
>  > anything?

> To keep you informed about the sizes of the margins of a window
> whenever the buffer will be shown in it via 'set-window-buffer'.

OK.  It seems there are two alternative strategies for manipulating a
window's margins.  One is to use set-window-margins together with
window-margins, the other is to use left/right-margin-width and
set-window-buffer.

>  > Yes, that's the thing.  We don't have "window local variables" in Emacs,
>  > so anything specific to a window needs a function interface with the
>  > window being one of the parameters.

> Right.  Windows behave like frames in this regard.

>  > I've proposed a simple amendment to the "Display Margins" page of the
>  > elisp manual, saying "don't use these variables to ....!".  This would
>  > solve the misunderstanding I experienced earlier.

> Hmm...  What is the "current width of the left or right margin"?

I'm not sure I understand the question.  In a given window with a left
margin, there will be a maximum length of string which can be displayed
in that margin.  That is its "current width".  The same for a right
margin.  What are you getting at, here?

> martin

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[martin rudalics]

 > OK.  It seems there are two alternative strategies for manipulating a
 > window's margins.  One is to use set-window-margins together with
 > window-margins, the other is to use left/right-margin-width and
 > set-window-buffer.

Right.  With fringes and scroll bars you can additionally set a frame
parameter.  I know that you're not interested in the latter but any
descriptions should be consistent.

 >> Hmm...  What is the "current width of the left or right margin"?
 >
 > I'm not sure I understand the question.  In a given window with a left
 > margin, there will be a maximum length of string which can be displayed
 > in that margin.  That is its "current width".  The same for a right
 > margin.  What are you getting at, here?

That you omitted the "In a given window" preamble in the manual.  When
you have a frame with two windows showing one and the same buffer, the
margins of these windows can have different widths.  What would be the
"current width" in that case?

martin

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[Alan Mackenzie]

Hello, Martin.

On Sun, Sep 01, 2019 at 14:19:37 +0200, martin rudalics wrote:
>  > OK.  It seems there are two alternative strategies for manipulating a
>  > window's margins.  One is to use set-window-margins together with
>  > window-margins, the other is to use left/right-margin-width and
>  > set-window-buffer.

> Right.  With fringes and scroll bars you can additionally set a frame
> parameter.  I know that you're not interested in the latter but any
> descriptions should be consistent.

None of this is simple.

>  >> Hmm...  What is the "current width of the left or right margin"?

>  > I'm not sure I understand the question.  In a given window with a left
>  > margin, there will be a maximum length of string which can be displayed
>  > in that margin.  That is its "current width".  The same for a right
>  > margin.  What are you getting at, here?

> That you omitted the "In a given window" preamble in the manual.  When
> you have a frame with two windows showing one and the same buffer, the
> margins of these windows can have different widths.  What would be the
> "current width" in that case?

Whatever it is, you can't get it reliably from left/right-margin-width.
You can get it by calling window-margins, and as window-margins takes a
window as a mandatory argument, that surely answers the question.

The point about the extra text I put in is to emphasise that Emacs does
not update left/right-margin-width to reflect the current width (in
whatever sense).  The former text was not clear about this point.

I don't think the current text needs further amendment.  If you
disagree, perhaps you could propose a specific change.

> martin

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[martin rudalics]

 > Hello, Emacs.

Hello, Alan.

 > In Emacs-27, recent master branch, do:
 >
 > emacs -Q
 > M-: (set-window-margins (selected-window) 2) ; This works.

In which sense?

 > M-: left-margin-width.
 >
 > The result is that left-margin-width is still at zero, although the
 > value should be 2.  This is a bug.

Neither of the last two statements is correct.  'set-window-margins'
sets the margin widths of its WINDOW argument (the selected window in
your case) and triggers an update of the display.  If WINDOW's buffer
is currently displayed in another window as well, the margins of that
other window remain unaffected.  You can verify that by splitting your
window before invoking 'set-window-margins'.

'left-margin-width' is the buffer-local value of the left margin for
showing that buffer in a window.  That value is put into effect only
when 'set-window-buffer' has a window display that buffer.  You can
verfiy this by setting 'left-margin-width' to some different value
before splitting the window as suggested above.

Concludingly, you've been comparing apples and oranges here.  If the
doc-strings or the manual made you do so, please consider adjusting
their texts appropriately.  Gladly, your questions was about margins
only; with fringes we would even have a frame parameter to take into
account here ...

Thanks, martin

bug#37213: Execute set-window-margins. left-margin-width remains 0.

[Alan Mackenzie]

Bug fixed by enhancing the documentation (elisp manual).

-- 
Alan Mackenzie (Nuremberg, Germany).