Docstring of make-symbolic-link

Docstring of make-symbolic-link

[Juanma Barranquero]

make-symbolic link uses NEWNAME in its docstring, but LINKNAME as the
argument name:

  (make-symbolic-link TARGET LINKNAME &optional OK-IF-ALREADY-EXISTS)

  Make a symbolic link to TARGET, named NEWNAME.
  If NEWNAME is a directory name, make a like-named symbolic link under
  NEWNAME.

  [etc...]

The easiest way to fix it is to change NEWNAME to LINKNAME in the
docstring, but I think NEWNAME is the preferred name, and it is also
used in the info files.

The alternative is to change linkname to newname in the code, and
encoded_linkname to encoded_newname (not required, but for
consistency).

It is a trivial change, but as it touches code in 26.2.50, better safe
than sorry. So, newname everywhere, or linkname everywhere (including
the info files)?

Re: Docstring of make-symbolic-link

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Mon, 10 Jun 2019 21:44:46 +0200
> 
> make-symbolic link uses NEWNAME in its docstring, but LINKNAME as the
> argument name:
> 
>   (make-symbolic-link TARGET LINKNAME &optional OK-IF-ALREADY-EXISTS)
> 
>   Make a symbolic link to TARGET, named NEWNAME.
>   If NEWNAME is a directory name, make a like-named symbolic link under
>   NEWNAME.
> 
>   [etc...]

This appears to be some kind of copy-pasta from add-name-to-file,
which creates a hard link.

> The easiest way to fix it is to change NEWNAME to LINKNAME in the
> docstring, but I think NEWNAME is the preferred name, and it is also
> used in the info files.
> 
> The alternative is to change linkname to newname in the code, and
> encoded_linkname to encoded_newname (not required, but for
> consistency).
> 
> It is a trivial change, but as it touches code in 26.2.50, better safe
> than sorry. So, newname everywhere, or linkname everywhere (including
> the info files)?

My vote is for LINKNAME.

Re: Docstring of make-symbolic-link

[Paul Eggert]

On 6/11/19 7:22 AM, Eli Zaretskii wrote:
> This appears to be some kind of copy-pasta from add-name-to-file,
> which creates a hard link.

Yes, and that's a good thing because hard links and symbolic links are 
similar here.

We should use "NEWNAME" here, not merely for consistency with 
add-name-to-file, but also because using "NEWNAME" makes it clearer that 
it's the thing being created instead of TARGET. It's all too easy to 
misread "(make-symbolic-link TARGET LINKNAME)" as meaning that TARGET 
gets created with the contents LINKNAME, which is the opposite of what 
the function actually does.

Re: Docstring of make-symbolic-link

[Juanma Barranquero]

Three people, two opinions.

It's your call, Eli. LINKNAME or NEWNAME?

Re: Docstring of make-symbolic-link

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Thu, 13 Jun 2019 00:31:39 +0200
> Cc: Eli Zaretskii <eliz@gnu.org>, Emacs developers <emacs-devel@gnu.org>
> 
> Three people, two opinions.
> 
> It's your call, Eli. LINKNAME or NEWNAME?

I understand that you prefer NEWNAME as well, so I'm in a minority
here.

I don't want to force my opinion on this, for reasons that might
become apparent from what I say below.  I do want to explain my
opinion, though, at least FTR.

This NEWNAME thing never made much sense to me.  When creating hard
links, we call the function ADD-NAME-to-file, so NEW makes sense.
With make-symbolic-link this reason is gone, and NEW is just out of
the blue, as there's no OLD anywhere in sight.  TARGET and LINK do
make sense, and unlike Paul, I have no problems figuring out which one
is created, since the function's name is make-symbolic-LINK, not
make-symbolic-TARGET.

I understand where Paul comes from: this description goes back to the
old days of 4.2BSD Unix, where symbolic links were introduced, AFAIK.
Look at the man pages from that era, you will see the same NEWNAME
nonsense.  So this is an old habit that dies hard, IMNSHO.  I suspect
that if we were to remove the NEWNAME part, many Unix old-timers will
object like Paul did.

Btw, the glibc manual at least tries to make it a bit more sensible:

  int symlink (const char *OLDNAME, const char *NEWNAME)
  [...]
  The 'symlink' function makes a symbolic link to OLDNAME named
  NEWNAME.

So now you know my views on this, and can make up your mind.  But
whatever you do, let's do that on master, as the first pretest of
Emacs 26.3 is already out, and I'd prefer to release it VSN, if
possible.  This text was with us since about forever, so no urgency to
fix it in 26.3.

Thanks.

Re: Docstring of make-symbolic-link

[Juanma Barranquero]

> I understand that you prefer NEWNAME as well, so I'm in a minority
> here.

Not really. My comment was (or at least, intended to be, but my
English perhaps got in the middle) that I thought that using NEWNAME
was not the result of copy&paste, but a deliberate decision. But I
didn't really express any preference on my own.

> So now you know my views on this, and can make up your mind.

I'm partial to LINKNAME. I find it much more descriptive and to the
point that NEWNAME.

> But
> whatever you do, let's do that on master, as the first pretest of
> Emacs 26.3 is already out, and I'd prefer to release it VSN, if
> possible.

Fixing it to LINKNAME is just adjusting the docstring and one info
file, so it shouldn't be a problem. I thought documentation fixes and
typos are allowed during the pretest? Or do you really prefer even
that change to go to the master?

Re: Docstring of make-symbolic-link

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Thu, 13 Jun 2019 09:41:49 +0200
> Cc: Paul Eggert <eggert@cs.ucla.edu>, Emacs developers <emacs-devel@gnu.org>
> 
> I'm partial to LINKNAME. I find it much more descriptive and to the
> point that NEWNAME.

OK, so we agree.

> > But
> > whatever you do, let's do that on master, as the first pretest of
> > Emacs 26.3 is already out, and I'd prefer to release it VSN, if
> > possible.
> 
> Fixing it to LINKNAME is just adjusting the docstring and one info
> file, so it shouldn't be a problem. I thought documentation fixes and
> typos are allowed during the pretest? Or do you really prefer even
> that change to go to the master?

If this is the change, then yes, emacs-26 should be fine for it.  But
let's first wait for a while, to let others object, and then decide.

Re: Docstring of make-symbolic-link

[Juanma Barranquero]

On Thu, Jun 13, 2019 at 10:57 AM Eli Zaretskii <eliz@gnu.org> wrote:

>
> If this is the change, then yes, emacs-26 should be fine for it.  But
> let's first wait for a while, to let others object, and then decide.

No other opinions for almost a week.

Re: Docstring of make-symbolic-link

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Wed, 19 Jun 2019 23:33:02 +0200
> Cc: Paul Eggert <eggert@cs.ucla.edu>, Emacs developers <emacs-devel@gnu.org>
> 
> On Thu, Jun 13, 2019 at 10:57 AM Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >
> > If this is the change, then yes, emacs-26 should be fine for it.  But
> > let's first wait for a while, to let others object, and then decide.
> 
> No other opinions for almost a week.

So what are your suggestions?

Re: Docstring of make-symbolic-link

[Juanma Barranquero]

Commiting to the release branch a simple patch that changes the
docstring and the info file to refer to LINKNAME.

This fixes a docstring bug in the release, doesn't touch any code, and
if there's dissent later, we can rename it to our heart's desire in
the trunk.

Re: Docstring of make-symbolic-link

[Eli Zaretskii]

> From: Juanma Barranquero <lekktu@gmail.com>
> Date: Fri, 21 Jun 2019 09:57:04 +0200
> Cc: Paul Eggert <eggert@cs.ucla.edu>, Emacs developers <emacs-devel@gnu.org>
> 
> Commiting to the release branch a simple patch that changes the
> docstring and the info file to refer to LINKNAME.

Fine with me.  If people are unhappy, we can always do better on
master.

Thanks.