bug#31194: 26.1; `display-buffer-in-major-side-window' was renamed without an alias.

[Phil Sainty <psainty@orcon.net.nz>]

On 2018-04-18 19:19, martin rudalics wrote:
> I've tried to do that now.  Please have a look.

Cheers. NEWS now says:

> ** The function 'display-buffer-in-major-side-window' is now internal.
> This hitherto undocumented function which existed since Emacs 24.1 has
> been renamed to 'window--make-major-side-window' and its semantics
> changed.  Applications should use the now properly documented function
> 'display-buffer-in-side-window' with appropriate arguments instead.


"hitherto undocumented" isn't actually true?

In Emacs 25.3, describe-function tells me:

> display-buffer-in-major-side-window is a compiled Lisp function in
> ‘window.el’.
> 
> (display-buffer-in-major-side-window BUFFER SIDE SLOT &optional ALIST)
> 
> Display BUFFER in a new window on SIDE of the selected frame.
> SIDE must be one of ‘left’, ‘top’, ‘right’ or ‘bottom’.  SLOT
> specifies the slot to use.  ALIST is an association list of
> symbols and values as passed to ‘display-buffer-in-side-window’.
> This function may be called only if no window on SIDE exists yet.
> The new window automatically becomes the "major" side window on
> SIDE.  Return the new window, nil if its creation window failed.


which is very similar to the docstring of the new function:

> window--make-major-side-window is a compiled Lisp function in
> ‘window.el’.
> 
> (window--make-major-side-window BUFFER SIDE SLOT &optional ALIST)
> 
> Display BUFFER in a new major side window on the selected frame.
> SIDE must be one of ‘left’, ‘top’, ‘right’ or ‘bottom’.  SLOT
> specifies the slot to use.  ALIST is an association list of
> symbols and values as passed to ‘display-buffer-in-side-window’.
> Return the new window, nil if its creation failed.
> 
> This is an auxiliary function of ‘display-buffer-in-side-window’
> and may be called only if no window on SIDE exists yet.


The main difference as far as the docstrings go seems to be:
"This function may be called only if no window on SIDE exists yet",
(and I don't know whether that's a difference in behaviour, or just
improved documentation).


This bit also seems wrong to me:

> the now properly documented function 'display-buffer-in-side-window'

As this function's docstring is unchanged between 25.3 and 26.1rc1.


I would suggest something more like:

** The function 'display-buffer-in-major-side-window' no longer exists.
It has been renamed as internal function 
'window--make-major-side-window',
however applications should instead call 'display-buffer-in-side-window'
(passing the SIDE and SLOT parameters as elements of ALIST).  This 
approach
is backwards-compatible with versions of Emacs in which the old function
is defined.


n.b. I don't know if that last statement is correct back to 24.1?  It's
the impression I have, but someone else would need to confirm it.