Subject: bug#13033: 24.3.50; regression: read-file-name-internal handles "~" wrong

From: Eli Zaretskii <[email-masked]>
Date: Fri, 30 Nov 2012 15:55:45 +0200

> From: Michael Heerdegen <[email-masked]>
> Date: Fri, 30 Nov 2012 14:12:14 +0100
> Cc: [email-masked]
> 
> Juanma Barranquero <[email-masked]> writes:
> 
> > On Thu, Nov 29, 2012 at 10:44 PM, Drew Adams <[email-masked]> wrote:
> >
> > > In this Emacs version,
> > > (read-file-name-internal "~" 'file-exists-p nil) returns "~/dradams/".
> >
> > read-file-name-internal's docstring clearly says:  "Internal
> > subroutine for `read-file-name'.  Do not call this."
> 
> I'm not sure if I understand the implications.  I thought something like
> "Do not call this." is meant for the end users, but also for developers?

It means "don't call it from Lisp applications outside basic Lisp
packages that come with Emacs."

If that is a limitation, then I suggest to request additional APIs or
extension of existing APIs, to cover the features which you miss in
the current code base and that prompted you to use this function.

> Emacs is the "extensible ... editor".  It is quite difficult for any
> developer to extend Emacs and contribute packages if we only allow the
> use of high-level public interface functions.

If that is true, then Emacs lacks some public APIs that should be
added or extended.  Using internal functions is not the way.

> If we start to change our habits and write Emacs in a way that essential
> primitives aren't allowed to be called by developers, this is the
> beginning of the end of extensibility.

Most primitives _are_ allowed to be called.  But when you see
something like "internal use only, don't call", that is not something
you should ignore, because whoever wrote that had something serious in
their minds.

> It is a bug if something like `read-file-name-internal' is not
> allowed to be called in third-party packages.

Then please submit bug reports, asking for features that you cannot
get from other APIs.

> At university I learned that writing software happens in a way that
> every function should have a clear specification for what it
> does/returns, and a documentation of this.

If they didn't teach you about the difference between internal APIs
and public APIs, then it's too bad.  Nevertheless, the distinction is
part of our lives.  Some languages have means to conceal private APIs
from external applications, but C and Emacs Lisp don't.  So we use
whatever we got; please always assume that there are good reasons for
that.  (It is OK, of course, to question those reasons, but ignoring
them is not wise, IMO.)