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

[Drew Adams]

>  > The doc doesn't tell you enough about what this function does to be able
>  > to use it.  Compare how?  What does a non-nil or nil return value mean?
>  > Does the order of the two arguments matter?  What's going on here?  What
>  > for?
> 
> I never understood the purpose of this function.  Does anyone use it?

1. Dunno.  Not I, at least not until I understand what it does etc. ;-)
How anyone could introduce a function like this without offering a clue to
what it is about is beyond me.

Looking at window.c, from Emacs 24.3, at least, I see that a comment in the
code says that this function returns t if the two window configs represent
"the same state of affairs", and nil otherwise.

It also says that the function is used by Fequal.  But actually it seems it
is used by internal_equal, which is used by several equality predicates, not
just `equal': `eql', `equal-including-properties', `memql'.

So based on that info I do not understand why this was ever added as a Lisp
function.  Perhaps someone thought we might do more with it in the future?
Or perhaps it was thought that this would be faster than calling `equal' etc.,
which have to test a few things before then get to invoking this.

Whatever the rationale, this function has been around for a long time.

2. Thank you, BTW, for adding Lisp-level things like `window-state-(get|put)'.

3. I would also like to see functions that accept or produce window and frame
configurations optionally accept and produce also Lisp-readable equivalents.

IOW, today, such configurations always use actual window and frame objects,
which are not Lisp-readable.  I would like to see them optionally (e.g. via
optional arguments) use Lisp-readable frame and window states.  IOW, make
it simple to persist such configurations.