Better handling of window margins

Better handling of window margins

[Joost Kremers]

In two recent threads, one here ("Window splitting issues with margins")
and one on bugs.gnu.emacs (bug 22009), some issues were discussed with
window margins that could stand improvement. Two issues specifically
came up:

1) If two modes use the margins at the same time, there is no way to
ensure that they don't interfere. Specifically, if package A sets the
(left) margin to a value x and package B sets it to a value y, whichever
mode sets the margin last will win out. Which of the two packages this
is depends on the order in which they were activated and on the hooks
that the modes use to adjust the margins. There is currently no good way
for a mode to prevent such interference reliably.

2) When a window's width is changed, Emacs currently assumes that the
margins need to be retained, i.e., their width doesn't change. This in
itself is not a problem, because a mode that does want to change the
margin width can do so in `window-configuration-change-hook'. However,
it becomes a problem in `window-splittable-p' (and
'split-window-sensibly'), because this function makes this same
assumption when determining whether a window can be split horizontally.
The assumption is not necessarily correct, specifically in modes such as
`writeroom-mode', `olivetti' (both on MELPA) or `darkroom-mode' (on
ELPA), that use the margins to center the text area in the window. In
such modes, the width of the margins is determined on the basis of the
desired text width and the current window width. When the window width
changes, the margins are recalculated. `window-splittable-p' currently
determines that such windows cannot be split horizontally, even when the
window (including margins) is wide enough. (It's just the text area that
isn't, but the aforementioned modes compensate for this by adjusting the
margins after the window has been split.)

I'd like to outline a way to hopefully solve both issues. The basic idea
of the proposal is that `set-window-margins' keeps track of which modes
set the margins and to which values they set them and whether they are
static (i.e., should not be changed when the window width changes) or
dynamic (can be changed). In detail:

* Add a window parameter (say `window-margins-alist') that records
  margin settings from different modes. E.g.:

  ((nlinum 4 0) (git-gutter 2 0))

* Amend `set-window-margins' to take two additional parameters:

  (set-window-margins WINDOW LEFT-WIDTH &optional RIGHT-WIDTH SYM DYNAMIC)

  SYM is a symbol (chosen by the caller) that identifies the mode that
  is setting the margins.

* If `set-window-margins' is called with a non-nil value for SYM, an
  entry is recorded in `window-margins-alist', or updated if one is
  already present, or deleted if both LEFT-WIDTH and RIGHT-WIDTH are
  nil. Subsequently, the window margins are set to the total of all
  requested widths, so in the example above to (6 0).

* If `set-window-margins' is called without SYM, it sets the margins
  without checking `window-margins-alist', i.e., it behaves as it does
  now, in order to prevent existing code from breaking.

* If DYNAMIC is t, this is recorded in `window-margins-alist', e.g.:

  ((nlinum 4 0) (git-gutter 2 0) (writeroom 40 40 t))  

  In this case, the window width is set to the *largest* dynamic value,
  or to the *total* of all static values, whichever is larger. So in the
  present example, `set-window-margins' should compare 4+2=6 with 40 for
  the left margin and 0+0=0 with 40 for the right margin and
  consequently set the margins to (40 40).

* `window-splittable-p' can check the contents of `window-margins-alist'
  and use the info to determine whether a window can be split
  horizontally: dynamic margins can be adjusted, so the horizontal
  splittability should be determined on the basis of text width plus
  dynamic margins minus static margins. In the present example:

  (+ (- 40 4 2) (- 40 0 0) (window-text-width))

  This value would be used instead of (window-width) in the current
  implementation of `window-splittable-p'.

* If the value of `window-margin-alist' is nil, but the margins are
  non-nil, `window-splittable-p' should behave as it does now.

* Obviously, `window-splittable-p' (or any function that calls it)
  should not update the margins itself. That is up to the modes that use
  the margins, using `window-configuration-change-hook'.

* A mode that wants to display something in the margin can check the
  value of `window-margins-alist' to see whether another mode is using
  the margins and can adjust its behaviour accordingly, e.g., by
  prepending a space to the string it displays, so that it is visually
  separate from whatever else is displayed in the margin.

I guess that's it. Comments & suggestions welcome.

[PS: I'm not really familiar with Emacs sources, so I may be overlooking
important things. Also, I can handle myself in Elisp, but I'm not much
of a C programmer, and `set-window-margins' is a C function. I'd be
willing to dive into the sources to try and come up with a patch, but it
would take its time and I'd probably need some hand-holding... If
someone else wants to do it, that would be fine with me.]


-- 
Joost Kremers
Life has its moments

Re: Better handling of window margins

[martin rudalics]

 > * Amend `set-window-margins' to take two additional parameters:
 >
 >    (set-window-margins WINDOW LEFT-WIDTH &optional RIGHT-WIDTH SYM DYNAMIC)
 >
 >    SYM is a symbol (chosen by the caller) that identifies the mode that
 >    is setting the margins.

Thinking about this twice, I'd rather leave the arguments of
‘set-window-margins’ alone.  Instead, ‘set-window-margins’ should call a
‘set-window-margins-function’ provided it's defined and delegate the
decision of how to proceed to that function.  The caller would set up
SYM and DYNAMIC directly via ‘window-margins-alist’ before calling
‘set-window-margins’.  And the function specified by
‘set-window-margins-function’ would decide how to process
‘window-margins-alist’.  This way we can easily code all the new parts
in Elisp and at the end have the function specified by
‘set-window-margins-function’ call back ‘set-window-margins’ with
‘set-window-margins-function’ let-bound to nil.

 > * `window-splittable-p' can check the contents of `window-margins-alist'
 >    and use the info to determine whether a window can be split
 >    horizontally: dynamic margins can be adjusted, so the horizontal
 >    splittability should be determined on the basis of text width plus
 >    dynamic margins minus static margins. In the present example:
 >
 >    (+ (- 40 4 2) (- 40 0 0) (window-text-width))
 >
 >    This value would be used instead of (window-width) in the current
 >    implementation of `window-splittable-p'.
 >
 > * If the value of `window-margin-alist' is nil, but the margins are
 >    non-nil, `window-splittable-p' should behave as it does now.
 >
 > * Obviously, `window-splittable-p' (or any function that calls it)
 >    should not update the margins itself. That is up to the modes that use
 >    the margins, using `window-configuration-change-hook'.

That's not sufficient.  We have to incorporate code handling dynamic
margins in practically all functions that resize windows as a whole
(like ‘set-frame-width’, ‘split-window-right’, ‘enlarge-window’ with
second argument non-nil) or only parts of it (like ‘set-window-fringes’
and ‘set-window-scroll-bars’).

For this purpose we have to change ‘window-min-size’ (more precisely
‘window--min-size-1’ or maybe just ‘window-margins’) and things like
WINDOW_MARGINS_WIDTH accordingly.

martin

Re: Better handling of window margins

[Eli Zaretskii]

> From: Joost Kremers <joostkremers@fastmail.fm>
> Date: Tue, 01 Dec 2015 22:28:44 +0100

I think we should consider the 2 issues separately:

 . how can multiple features each display its own stuff in the margins
   without breaking other such features

 . how to split windows that have margins

For the first issue, IMO it isn't enough to specify just one value,
the required margin width.  You need also to specify the width of the
stuff, if any, that is displayed in the margin.  (This will have to be
specified in pixels, because you can display images and pixel-granular
stretches of white space in the margins.)  For example, linum-mode
will specify a margin width of N columns, and display width of the
same N columns in pixels.  By contrast, modes such as writeroom-mode
will specify a margin width of M columns and display width of zero.

So we need to maintain, for each of the 2 margins, a list of elements
of the form:

   (SYMBOL MARGIN-WIDTH DISPLAY-WIDTH)

where SYMBOL is a unique symbol used to identify the request that came
from a specific feature/mode.  We should provide a function to return
this list, or maybe make it the value of a local public variable.  We
should also have a way for a feature to update its request.

Given such a list of requests, we compute the required margin width
using the following simple algorithm:

 . compute maximum of all MARGIN-WIDTH values
 . compute the sum of all DISPLAY-WIDTH values
 . take the maximum of the above two

(I omitted the translation from columns to pixels and back that will
be needed here.)

This solves a large portion of the interference issue, but it still
leaves at least one aspect unsolved: what if some feature wants to
limit the margin width from above?  For example, I presume that
writeroom-mode and its ilk would like to do that, because they want to
keep the text area at some constant width.  But if the width
calculated as above is greater than that, the text area will have no
alternative but to shrink.  Is that acceptable?  Or should we refuse
the request that causes this?  (In the latter case, we will have to
ask each feature to supply one more parameter with its request.)

Now regarding the split-window issue.  I believe we shouldn't try to
second-guess how to split windows in these cases.  Instead, we should
place the burden of doing TRT on the modes.  Specifically:

 . for splitting the window with "C-x 2" and "C-x 3", the mode could
   simply invoke the correct splitting function itself

 . for splitting the window as result of some command calling
   display-buffer, we could expect the modes to customize the
   display-buffer-* variables to control how the window is split (if
   there are currently no features/variables to that effect, we should
   add them)

The reason I don't believe in some general-purpose heuristics in this
case is that there's any number of possible needs of modes wrt
margins.  You are trying to classify these into "static" and
"dynamic", but the "dynamic" kind can be something very different from
what writeroom-mode and its ilk need in this regard.  So the
heuristics will fail when we have a mode whose margins are not
"static", but not like writeroom-mode, either.

Does this make sense?

Re: Better handling of window margins

[martin rudalics]

 > For the first issue, IMO it isn't enough to specify just one value,
 > the required margin width.  You need also to specify the width of the
 > stuff, if any, that is displayed in the margin.  (This will have to be
 > specified in pixels, because you can display images and pixel-granular
 > stretches of white space in the margins.)  For example, linum-mode
 > will specify a margin width of N columns, and display width of the
 > same N columns in pixels.

How would this work with scaled text?

 > By contrast, modes such as writeroom-mode
 > will specify a margin width of M columns and display width of zero.
 >
 > So we need to maintain, for each of the 2 margins, a list of elements
 > of the form:
 >
 >     (SYMBOL MARGIN-WIDTH DISPLAY-WIDTH)
 >
 > where SYMBOL is a unique symbol used to identify the request that came
 > from a specific feature/mode.  We should provide a function to return
 > this list, or maybe make it the value of a local public variable.  We
 > should also have a way for a feature to update its request.

This probably has to be a window parameter because at least the
margin-width may differ according to the window the buffer is displayed in.

 > Now regarding the split-window issue.  I believe we shouldn't try to
 > second-guess how to split windows in these cases.  Instead, we should
 > place the burden of doing TRT on the modes.  Specifically:
 >
 >   . for splitting the window with "C-x 2" and "C-x 3", the mode could
 >     simply invoke the correct splitting function itself

When two modes simultaneously use the margins, which splitting function
would be chosen?

 >   . for splitting the window as result of some command calling
 >     display-buffer, we could expect the modes to customize the
 >     display-buffer-* variables to control how the window is split (if
 >     there are currently no features/variables to that effect, we should
 >     add them)

When two modes simultaneously use the margins, which buffer display
function would be chosen?

And how would we handle functions like ‘set-window-fringes’ or
‘set-frame-width’?

martin

Re: Better handling of window margins

[Eli Zaretskii]

> Date: Wed, 02 Dec 2015 18:43:47 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: emacs-devel@gnu.org
> 
>  > For the first issue, IMO it isn't enough to specify just one value,
>  > the required margin width.  You need also to specify the width of the
>  > stuff, if any, that is displayed in the margin.  (This will have to be
>  > specified in pixels, because you can display images and pixel-granular
>  > stretches of white space in the margins.)  For example, linum-mode
>  > will specify a margin width of N columns, and display width of the
>  > same N columns in pixels.
> 
> How would this work with scaled text?

Not sure what problem bothers you.  set-window-margins interpret its
argument as the number of character cells.  Converting from pixels, if
needed, is simple.  If worse comes to worst, the requesting mode can
use the likes of string-width to compute that.

>  >   . for splitting the window with "C-x 2" and "C-x 3", the mode could
>  >     simply invoke the correct splitting function itself
> 
> When two modes simultaneously use the margins, which splitting function
> would be chosen?

It's up to the mode that wants to support splitting in any non-trivial
manner.  The mode knows exactly what are its needs, so it is free of
the guesswork.

In any case, the same problem exists if this is somehow guessed.  The
infrastructure cannot know enough about the modes to make a decision.

>  >   . for splitting the window as result of some command calling
>  >     display-buffer, we could expect the modes to customize the
>  >     display-buffer-* variables to control how the window is split (if
>  >     there are currently no features/variables to that effect, we should
>  >     add them)
> 
> When two modes simultaneously use the margins, which buffer display
> function would be chosen?

The same problem exists with the proposed solution, doesn't it?

> And how would we handle functions like ‘set-window-fringes’ or
> ‘set-frame-width’?

Hey, one problem at a time, please!

Re: Better handling of window margins

[martin rudalics]

 >>   > For example, linum-mode
 >>   > will specify a margin width of N columns, and display width of the
 >>   > same N columns in pixels.
 >>
 >> How would this work with scaled text?
 >
 > Not sure what problem bothers you.

You say that linum-mode will specify a "display width of the same N
columns in pixels".  How would it react to an increase of the width of
the default face?  IIUC this is not covered by any special hook so it
has to be done via ‘post-command-hook’.  No great deal but it shows that
‘post-command-hook’ is indispensable for such modes.

 > set-window-margins interpret its
 > argument as the number of character cells.  Converting from pixels, if
 > needed, is simple.  If worse comes to worst, the requesting mode can
 > use the likes of string-width to compute that.
 >
 >>   >   . for splitting the window with "C-x 2" and "C-x 3", the mode could
 >>   >     simply invoke the correct splitting function itself
 >>
 >> When two modes simultaneously use the margins, which splitting function
 >> would be chosen?
 >
 > It's up to the mode that wants to support splitting in any non-trivial
 > manner.  The mode knows exactly what are its needs, so it is free of
 > the guesswork.

So you mean there's no need for any new infrastructure here - the
‘split-window’ window parameter can take care of this.

 > In any case, the same problem exists if this is somehow guessed.  The
 > infrastructure cannot know enough about the modes to make a decision.
 >
 >>   >   . for splitting the window as result of some command calling
 >>   >     display-buffer, we could expect the modes to customize the
 >>   >     display-buffer-* variables to control how the window is split (if
 >>   >     there are currently no features/variables to that effect, we should
 >>   >     add them)
 >>
 >> When two modes simultaneously use the margins, which buffer display
 >> function would be chosen?
 >
 > The same problem exists with the proposed solution, doesn't it?

Is there one?

martin

Re: Better handling of window margins

[Eli Zaretskii]

> Date: Wed, 02 Dec 2015 19:11:13 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: joostkremers@fastmail.fm, emacs-devel@gnu.org
> 
>  >>   > For example, linum-mode
>  >>   > will specify a margin width of N columns, and display width of the
>  >>   > same N columns in pixels.
>  >>
>  >> How would this work with scaled text?
>  >
>  > Not sure what problem bothers you.
> 
> You say that linum-mode will specify a "display width of the same N
> columns in pixels".  How would it react to an increase of the width of
> the default face?

How is it covered today?

> IIUC this is not covered by any special hook so it has to be done
> via ‘post-command-hook’.  No great deal but it shows that
> ‘post-command-hook’ is indispensable for such modes.

Even if this conclusion is correct, is it really relevant to the
concrete issue being discussed?  If the only problems we could think
about, after my suggested solution is implemented, are the ones that
don't have any good solution now, it means the main problem -- how to
allow several features request display margins without stomping on
each other's toes -- is most probably solved.  Then the other problems
should be considered and solutions for them sought.

IOW, what I suggested wasn't supposed to solve any problem except one:
how can several features display simultaneously on the same display
margin.  It wasn't supposed magically solve other related or unrelated
problems.

>  >>   >   . for splitting the window with "C-x 2" and "C-x 3", the mode could
>  >>   >     simply invoke the correct splitting function itself
>  >>
>  >> When two modes simultaneously use the margins, which splitting function
>  >> would be chosen?
>  >
>  > It's up to the mode that wants to support splitting in any non-trivial
>  > manner.  The mode knows exactly what are its needs, so it is free of
>  > the guesswork.
> 
> So you mean there's no need for any new infrastructure here - the
> ‘split-window’ window parameter can take care of this.

I simply don't believe there could be a generic solution that doesn't
involve active participation of the modes that are affected by this.

>  > In any case, the same problem exists if this is somehow guessed.  The
>  > infrastructure cannot know enough about the modes to make a decision.
>  >
>  >>   >   . for splitting the window as result of some command calling
>  >>   >     display-buffer, we could expect the modes to customize the
>  >>   >     display-buffer-* variables to control how the window is split (if
>  >>   >     there are currently no features/variables to that effect, we should
>  >>   >     add them)
>  >>
>  >> When two modes simultaneously use the margins, which buffer display
>  >> function would be chosen?
>  >
>  > The same problem exists with the proposed solution, doesn't it?
> 
> Is there one?

Of course: imagine that the effects of 2 or more elements of the list
contradict each other.  Which one to choose?

Re: Better handling of window margins

[martin rudalics]

 >> You say that linum-mode will specify a "display width of the same N
 >> columns in pixels".  How would it react to an increase of the width of
 >> the default face?
 >
 > How is it covered today?

Via ‘post-command-hook’ I suppose.

 >> IIUC this is not covered by any special hook so it has to be done
 >> via ‘post-command-hook’.  No great deal but it shows that
 >> ‘post-command-hook’ is indispensable for such modes.
 >
 > Even if this conclusion is correct, is it really relevant to the
 > concrete issue being discussed?

Hopefully.  If we want to get rid of ‘post-command-hook’ dependencies.
If we don't care, it's obviously not relevant.

 > If the only problems we could think
 > about, after my suggested solution is implemented, are the ones that
 > don't have any good solution now, it means the main problem -- how to
 > allow several features request display margins without stomping on
 > each other's toes -- is most probably solved.  Then the other problems
 > should be considered and solutions for them sought.
 >
 > IOW, what I suggested wasn't supposed to solve any problem except one:
 > how can several features display simultaneously on the same display
 > margin.  It wasn't supposed magically solve other related or unrelated
 > problems.

How does the ability to specify a margin size in pixels help to display
several features simultaneously?  I'm all for specifying margin sizes in
pixels.  But then I have no idea why we should keep the "character cell
units" specification.  And obviously a transit to pixel specification
has its price.

 >> So you mean there's no need for any new infrastructure here - the
 >> ‘split-window’ window parameter can take care of this.
 >
 > I simply don't believe there could be a generic solution that doesn't
 > involve active participation of the modes that are affected by this.

If modes can specify their needs for each window they act on, the
overhead will be encapsulated in calculating a window's minimum width.
If we can't manage that, then modes will also have to intervene every
time we set a window's fringes or scroll-bar width or adjust its right
trailing edge.  I'm afraid that mode authors won't want to do that.

 >>   >> When two modes simultaneously use the margins, which buffer display
 >>   >> function would be chosen?
 >>   >
 >>   > The same problem exists with the proposed solution, doesn't it?
 >>
 >> Is there one?
 >
 > Of course: imagine that the effects of 2 or more elements of the list
 > contradict each other.  Which one to choose?

I thought Joost's idea was to capture this issue by having
‘window-splittable-p’ count static margins only.  So I don't see any
contradiction.

martin

Re: Better handling of window margins

[Eli Zaretskii]

> Date: Thu, 03 Dec 2015 19:16:26 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: joostkremers@fastmail.fm, emacs-devel@gnu.org
> 
>  >> You say that linum-mode will specify a "display width of the same N
>  >> columns in pixels".  How would it react to an increase of the width of
>  >> the default face?
>  >
>  > How is it covered today?
> 
> Via ‘post-command-hook’ I suppose.
> 
>  >> IIUC this is not covered by any special hook so it has to be done
>  >> via ‘post-command-hook’.  No great deal but it shows that
>  >> ‘post-command-hook’ is indispensable for such modes.
>  >
>  > Even if this conclusion is correct, is it really relevant to the
>  > concrete issue being discussed?
> 
> Hopefully.  If we want to get rid of ‘post-command-hook’ dependencies.

My suggestion wasn't supposed to do anything about post-command-hook.
It aimed only at allowing separate features display in the margins
without interfering with one another.

>  > IOW, what I suggested wasn't supposed to solve any problem except one:
>  > how can several features display simultaneously on the same display
>  > margin.  It wasn't supposed magically solve other related or unrelated
>  > problems.
> 
> How does the ability to specify a margin size in pixels help to display
> several features simultaneously?

Size in pixels is not the main part of what I proposed.  I only
mentioned pixels because the margins can display images, and there's
no easy way of knowing how many columns an image will take.

The main part of my proposal is that each request for a window margin
will specify both the margin size and the size of the stuff that will
be displayed there.  Two values, not one.

>  >> So you mean there's no need for any new infrastructure here - the
>  >> ‘split-window’ window parameter can take care of this.
>  >
>  > I simply don't believe there could be a generic solution that doesn't
>  > involve active participation of the modes that are affected by this.
> 
> If modes can specify their needs for each window they act on, the
> overhead will be encapsulated in calculating a window's minimum width.

How can you encapsulate what an unknown mode will want to do?

> If we can't manage that, then modes will also have to intervene every
> time we set a window's fringes or scroll-bar width or adjust its right
> trailing edge.  I'm afraid that mode authors won't want to do that.

Sorry, you lost me.  What do fringes and scroll bars have in common
with the issue at point?  Do you envision a window with 20-column wide
fringes or something?

>  >>   >> When two modes simultaneously use the margins, which buffer display
>  >>   >> function would be chosen?
>  >>   >
>  >>   > The same problem exists with the proposed solution, doesn't it?
>  >>
>  >> Is there one?
>  >
>  > Of course: imagine that the effects of 2 or more elements of the list
>  > contradict each other.  Which one to choose?
> 
> I thought Joost's idea was to capture this issue by having
> ‘window-splittable-p’ count static margins only.  So I don't see any
> contradiction.

It makes little sense to me to solve a small portion of a problem.

Re: Better handling of window margins

[Stefan Monnier]

> My suggestion wasn't supposed to do anything about post-command-hook.
> It aimed only at allowing separate features display in the margins
> without interfering with one another.

WRT to sizing the margin, I think if we want to "do it right" it'd make
sense to provide an Elisp-layer that defines two functions which could
look like:

   (window-margin-register OWNER SIZING-DESCRIPTOR)

and

   (window-margin-unregister OWNER)

so those two functions can appropriately combine the SIZING-DESCRIPTORS
still active.

Not sure what SIZING-DESCRIPTOR should look like (it could be
a function which takes a size and returns a new size).


        Stefan

Re: Better handling of window margins

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Thu, 03 Dec 2015 15:43:34 -0500
> 
> > My suggestion wasn't supposed to do anything about post-command-hook.
> > It aimed only at allowing separate features display in the margins
> > without interfering with one another.
> 
> WRT to sizing the margin, I think if we want to "do it right" it'd make
> sense to provide an Elisp-layer that defines two functions which could
> look like:
> 
>    (window-margin-register OWNER SIZING-DESCRIPTOR)
> 
> and
> 
>    (window-margin-unregister OWNER)
> 
> so those two functions can appropriately combine the SIZING-DESCRIPTORS
> still active.

Not sure why window-margin-register and window-margin-unregister
couldn't be set-window-margins with additional arguments.

> Not sure what SIZING-DESCRIPTOR should look like (it could be
> a function which takes a size and returns a new size).

I don't think such a function can be implemented by any particular
mode, because a mode only knows well what it needs from the margins,
it has no better idea about other modes' needs than the rest of Emacs.

Given the SIZING-DESCRIPTOR I suggested, it's trivial to determine how
wide the margins should be at any given time in order to accommodate
the needs of all the modes that requested screen estate in the
margins.  So we can do that without asking modes to provide their
functions for it.  To say nothing of the fact that having more than
one function again raises a problem of in what order to apply them,
and what would be the results of applying conflicting functions in any
order.

Re: Better handling of window margins

[Stefan Monnier]

>> WRT to sizing the margin, I think if we want to "do it right" it'd make
>> sense to provide an Elisp-layer that defines two functions which could
>> look like:
>>    (window-margin-register OWNER SIZING-DESCRIPTOR)
>> and
>>    (window-margin-unregister OWNER)
>> so those two functions can appropriately combine the SIZING-DESCRIPTORS
>> still active.
> Not sure why window-margin-register and window-margin-unregister
> couldn't be set-window-margins with additional arguments.

Because we want this to be flexible, so it's better written in Elisp, so
it's an extra layer, so it's another function.  set-window-margins then
becomes an internal function that we'd encourage people to stop using.

>> Not sure what SIZING-DESCRIPTOR should look like (it could be
>> a function which takes a size and returns a new size).
> I don't think such a function can be implemented by any particular
> mode, because a mode only knows well what it needs from the margins,
> it has no better idea about other modes' needs than the rest of Emacs.

That's the point of having SIZING-DESCRIPTOR be a function: it receives
a description of the margin chosen by "all other users" and adjusts it
according to its own needs.

> functions for it.  To say nothing of the fact that having more than
> one function again raises a problem of in what order to apply them,
> and what would be the results of applying conflicting functions in any
> order.

We'd push this responsibility on the package authors.
If SIZING-DESCRIPTOR just returns the sum (or the max) of the provided
size and its own use, ordering doesn't matter, for example.
And for the remaining cases we could rely on add-function's `depth' to
impose a particular ordering.


        Stefan

Re: Better handling of window margins

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Fri, 04 Dec 2015 08:22:26 -0500
> 
> >> Not sure what SIZING-DESCRIPTOR should look like (it could be
> >> a function which takes a size and returns a new size).
> > I don't think such a function can be implemented by any particular
> > mode, because a mode only knows well what it needs from the margins,
> > it has no better idea about other modes' needs than the rest of Emacs.
> 
> That's the point of having SIZING-DESCRIPTOR be a function: it receives
> a description of the margin chosen by "all other users" and adjusts it
> according to its own needs.

Then that function is not specific to any particular user of the
margin, and so Emacs could just always use that code, instead of
asking the users of the margins to explicitly request that.

> > functions for it.  To say nothing of the fact that having more than
> > one function again raises a problem of in what order to apply them,
> > and what would be the results of applying conflicting functions in any
> > order.
> 
> We'd push this responsibility on the package authors.

They won't know what to do with that, I think.

> If SIZING-DESCRIPTOR just returns the sum (or the max) of the provided
> size and its own use, ordering doesn't matter, for example.
> And for the remaining cases we could rely on add-function's `depth' to
> impose a particular ordering.

IIUC what you mean by "ordering", it cannot be controlled anyway, not
without non-trivial changes in the display engine.

Re: Better handling of window margins

[Stefan Monnier]

>> That's the point of having SIZING-DESCRIPTOR be a function: it receives
>> a description of the margin chosen by "all other users" and adjusts it
>> according to its own needs.
> Then that function is not specific to any particular user of the margin,

To me it's obvious that it is specific.  So I think I lost you.

>> If SIZING-DESCRIPTOR just returns the sum (or the max) of the provided
>> size and its own use, ordering doesn't matter, for example.
>> And for the remaining cases we could rely on add-function's `depth' to
>> impose a particular ordering.
> IIUC what you mean by "ordering", it cannot be controlled anyway, not
> without non-trivial changes in the display engine.

Yep, I definitely lost you, because the way I see it the display engine
has nothing to do with this.

Here's the scenario I have in mind:

Basically, package A uses the margin to place a few things in it.  So it
needs a left margin that at least X pixels wide so its goodies
are visible (i.e. its function will return the max between X and
whatever else is decided).

Then comes package B which uses that same margin for other things of
size Y.  Since its other things are placed elsewhere, it requests that
the margin be the max of Y and whatever else is decided.

Then comes package C which adds something of size Z to every line in
that same margin.  So it requests (with "depth") to be placed
last, and its function returns the sum of Z and whatever else
is decided.


        Stefan


PS: Clearly, this is related to the issue of how to share the margin
itself (rather than how to cooperate in setting the margin's width).
Currently, this is done arbitrarily by the display engine, but we should
instead provide new functions which perform this combination in Elisp
and then place a single `display' property for the margin.

Re: Better handling of window margins

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Fri, 04 Dec 2015 12:30:21 -0500
> 
> >> That's the point of having SIZING-DESCRIPTOR be a function: it receives
> >> a description of the margin chosen by "all other users" and adjusts it
> >> according to its own needs.
> > Then that function is not specific to any particular user of the margin,
> 
> To me it's obvious that it is specific.  So I think I lost you.

If the function needs to consider what other modes want, it is not
mode specific.  It should know enough about any other possible modes
that could need the margins.  Such functions should be provided by the
infrastructure, since no mode author is wiser than the Emacs
maintainers.

> Basically, package A uses the margin to place a few things in it.  So it
> needs a left margin that at least X pixels wide so its goodies
> are visible (i.e. its function will return the max between X and
> whatever else is decided).
> 
> Then comes package B which uses that same margin for other things of
> size Y.  Since its other things are placed elsewhere, it requests that
> the margin be the max of Y and whatever else is decided.
> 
> Then comes package C which adds something of size Z to every line in
> that same margin.  So it requests (with "depth") to be placed
> last, and its function returns the sum of Z and whatever else
> is decided.

My suggestion was to ask each package to provide 2 numbers, not one.
You provided only one for each package, so I don't know how to
interpret this within the model that I described.

(I also don't understand the "displayed elsewhere" part of package B.
What does "elsewhere" mean here?  Is that stuff displayed on the
margins or not?)

If you are saying that both numbers are the same for each of the
packages in your scenario, then the result under my suggestion will be
X+Y+Z, and we don't need to rely on any package for this wisdom, or
request them to understand how we allocate space for the margins.

> PS: Clearly, this is related to the issue of how to share the margin
> itself (rather than how to cooperate in setting the margin's width).

Under the model I suggested, the two parameters determine both the
margin width and how that width is shared.

> Currently, this is done arbitrarily by the display engine, but we should
> instead provide new functions which perform this combination in Elisp
> and then place a single `display' property for the margin.

How can you provide a single display property when the original
properties are in different buffer locations?  (I also don't
understand why should we bother to produce a single property, but
that's a separate issue.)

Re: Better handling of window margins

[Stefan Monnier]

>> Basically, package A uses the margin to place a few things in it.  So it
>> needs a left margin that at least X pixels wide so its goodies
>> are visible (i.e. its function will return the max between X and
>> whatever else is decided).
>> 
>> Then comes package B which uses that same margin for other things of
>> size Y.  Since its other things are placed elsewhere, it requests that
>> the margin be the max of Y and whatever else is decided.
>> 
>> Then comes package C which adds something of size Z to every line in
>> that same margin.  So it requests (with "depth") to be placed
>> last, and its function returns the sum of Z and whatever else
>> is decided.

> My suggestion was to ask each package to provide 2 numbers, not one.

Each package above knows (internally) a single number in this case, but
it does not provide it.  It only provides a function which combines this
number with the one it gets from the rest.

> (I also don't understand the "displayed elsewhere" part of package B.
> What does "elsewhere" mean here?  Is that stuff displayed on the
> margins or not?)

It means that package A and B place their things on different lines, so
the needed margin size is the max of X and Y rather than the sum.

> If you are saying that both numbers are the same for each of the
> packages in your scenario, then the result under my suggestion will be
> X+Y+Z, and we don't need to rely on any package for this wisdom, or
> request them to understand how we allocate space for the margins.

That would be too wide a margin in my example where we'd want
(+ (max X Y) Z) instead.

>> Currently, this is done arbitrarily by the display engine, but we should
>> instead provide new functions which perform this combination in Elisp
>> and then place a single `display' property for the margin.
> How can you provide a single display property when the original
> properties are in different buffer locations?

You can't.  But if you need to share those two properties, it means
they're displayed at the same place, which also means that maybe they
don't need to be in different buffer location.
At least, that's my assumption.


        Stefan

Re: Better handling of window margins

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Fri, 04 Dec 2015 15:55:59 -0500
> 
> > My suggestion was to ask each package to provide 2 numbers, not one.
> 
> Each package above knows (internally) a single number in this case, but
> it does not provide it.  It only provides a function which combines this
> number with the one it gets from the rest.

That's a different proposal.  I think it's more complex, and don't
quite see the need for the added complexity.

> > (I also don't understand the "displayed elsewhere" part of package B.
> > What does "elsewhere" mean here?  Is that stuff displayed on the
> > margins or not?)
> 
> It means that package A and B place their things on different lines, so
> the needed margin size is the max of X and Y rather than the sum.

How can we know that they will never try to display anything on the
same screen line?  How can the packages themselves know that?

> > How can you provide a single display property when the original
> > properties are in different buffer locations?
> 
> You can't.  But if you need to share those two properties, it means
> they're displayed at the same place, which also means that maybe they
> don't need to be in different buffer location.
> At least, that's my assumption.

I don't see how that assumption could be a valid one.  Imagine a
buffer with linum-mode turned on, and an (imaginary) package that
displays in the margin short notes to specific places in the buffer.
The buffer position that correspond to the notes must be obeyed, or
else editing the buffer will not move the notes as expected.

Re: Better handling of window margins

[Stefan Monnier]

>> It means that package A and B place their things on different lines, so
>> the needed margin size is the max of X and Y rather than the sum.
> How can the packages themselves know that?

Good question.  Presumably they'd need to detect when they add
a display-margin element somewhere where there is already another
such element.

>> You can't.  But if you need to share those two properties, it means
>> they're displayed at the same place, which also means that maybe they
>> don't need to be in different buffer location.
>> At least, that's my assumption.
> I don't see how that assumption could be a valid one.  Imagine a
> buffer with linum-mode turned on, and an (imaginary) package that
> displays in the margin short notes to specific places in the buffer.
> The buffer position that correspond to the notes must be obeyed, or
> else editing the buffer will not move the notes as expected.

I'm not sure whether we can handle well all possible cases, indeed.
But if we design an API where the elements are always associated with
lines rather than with precise buffer positions, it should
be manageable.  Maybe this API will be inconvenient for some use cases,
of course.


        Stefan

Re: Better handling of window margins

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Fri, 04 Dec 2015 16:33:00 -0500
> 
> >> It means that package A and B place their things on different lines, so
> >> the needed margin size is the max of X and Y rather than the sum.
> > How can the packages themselves know that?
> 
> Good question.  Presumably they'd need to detect when they add
> a display-margin element somewhere where there is already another
> such element.

It is much simpler to assume that each one of the packages displays
something in the margin on each screen line, at least potentially.  It
wastes some screen real estate, but it will never fail to show what
the packages want to display.

> >> You can't.  But if you need to share those two properties, it means
> >> they're displayed at the same place, which also means that maybe they
> >> don't need to be in different buffer location.
> >> At least, that's my assumption.
> > I don't see how that assumption could be a valid one.  Imagine a
> > buffer with linum-mode turned on, and an (imaginary) package that
> > displays in the margin short notes to specific places in the buffer.
> > The buffer position that correspond to the notes must be obeyed, or
> > else editing the buffer will not move the notes as expected.
> 
> I'm not sure whether we can handle well all possible cases, indeed.
> But if we design an API where the elements are always associated with
> lines rather than with precise buffer positions, it should
> be manageable.  Maybe this API will be inconvenient for some use cases,
> of course.

Once again, my proposal handles this for all cases.  So I think it's a
good starting point.

Re: Better handling of window margins

[Stefan Monnier]

>> I'm not sure whether we can handle well all possible cases, indeed.
>> But if we design an API where the elements are always associated with
>> lines rather than with precise buffer positions, it should
>> be manageable.  Maybe this API will be inconvenient for some use cases,
>> of course.
> Once again, my proposal handles this for all cases.

AFAIK your proposal is unrelated because it only affects the size of the
display margin, whereas part of the issue is to control ordering of
mergin elements on specific lines.


        Stefan

Re: Better handling of window margins

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org
> Date: Sat, 05 Dec 2015 10:17:42 -0500
> 
> >> I'm not sure whether we can handle well all possible cases, indeed.
> >> But if we design an API where the elements are always associated with
> >> lines rather than with precise buffer positions, it should
> >> be manageable.  Maybe this API will be inconvenient for some use cases,
> >> of course.
> > Once again, my proposal handles this for all cases.
> 
> AFAIK your proposal is unrelated because it only affects the size of the
> display margin, whereas part of the issue is to control ordering of
> mergin elements on specific lines.

Indeed, control of the ordering was not on the table, AFAIU.

If we want to be able to control the order, we will have to completely
redesign how display in the margins works, because currently this is
completely determined by the order we traverse the buffer text during
redisplay, i.e. the 'margin' display property that is on buffer
position displayed more to the left will be displayed before the one
to its right.

Re: Better handling of window margins

[Stefan Monnier]

> If we want to be able to control the order, we will have to completely
> redesign how display in the margins works, because currently this is
> completely determined by the order we traverse the buffer text during
> redisplay, i.e. the 'margin' display property that is on buffer
> position displayed more to the left will be displayed before the one
> to its right.

Yes, and it's for this problem that I suggest we introduce a new Elisp
API to manage margin display properties (and make the API be
line-based).


        Stefan

Re: Better handling of window margins

[John Wiegley]

>>>>> Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> If we want to be able to control the order, we will have to completely
>> redesign how display in the margins works, because currently this is
>> completely determined by the order we traverse the buffer text during
>> redisplay, i.e. the 'margin' display property that is on buffer position
>> displayed more to the left will be displayed before the one to its right.

> Yes, and it's for this problem that I suggest we introduce a new Elisp API
> to manage margin display properties (and make the API be line-based).

Do we really want to make margins more capable like this, or is there a better
way to approach this problem? Margins are just one aspect of a window's
overall display. It would be nice to have control over arbitrary regions
within the total window area. This could serve to better unify fringes and
margins, for example.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Better handling of window margins

[Eli Zaretskii]

> From: John Wiegley <jwiegley@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
> Date: Sat, 05 Dec 2015 21:02:04 -0800
> 
> >>>>> Stefan Monnier <monnier@iro.umontreal.ca> writes:
> 
> >> If we want to be able to control the order, we will have to completely
> >> redesign how display in the margins works, because currently this is
> >> completely determined by the order we traverse the buffer text during
> >> redisplay, i.e. the 'margin' display property that is on buffer position
> >> displayed more to the left will be displayed before the one to its right.
> 
> > Yes, and it's for this problem that I suggest we introduce a new Elisp API
> > to manage margin display properties (and make the API be line-based).
> 
> Do we really want to make margins more capable like this, or is there a better
> way to approach this problem?

Good question.  I don't know.  In fact, I find it hard to define the
problem we are trying to solve.

What I suggested should allow several packages displaying in the
margin without interfering with each other.  That is already a
solution that looks for a problem, since the most complex use case I'm
aware of involves one package that displays in the margin and another
that just needs the margins to be of certain width, but doesn't
display anything there.

Now we are talking about going even farther into the fantasy land, and
imagine packages that also want to control the order with which their
stuff is displayed in the margins.  Sounds like over-engineering to
me, but if someone can show such packages, perhaps it's not fantasy
after all.

Re: Better handling of window margins

[Yuri Khan]

On Sun, Dec 6, 2015 at 10:10 PM, Eli Zaretskii <eliz@gnu.org> wrote:

> What I suggested should allow several packages displaying in the
> margin without interfering with each other.  That is already a
> solution that looks for a problem, since the most complex use case I'm
> aware of involves one package that displays in the margin and another
> that just needs the margins to be of certain width, but doesn't
> display anything there.

I can name several uses for the margin off the top of my head:

* Line numbers
* Bookmark markers (name(s) of register(s) which contain locations in this line)
* Modification bars (which might display one marker on lines modified
since the last save, another marker on lines which differ from the
staged state, and yet another for differences from last commit)
* Outlining widgets (collapse/expand whichever syntax constructs the
current mode defines)
* Breakpoints and current statement (which currently display in the
fringe but the fringe is limited)
* Lines that contain errors found during the last compilation
* Lines that contain matches found during the last grep
* “git blame” annotations
* Test coverage (or lack thereof) markers

> Now we are talking about going even farther into the fantasy land, and
> imagine packages that also want to control the order with which their
> stuff is displayed in the margins.  Sounds like over-engineering to
> me, but if someone can show such packages, perhaps it's not fantasy
> after all.

IMO packages shouldn’t want to — not without knowing a great deal
about each other. The user, on the other hand, should be able to. A
simple priority map or a list of modes ordered by priority might be
sufficient.

Re: Better handling of window margins

[Eli Zaretskii]

> From: Yuri Khan <yuri.v.khan@gmail.com>
> Date: Mon, 7 Dec 2015 02:24:26 +0600
> Cc: John Wiegley <jwiegley@gmail.com>, Stefan Monnier <monnier@iro.umontreal.ca>, 
> 	Emacs developers <emacs-devel@gnu.org>
> 
> On Sun, Dec 6, 2015 at 10:10 PM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> I can name several uses for the margin off the top of my head:
> 
> * Line numbers
> * Bookmark markers (name(s) of register(s) which contain locations in this line)
> * Modification bars (which might display one marker on lines modified
> since the last save, another marker on lines which differ from the
> staged state, and yet another for differences from last commit)
> * Outlining widgets (collapse/expand whichever syntax constructs the
> current mode defines)
> * Breakpoints and current statement (which currently display in the
> fringe but the fringe is limited)
> * Lines that contain errors found during the last compilation
> * Lines that contain matches found during the last grep
> * “git blame” annotations
> * Test coverage (or lack thereof) markers

Can you name Emacs packages that implement those?  (The first item
excluded, of course.)

> > Now we are talking about going even farther into the fantasy land, and
> > imagine packages that also want to control the order with which their
> > stuff is displayed in the margins.  Sounds like over-engineering to
> > me, but if someone can show such packages, perhaps it's not fantasy
> > after all.
> 
> IMO packages shouldn’t want to — not without knowing a great deal
> about each other. The user, on the other hand, should be able to. A
> simple priority map or a list of modes ordered by priority might be
> sufficient.

If there are no packages that use the margins except the 2 classes
mentioned here, then this user preference is for now theoretical.

Re: Better handling of window margins

[Yuri Khan]

On Mon, Dec 7, 2015 at 9:32 AM, Eli Zaretskii <eliz@gnu.org> wrote:

> Can you name Emacs packages that implement those?  (The first item
> excluded, of course.)

>> * Modification bars (which might display one marker on lines modified
>> since the last save, another marker on lines which differ from the
>> staged state, and yet another for differences from last commit)

[git-gutter.el by Syohei Yoshida]
(https://github.com/syohex/emacs-git-gutter)

>> * “git blame” annotations

git-blame.el distributed with Git — currently emulates margins using overlays.

Re: Better handling of window margins

[Eli Zaretskii]

> From: Yuri Khan <yuri.v.khan@gmail.com>
> Date: Mon, 7 Dec 2015 16:35:06 +0600
> Cc: John Wiegley <jwiegley@gmail.com>, Stefan Monnier <monnier@iro.umontreal.ca>, 
> 	Emacs developers <emacs-devel@gnu.org>
> 
> On Mon, Dec 7, 2015 at 9:32 AM, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> > Can you name Emacs packages that implement those?  (The first item
> > excluded, of course.)
> 
> >> * Modification bars (which might display one marker on lines modified
> >> since the last save, another marker on lines which differ from the
> >> staged state, and yet another for differences from last commit)
> 
> [git-gutter.el by Syohei Yoshida]
> (https://github.com/syohex/emacs-git-gutter)
> 
> >> * “git blame” annotations
> 
> git-blame.el distributed with Git — currently emulates margins using overlays.

Thanks.  (But why do you say git-blame "emulates margins"?  It seems
like it uses line-prefix property entirely on purpose.)

These two fit well into the scheme I proposed.  Moreover, they both
display information that is per-line, i.e. not tied to any particular
buffer position, but to a whole line.  For such use cases, we already
have a way to control the order of display in the margin: the overlay
priority.  If all the packages put an overlay with a before-string
having the 'margin' display spec before the first character on the
line, then their stuff will be displayed in the order of the overlay
priorities.

Re: Better handling of window margins

[John Wiegley]

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

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

> Now we are talking about going even farther into the fantasy land, and
> imagine packages that also want to control the order with which their stuff
> is displayed in the margins. Sounds like over-engineering to me, but if
> someone can show such packages, perhaps it's not fantasy after all.

If the driving force behind this discussion is the inability of linum.el and
darkroom.el to play together, then I'm simply OK with them being incompatible
at this stage in Emacs' development.

I would much rather we solve the general case of dealing with window display
overall -- solving the multi-margin problem en passant -- than to invent new
APIs for a specific use case.

It's OK if some things don't work -- even if it feels like they should. It's
better to wait for the right solution, then to scramble for an immediate
half-solution.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 629 bytes --]

Re: Better handling of window margins

[Eli Zaretskii]

> From: John Wiegley <jwiegley@gmail.com>
> Cc: monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Sun, 06 Dec 2015 16:29:01 -0800
> 
> > Now we are talking about going even farther into the fantasy land, and
> > imagine packages that also want to control the order with which their stuff
> > is displayed in the margins. Sounds like over-engineering to me, but if
> > someone can show such packages, perhaps it's not fantasy after all.
> 
> If the driving force behind this discussion is the inability of linum.el and
> darkroom.el to play together, then I'm simply OK with them being incompatible
> at this stage in Emacs' development.

It is driven by inability of _any_ 2 packages to request margin space
without stomping on the other package's needs.

> I would much rather we solve the general case of dealing with window display
> overall -- solving the multi-margin problem en passant -- than to invent new
> APIs for a specific use case.
> 
> It's OK if some things don't work -- even if it feels like they should. It's
> better to wait for the right solution, then to scramble for an immediate
> half-solution.

I don't think we know what _is_ the right solution for the more
general problem.  We don't have any experience and AFAIK no packages
that need such a solution.

Anyway, I'm okay with trying to solve a more general case, if
someone's got that itch, but I'd object to significant changes in the
display engine on behalf of that, unless we have clear use cases that
we want to support.  The display engine already supports a gazillion
minor features, many of which were almost unknown, until some
inquiring minds discovered them, thought they were very cool, and are
using each one of them in a couple of obscure packages, mostly
unbundled, that are very precious to their users.  So now we are in a
situation where no significant cleanups are possible that won't cause
bug reports about broken features, and adding new features is a royal
pain.

So I think we should be very cautious with adding non-trivial display
features, and be sure they have important use cases backing them up
that we want to support for the observable future.

Re: Better handling of window margins

[John Wiegley]

>>>>> Eli Zaretskii <eliz@gnu.org> writes:

>> If the driving force behind this discussion is the inability of linum.el and
>> darkroom.el to play together, then I'm simply OK with them being incompatible
>> at this stage in Emacs' development.

> It is driven by inability of _any_ 2 packages to request margin space
> without stomping on the other package's needs.

Alright, I'm still OK with that not working right now.

> Anyway, I'm okay with trying to solve a more general case, if someone's got
> that itch, but I'd object to significant changes in the display engine on
> behalf of that, unless we have clear use cases that we want to support. The
> display engine already supports a gazillion minor features, many of which
> were almost unknown, until some inquiring minds discovered them, thought
> they were very cool, and are using each one of them in a couple of obscure
> packages, mostly unbundled, that are very precious to their users. So now we
> are in a situation where no significant cleanups are possible that won't
> cause bug reports about broken features, and adding new features is a royal
> pain.

I very much agree. There should be a whole lot more "bang for the buck" before
we make these sorts of changes at this level.

So until we have a comprehensive proposal, from someone willing to pitch in to
find the right solution, we accept that two modules manipulating the margins
are unable to play together.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Better handling of window margins

[Achim Gratz]

John Wiegley writes:
> So until we have a comprehensive proposal, from someone willing to pitch in to
> find the right solution, we accept that two modules manipulating the margins
> are unable to play together.

The mandate should be that the user must be able to tell which
module gets to use the margin, then.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptation for Waldorf microQ V2.22R2:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: Better handling of window margins

[John Wiegley]

>>>>> Achim Gratz <Stromeko@nexgo.de> writes:

>> So until we have a comprehensive proposal, from someone willing to pitch in
>> to find the right solution, we accept that two modules manipulating the
>> margins are unable to play together.

> The mandate should be that the user must be able to tell which module gets
> to use the margin, then.

I don't see why that is necessary. Multiple margin use is simply undefined
territory at the moment; we make no guarantees. What it does mean is that we
should ensure it cannot happen using core modules, at least not without some
kind of notification of the problem.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Better handling of window margins

[Achim Gratz]

John Wiegley writes:
>>>>>> Achim Gratz <Stromeko@nexgo.de> writes:
>
>>> So until we have a comprehensive proposal, from someone willing to pitch in
>>> to find the right solution, we accept that two modules manipulating the
>>> margins are unable to play together.
>
>> The mandate should be that the user must be able to tell which module gets
>> to use the margin, then.
>
> I don't see why that is necessary. Multiple margin use is simply undefined
> territory at the moment; we make no guarantees. What it does mean is that we
> should ensure it cannot happen using core modules, at least not without some
> kind of notification of the problem.

If only one module can have the margin, then it should be able to cope
without it if it's already used.  By extension, a user wishing to use
two such modules should be able to tell which one wins.


Regards,
Achim.
-- 
+<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+

SD adaptations for Waldorf Q V3.00R3 and Q+ V3.54R2:
http://Synth.Stromeko.net/Downloads.html#WaldorfSDada

Re: Better handling of window margins

[Stefan Monnier]

> I don't think we know what _is_ the right solution for the more
> general problem.  We don't have any experience and AFAIK no packages
> that need such a solution.

It's a bit of a cats&dog situation, tho.  The conflicts with other
packages are a strong deterrent to the use of the margin.

> So I think we should be very cautious with adding non-trivial display
> features, and be sure they have important use cases backing them up
> that we want to support for the observable future.

Which is why I suggested we go with a purely Elisp library layed on
top of the current display features.  That lets us play freely with
various design options.  Contrary to the redisplay code, such a library
will have to do its job at the time the margin-display-properties are
added to the buffer, rather than at the time they're rendered on screen.


        Stefan

Re: Better handling of window margins

[John Wiegley]

>>>>> Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Which is why I suggested we go with a purely Elisp library layed on top of
> the current display features. That lets us play freely with various design
> options. Contrary to the redisplay code, such a library will have to do its
> job at the time the margin-display-properties are added to the buffer,
> rather than at the time they're rendered on screen.

Can this be done totally side-band, without affecting long-standing APIs? If
it's something that could live in ELPA, it would be hard to object to.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Better handling of window margins

[Stefan Monnier]

>> Which is why I suggested we go with a purely Elisp library layed on top of
>> the current display features. That lets us play freely with various design
>> options. Contrary to the redisplay code, such a library will have to do its
>> job at the time the margin-display-properties are added to the buffer,
>> rather than at the time they're rendered on screen.
> Can this be done totally side-band, without affecting long-standing APIs? If
> it's something that could live in ELPA,

Yes, that's the idea.


        Stefan

Re: Better handling of window margins

[John Wiegley]

>>>>> Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Can this be done totally side-band, without affecting long-standing APIs?
>> If it's something that could live in ELPA,

> Yes, that's the idea.

Then I'd be interested to see what you come up with.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Better handling of window margins

[martin rudalics]

 > Size in pixels is not the main part of what I proposed.  I only
 > mentioned pixels because the margins can display images, and there's
 > no easy way of knowing how many columns an image will take.
 >
 > The main part of my proposal is that each request for a window margin
 > will specify both the margin size and the size of the stuff that will
 > be displayed there.  Two values, not one.

OK.

 >> If modes can specify their needs for each window they act on, the
 >> overhead will be encapsulated in calculating a window's minimum width.
 >
 > How can you encapsulate what an unknown mode will want to do?

The unknown mode will have posted its display-width as you suggested.
‘window-min-size’ (better ‘window--min-size-1’) will then, instead of
calling ‘window-margins’, call a function say ‘window-min-margins’ which
returns the sum of the display-widths of all modes that want to display
something in the margins of that window.

 >> If we can't manage that, then modes will also have to intervene every
 >> time we set a window's fringes or scroll-bar width or adjust its right
 >> trailing edge.  I'm afraid that mode authors won't want to do that.
 >
 > Sorry, you lost me.  What do fringes and scroll bars have in common
 > with the issue at point?  Do you envision a window with 20-column wide
 > fringes or something?

No.  I meant that enlarging a fringe by a few pixels or calling
‘adjust-window-trailing-edge’ should probably be allowed to reduce the
margin-width for that window while preserving the display-width of its
margins.  Currently these work by the simple magic that the text area is
usually large enough so it can be shrunk when the window gets resized or
its fringes enlarged.

martin

Re: Better handling of window margins

[Eli Zaretskii]

> Date: Fri, 04 Dec 2015 09:07:56 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: joostkremers@fastmail.fm, emacs-devel@gnu.org
> 
>  >> If modes can specify their needs for each window they act on, the
>  >> overhead will be encapsulated in calculating a window's minimum width.
>  >
>  > How can you encapsulate what an unknown mode will want to do?
> 
> The unknown mode will have posted its display-width as you suggested.
> ‘window-min-size’ (better ‘window--min-size-1’) will then, instead of
> calling ‘window-margins’, call a function say ‘window-min-margins’ which
> returns the sum of the display-widths of all modes that want to display
> something in the margins of that window.

And how will this help in deciding how to split a window, when you
cannot predict how the margins will change (or _whether_ they will
change) as result of the split?

We are still talking about splitting windows here, right?

>  >> If we can't manage that, then modes will also have to intervene every
>  >> time we set a window's fringes or scroll-bar width or adjust its right
>  >> trailing edge.  I'm afraid that mode authors won't want to do that.
>  >
>  > Sorry, you lost me.  What do fringes and scroll bars have in common
>  > with the issue at point?  Do you envision a window with 20-column wide
>  > fringes or something?
> 
> No.  I meant that enlarging a fringe by a few pixels or calling
> ‘adjust-window-trailing-edge’ should probably be allowed to reduce the
> margin-width for that window while preserving the display-width of its
> margins.  Currently these work by the simple magic that the text area is
> usually large enough so it can be shrunk when the window gets resized or
> its fringes enlarged.

OK, but how does this lead to "modes will also have to intervene every
time we set a window's fringes" part?

Re: Better handling of window margins

[martin rudalics]

 > And how will this help in deciding how to split a window, when you
 > cannot predict how the margins will change (or _whether_ they will
 > change) as result of the split?

We never can predict such things.  For ‘linum-mode’ the display-width of
a window's margin will change when you show another buffer in that
window and that other buffer has 10000 lines and the buffer you showed
before has 5.

If ‘split-window’ is supposed to show the buffer of the original window,
the display-width of the margin is not supposed to change.  And that's
everything ‘split-window’ can care about.  If we are going to display
another buffer in the new window, all bets are off.

Years ago I proposed to introduce a function ‘make-window’ which would
accept as argument the buffer of the new window.  ‘make-window’ could
then have determined the minimum width of that window from buffer local
variables of the buffer to show there.  Nobody was interested.

Anyway.  Modes like ‘linum-mode’ which specify the display-width of the
margin in ‘post-command-hook’ could defeat any prediction unless they
provide a function that would allow ‘split-window’ to calculate the
expected display-width of the margin.

 > We are still talking about splitting windows here, right?

And about resizing windows, right?

 >> No.  I meant that enlarging a fringe by a few pixels or calling
 >> ‘adjust-window-trailing-edge’ should probably be allowed to reduce the
 >> margin-width for that window while preserving the display-width of its
 >> margins.  Currently these work by the simple magic that the text area is
 >> usually large enough so it can be shrunk when the window gets resized or
 >> its fringes enlarged.
 >
 > OK, but how does this lead to "modes will also have to intervene every
 > time we set a window's fringes" part?

Because the decision whether we can enlarge the fringes of a window is
also based on the size of the window's margins (see set_window_fringes).
So if a mode should be allowed to affect the behavior of ‘split-window’
based on how it wants its margins to behave in the old or new window, it
should be also allowed to affect the behavior of ‘set-window-fringes’,
for example, by reducing the margin-width when enlarging a fringe.

martin

Re: Better handling of window margins

[Eli Zaretskii]

> Date: Fri, 04 Dec 2015 11:21:22 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: joostkremers@fastmail.fm, emacs-devel@gnu.org
> 
>  > And how will this help in deciding how to split a window, when you
>  > cannot predict how the margins will change (or _whether_ they will
>  > change) as result of the split?
> 
> We never can predict such things.  For ‘linum-mode’ the display-width of
> a window's margin will change when you show another buffer in that
> window and that other buffer has 10000 lines and the buffer you showed
> before has 5.
> 
> If ‘split-window’ is supposed to show the buffer of the original window,
> the display-width of the margin is not supposed to change.  And that's
> everything ‘split-window’ can care about.  If we are going to display
> another buffer in the new window, all bets are off.

I agree.  But if we only care about showing the same buffer case, then
we do really need to consider only the width of the text area when we
decide whether to split horizontally or vertically, right?  Moreover,
even when another buffer is shown in one of the two windows, the
window that continues to display the original buffer should still have
reasonable width of its text area, right?  And the only way to
guarantee the latter is to consider the width of only the text area,
excluding the margins.

>  > We are still talking about splitting windows here, right?
> 
> And about resizing windows, right?

I wasn't aware that resizing windows was part of the use cases
considered by this discussion.  How is it relevant?  What decisions
during resizing depend on the margins?

>  > OK, but how does this lead to "modes will also have to intervene every
>  > time we set a window's fringes" part?
> 
> Because the decision whether we can enlarge the fringes of a window is
> also based on the size of the window's margins (see set_window_fringes).

You mean, when the window is so thin that it cannot allow to be any
thinner?  Yes, but that's a marginal (pun intended) use case.  By
contrast, splitting a window with margins is not.

> So if a mode should be allowed to affect the behavior of ‘split-window’
> based on how it wants its margins to behave in the old or new window, it
> should be also allowed to affect the behavior of ‘set-window-fringes’,
> for example, by reducing the margin-width when enlarging a fringe.

Maybe so, but that's much less important, IMO.

Re: Better handling of window margins

[martin rudalics]

 > I agree.  But if we only care about showing the same buffer case, then
 > we do really need to consider only the width of the text area when we
 > decide whether to split horizontally or vertically, right?  Moreover,
 > even when another buffer is shown in one of the two windows, the
 > window that continues to display the original buffer should still have
 > reasonable width of its text area, right?  And the only way to
 > guarantee the latter is to consider the width of only the text area,
 > excluding the margins.

I miss you here.  This discussion started with the problem that while
modes are able to readjust their margins when a window is split,
‘split-window-sensibly’ won't split the window because it looks only at
the width of the text area.  C-x 3 would fail in the same manner because
it would compare ‘window-min-width’ (whose "value has to accommodate two
text columns as well as margins, fringes, a scroll bar and a right
divider, if present") with a text only area.

 >>   > We are still talking about splitting windows here, right?
 >>
 >> And about resizing windows, right?
 >
 > I wasn't aware that resizing windows was part of the use cases
 > considered by this discussion.  How is it relevant?  What decisions
 > during resizing depend on the margins?

When I split a window I have to shrink the original one.  When I have
two side by side window and want to enlarge one of them I have to shrink
the other one.  So we have to solve the same problem in both cases.

martin

Re: Better handling of window margins

[Eli Zaretskii]

> Date: Fri, 04 Dec 2015 17:56:14 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: joostkremers@fastmail.fm, emacs-devel@gnu.org
> 
>  > I agree.  But if we only care about showing the same buffer case, then
>  > we do really need to consider only the width of the text area when we
>  > decide whether to split horizontally or vertically, right?  Moreover,
>  > even when another buffer is shown in one of the two windows, the
>  > window that continues to display the original buffer should still have
>  > reasonable width of its text area, right?  And the only way to
>  > guarantee the latter is to consider the width of only the text area,
>  > excluding the margins.
> 
> I miss you here.  This discussion started with the problem that while
> modes are able to readjust their margins when a window is split,
> ‘split-window-sensibly’ won't split the window because it looks only at
> the width of the text area.  C-x 3 would fail in the same manner because
> it would compare ‘window-min-width’ (whose "value has to accommodate two
> text columns as well as margins, fringes, a scroll bar and a right
> divider, if present") with a text only area.

"C-x 3" should compare window-min-width with the size of the text area
only.

>  >>   > We are still talking about splitting windows here, right?
>  >>
>  >> And about resizing windows, right?
>  >
>  > I wasn't aware that resizing windows was part of the use cases
>  > considered by this discussion.  How is it relevant?  What decisions
>  > during resizing depend on the margins?
> 
> When I split a window I have to shrink the original one.  When I have
> two side by side window and want to enlarge one of them I have to shrink
> the other one.  So we have to solve the same problem in both cases.

What problem is that?

The problem we need to solve in the split-window case is whether to
split vertically or horizontally.  There's no such problem when
resizing a window.

If you mean the problem when to refuse the resize because the window
is too small, then yes, it should also look at the size of the text
area alone.

Re: Better handling of window margins

[martin rudalics]

 > "C-x 3" should compare window-min-width with the size of the text area
 > only.

Why break the window code?

 >> When I split a window I have to shrink the original one.  When I have
 >> two side by side window and want to enlarge one of them I have to shrink
 >> the other one.  So we have to solve the same problem in both cases.
 >
 > What problem is that?

That of shrinking a window.

 > The problem we need to solve in the split-window case is whether to
 > split vertically or horizontally.

There is no such problem.

 > There's no such problem when
 > resizing a window.
 >
 > If you mean the problem when to refuse the resize because the window
 > is too small, then yes, it should also look at the size of the text
 > area alone.

We started miscommunicating in a strange way.  I'll better leave this
discussion now.  It has become too confusing for me.

martin

Re: Better handling of window margins

[Joost Kremers]

On Wed, Dec 02 2015, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Wed, 02 Dec 2015 18:43:47 +0100
>> From: martin rudalics <rudalics@gmx.at>
>> CC: emacs-devel@gnu.org
>> 
>>  >   . for splitting the window with "C-x 2" and "C-x 3", the mode could
>>  >     simply invoke the correct splitting function itself
>> 
>> When two modes simultaneously use the margins, which splitting function
>> would be chosen?
>
> It's up to the mode that wants to support splitting in any non-trivial
> manner.  The mode knows exactly what are its needs, so it is free of
> the guesswork.
>
> In any case, the same problem exists if this is somehow guessed.  The
> infrastructure cannot know enough about the modes to make a decision.

Speaking as a minor-mode author, I would expect Emacs to provide a
default that handles the known cases in a reasonable manner, the known
cases IMHO being those I described. If someday someone comes up with a
use for the margins that cannot be handled properly, it makes sense to
allow the default to be overridden.

>>  >   . for splitting the window as result of some command calling
>>  >     display-buffer, we could expect the modes to customize the
>>  >     display-buffer-* variables to control how the window is split (if
>>  >     there are currently no features/variables to that effect, we should
>>  >     add them)
>> 
>> When two modes simultaneously use the margins, which buffer display
>> function would be chosen?
>
> The same problem exists with the proposed solution, doesn't it?

If the value of `set-window-margins-function' is a single function, then
probably the function provided by the last mode to be activated in a
buffer.

Isn't that a potential problem?

-- 
Joost Kremers
Life has its moments

Re: Better handling of window margins

[Eli Zaretskii]

> From: Joost Kremers <joostkremers@fastmail.fm>
> Cc: martin rudalics <rudalics@gmx.at>, emacs-devel@gnu.org
> Date: Wed, 02 Dec 2015 20:52:51 +0100
> 
> > In any case, the same problem exists if this is somehow guessed.  The
> > infrastructure cannot know enough about the modes to make a decision.
> 
> Speaking as a minor-mode author, I would expect Emacs to provide a
> default that handles the known cases in a reasonable manner, the known
> cases IMHO being those I described.

If we are fairly sure these 2 use cases cover most of the ground,
perhaps.  Are we sure?  If we aren't, then building non-trivial
infrastructure tailored to just 2 use cases doesn't sound like a good
design strategy to me.

> >>  >   . for splitting the window as result of some command calling
> >>  >     display-buffer, we could expect the modes to customize the
> >>  >     display-buffer-* variables to control how the window is split (if
> >>  >     there are currently no features/variables to that effect, we should
> >>  >     add them)
> >> 
> >> When two modes simultaneously use the margins, which buffer display
> >> function would be chosen?
> >
> > The same problem exists with the proposed solution, doesn't it?
> 
> If the value of `set-window-margins-function' is a single function, then
> probably the function provided by the last mode to be activated in a
> buffer.
> 
> Isn't that a potential problem?

Yes, that's exactly what I meant -- the problem with choosing between
several potentially conflicting requests exists, and should somehow be
solved.

Re: Better handling of window margins

[Joost Kremers]

On Wed, Dec 02 2015, Eli Zaretskii <eliz@gnu.org> wrote:
> The reason I don't believe in some general-purpose heuristics in this
> case is that there's any number of possible needs of modes wrt
> margins.  You are trying to classify these into "static" and
> "dynamic", but the "dynamic" kind can be something very different from
> what writeroom-mode and its ilk need in this regard.  So the
> heuristics will fail when we have a mode whose margins are not
> "static", but not like writeroom-mode, either.
>
> Does this make sense?

To an extent, but I'm not sure what kind of uses of the margins you have
in mind (if any). Anything concrete, or possible uses that we haven't
thought of yet but someone someday may think of?

-- 
Joost Kremers
Life has its moments

Re: Better handling of window margins

[Eli Zaretskii]

> From: Joost Kremers <joostkremers@fastmail.fm>
> Cc: emacs-devel@gnu.org
> Date: Wed, 02 Dec 2015 20:55:34 +0100
> 
> 
> On Wed, Dec 02 2015, Eli Zaretskii <eliz@gnu.org> wrote:
> > The reason I don't believe in some general-purpose heuristics in this
> > case is that there's any number of possible needs of modes wrt
> > margins.  You are trying to classify these into "static" and
> > "dynamic", but the "dynamic" kind can be something very different from
> > what writeroom-mode and its ilk need in this regard.  So the
> > heuristics will fail when we have a mode whose margins are not
> > "static", but not like writeroom-mode, either.
> >
> > Does this make sense?
> 
> To an extent, but I'm not sure what kind of uses of the margins you have
> in mind (if any). Anything concrete, or possible uses that we haven't
> thought of yet but someone someday may think of?

The suggestion was supposed to cover any and all uses of the margins.
If you can envision any uses, even theoretical, that don't fit into
the scheme I proposed, please tell.

The basic assumption was that a margin has a width, and then something
might or might not be displayed there.  I don't think there are other
possible uses: putting stuff in the margin involves a 'display'
property, so valid values of that property are the only things that
can appear in the margin.

Re: Better handling of window margins

[John Wiegley]

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

>>>>> Joost Kremers <joostkremers@fastmail.fm> writes:

> In two recent threads, one here ("Window splitting issues with margins") and
> one on bugs.gnu.emacs (bug 22009), some issues were discussed with window
> margins that could stand improvement. Two issues specifically came up[...]

Hi Joost,

I appreciate your willingness to grapple with this problem. Something feels
overly complex, however, about trying to satisfy the needs of various modes
(linum, darkroom, etc) in this way. It sounds you are trying to adapt an
existing mechanism to a specific need, but this will lead to both a more
complex mechanism, and more unmet needs in future.

This all makes me wonder whether our notion of "window" has become outdated,
based on what new authors are trying to make Emacs do. Richard has long wanted
better WYSIWYG behavior from Emacs, and these issues seem to underscore our
lack of support for such behavior.

Perhaps what we need is a richer notion of "window", with multiple sub-areas,
some for content, some for positioning, etc. This would make it possible to
define exactly what the appearance of a window should be, at a pixel level.
Given such a mechanism, fringes and margins would be distinguished merely as
different display areas within a window, rather than being the first-class
entities they are now. (For example, variables like `fringes-outside-margins'
would not be necessary, if one were able to manipulate such display areas in a
general fashion).

I strongly want to avoid extending the APIs of long-standing capabilities --
such as windows and frames -- just to make new features possible, or to enable
cooperation among non-core modes. If we're going to submit to that sort of
pain, it's worth considering what sort of design we'd if we had the freedom to
do it all over again. Then we can think of how to adapt such a clean-slate
approach into our existing environment.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 629 bytes --]