bug#29279: Sharing the margins

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Mon, 13 Nov 2017 01:51:53 +0200
> 
> This is a rough proposal on how separate bodies of code (minor modes, etc) 
> can use the same margin without conflict.

Thanks for reviving the issue.

> Previous discussions:
> 
> http://lists.gnu.org/archive/html/emacs-devel/2015-11/msg01171.html
> https://debbugs.gnu.org/cgi/bugreport.cgi?bug=27427#53

The second discussion doesn't seem to be relevant, although it touches
this tangentially.  It has nothing useful to add to this discussion,
AFAICT.

> Primary goals:
> 
> - Allow multiple kinds of margin content to coexist (examples: 
> http://lists.gnu.org/archive/html/emacs-devel/2015-11/msg01505.html).

Yes, that's the goal.

> - Continue to use the text properties to set the contents of the margins (as 
> opposed to having a line number based API, which seems to come with its own 
> difficulties).

Not sure I understand this.  AFAIK no one proposed to get rid of the
mechanism of specifying margin display, be it via text properties or
overlays.  The line number display of Emacs 26 avoids using the
margins, but that wasn't proposed as some more general API for
anything else.  So I think this is a non-issue, and will just leads us
astray.

> Outline:
> 
> We introduce two new variables, named like left-margin-columns-alist.
> 
> Each element is a cons which specifies some properties of the element, for 
> instance:

I think we need to come up with a specific list of properties, because
discussing an example will always be too vague and uncommitted.  So is
this the actual list you propose, or are there other properties you
envision?  If the latter, please add them to the list.

> - Priority (so the columns are in the same order on each line)

You mean "order", right?  That is, which part will be rendered first,
which after it, etc., right?  If not, what is the practical meaning of
"priority" here?

> - Minimum width (if we want that, as opposed to just adding strings with that 
> length the contents of this margin column)
> - Minimum "total" width, which would allow to use this column as padding so 
> that the combined width of the margin reaches a given number (hopefully 
> solving the writeroom-mode problem).

I don't understand the difference between these two.  Can you
elaborate?

And what about the maximum width?  I think this is much more important
than the minimum.

> - Padding (whether to pad this column with a space on one side if there is a 
> next column)

Doesn't the minimum width already cover this?  If the actual width is
less than the advertised minimum, text should be padded, otherwise it
shouldn't.  Right?

> - Text alignment within the column (left or right)

Why does this need to be a separate property?  We don't have anything
like that for any other kind of text.

> The keys in left-margin-columns-alist will be used as alternatives to 
> `left-margin' in margin display specs.

I think we need to agree on the model of the display in the margins.
The fact that you use "columns" in your proposal hints that each
"user" of the margin (a Lisp program which displays there) will have a
separate "column" in the margin, and that column will be of the same
pixel width for each screen line.  If this is the model, then it makes
little sense to have different display specs regarding the "column"
width for each buffer position where display in the margin is
requested, because the resulting column width will be the same for all
such displays.  If we specify these in each display spec, we are in
effect wasting Lisp storage, and potentially also working against the
fundamental design of the display engine (more about that below).

> The display engine would scan the contents of the current window, process 
> said specs, calculate which lines fit the window and which do not, set the 
> total margin width appropriately, and display all columns in it. Some 
> reflowing might be required.

This will not work with the current design of the display engine, at
least not without significant pains and at least twofold performance
degradation.  To realize why, you need to remember that when the
display engine is redisplaying a window, it initially has no idea
where the window will end, it normally (but not always) knows only
where it will begin.  This is because the stuff to be displayed in the
window could have changed significantly since the last redisplay
cycle, so any "memory" of where the window ended back then could
easily be invalid (which is why the display engine keeps almost no
memory about the results of the last redisplay).

The actual place where the window display ends is the consequence of
the display engine trying to lay out the window starting at
window-start, and going on until the window bottom is reached, at
which point it checks that point is visible in the window, and if not,
chooses a different window-start to bring point into the view, and
retries.

(The above description is a simplification: it omits various redisplay
optimizations which refrain from displaying the entire window in the
frequent use cases.  But for the purposes of this discussion, let's
forget about those optimizations, because their semantics is, and must
be, identical to redisplaying the whole window anew each time.)

For this reason, "scanning the contents of the current window" is not
something the display engine can do at the start of a window
redisplay.  It can only do so after one full cycle of window layout.
In addition, changing the dimensions of the margins requires to start
the window display anew, after reallocating the glyph matrices.

So what you suggest can only be implemented by displaying each window
twice.  On top of that, it will disable important redisplay
optimizations, which refrain from examining all of the screen lines
and the corresponding buffer text -- since you require to scan all of
the display specs in the window to dynamically compute the margin
dimensions.

The way the current display engine is designed, it makes the layout
decisions either at the start of a window's redisplay, or as it
traverses buffer text one character at a time.  The decisions related
to the dimensions of the canvas are best made at the beginning,
otherwise they will cause the redisplay to be abandoned and restarted
anew, which slows it down.  We have a few cases where we do that, but
they should be rare to provide good user experience.  (These cases
could also complicate the move_it_* functions, which simulate display.
As of now, they don't handle such cases, but won't be able to ignore
the consequences of your proposal to calculate margins dynamically as
part of redisplay.)

Therefore, features that require dynamic recalculation of the window
dimensions as part of redisplay should IMO be avoided at all costs.
We should try to find a way of making these calculations in Lisp, as
part of the program(s) that require display in the margins, so that by
the time redisplay kicks in, the calculation of the margin widths,
including the column width for each "user" of the margin, was already
done and stored in some form that the display engine could use when it
initializes redisplay of a window.

> If the latter is considered too difficult

I think "unworkable" is a more proper word, unfortunately, because I
don't see anyone who'd step forward to perform a major redesign of the
display engine required for your proposal.  (And if we are redesigning
the display engine, I have a few more important requirements for it ;-)

I will post an alternative proposal in a separate email.

> we can add "width" as a necessary parameter to the column properties. I think 
> that would rule out the possibility of efficiently using the margins for the 
> line numbers feature, though, which seems unfortunate. But the other uses of 
> the margin that I'm aware of are not as dynamic.

Sorry, I think you lost me here.  What is that "width" parameter,
which "column properties" are being alluded to, and why would it
disallow dynamic resizing of the margins?  The only requirement for a
feature that will allow relatively simple and efficient implementation
is that the necessary total width of each window margin is known, or
can be calculated by accessing some buffer- or window-local variable,
at the beginning of a redisplay cycle.  Is that hard to accomplish?

> Similar feature can be added for the fringes, too (for them, dynamic sizing 
> isn't needed at all, probably).

I think fringes are a separate issue.  AFAIK, we current cannot
display more than one bitmap on the fringe at any given screen line.