bug#14964: 24.3.50; doc of `compare-window-configurations'

[martin rudalics]

> Is there some internal use of Emacs window and frame configurations?

The main purpose of window configurations is with implementing
`save-window-excursion'.

> If not, i.e., if the only use is by users and Lisp code, using the
> available commands and other functions, then is there some reason that
> window and frame configurations should not enjoy the properties you
> mention that are missing and that are available with `window-state-*'?

Speed, I think.  `save-window-excursion' is (unfortunately) used much
too often in order to compromise its behavior.  Saving and restoring a
frame configurations doesn't do any size checking, window splitting,
suppression of associated error messages - it does its job as quickly as
possible.  For this purpose, a stored window configuration inhibits the
collection of its window objects so it doesn't have to create them anew.

> The data structure returned by `window-state-get' is not recognizable as
> such.  There is not even a `window-state-p' predicate, let alone documented
> components.  This is the only documentation I have seen - a comment in
> `window-state-get':
>
> ;; The return value is a cons whose car specifies some constraints on
> ;; the size of WINDOW.  The cdr lists the states of the child windows
> ;; of WINDOW.
>
> And there is no documentation of either the car (what constraints? in what
> form?) or the cdr (what form? what order (if important)?)), beyond that.

If I had wanted to document that, I would have added the above text to
the doc-string of `window-state-get'.

> A proper, documented structure (whether list or defstruct) is what I would
> like to see instead.

Then please, please write one.  We all would have to start from scratch
doing that.  And you know best what you want to see.

> And unless there are really some good reasons not to,
> I would like to see the same structure used by the window-configuration
> functions (`current-window-configuration', `set-window-configuration',
> `window-configuration-p', `window-configuration-to-register').

Where would you like to see that?  That's a C structure without any Lisp
equivalent.  It would have to go to the Window Internals section but
that one is far from accurate.

Window configurations have been devised to restore a previous frame
state in one and the same session.  Otherwise they were completely
opaque.  Window states have been devised to restore a previous frame
state in another session and are opaque as well.  Looking into such
objects, documenting them accurately and providing routines to convert
one into the other would be quite beneficial for both - users and
developers.  But this should be really done by someone who wants to
exploit and test the results in actual code.

martin