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

[martin rudalics]

> In (elisp) `Window Parameters', the description of `quit-restore' is not
> very helpful.  It says what the parameter is used for, and how it is
> established, and even which function uses it.  But it says _nothing_
> about what the parameter value is or how to understand its various
> components.
>
>>From the description of `window-parameters' and experimenting using that
> function we can discover that `quit-restore' has a value that is a list.
> But that is all.  What the parts of that list are and what they mean or
> are used for is a complete mystery.  Here is an example `quit-restore'
> value:
>
> (frame frame #<window 3 on *Messages*> #<buffer *Process List*>)
>
> And?  What is the expected form of the parameter value?  Does it always
> have 4 elements?  What are they - what do they mean?  How are they used?

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.

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/annotate/head:/doc/lispref/windows.texi

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

> OK, so there are two cross references here, that should presumably
> enlighten us.  Following the first and searching for `quit-restore', we
> find NOTHING - it is not even mentioned in that node.
>
> Following the second and searching for `quit-restore', we find only
> this:
>
>  "The function `quit-window' bases its decisions on information stored
>   in WINDOW's `quit-restore' window parameter (*note Window Parameters::),
>   and resets that parameter to `nil' after it's done."
>
> That does not help us at all to understand the `quit-restore' value.
> Searching the rest of the manual shows that there is nothing anywhere
> that helps us interpret `quit-restore' values.
>
> NOTE: It is possible that this comment applies also to other window
> parameters listed in this node.  Please describe each parameter: its
> format (possible values), including the use/meaning of any components of
> possible values.

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.

martin