GNU bug report logs - #20180
Missing documentation about redisplay.

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: emacs; Severity: wishlist; Reported by: Alan Mackenzie <acm@HIDDEN>; Keywords: wontfix; Done: Lars Ingebrigtsen <larsi@HIDDEN>; Maintainer for emacs is bug-gnu-emacs@HIDDEN.
bug closed, send any further explanations to 20180 <at> debbugs.gnu.org and Alan Mackenzie <acm@HIDDEN> Request was from Lars Ingebrigtsen <larsi@HIDDEN> to control <at> debbugs.gnu.org. Full text available.
Added tag(s) wontfix. Request was from Lars Ingebrigtsen <larsi@HIDDEN> to control <at> debbugs.gnu.org. Full text available.

Message received at 20180 <at> debbugs.gnu.org:


Received: (at 20180) by debbugs.gnu.org; 2 Dec 2021 10:13:15 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Dec 02 05:13:15 2021
Received: from localhost ([127.0.0.1]:46715 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1msj5X-0000Ma-9m
	for submit <at> debbugs.gnu.org; Thu, 02 Dec 2021 05:13:15 -0500
Received: from quimby.gnus.org ([95.216.78.240]:37282)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <larsi@HIDDEN>) id 1msj5V-0000MI-G9
 for 20180 <at> debbugs.gnu.org; Thu, 02 Dec 2021 05:13:14 -0500
DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org;
 s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date:
 References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding:
 Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender:
 Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:
 List-Subscribe:List-Post:List-Owner:List-Archive;
 bh=TsmjhjX6/w14an19Y1ggPL5FKMA7jmLSPkMmS74KJ6w=; b=dMe3tFJNnhgO4fCbNLFPJkQOrz
 0bSTtPztPZ9wALIjZkr2QOUiR5boAmLNgzLcwxBprqeLxdgvWdHrFPEiWOnFj+82jZN2p3fse5k+p
 QDBICJyRTSLnoMmbvvEYwNdjAk6eLvZv/RIcVVKYmt9tombkvmbEkZZ7mYekXGkG0koA=;
Received: from [84.212.220.105] (helo=xo)
 by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.92) (envelope-from <larsi@HIDDEN>)
 id 1msj5M-0008AA-SU; Thu, 02 Dec 2021 11:13:07 +0100
From: Lars Ingebrigtsen <larsi@HIDDEN>
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#20180: Missing documentation about redisplay.
References: <20150323160850.GA23576@HIDDEN> <83oanjr75n.fsf@HIDDEN>
 <20150323175524.GB23576@HIDDEN> <83lhinr2j4.fsf@HIDDEN>
 <20150323201752.GC23576@HIDDEN> <83bnjjqvwv.fsf@HIDDEN>
X-Now-Playing: Riow Aral's _Beat Bracelet_: "Kusakari"
Date: Thu, 02 Dec 2021 11:13:04 +0100
In-Reply-To: <83bnjjqvwv.fsf@HIDDEN> (Eli Zaretskii's message of "Mon, 23 Mar
 2015 22:52:00 +0200")
Message-ID: <87h7br5n7z.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain
X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org",
 has NOT identified this incoming email as spam.  The original
 message has been attached to this so you can view it or label
 similar future email.  If you have any questions, see
 @@CONTACT_ADDRESS@@ for details.
 Content preview:  Reading this thread, I think the conclusion here is that the
 redisplay stuff is just too low-level and finicky to be meaningfully
 documented
 in the lispref manual. You really have to read xdisp.c to s [...] 
 Content analysis details:   (-2.9 points, 5.0 required)
 pts rule name              description
 ---- ---------------------- --------------------------------------------------
 -1.0 ALL_TRUSTED            Passed through trusted hosts only via SMTP
 -1.9 BAYES_00               BODY: Bayes spam probability is 0 to 1%
 [score: 0.0000]
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 20180
Cc: Alan Mackenzie <acm@HIDDEN>, 20180 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)

Reading this thread, I think the conclusion here is that the redisplay
stuff is just too low-level and finicky to be meaningfully documented in
the lispref manual.  You really have to read xdisp.c to start to
understand how that works.

And I think that's fine -- not everything can be put into the lispref
manual.  So I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no





Information forwarded to bug-gnu-emacs@HIDDEN:
bug#20180; Package emacs. Full text available.

Message received at 20180 <at> debbugs.gnu.org:


Received: (at 20180) by debbugs.gnu.org; 23 Mar 2015 20:52:25 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Mar 23 16:52:24 2015
Received: from localhost ([127.0.0.1]:34208 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Ya9Ki-0001d8-A3
	for submit <at> debbugs.gnu.org; Mon, 23 Mar 2015 16:52:24 -0400
Received: from mtaout20.012.net.il ([80.179.55.166]:62703)
 by debbugs.gnu.org with esmtp (Exim 4.80)
 (envelope-from <eliz@HIDDEN>) id 1Ya9Ke-0001cq-LP
 for 20180 <at> debbugs.gnu.org; Mon, 23 Mar 2015 16:52:22 -0400
Received: from conversion-daemon.a-mtaout20.012.net.il by
 a-mtaout20.012.net.il (HyperSendmail v2007.08) id
 <0NLO00600N31XN00@HIDDEN> for 20180 <at> debbugs.gnu.org;
 Mon, 23 Mar 2015 22:52:13 +0200 (IST)
Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout20.012.net.il
 (HyperSendmail v2007.08) with ESMTPA id
 <0NLO00600NB1LTB0@HIDDEN>;
 Mon, 23 Mar 2015 22:52:13 +0200 (IST)
Date: Mon, 23 Mar 2015 22:52:00 +0200
From: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#20180: Missing documentation about redisplay.
In-reply-to: <20150323201752.GC23576@HIDDEN>
X-012-Sender: halo1@HIDDEN
To: Alan Mackenzie <acm@HIDDEN>
Message-id: <83bnjjqvwv.fsf@HIDDEN>
References: <20150323160850.GA23576@HIDDEN> <83oanjr75n.fsf@HIDDEN>
 <20150323175524.GB23576@HIDDEN> <83lhinr2j4.fsf@HIDDEN>
 <20150323201752.GC23576@HIDDEN>
X-Spam-Score: 1.0 (+)
X-Debbugs-Envelope-To: 20180
Cc: 20180 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
Reply-To: Eli Zaretskii <eliz@HIDDEN>
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: 1.0 (+)

> Date: Mon, 23 Mar 2015 20:17:52 +0000
> Cc: 20180 <at> debbugs.gnu.org
> From: Alan Mackenzie <acm@HIDDEN>
> 
> > > There, if jit-lock suspects that properties at an
> > > earlier location in the buffer have been changed, it arranges that after
> > > the end of the current display cycle, some text properties at some of
> > > these locations get set, thus triggering another redisplay.
> 
> > > How?
> 
> > By changing the special text property 'fontified'.
> 
> > > Why does this trigger a redisplay when the setting of the
> > > properties during the previous redisplay cycle didn't?
> 
> > I don't understand the question.  What "setting of properties" during
> > which "previous redisplay cycle" do you have in mind?
> 
> 1. Redisplay cycle 1 starts.
> 2. First 500-byte chunk gets fontified through fontification-functions.
> 3. Second 500-byte chunk fontification starts.
> 4.   jit-lock-fontify-now applies face properties to a few characters of
>      the first 500-byte chunk at locations 496, 497, 498, 499.
> 5.   jit-lock-fontify-now arranges for 10. to happen at the expiry of a 0
>      second timeout.  (`run-with-timer')
> 6. Second 500-byte chunk is completely fontified.  It gets drawn on the
>    screen.
> 7. Redisplay cycle 1 is now complete.
> 
> 10. (At expiry of 0 second timeout), jit-lock-force-redisplay applies
>    text property (fontified t) to location 496, 497, 498, 499.  496..499
>    already had the property (fontified t).
> 11. Redisplay cycle 2 starts, having been triggered by 10.
> 12. ???? Redisplay draws 496, .., 499 on the screen, but no others.
> 13. Redisplay cycle 2 is now complete.
> 
> I think I meant to ask: why does setting text property 'fontified to t at
> stage 10 trigger redisplay cycle 2, whereas setting them at stage 4.5
> wouldn't have done?

Because stage 10 happens _after_ redisplay cycle 1 is complete.
Changing text properties after redisplay triggers another redisplay of
the buffer portion where the properties changed, because changes in
properties bump up the buffer-changed counter, and redisplay examines
that counter to determine whether anything changed since the previous
redisplay cycle.

IOW, if those properties weren't changed after redisplay finished, the
next redisplay would have decided that no changes happened, and do
nothing.

> In 10. above, the `fontified' text property is set to the value it
> already had.  This seems to be sufficient to trigger a redisplay.

Because it counts as a change regardless.




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#20180; Package emacs. Full text available.

Message received at 20180 <at> debbugs.gnu.org:


Received: (at 20180) by debbugs.gnu.org; 23 Mar 2015 20:18:17 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Mar 23 16:18:17 2015
Received: from localhost ([127.0.0.1]:34180 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Ya8ng-0000oL-5C
	for submit <at> debbugs.gnu.org; Mon, 23 Mar 2015 16:18:16 -0400
Received: from colin.muc.de ([193.149.48.1]:13293 helo=mail.muc.de)
 by debbugs.gnu.org with esmtp (Exim 4.80)
 (envelope-from <acm@HIDDEN>) id 1Ya8nZ-0000o8-GG
 for 20180 <at> debbugs.gnu.org; Mon, 23 Mar 2015 16:18:15 -0400
Received: (qmail 64307 invoked by uid 3782); 23 Mar 2015 20:18:08 -0000
Received: from acm.muc.de (pD95199EB.dip0.t-ipconnect.de [217.81.153.235]) by
 colin.muc.de (tmda-ofmipd) with ESMTP;
 Mon, 23 Mar 2015 21:18:07 +0100
Received: (qmail 24410 invoked by uid 1000); 23 Mar 2015 20:17:52 -0000
Date: Mon, 23 Mar 2015 20:17:52 +0000
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#20180: Missing documentation about redisplay.
Message-ID: <20150323201752.GC23576@HIDDEN>
References: <20150323160850.GA23576@HIDDEN> <83oanjr75n.fsf@HIDDEN>
 <20150323175524.GB23576@HIDDEN> <83lhinr2j4.fsf@HIDDEN>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <83lhinr2j4.fsf@HIDDEN>
User-Agent: Mutt/1.5.23 (2014-03-12)
X-Delivery-Agent: TMDA/1.1.12 (Macallan)
From: Alan Mackenzie <acm@HIDDEN>
X-Primary-Address: acm@HIDDEN
X-Spam-Score: -0.7 (/)
X-Debbugs-Envelope-To: 20180
Cc: 20180 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -0.7 (/)

On Mon, Mar 23, 2015 at 08:29:03PM +0200, Eli Zaretskii wrote:
> > Date: Mon, 23 Mar 2015 17:55:25 +0000
> > Cc: 20180 <at> debbugs.gnu.org
> > From: Alan Mackenzie <acm@HIDDEN>

> > What triggered my documentation search was looking at
> > jit-lock-fontify-now.

> Note that digging into JIT Lock means going deep into the internals of
> the display engine.  It's no accident that jit-lock.el was written by
> Gerd Moellmann, who designed and implemented the current display
> engine.

OK.  I thought it was Simon Marshall who wrote jit-lock.el.  Obviously
I'm mistaken.

> IOW, it's by no means ELisp manual level stuff (although I of course
> agree that IWBN to have the display engine's internals described in
> full, along with all the other internals).

I think some of what we've been discussing would be useful to put in a
new page in the elisp manual; it wouldn't have to be a very big page.

> > There, if jit-lock suspects that properties at an
> > earlier location in the buffer have been changed, it arranges that after
> > the end of the current display cycle, some text properties at some of
> > these locations get set, thus triggering another redisplay.

> > How?

> By changing the special text property 'fontified'.

> > Why does this trigger a redisplay when the setting of the
> > properties during the previous redisplay cycle didn't?

> I don't understand the question.  What "setting of properties" during
> which "previous redisplay cycle" do you have in mind?

1. Redisplay cycle 1 starts.
2. First 500-byte chunk gets fontified through fontification-functions.
3. Second 500-byte chunk fontification starts.
4.   jit-lock-fontify-now applies face properties to a few characters of
     the first 500-byte chunk at locations 496, 497, 498, 499.
5.   jit-lock-fontify-now arranges for 10. to happen at the expiry of a 0
     second timeout.  (`run-with-timer')
6. Second 500-byte chunk is completely fontified.  It gets drawn on the
   screen.
7. Redisplay cycle 1 is now complete.

10. (At expiry of 0 second timeout), jit-lock-force-redisplay applies
   text property (fontified t) to location 496, 497, 498, 499.  496..499
   already had the property (fontified t).
11. Redisplay cycle 2 starts, having been triggered by 10.
12. ???? Redisplay draws 496, .., 499 on the screen, but no others.
13. Redisplay cycle 2 is now complete.

I think I meant to ask: why does setting text property 'fontified to t at
stage 10 trigger redisplay cycle 2, whereas setting them at stage 4.5
wouldn't have done?

> > In the new redisplay, does the whole frame/window/minibuffer get
> > redrawn (for whatever value of "redraw") or just the bits where text
> > properties were set?

> This depends on what you mean by "redraw".  A redisplay cycle has 2
> phases.  In the first phase, Emacs examines the visible portion of the
> buffer and tries to determine the minimal number of screen lines that
> might need to be redrawn; it then prepares the corresponding portions
> of the glyph matrix for those screen lines.  Normally, only the screen
> lines where the 'fontified' text property changed will be considered.

In 10. above, the `fontified' text property is set to the value it
already had.  This seems to be sufficient to trigger a redisplay.

> In the second phase of redisplay, the prepared glyph matrix is
> compared to the previous one, which describes what's on the glass, and
> only the different portions are actually redrawn.  It could be that
> nothing needs to be redrawn at all.

OK.

> > If I were to execute the command `ignore' via a key sequence, would that
> > trigger redisplay?

> Yes, redisplay is triggered each time Emacs waits for more input and
> has nothing else to do.

> > If so, how much would get redrawn?

> Nothing at all, since nothing changed.

Thanks, that's good to understand.

> > I read the "whenever" as meaning "when it's waiting for input, it tries
> > _once_ to redisplay".  Having tried once, and 0.5s
> > (jit-lock-context-time) have passed, then jit-lock-context-fontify kicks
> > in to fontify screen lines below where a buffer change happened.  Another
> > redisplay then happens.  What triggers this second redisplay, given there
> > hasn't been any more "input"?

> The JIT Lock timer.

OK.

> > Or does the expiry of the timer count as "input" here?  Or is
> > something other than input (?a buffer change) triggering this second
> > redisplay?

> Yes, timers have the same effect as input: they return to the command
> loop after the timer function is run, and the command loop enters
> redisplay if there's no input.

> > > > One clearly needs an answer to 2. if one ever wants to cause the
> > > > redisplay of a particular part of a window or frame.

> > > To do that, you need to change the text of that part or the text
> > > properties/overlays that affect how that part looks on display.  But
> > > you most probably already know that, so I'm again not sure what the
> > > question is.

To summarize: to cause a redisplay which changes what you see (without
any scrolling happening) it is necessary to (i) change some text or
"significant" property/overlay on a displayed portion of a buffer; (ii)
cause an input event of any kind.

What I'm now thinking is that jit-lock-trigger-redisplay, and its setting
of text properties to the value they already have, is a complete red
herring[*] - the same effect could have been achieved by putting `ignore'
on the run-with-timer at stage 5, it merely being the expiry of the timer
triggering the redisplay cycle 2.

[*] "Red herring": anything which diverts attention from a topic or line
of enquiry.

> > In jit-lock-fontify-now, the top half of a screen window has just been
> > redisplayed, and j-l-fontify-now is busily applying faces for the next
> > 500-byte chunk.  In so doing, it sets faces in the part of the window
> > that have already been redisplayed.  This is apparently insufficient in
> > itself to trigger another redisplay of those already displayed window
> > parts.  I would like to understand why.

> jit-lock-fontify-now can be called in 2 different ways.  One is as
> part of redisplay itself, because jit-lock-function, which calls
> jit-lock-fontify-now, is added to fontification-functions, which are
> run by the display engine when it bumps into a buffer position that
> has the 'fontified' text property whose value is nil.  When
> jit-lock-fontify-now is called by this mechanism, it fontifies
> portions that were not yet displayed.  After fontification-functions
> return, the display engine re-examines the buffer position where they
> were called, since it knows that faces could change there.  This
> constitutes "another redisplay" you were looking for, without actually
> triggering a full redisplay cycle.  Keep in mind that the display
> engine examines buffer text one character at a time, so it is only
> ever interested in the faces at the single buffer position it is
> examining.

> The other way jit-lock-fontify-now is called is from the Jit Stealth
> or deferred Jit Lock, in which case it does trigger another redisplay,
> as you expect.

> HTH

Enormously!  Thanks very much.

-- 
Alan Mackenzie (Nuremberg, Germany).




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#20180; Package emacs. Full text available.

Message received at 20180 <at> debbugs.gnu.org:


Received: (at 20180) by debbugs.gnu.org; 23 Mar 2015 18:29:27 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Mar 23 14:29:27 2015
Received: from localhost ([127.0.0.1]:34109 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Ya76N-0006c4-1h
	for submit <at> debbugs.gnu.org; Mon, 23 Mar 2015 14:29:27 -0400
Received: from mtaout23.012.net.il ([80.179.55.175]:35784)
 by debbugs.gnu.org with esmtp (Exim 4.80)
 (envelope-from <eliz@HIDDEN>) id 1Ya76J-0006bj-NG
 for 20180 <at> debbugs.gnu.org; Mon, 23 Mar 2015 14:29:25 -0400
Received: from conversion-daemon.a-mtaout23.012.net.il by
 a-mtaout23.012.net.il (HyperSendmail v2007.08) id
 <0NLO00J00GLAHH00@HIDDEN> for 20180 <at> debbugs.gnu.org;
 Mon, 23 Mar 2015 20:29:17 +0200 (IST)
Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout23.012.net.il
 (HyperSendmail v2007.08) with ESMTPA id
 <0NLO00J06GOSH410@HIDDEN>;
 Mon, 23 Mar 2015 20:29:16 +0200 (IST)
Date: Mon, 23 Mar 2015 20:29:03 +0200
From: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#20180: Missing documentation about redisplay.
In-reply-to: <20150323175524.GB23576@HIDDEN>
X-012-Sender: halo1@HIDDEN
To: Alan Mackenzie <acm@HIDDEN>
Message-id: <83lhinr2j4.fsf@HIDDEN>
References: <20150323160850.GA23576@HIDDEN> <83oanjr75n.fsf@HIDDEN>
 <20150323175524.GB23576@HIDDEN>
X-Spam-Score: 1.0 (+)
X-Debbugs-Envelope-To: 20180
Cc: 20180 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
Reply-To: Eli Zaretskii <eliz@HIDDEN>
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: 1.0 (+)

> Date: Mon, 23 Mar 2015 17:55:25 +0000
> Cc: 20180 <at> debbugs.gnu.org
> From: Alan Mackenzie <acm@HIDDEN>
> 
> What triggered my documentation search was looking at
> jit-lock-fontify-now.

Note that digging into JIT Lock means going deep into the internals of
the display engine.  It's no accident that jit-lock.el was written by
Gerd Moellmann, who designed and implemented the current display
engine.

IOW, it's by no means ELisp manual level stuff (although I of course
agree that IWBN to have the display engine's internals described in
full, along with all the other internals).

> There, if jit-lock suspects that properties at an
> earlier location in the buffer have been changed, it arranges that after
> the end of the current display cycle, some text properties at some of
> these locations get set, thus triggering another redisplay.
> 
> How?

By changing the special text property 'fontified'.

> Why does this trigger a redisplay when the setting of the
> properties during the previous redisplay cycle didn't?

I don't understand the question.  What "setting of properties" during
which "previous redisplay cycle" do you have in mind?

> In the new redisplay, does the whole frame/window/minibuffer get
> redrawn (for whatever value of "redraw") or just the bits where text
> properties were set?

This depends on what you mean by "redraw".  A redisplay cycle has 2
phases.  In the first phase, Emacs examines the visible portion of the
buffer and tries to determine the minimal number of screen lines that
might need to be redrawn; it then prepares the corresponding portions
of the glyph matrix for those screen lines.  Normally, only the screen
lines where the 'fontified' text property changed will be considered.

In the second phase of redisplay, the prepared glyph matrix is
compared to the previous one, which describes what's on the glass, and
only the different portions are actually redrawn.  It could be that
nothing needs to be redrawn at all.

> If I were to execute the command `ignore' via a key sequence, would that
> trigger redisplay?

Yes, redisplay is triggered each time Emacs waits for more input and
has nothing else to do.

> If so, how much would get redrawn?

Nothing at all, since nothing changed.

> I read the "whenever" as meaning "when it's waiting for input, it tries
> _once_ to redisplay".  Having tried once, and 0.5s
> (jit-lock-context-time) have passed, then jit-lock-context-fontify kicks
> in to fontify screen lines below where a buffer change happened.  Another
> redisplay then happens.  What triggers this second redisplay, given there
> hasn't been any more "input"?

The JIT Lock timer.

> Or does the expiry of the timer count as "input" here?  Or is
> something other than input (?a buffer change) triggering this second
> redisplay?

Yes, timers have the same effect as input: they return to the command
loop after the timer function is run, and the command loop enters
redisplay if there's no input.

> > > One clearly needs an answer to 2. if one ever wants to cause the
> > > redisplay of a particular part of a window or frame.
> 
> > To do that, you need to change the text of that part or the text
> > properties/overlays that affect how that part looks on display.  But
> > you most probably already know that, so I'm again not sure what the
> > question is.
> 
> In jit-lock-fontify-now, the top half of a screen window has just been
> redisplayed, and j-l-fontify-now is busily applying faces for the next
> 500-byte chunk.  In so doing, it sets faces in the part of the window
> that have already been redisplayed.  This is apparently insufficient in
> itself to trigger another redisplay of those already displayed window
> parts.  I would like to understand why.

jit-lock-fontify-now can be called in 2 different ways.  One is as
part of redisplay itself, because jit-lock-function, which calls
jit-lock-fontify-now, is added to fontification-functions, which are
run by the display engine when it bumps into a buffer position that
has the 'fontified' text property whose value is nil.  When
jit-lock-fontify-now is called by this mechanism, it fontifies
portions that were not yet displayed.  After fontification-functions
return, the display engine re-examines the buffer position where they
were called, since it knows that faces could change there.  This
constitutes "another redisplay" you were looking for, without actually
triggering a full redisplay cycle.  Keep in mind that the display
engine examines buffer text one character at a time, so it is only
ever interested in the faces at the single buffer position it is
examining.

The other way jit-lock-fontify-now is called is from the Jit Stealth
or deferred Jit Lock, in which case it does trigger another redisplay,
as you expect.

HTH




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#20180; Package emacs. Full text available.

Message received at 20180 <at> debbugs.gnu.org:


Received: (at 20180) by debbugs.gnu.org; 23 Mar 2015 17:55:47 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Mar 23 13:55:47 2015
Received: from localhost ([127.0.0.1]:34099 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Ya6Zm-0005p6-RW
	for submit <at> debbugs.gnu.org; Mon, 23 Mar 2015 13:55:47 -0400
Received: from colin.muc.de ([193.149.48.1]:35843 helo=mail.muc.de)
 by debbugs.gnu.org with esmtp (Exim 4.80)
 (envelope-from <acm@HIDDEN>) id 1Ya6Zk-0005ox-A9
 for 20180 <at> debbugs.gnu.org; Mon, 23 Mar 2015 13:55:45 -0400
Received: (qmail 32823 invoked by uid 3782); 23 Mar 2015 17:55:41 -0000
Received: from acm.muc.de (pD95199EB.dip0.t-ipconnect.de [217.81.153.235]) by
 colin.muc.de (tmda-ofmipd) with ESMTP;
 Mon, 23 Mar 2015 18:55:40 +0100
Received: (qmail 23921 invoked by uid 1000); 23 Mar 2015 17:55:25 -0000
Date: Mon, 23 Mar 2015 17:55:25 +0000
To: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#20180: Missing documentation about redisplay.
Message-ID: <20150323175524.GB23576@HIDDEN>
References: <20150323160850.GA23576@HIDDEN>
 <83oanjr75n.fsf@HIDDEN>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <83oanjr75n.fsf@HIDDEN>
User-Agent: Mutt/1.5.23 (2014-03-12)
X-Delivery-Agent: TMDA/1.1.12 (Macallan)
From: Alan Mackenzie <acm@HIDDEN>
X-Primary-Address: acm@HIDDEN
X-Spam-Score: -0.7 (/)
X-Debbugs-Envelope-To: 20180
Cc: 20180 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -0.7 (/)

Hi, Eli.

On Mon, Mar 23, 2015 at 06:49:08PM +0200, Eli Zaretskii wrote:
> > Date: Mon, 23 Mar 2015 16:08:50 +0000
> > From: Alan Mackenzie <acm@HIDDEN>

> > The elisp manual doesn't contain adequate documentation about
> > (re)display.

> > The topics not covered include

> They include much more.  Describing the display engine to any depth is
> a research project, not a bug report.

:-)

> Maybe if you had more specific questions, they could be answered.

What triggered my documentation search was looking at
jit-lock-fontify-now.  There, if jit-lock suspects that properties at an
earlier location in the buffer have been changed, it arranges that after
the end of the current display cycle, some text properties at some of
these locations get set, thus triggering another redisplay.

How?  Why does this trigger a redisplay when the setting of the
properties during the previous redisplay cycle didn't?  In the new
redisplay, does the whole frame/window/minibuffer get redrawn (for
whatever value of "redraw") or just the bits where text properties were
set?

If I were to execute the command `ignore' via a key sequence, would that
trigger redisplay?  If so, how much would get redrawn?

> The closest thing to what you are asking for is in the large
> commentary at the beginning of xdisp.c.

> > 1. What triggers redisplay.

> See below: this is already covered.

> > 2. What portions of the frame/all frames get redisplayed when a
> >   redisplay occurs, and how does this relate to the answer to 1..

> > There is a partial answer to 1. on the page "Forcing Redisplay" which
> > states that "Emacs normally tries to redisplay the screen whenever it
> > waits for input.", but this is clearly incomplete - redisplay also
> > happens in the absence of input (e.g. by context fontification).

> I don't understand what you are saying here: "waiting for input" and
> "there's no input" is not a contradiction, on the contrary: you wait
> for input when there's none.  And what is "context fontification"?

I read the "whenever" as meaning "when it's waiting for input, it tries
_once_ to redisplay".  Having tried once, and 0.5s
(jit-lock-context-time) have passed, then jit-lock-context-fontify kicks
in to fontify screen lines below where a buffer change happened.  Another
redisplay then happens.  What triggers this second redisplay, given there
hasn't been any more "input"?  Or does the expiry of the timer count as
"input" here?  Or is something other than input (?a buffer change)
triggering this second redisplay?

> > One clearly needs an answer to 2. if one ever wants to cause the
> > redisplay of a particular part of a window or frame.

> To do that, you need to change the text of that part or the text
> properties/overlays that affect how that part looks on display.  But
> you most probably already know that, so I'm again not sure what the
> question is.

In jit-lock-fontify-now, the top half of a screen window has just been
redisplayed, and j-l-fontify-now is busily applying faces for the next
500-byte chunk.  In so doing, it sets faces in the part of the window
that have already been redisplayed.  This is apparently insufficient in
itself to trigger another redisplay of those already displayed window
parts.  I would like to understand why.

-- 
Alan Mackenzie (Nuremberg, Germany).




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#20180; Package emacs. Full text available.

Message received at 20180 <at> debbugs.gnu.org:


Received: (at 20180) by debbugs.gnu.org; 23 Mar 2015 16:49:30 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Mar 23 12:49:30 2015
Received: from localhost ([127.0.0.1]:34053 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Ya5Xe-0004FK-3Y
	for submit <at> debbugs.gnu.org; Mon, 23 Mar 2015 12:49:30 -0400
Received: from mtaout27.012.net.il ([80.179.55.183]:46047)
 by debbugs.gnu.org with esmtp (Exim 4.80)
 (envelope-from <eliz@HIDDEN>) id 1Ya5Xb-0004F3-Kk
 for 20180 <at> debbugs.gnu.org; Mon, 23 Mar 2015 12:49:28 -0400
Received: from conversion-daemon.mtaout27.012.net.il by mtaout27.012.net.il
 (HyperSendmail v2007.08) id <0NLO00100BO1HI00@HIDDEN> for
 20180 <at> debbugs.gnu.org; Mon, 23 Mar 2015 18:44:05 +0200 (IST)
Received: from HOME-C4E4A596F7 ([87.69.4.28]) by mtaout27.012.net.il
 (HyperSendmail v2007.08) with ESMTPA id
 <0NLO001S8BTHI200@HIDDEN>; Mon, 23 Mar 2015 18:44:05 +0200 (IST)
Date: Mon, 23 Mar 2015 18:49:08 +0200
From: Eli Zaretskii <eliz@HIDDEN>
Subject: Re: bug#20180: Missing documentation about redisplay.
In-reply-to: <20150323160850.GA23576@HIDDEN>
X-012-Sender: halo1@HIDDEN
To: Alan Mackenzie <acm@HIDDEN>
Message-id: <83oanjr75n.fsf@HIDDEN>
References: <20150323160850.GA23576@HIDDEN>
X-Spam-Score: 1.0 (+)
X-Debbugs-Envelope-To: 20180
Cc: 20180 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
Reply-To: Eli Zaretskii <eliz@HIDDEN>
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: 1.0 (+)

> Date: Mon, 23 Mar 2015 16:08:50 +0000
> From: Alan Mackenzie <acm@HIDDEN>
> 
> The elisp manual doesn't contain adequate documentation about
> (re)display.
> 
> The topics not covered include

They include much more.  Describing the display engine to any depth is
a research project, not a bug report.  Maybe if you had more specific
questions, they could be answered.

The closest thing to what you are asking for is in the large
commentary at the beginning of xdisp.c.

> 1. What triggers redisplay.

See below: this is already covered.

> 2. What portions of the frame/all frames get redisplayed when a
>   redisplay occurs, and how does this relate to the answer to 1..
> 
> There is a partial answer to 1. on the page "Forcing Redisplay" which
> states that "Emacs normally tries to redisplay the screen whenever it
> waits for input.", but this is clearly incomplete - redisplay also
> happens in the absence of input (e.g. by context fontification).

I don't udnerstand what you are saying here: "waiting for input" and
"there's no input" is not a contradiction, on the contrary: yo uwait
for input when there's none.  And what is "context fontification"?

> One clearly needs an answer to 2. if one ever wants to cause the
> redisplay of a particular part of a window or frame.

To do that, you need to change the text of that part or the text
properties/overlays that affect how that part looks on display.  But
you most probably already know that, so I'm again not sure what the
question is.




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#20180; Package emacs. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 23 Mar 2015 16:16:15 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Mar 23 12:16:15 2015
Received: from localhost ([127.0.0.1]:34023 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1Ya51T-0003Oz-Dt
	for submit <at> debbugs.gnu.org; Mon, 23 Mar 2015 12:16:15 -0400
Received: from eggs.gnu.org ([208.118.235.92]:37798)
 by debbugs.gnu.org with esmtp (Exim 4.80)
 (envelope-from <acm@HIDDEN>) id 1Ya51Q-0003Om-MK
 for submit <at> debbugs.gnu.org; Mon, 23 Mar 2015 12:16:13 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <acm@HIDDEN>) id 1Ya51H-00072b-7g
 for submit <at> debbugs.gnu.org; Mon, 23 Mar 2015 12:16:07 -0400
X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org
X-Spam-Level: 
X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50 autolearn=disabled
 version=3.3.2
Received: from lists.gnu.org ([2001:4830:134:3::11]:33882)
 by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <acm@HIDDEN>)
 id 1Ya51H-00072W-4r
 for submit <at> debbugs.gnu.org; Mon, 23 Mar 2015 12:16:03 -0400
Received: from eggs.gnu.org ([2001:4830:134:3::10]:39482)
 by lists.gnu.org with esmtp (Exim 4.71) (envelope-from <acm@HIDDEN>)
 id 1Ya51D-0005DC-2X
 for bug-gnu-emacs@HIDDEN; Mon, 23 Mar 2015 12:16:03 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <acm@HIDDEN>) id 1Ya517-0006zz-Cr
 for bug-gnu-emacs@HIDDEN; Mon, 23 Mar 2015 12:15:59 -0400
Received: from colin.muc.de ([193.149.48.1]:26858 helo=mail.muc.de)
 by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from <acm@HIDDEN>)
 id 1Ya517-0006zC-5g
 for bug-gnu-emacs@HIDDEN; Mon, 23 Mar 2015 12:15:53 -0400
Received: (qmail 10152 invoked by uid 3782); 23 Mar 2015 16:09:07 -0000
Received: from acm.muc.de (pD95199EB.dip0.t-ipconnect.de [217.81.153.235]) by
 colin.muc.de (tmda-ofmipd) with ESMTP;
 Mon, 23 Mar 2015 17:09:06 +0100
Received: (qmail 23629 invoked by uid 1000); 23 Mar 2015 16:08:50 -0000
Date: Mon, 23 Mar 2015 16:08:50 +0000
To: bug-gnu-emacs@HIDDEN
Subject: Missing documentation about redisplay.
Message-ID: <20150323160850.GA23576@HIDDEN>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.5.23 (2014-03-12)
X-Delivery-Agent: TMDA/1.1.12 (Macallan)
From: Alan Mackenzie <acm@HIDDEN>
X-Primary-Address: acm@HIDDEN
X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x
X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address
 (bad octet value).
X-Received-From: 2001:4830:134:3::11
X-Spam-Score: -4.3 (----)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -4.3 (----)

Hello, Emacs.

The elisp manual doesn't contain adequate documentation about
(re)display.

The topics not covered include
1. What triggers redisplay.
2. What portions of the frame/all frames get redisplayed when a
  redisplay occurs, and how does this relate to the answer to 1..

There is a partial answer to 1. on the page "Forcing Redisplay" which
states that "Emacs normally tries to redisplay the screen whenever it
waits for input.", but this is clearly incomplete - redisplay also
happens in the absence of input (e.g. by context fontification).

One clearly needs an answer to 2. if one ever wants to cause the
redisplay of a particular part of a window or frame.

-- 
Alan Mackenzie (Nuremberg, Germany).




Acknowledgement sent to Alan Mackenzie <acm@HIDDEN>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs@HIDDEN. Full text available.
Report forwarded to bug-gnu-emacs@HIDDEN:
bug#20180; Package emacs. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Thu, 2 Dec 2021 10:15:01 UTC

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.