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

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

[Drew Adams]

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

In GNU Emacs 24.1.1 (i386-mingw-nt5.1.2600)
 of 2012-06-10 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include'
 

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

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

[Drew Adams]

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

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

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.

Should be documented with revision 110768 on Emacs 24 branch.  Bug closed.

martin