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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 27 Aug 2019 20:05:20 +0000
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > > 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"?

> 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.

> 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 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?  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.

> 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.  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.  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.

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.