Re: Window tree and window's internal height

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 20 Nov 2018 10:28:19 +0100
> From: martin rudalics <rudalics@gmx.at>
> CC: emacs-devel@gnu.org
> 
>  > Well, I turned to the manual after becoming disappointed in the
>  > comments to 'struct window' definition...
> 
> Tell me which ones you find not useful or incomplete and I'll try to
> fix them.

The next/prev pointers and their relation to the parent pointer and to
the 'contents' and pseudo_window_p members.  You will see that I
already added some details there, but maybe they aren't accurate
enough, or you can add more explanations.

The original problem was that when I saw this:

      if (!NILP (w->parent)
	  || WINDOWP (w->contents)
	  || !NILP (w->next)
	  || !NILP (w->prev)

I concluded that I didn't have a clear idea what each one of the tests
means, and how they differ from the following test from
window_wants_mode_line:

  return ((WINDOW_LEAF_P (w)
	   && !MINI_WINDOW_P (w)
	   && !WINDOW_PSEUDO_P (w)
	   && !EQ (window_mode_line_format, Qnone)
	   && (!NILP (window_mode_line_format)
	       || !NILP (BVAR (XBUFFER (WINDOW_BUFFER (w)), mode_line_format)))
	   && WINDOW_PIXEL_HEIGHT (w) > WINDOW_FRAME_LINE_HEIGHT (w))

> We should also decide what to do with the Object Internals
> section of the Elisp manual - update or remove it.  I'd do the latter
> because IMHO we'll be hardly able to keep it up to date unless we add
> rather strong advices to window.h, buffer.h and process.h.

Emacs is sometimes accused to be completely devoid of documentation of
its internals, something that is said to be an obstacle for people who
might otherwise try hacking Emacs on the C level.  So I think we
should keep the little of the internals documentation we have.  We
don't (or rather shouldn't) change the internals too frequently, so
the maintenance burden isn't supposed to be too heavy.

I will fix that chapter soon.