Re: [Emacs-diffs] master 4d3a595: `load-path' should contain only directory names

[Eli Zaretskii]

> From: Stefan Monnier <address@hidden>
> Date: Tue, 27 Oct 2015 18:25:52 -0400
> Cc: address@hidden, address@hidden, address@hidden
> 
> > The manual says "directory name" ends in a slash, and talks about
> > "file name of a directory" which doesn't.
> 
> I don't think we generally use the term "directory name" in such
> a strict sense.  At the very least, in all these years, I never noticed
> that this term had such a precise meaning and it's never bitten me.

It's a very old confusion, yes.  But that doesn't mean IMO that we
shouldn't try to fix it, at least in those places where it's
important.  Like this one.

> > The doc string used "directory name" while the strings in load-path
> > didn't end in a slash.
> 
> That doesn't sound like a problem to me.  I still think:
> 
>    "directory name" is used all over the place to mean "with or without
>    trailing slash, it doesn't matter", so the original doc-string
>    was fine.

Let me describe in more detail the situation which led to these
changes, so that we are sure we are talking about the same issues.

  . Stephen saw that some directories in load-path end in a slash,
    while others don't.

  . He then looked at the doc string and saw that it refers to
    "directory names".

  . He then went to the ELisp manual, which describes "directory name"
    as ending in a slash, and also explains the sometimes-crucial
    difference between that and "a file name of a directory", which
    doesn't end in a slash.

If you disagree that this situation is confusing, I guess we will have
to agree to disagree, because it sounds confusing to me, and it surely
confused Stephen, who is not exactly a newbie.  Specifically, if a
term is in @dfn and indexed, it should define terminology that is both
reasonably rigorous and clear-cut, and is followed by us elsewhere in
Emacs documentation, so that a user who is looking for the meaning of
some term will find its definition, and that definition won't
contradict the actual use (as happened in the case in point).

The changes to the doc string and to the manual were intended to
rectify this confusion.  We now define another term, "directory file
name", and use it in the doc string of load-path, in the text whose
goal is specifically to distinguish between these two forms.