Re: [Emacs-diffs] master 29d1c72: Introduce new value t for compilation-context-lines to eliminate scrolling

[Alan Mackenzie]

Hello, Eli.

On Thu, Aug 29, 2019 at 21:22:06 +0300, Eli Zaretskii wrote:
> > Date: Tue, 27 Aug 2019 20:05:20 +0000
> > Cc: address@hidden, address@hidden
> > From: Alan Mackenzie <address@hidden>

> > > > Should I have been aware of this?

> > > What is "this" in this context?  The display margins or how to use
> > > them with overlays?

> > I think, more the first of these.

> > > > Somehow, in the elisp manual, it seems buried under several levels
> > > > of chapters, sections, and sub-sections.

> The subsection describing the display margins is part of the section
> which documents the 'display' properties in general, so I think it's
> in a correct and logical place.

> Where would you expect it to be mentioned, not to be "buried"?

Maybe on the page "Emacs Display", rather than the current menu point:

    * Display Property      Enabling special display features.

, something like:

    * Display Property      Images, margins, text size, etc.

might be more helpful.

> > I found implementing these margins (see patch in separate post) to be
> > particularly difficult.  There is no complete example of how to do this
> > on the "Display Margins" elisp manual page.

> Feel free to provide an example.  The simplest way, one that doesn't
> use an overlay string, is just setting a display property on buffer
> text, something that hardly needs an example.

This would involve that text not getting displayed.  I'm not sure doing
that would ever be useful - if such a display text property were put on
the first character of a line, and that line were empty, it would
(presumably) make that line disappear from the display.

I will get an example together, but at the moment Real Life is somewhat
stressful.  Maybe I could base it on the margin I'm putting into
fringeless windows in compilation-mode.

> > There, the word "property" is used, rather than "text property or
> > overlay property", leaving me uncertain of whether I could have
> > implemented this "=>" in the margin solely with overlays.

> This is a subsection of a section about 'display' property, which is
> only available for text in buffers and Lisp strings, not for overlays.
> One should read the manual in the context of the parent sections.

I was floundering around in confusion for several hours, trying to get
some concrete handle on how to code the margins.  If the sentence in
"Display Margins" had read:

    The way to display something in the margins is to specify it in a
    margin display specification in the `display' TEXT property of some
    text.
                                                  ^^^^

, this would have helped me.

> > I was uncertain, right up till near when I had the thing ready,
> > whether the variables implementing this need to be buffer local or
> > not.

> Which variables?

compilation-margin-string ;; the "=>" which appears in the margin
compilation--dummy-string ;; the before-string which has a `display' text
                          ;; property for the margin.
compilation-arrow-overlay ;; The overlay causing the "=>" to be displayed
                          ;; at the appropriate line in the window.

Of these, only the last needs to be buffer local, since there might be
several compilation-mode windows live at the same time.  Really it ought
to be a "window local variable", but we don't have these.  That's
probably a good thing.

> And why did you think they need to be buffer-local?  Text properties
> already localize their values enough, so there should be no need for
> anything buffer-local.  That's in general, not only for the display
> properties.

Yes.  I think I've got that, now.

> > Also, the setup seems wierd.  Why isn't there a direct `margin' overlay
> > property, much the same way there's a `before-string' overlay property?

> Because no one wrote the code to do that.

That's a good answer.  Thanks!

> This is a display property, so you can put it on buffer text or on a
> Lisp string, in particular on a Lisp string that is before- or
> after-string of an overlay.

> > Instead, what we have is a required "dummy" `before-string', which is
> > supplanted by a `display' text property on it.  It just seems a strange
> > way of implementing it.  This certainly doesn't promote easy
> > understanding.  IMHO, of course.

> Display properties (really, any "replacing" properties) are tricky in
> implementation, you should look up the code some day.  Then you will
> maybe understand why no one ever wanted to add one more such
> facility.

Yes.  I spent quite a bit of time a couple of weeks ago getting my head
around the code in xdisp.c for before-strings and after-strings.  Maybe
adding margins into the mix wouldn't really be a good idea.  ;-)

> The way of using the display properties to display in the margins was
> originally implemented only for buffer text; placing it on overlay
> strings had bugs until Emacs 24 or 25, I think.

Ah.

> In any case, the ELisp manual describes this possibility, precisely
> because it is not easy to come up on one's own.  So I think we are OK
> here, documentation-wise.

As above, I think a complete example in the "Display Margins" page would
be helpful.  I'll get around to formulating this some time (soon?).

-- 
Alan Mackenzie (Nuremberg, Germany).