static bool message_enable_multibyte;
-/* Nonzero if we should redraw the mode lines on the next redisplay.
- If it has value REDISPLAY_SOME, then only redisplay the mode lines where
- the `redisplay' bit has been set. Otherwise, redisplay all mode lines
- (the number used is then only used to track down the cause for this
- full-redisplay). */
+/* At each redisplay cycle, we should refresh everything there is to refresh.
+ To do that efficiently, we use many optimizations that try to make sure we
+ don't waste too much time updating things that haven't changed.
+ The coarsest such optimization is that, in the most common cases, we only
+ look at the selected-window.
+
+ To know whether other windows should be considered for redisplay, we use the
+ variable windows_or_buffers_changed: as long as it is 0, it means that we
+ have not noticed anything that should require updating anything else than
+ the selected-window. If it is set to REDISPLAY_SOME, it means that since
+ last redisplay, some changes have been made which could impact other
+ windows. To know which ones need redisplay, every buffer, window, and frame
+ has a `redisplay' bit, which (if true) means that this object needs to be
+ redisplayed. If windows_or_buffers_changed is 0, we know there's no point
+ looking for those `redisplay' bits (actually, there might be some such bits
+ set, but then only on objects which aren't displayed anyway).
+
+ OTOH if it's non-zero we wil have to loop through all windows and then check
+ the `redisplay' bit of the corresponding window, frame, and buffer, in order
+ to decide whether that window needs attention or not. Not that we can't
+ just look at the frame's redisplay bit to decide that the whole frame can be
+ skipped, since even if the frame's redisplay bit is unset, some of its
+ windows's redisplay bits may be set.
+
+ Mostly for historical reasons, windows_or_buffers_changed can also take
+ other non-zero values. In that case, the precise value doesn't matter (it
+ encodes the cause of the setting but is only used for debugging purposes),
+ and what it means is that we shouldn't pay attention to any `redisplay' bits
+ and we should simply try and redisplay every window out there. */
-int update_mode_lines;
+int windows_or_buffers_changed;
-/* Nonzero if window sizes or contents other than selected-window have changed
- since last redisplay that finished.
- If it has value REDISPLAY_SOME, then only redisplay the windows where
- the `redisplay' bit has been set. Otherwise, redisplay all windows
- (the number used is then only used to track down the cause for this
- full-redisplay). */
+/* Nonzero if we should redraw the mode lines on the next redisplay.
+ Similarly to `windows_or_buffers_changed', If it has value REDISPLAY_SOME,
+ then only redisplay the mode lines in those buffers/windows/frames where the
+ `redisplay' bit has been set.
+ For any other value, redisplay all mode lines (the number used is then only
+ used to track down the cause for this full-redisplay).
+
+ The `redisplay' bits are the same as those used for
+ windows_or_buffers_changed, and setting windows_or_buffers_changed also
+ causes recomputation of the mode lines of all those windows. IOW this
+ variable only has an effect if windows_or_buffers_changed is zero, in which
+ case we should only need to redisplay the mode-line of those objects with
+ a `redisplay' bit set but not the window's text content (tho we may still
+ need to refresh the text content of the selected-window). */
-int windows_or_buffers_changed;
+int update_mode_lines;
/* True after display_mode_line if %l was used and it displayed a
line number. */