Subject: RE: bug#12158: 24.1; unclear, incomplete doc of window parameter `quit-restore'

From: "Drew Adams" <[email-masked]>
Date: Thu, 9 Aug 2012 07:21:06 -0700

> The value of the `quit-restore' parameter is set by the buffer display
> routines and inspected when quitting the window.  Applications are not
> supposed to inspect or alter the value of this parameter.

If this is supposed to be internal, then do not doc it.  If not, please doc it
so readers can understand.

I only came to this doc because you pointed me to it explicitly, when trying to
investigate a (user) bug.  So it's not super clear (to me) just how internal
this topic should be.

> The window-pub branch contains a detailed description of an earlier
> version of this parameter.  You can find it here:
> http://bzr.savannah.gnu.org/lh/emacs/old-branches/window-pub/a
nnotate/head:/doc/lispref/windows.texi

The existence of that description outside of Emacs does not help users much.

> In the course of subsequent changes to the buffer display code, this
> description was omitted from the current version of the manual.

I guess you are saying that that omission was a mistake.  Please include the
missing info, then.

> These parameters are listed in this node in order to tell programmers
> that their names are in use and which parts of the Emacs code use it.
> If any information is missing, please provide a report.

It is not up to me to determine all that might be missing - I have no idea.  The
explanation should be be complete and understandable; that's all.