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

[martin rudalics]

>> 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.

The value of the parameter is supposed to be internal.

> 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.

I pointed you to it because you apparently were not aware of the
existence of window parameters and looked for frame parameters instead.

>> 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.

It can help anyone interested understand whether describing the
parameter in the manual would help users at all.

>> 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.

Your guess is wrong.

> Please include the
> missing info, then.

AFAICT that information is of no practical value for users.  OTOH
informing users that a parameter with that name exists _is_ of practical
value to avoid that they implement a parameter with the same name.  And
it is of practical value for users to know who creates that parameter
and who uses it.  Otherwise users might think that _they_ are supposed
to change or check that parameter.  If people think that the information
I gave is not needed, I have no problems removing it from the manual.

>> 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.

IMHO the present explantion is complete and understandable.  Programmers
who do need more information will find it in the doc-string of
`display-buffer-record-window'.

martin