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

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

[Phil Sainty]

Changelog.3 records that `display-buffer-in-major-side-window' was
renamed to `window--make-major-side-window'; but no alias from the old
name to the new name was added for backwards-compatibility.

I have at least one library installed (which-key.el) which triggers an
error on this account.






In GNU Emacs 26.1 (build 1, x86_64-pc-linux-gnu, X toolkit, Xaw3d scroll 
bars)
  of 2018-04-15 built on shodan
Windowing system distributor 'The X.Org Foundation', version 
11.0.11804000
System Description:	Ubuntu 16.04.4 LTS

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.

Configured using:
  'configure --prefix=/home/phil/emacs/26.1rc1/usr/local
  --with-x-toolkit=lucid --without-sound'

Configured features:
XAW3D XPM JPEG TIFF GIF PNG RSVG IMAGEMAGICK DBUS GSETTINGS NOTIFY
GNUTLS LIBXML2 FREETYPE XFT ZLIB TOOLKIT_SCROLL_BARS LUCID X11 THREADS
LCMS2

Important settings:
   value of $LANG: en_NZ.UTF-8
   locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
   tooltip-mode: t
   global-eldoc-mode: t
   eldoc-mode: t
   electric-indent-mode: t
   mouse-wheel-mode: t
   tool-bar-mode: t
   menu-bar-mode: t
   file-name-shadow-mode: t
   global-font-lock-mode: t
   font-lock-mode: t
   blink-cursor-mode: t
   auto-composition-mode: t
   auto-encryption-mode: t
   auto-compression-mode: t
   line-number-mode: t
   transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message rmc puny seq byte-opt gv
bytecomp byte-compile cconv cl-loaddefs cl-lib dired dired-loaddefs
format-spec rfc822 mml easymenu mml-sec password-cache epa derived epg
epg-config gnus-util rmail rmail-loaddefs mm-decode mm-bodies mm-encode
mail-parse rfc2231 mailabbrev gmm-utils mailheader sendmail rfc2047
rfc2045 ietf-drums mm-util mail-prsvr mail-utils elec-pair time-date
mule-util tooltip eldoc electric uniquify ediff-hook vc-hooks
lisp-float-type mwheel term/x-win x-win term/common-win x-dnd tool-bar
dnd fontset image regexp-opt fringe tabulated-list replace newcomment
text-mode elisp-mode lisp-mode prog-mode register page menu-bar
rfn-eshadow isearch timer select scroll-bar mouse jit-lock font-lock
syntax facemenu font-core term/tty-colors frame cl-generic cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese eucjp-ms cp51932 hebrew greek romanian slovak czech european
ethiopic indian cyrillic chinese composite charscript charprop
case-table epa-hook jka-cmpr-hook help simple abbrev obarray minibuffer
cl-preloaded nadvice loaddefs button faces cus-face macroexp files
text-properties overlay sha1 md5 base64 format env code-pages mule
custom widget hashtable-print-readable backquote dbusbind inotify lcms2
dynamic-setting system-font-setting font-render-setting x-toolkit x
multi-tty make-network-process emacs)

Memory information:
((conses 16 96629 11156)
  (symbols 48 20708 3)
  (miscs 40 52 168)
  (strings 32 29647 1508)
  (string-bytes 1 762488)
  (vectors 16 13980)
  (vector-slots 8 492622 10468)
  (floats 8 51 93)
  (intervals 56 239 0)
  (buffers 992 11)
  (heap 1024 26898 1103))

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

[Glenn Morris]

Phil Sainty wrote:

> I have at least one library installed (which-key.el) which triggers an
> error on this account.

Sounds like you need to update; ref https://debbugs.gnu.org/24828#19 .

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

[Phil Sainty]

On 2018-04-18 03:51, Glenn Morris wrote:
>> I have at least one library installed (which-key.el) which triggers an
>> error on this account.
> 
> Sounds like you need to update; ref https://debbugs.gnu.org/24828#19 .

Apologies, I should have found that myself.  That's certainly a 
different
situation to what I had thought.

FWIW I've confirmed that the old name doesn't crop up elsewhere in my
own config.

I think that cases like this need to have NEWS entries under the
"Incompatible Lisp Changes" section?  This was a function name which
was not obviously internal (no double-hyphen), so one does tend to
expect it to be documented if it no longer works (and the Changelog
entry is not addressing this aspect).

If the NEWS file mentioned the change and stated plainly that any
libraries using the old name need to be updated, I think it would
assist people who will run into this the way I did.


-Phil

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

[martin rudalics]

 > I think that cases like this need to have NEWS entries under the
 > "Incompatible Lisp Changes" section?  This was a function name which
 > was not obviously internal (no double-hyphen), so one does tend to
 > expect it to be documented if it no longer works (and the Changelog
 > entry is not addressing this aspect).
 >
 > If the NEWS file mentioned the change and stated plainly that any
 > libraries using the old name need to be updated, I think it would
 > assist people who will run into this the way I did.

I've tried to do that now.  Please have a look.

Thanks, martin

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

[Phil Sainty]

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.

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

[Eli Zaretskii]

> Date: Wed, 18 Apr 2018 20:42:23 +1200
> From: Phil Sainty <psainty@orcon.net.nz>
> Cc: 31194@debbugs.gnu.org,
> 	bug-gnu-emacs <bug-gnu-emacs-bounces+psainty=orcon.net.nz@gnu.org>
> 
> "hitherto undocumented" isn't actually true?
> 
> In Emacs 25.3, describe-function tells me:

I'm guessing Martin meant "documented" as in "in the ELisp manual".

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

[Phil Sainty]

On 2018-04-18 20:53, Eli Zaretskii wrote:
> I'm guessing Martin meant "documented" as in "in the ELisp manual".

Right, that probably explains both of my points of confusion!

In that case, I would suggest including a direct reference to the node.

  ** 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
exists.  See the node "(elisp) Displaying Buffers in Side Windows"
in the ELisp manual for more details.

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

[martin rudalics]

>   ** 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
> exists.  See the node "(elisp) Displaying Buffers in Side Windows"
> in the ELisp manual for more details.

Installed.

Thank you, martin

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

[Phil Sainty]

On 2018-04-19 00:20, martin rudalics wrote:
> Installed.

Thanks Martin.  I've just reviewed #24828 and noted that it was you
who made the original code changes, so I'm taking this as confirmation
that I didn't write anything invalid in that NEWS entry :) in which
case this bug can be closed.

cheers,
-Phil

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

[martin rudalics]

> Thanks Martin.  I've just reviewed #24828 and noted that it was you
> who made the original code changes, so I'm taking this as confirmation
> that I didn't write anything invalid in that NEWS entry :) in which
> case this bug can be closed.

Done.

Thanks again for the NEWS entry, martin

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

[Juri Linkov]

>>>   ** 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
>>> exists.  See the node "(elisp) Displaying Buffers in Side Windows"
>>> in the ELisp manual for more details.
>>
>> Installed.
>
> Thanks Martin.  I've just reviewed #24828 and noted that it was you
> who made the original code changes, so I'm taking this as confirmation
> that I didn't write anything invalid in that NEWS entry :) in which
> case this bug can be closed.

Unfortunately, you wrote something invalid in that NEWS entry.
When point is on existing function names, ‘C-h f’ can't find them.
Also coping them causes problems.  This is because there are
many special Unicode characters in your text, namely, “WORD JOINER”.
I can see these hidden characters because I customized the face
‘glyphless-char’ to background "red".

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

[Phil Sainty]

On 2018-04-20 09:24, Juri Linkov wrote:
> Unfortunately, you wrote something invalid in that NEWS entry.
> When point is on existing function names, ‘C-h f’ can't find them.
> Also coping them causes problems.  This is because there are
> many special Unicode characters in your text, namely, “WORD JOINER”.
> I can see these hidden characters because I customized the face
> ‘glyphless-char’ to background "red".

Yikes.  Thank you for catching that.  I'm trying and failing to fathom
how that could have happened.  I thought this webmail client must have
been at fault, but I've also found counter-examples to that, so I'm at
a loss.

Is that glyphless-char face background something you use as standard?
If it doesn't show itself in any normal circumstances, I'd be inclined
to start using it as a safety measure.


-Phil

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

[Phil Sainty]

I take it back -- it's definitely this webmail client.  It's just
automatically inserting WORD JOINER after hyphens in hyphenated words
when it renders email, and seemingly provides no option to control
that behaviour.  I'd obviously copied the previous version of that
NEWS entry from one of the email messages, in order to compose the
final version.

I was never going to notice that on my own, so thanks again for that
and for the glyphless-char pointer.  I'll keep that customized.

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

[martin rudalics]

> Unfortunately, you wrote something invalid in that NEWS entry.
> When point is on existing function names, ‘C-h f’ can't find them.
> Also coping them causes problems.  This is because there are
> many special Unicode characters in your text, namely, “WORD JOINER”.
> I can see these hidden characters because I customized the face
> ‘glyphless-char’ to background "red".

Hopefully fixed now.  Thanks for the heads-up.

martin