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

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

[Stefan Monnier]

>     `load-path' should contain only directory names

You mean names with a trailing slash?  Why?


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Date: Sat, 24 Oct 2015 09:49:29 -0400
> Cc: Stephen Leake <stephen_leake@stephe-leake.org>
> 
> >     `load-path' should contain only directory names
> 
> You mean names with a trailing slash?  Why?

No, he means without the trailing slash.

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

[Stefan Monnier]

>> >     `load-path' should contain only directory names
>> You mean names with a trailing slash?  Why?
> No, he means without the trailing slash.

Same difference: why?
In any case the code that uses load-path can't assume that there is (or
isn't) a slash, because some .emacs files use a trailing slash and
others don't.


        Stefan

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

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
>> Date: Sat, 24 Oct 2015 09:49:29 -0400
>> Cc: Stephen Leake <stephen_leake@stephe-leake.org>
>> 
>> >     `load-path' should contain only directory names
>> 
>> You mean names with a trailing slash?  Why?
>
> No, he means without the trailing slash.

Hmm. I now realize this is confused, and the doc string for `load-path'
does not match the implementation.

Here's the `load-path' doc string (from master):

   List of directories to search for files to load.
   Each element is a string (directory name) or nil (meaning ‘default-directory’).
   Initialized during startup as described in Info node ‘(elisp)Library Search’.


That says "directory name".

(info "(elisp) Directory Names") says:

   On GNU and Unix systems, this is simple: a directory name ends in a
   slash, whereas the directory’s name as a file lacks that slash.


This info node does not give a canonical phrase for "the directory's name as
a file". This is the string returned by `directory-file-name'; I guess
"directory file name" works.

In emacs -Q, `load-path' has no terminating slashes.


I have the impression that some other documentation uses "directory"
instead of "directory name", but I can't find a good example at the moment.


So the doc string for `load-path' should be changed to:

   List of directories to search for files to load.
   Each element is a string (directory file name) or nil (meaning ‘default-directory’).
   Initialized during startup as described in Info node ‘(elisp)Library Search’.

(just added 'file') possibly refilled.

And the info node should define "directory file name".


However, there is one more quirk; `default-directory' does end in a
slash, so having nil mean that in `load-path' is inconsistent. Should
that then be:

 ... or nil (meaning (directory-file-name default-directory)).

?

I don't think I've ever had nil in `load-path'; that seems like a bug,
comparable to having "." in PATH. And most of the path iterating code
I've written would fail on nil (sigh).


-- 
-- Stephe

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: emacs-devel@gnu.org, stephen_leake@stephe-leake.org
> Date: Sat, 24 Oct 2015 17:15:27 -0400
> 
> >> >     `load-path' should contain only directory names
> >> You mean names with a trailing slash?  Why?
> > No, he means without the trailing slash.
> 
> Same difference: why?

Because the documentation says so.

> In any case the code that uses load-path can't assume that there is (or
> isn't) a slash, because some .emacs files use a trailing slash and
> others don't.

I agree that the code should be defensive.  But that's not the issue
here.  The issue was the additions made by package.el.

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

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Cc: Stefan Monnier <monnier@IRO.UMontreal.CA>,  emacs-devel@gnu.org
> Date: Sat, 24 Oct 2015 16:37:43 -0500
> 
> > No, he means without the trailing slash.
> 
> Hmm. I now realize this is confused, and the doc string for `load-path'
> does not match the implementation.
> 
> Here's the `load-path' doc string (from master):
> 
>    List of directories to search for files to load.
>    Each element is a string (directory name) or nil (meaning 
> ‘default-directory’).
>    Initialized during startup as described in Info node ‘(elisp)Library Search’.
> 
> That says "directory name".

> (info "(elisp) Directory Names") says:
> 
>    On GNU and Unix systems, this is simple: a directory name ends in a
>    slash, whereas the directory’s name as a file lacks that slash.
> 
> This info node does not give a canonical phrase for "the directory's name as
> a file". This is the string returned by `directory-file-name'; I guess
> "directory file name" works.

It's easy to get these two confused, especially since one is shorter.

Let's say "directory file name" in the doc string of 'load-path',
since we've been doing that since time immemoriam.

> In emacs -Q, `load-path' has no terminating slashes.

Yes, because startup.el uses directory-files to get the standard
subdirectories of lisp/, and the lisp/ directory itself starts without
the trailing slash (by magic of the processed epaths.in).

> I have the impression that some other documentation uses "directory"
> instead of "directory name", but I can't find a good example at the moment.

I don't think this distinction between "directory" the object and its
name (see Lewis Carrol's immortal text on that) is relevant to the
issue at hand.  Here we are talking about 2 possible forms of the
directory's name.

> So the doc string for `load-path' should be changed to:
> 
>    List of directories to search for files to load.
>    Each element is a string (directory file name) or nil (meaning 
> ‘default-directory’).

Yes, and also a reference to 'directory-file-name' would be useful
here.

>    Initialized during startup as described in Info node ‘(elisp)Library Search’.
> 
> (just added 'file') possibly refilled.
> 
> And the info node should define "directory file name".

Yup.  Patches welcome, thanks in advance.

> However, there is one more quirk; `default-directory' does end in a
> slash, so having nil mean that in `load-path' is inconsistent. Should
> that then be:
> 
>  ... or nil (meaning (directory-file-name default-directory)).
> 
> ?

I don't think this subtlety is relevant.  The issue at hand is the
_form_, not the _semantics_.  As far as the form is concerned, nil
doesn't end in a slash, and you cannot use it in 'concat' for
generating a file name with leading directories anyway; you must use
'expand-file-name', which already does TRT.

> I don't think I've ever had nil in `load-path'; that seems like a bug,
> comparable to having "." in PATH.

No, it's a feature.  I did see that at some point, don't remember
where and why.

> And most of the path iterating code I've written would fail on nil
> (sigh).

If you use 'expand-file-name', it will "just work".

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

[Stefan Monnier]

> I agree that the code should be defensive.  But that's not the issue
> here.  The issue was the additions made by package.el.

I don't think we could/should aim to get rid of the defensiveness, so
it'd here to stay.  So we may as well take advantage of it and use
either the slashed or the non-slashed form depending on the convenience
of the moment.  That's what we've been doing "for ever" and it seems to
work just fine, I see no need to change it.


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: emacs-devel@gnu.org, stephen_leake@stephe-leake.org
> Date: Sun, 25 Oct 2015 22:04:19 -0400
> 
> > I agree that the code should be defensive.  But that's not the issue
> > here.  The issue was the additions made by package.el.
> 
> I don't think we could/should aim to get rid of the defensiveness, so
> it'd here to stay.  So we may as well take advantage of it and use
> either the slashed or the non-slashed form depending on the convenience
> of the moment.  That's what we've been doing "for ever" and it seems to
> work just fine, I see no need to change it.

IMO, it just looks sloppy on our part if we are inconsistent in
setting the value of that list.  The solution was easy, so I think it
was a good cleanup.

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

[Stephen J. Turnbull]

Eli Zaretskii writes:

 > IMO, it just looks sloppy on our part if we are inconsistent in
 > setting the value of that list.  The solution was easy, so I think it
 > was a good cleanup.

+1.

XEmacs is pretty careful about using directory names (ie, with
trailing slash) in variables named like "foo-path".  I do think it
looks better to be consistent.

Perhaps it would be useful to have

(defun prepend-to-directory-path (path-variable &rest directories)
  ;; don't use add-to-list because it won't reorder the path for
  ;; directories already present
  (set path-variable (nconc (nreverse (mapcar (lambda (dir)
                                               (file-name-as-directory
                                                (expand-file-name dir)))))
                            (symbol-value path-variable))))

Of course the `file-name-as-directory' could be replaced by
`directory-file-name' if preferred (yes, it's needed for consistency,
in XEmacs at least: `expand-file-name' doesn't strip trailing slashes).

I hereby relinquish all claim to the above defun.  Ie, it's now in the
public domain AFAIK.  Even if it does qualify as a small change. :-)

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

[Stephen Leake]

[-- Attachment #1: Type: text/plain, Size: 1320 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

> Let's say "directory file name" in the doc string of 'load-path',
> since we've been doing that since time immemoriam.

See attached patch; if approved, I'll push it.
>
> Yes, and also a reference to 'directory-file-name' would be useful
> here.

Added "Use `directory-file-name' when adding items to this path."

>> And the info node should define "directory file name".
>
> Yup.  Patches welcome, thanks in advance.

Using "directory file name" consistently in that section makes it
cleaner, I think; see patch.

>> However, there is one more quirk; `default-directory' does end in a
>> slash, so having nil mean that in `load-path' is inconsistent. Should
>> that then be:
>> 
>>  ... or nil (meaning (directory-file-name default-directory)).
>> 
>> ?
>
> I don't think this subtlety is relevant.  The issue at hand is the
> _form_, not the _semantics_.  As far as the form is concerned, nil
> doesn't end in a slash, and you cannot use it in 'concat' for
> generating a file name with leading directories anyway; you must use
> 'expand-file-name', which already does TRT.

I added the suggestion to use `expand-file-name' in the info section. It
might make sense to suggest only that; I'm not clear if there is a speed
difference, but it's probably negligible.

-- 
-- Stephe

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: dirnames.patch --]
[-- Type: text/x-patch, Size: 4373 bytes --]

diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index ca8abe5..61a00cd 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2041,29 +2041,31 @@ forward slash (@samp{/}) character.
 @cindex file name of directory
 
   A @dfn{directory name} is the name of a directory.  A directory is
-actually a kind of file, so it has a file name, which is related to
-the directory name but not identical to it.  (This is not quite the
-same as the usual Unix terminology.)  These two different names for
-the same entity are related by a syntactic transformation.  On GNU and
-Unix systems, this is simple: a directory name ends in a slash,
-whereas the directory's name as a file lacks that slash.  On MS-DOS
-the relationship is more complicated.
-
-  The difference between a directory name and its name as a file is
+actually a kind of file, so it has a file name (called the
+@dfn{directory file name}, which is related to the directory name but
+not identical to it.  (This is not quite the same as the usual Unix
+terminology.)  These two different names for the same entity are
+related by a syntactic transformation.  On GNU and Unix systems, this
+is simple: a directory name ends in a slash, whereas the directory
+file name lacks that slash.  On MS-DOS the relationship is more
+complicated.
+
+  The difference between directory name and directory file name is
 subtle but crucial.  When an Emacs variable or function argument is
-described as being a directory name, a file name of a directory is not
+described as being a directory name, a directory file name is not
 acceptable.  When @code{file-name-directory} returns a string, that is
 always a directory name.
 
-  The following two functions convert between directory names and file
-names.  They do nothing special with environment variable substitutions
-such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
+  The following two functions convert between directory names and
+directory file names.  They do nothing special with environment
+variable substitutions such as @samp{$HOME}, and the constructs
+@samp{~}, @samp{.} and @samp{..}.
 
 @defun file-name-as-directory filename
 This function returns a string representing @var{filename} in a form
-that the operating system will interpret as the name of a directory.  On
-most systems, this means appending a slash to the string (if it does not
-already end in one).
+that the operating system will interpret as the name of a directory (a
+directory name).  On most systems, this means appending a slash to the
+string (if it does not already end in one).
 
 @example
 @group
@@ -2074,10 +2076,10 @@ already end in one).
 @end defun
 
 @defun directory-file-name dirname
-This function returns a string representing @var{dirname} in a form that
-the operating system will interpret as the name of a file.  On most
-systems, this means removing the final slash (or backslash) from the
-string.
+This function returns a string representing @var{dirname} in a form
+that the operating system will interpret as the name of a file (a
+directory file name).  On most systems, this means removing the final
+slash (or backslash) from the string.
 
 @example
 @group
@@ -2119,6 +2121,13 @@ Don't try concatenating a slash by hand, as in
 because this is not portable.  Always use
 @code{file-name-as-directory}.
 
+  To avoid the issues mentioned above, or if the @var{dirname} value
+might be nil (for example, from an element of @var{load-path}), use:
+
+@example
+(expand-file-name @var{relfile} @var{dirname})
+@end example
+
   To convert a directory name to its abbreviation, use this
 function:
 
--- a/src/lread.c
+++ b/src/lread.c
@@ -4479,8 +4479,9 @@ were read in.  */);
 
   DEFVAR_LISP ("load-path", Vload_path,
 	       doc: /* List of directories to search for files to load.
-Each element is a string (directory name) or nil (meaning `default-directory').
-Initialized during startup as described in Info node `(elisp)Library Search'.  */);
+Each element is a string (directory file name) or nil (meaning `default-directory').
+Initialized during startup as described in Info node `(elisp)Library Search'.
+Use `directory-file-name' when adding items to this path.  */);
 
   DEFVAR_LISP ("load-suffixes", Vload_suffixes,
 	       doc: /* List of suffixes for (compiled or source) Emacs Lisp files.

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

[Dmitry Gutov]

On 10/26/2015 03:19 PM, Stephen Leake wrote:

> Added "Use `directory-file-name' when adding items to this path."

Do you expect any code on Emacs to rely on this? Will it make a difference?

What's going to happen to existing user configurations which use the 
"other" name (with trailing slash)?

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

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Cc: monnier@IRO.UMontreal.CA,  emacs-devel@gnu.org
> Date: Mon, 26 Oct 2015 08:19:25 -0500
> 
> > Let's say "directory file name" in the doc string of 'load-path',
> > since we've been doing that since time immemoriam.
> 
> See attached patch; if approved, I'll push it.

LGTM, but see the few comments below.

>    A @dfn{directory name} is the name of a directory.  A directory is
> -actually a kind of file, so it has a file name, which is related to
> -the directory name but not identical to it.  (This is not quite the
> -same as the usual Unix terminology.)  These two different names for
> -the same entity are related by a syntactic transformation.  On GNU and
> -Unix systems, this is simple: a directory name ends in a slash,
> -whereas the directory's name as a file lacks that slash.  On MS-DOS
> -the relationship is more complicated.
> -
> -  The difference between a directory name and its name as a file is
> +actually a kind of file, so it has a file name (called the
> +@dfn{directory file name}, which is related to the directory name but
> +not identical to it.  (This is not quite the same as the usual Unix
> +terminology.)  These two different names for the same entity are
> +related by a syntactic transformation.  On GNU and Unix systems, this
> +is simple: a directory name ends in a slash, whereas the directory
> +file name lacks that slash.  On MS-DOS the relationship is more
> +complicated.

This is a good change, but we generally observe the rule of indexing
any phrase that we give the @dfn markup.  The rationale is that this
is terminology, and someone might want to find its description by
using the Info index searching commands (or by looking in the Inde of
a printed book).  So please add an index entry for "directory file
name", similarly to what we already have for "directory name".

> +  To avoid the issues mentioned above, or if the @var{dirname} value
> +might be nil (for example, from an element of @var{load-path}), use:

load-path is a literal symbol, so it should be in @code, not @var.
The latter is for symbols that stand for something else (a.k.a.
"variables" that can be assigned a value)

> +Each element is a string (directory file name) or nil (meaning `default-directory').

This line is too long, please break it into two.

Otherwise okay, thanks.

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

[Eli Zaretskii]

> Cc: monnier@IRO.UMontreal.CA, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Mon, 26 Oct 2015 15:28:42 +0200
> 
> On 10/26/2015 03:19 PM, Stephen Leake wrote:
> 
> > Added "Use `directory-file-name' when adding items to this path."
> 
> Do you expect any code on Emacs to rely on this? Will it make a difference?

IMO, code shouldn't rely on that.

The modified documentation advises to use expand-file-name, in which
case both forms will work.

> What's going to happen to existing user configurations which use the 
> "other" name (with trailing slash)?

Nothing, except that we can point them to the docs and say that they
live dangerously ;-)

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

[Stefan Monnier]

> Nothing, except that we can point them to the docs and say that they
> live dangerously ;-)

So you live dangerously if you forget the trailing slash in
default-directory, but you live dangerously if you do add it in
load-path?

What's the benefit of this pickiness?

Unless there's a real performance advantage (which I fail to see), I'd
rather go the other way and be more permissive and fix default-directory
so it also works correctly when it doesn't have a trailing slash.


        Stefan "who's waiting for someone to quote him opposing such
                a move on default-directory"

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

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

> So please add an index entry for "directory file
> name", similarly to what we already have for "directory name".

I think this just means replacing this current line in files.texi:

@cindex file name of directory

with:

@cindex directory file name

Or is there more to do to create an index entry?

Hmm. I guess it would not hurt to keep both index entries?

-- 
-- Stephe

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Dmitry Gutov <dgutov@yandex.ru>,  stephen_leake@stephe-leake.org,  emacs-devel@gnu.org
> Date: Mon, 26 Oct 2015 13:47:14 -0400
> 
> > Nothing, except that we can point them to the docs and say that they
> > live dangerously ;-)
> 
> So you live dangerously if you forget the trailing slash in
> default-directory, but you live dangerously if you do add it in
> load-path?

If you wish.

> What's the benefit of this pickiness?

Which one?

> Unless there's a real performance advantage (which I fail to see), I'd
> rather go the other way and be more permissive and fix default-directory
> so it also works correctly when it doesn't have a trailing slash.

We are permissive.  We just want to be consistent in the stuff we
generate.

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

[Eli Zaretskii]

> From: Stephen Leake <stephen_leake@stephe-leake.org>
> Cc: monnier@IRO.UMontreal.CA,  emacs-devel@gnu.org
> Date: Mon, 26 Oct 2015 12:55:20 -0500
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > So please add an index entry for "directory file
> > name", similarly to what we already have for "directory name".
> 
> I think this just means replacing this current line in files.texi:
> 
> @cindex file name of directory
> 
> with:
> 
> @cindex directory file name

No, I'd rather we kept that and added the new one.

In general, it's normally a good idea to have "permuted" index
entries, because you cannot know in advance how people will think
about a certain subject and what will they type at the `i's prompt.

> Hmm. I guess it would not hurt to keep both index entries?

Yes, please.

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

[Dmitry Gutov]

On 10/26/2015 07:47 PM, Stefan Monnier wrote:

> Unless there's a real performance advantage (which I fail to see), I'd
> rather go the other way and be more permissive and fix default-directory
> so it also works correctly when it doesn't have a trailing slash.

Yes. I don't remember how exactly much, but I've spent an inordinate 
amount of time finding out that default-directory needs a trailing 
slash, when working on xref.

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

[Dmitry Gutov]

On 10/26/2015 08:30 PM, Eli Zaretskii wrote:

>> What's the benefit of this pickiness?
>
> Which one?

I'd say both: especially when they're inconsistent.

>> Unless there's a real performance advantage (which I fail to see), I'd
>> rather go the other way and be more permissive and fix default-directory
>> so it also works correctly when it doesn't have a trailing slash.
>
> We are permissive.  We just want to be consistent in the stuff we
> generate.

load-path is a user-level variable. Changing package.el behavior is 
fine, but if we document load-path to only have "directory name" 
elements, some code might decide to rely on it.

Not sure if it's plausible to write code that would work on elements 
without trailing slash but wouldn't work without, but if it is, that's a 
more in the wrong direction, IMHO.

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

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org, stephen_leake@stephe-leake.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Mon, 26 Oct 2015 20:47:36 +0200
> 
> > We are permissive.  We just want to be consistent in the stuff we
> > generate.
> 
> load-path is a user-level variable. Changing package.el behavior is 
> fine, but if we document load-path to only have "directory name" 
> elements, some code might decide to rely on it.

We don't advise to rely on that.  We also recommend using
expand-file-name, which should tolerate both.

If someone wants to fix default-directory to not use the trailing
slash, I don't object.  I just hope we won't have to discuss all the
other variables that hold directory names.

All in all, I feel that this bikeshedding episode should end.

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

[Dmitry Gutov]

On 10/26/2015 08:58 PM, Eli Zaretskii wrote:

> We don't advise to rely on that.

AFAICS, Stephen's patch documents the value in detail ("directory file 
name", "Use `directory-file-name' when adding items to this path"). 
That's something a programmer might choose to rely on.

> We also recommend using
> expand-file-name, which should tolerate both.

It's not for all use cases.

> If someone wants to fix default-directory to not use the trailing
> slash, I don't object.  I just hope we won't have to discuss all the
> other variables that hold directory names.

But default-directory is relevant: I actually had to use load-path 
elements as default-directory values.

> All in all, I feel that this bikeshedding episode should end.

I said my part.

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

[Stephen Leake]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stephen Leake <stephen_leake@stephe-leake.org>
>> Cc: monnier@IRO.UMontreal.CA,  emacs-devel@gnu.org
>> Date: Mon, 26 Oct 2015 12:55:20 -0500
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> > So please add an index entry for "directory file
>> > name", similarly to what we already have for "directory name".
>> 
>> I think this just means replacing this current line in files.texi:
>> 
>> @cindex file name of directory
>> 
>> with:
>> 
>> @cindex directory file name
>
> No, I'd rather we kept that and added the new one.
>
> In general, it's normally a good idea to have "permuted" index
> entries, because you cannot know in advance how people will think
> about a certain subject and what will they type at the `i's prompt.
>
>> Hmm. I guess it would not hurt to keep both index entries?
>
> Yes, please.

Ok, pushed.

-- 
-- Stephe

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

[Stephen Leake]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Nothing, except that we can point them to the docs and say that they
>> live dangerously ;-)
>
> So you live dangerously if you forget the trailing slash in
> default-directory, but you live dangerously if you do add it in
> load-path?

Yes, that's what the current implementation provides. I agree it's not
consistent (apparently XEmacs is more consistent here).

> What's the benefit of this pickiness?

When you are writing code that iterates thru load-path, using the
entries for various things (checking that they exist, listing contents),
it helps to know how they are defined.

> Unless there's a real performance advantage (which I fail to see), 

The only performance advantage so far is the difference between:

(expand-file-name file dir)
;; full defensive programming

(concat dir file)
;; assuming the doc string is right, and/or has been verified at a
;; higher level

which is not likely to be significant in code that is reading the actual
disk (that will be the slow part).

> I'd rather go the other way and be more permissive and fix
> default-directory so it also works correctly when it doesn't have a
> trailing slash.

You can't "fix" default-directory; you could change its definition, but
then you would have to fix (or at least verify)_every_ use of it, which
is impossible, since it could be used in everyone's private code.

We are changing the doc string of load-path, but only because it was
inconsistent with the actual implementation in core. It is now consistent.

-- 
-- Stephe

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

[Dmitry Gutov]

On 10/26/2015 10:02 PM, Stephen Leake wrote:

> You can't "fix" default-directory; you could change its definition, but
> then you would have to fix (or at least verify)_every_ use of it, which
> is impossible, since it could be used in everyone's private code.

All uses that take advantage of "requires trailing slash" are arguably 
bugs. This kind of uses:

(let ((default-directory "~/.emacs.d")) (shell-command-to-string "pwd"))

=> "/home/gutov\n"

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

[Stefan Monnier]

>> > Nothing, except that we can point them to the docs and say that they
>> > live dangerously ;-)
[...]
> We are permissive.

The above two statement are not mutually consistent, IMO.

> We just want to be consistent in the stuff we generate.

I'm fine with this.  But I object to documenting too precisely the form
that should be in load-path and then tell people that if they don't do
that they live dangerously.


        Stefan

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

[Stefan Monnier]

>> Unless there's a real performance advantage (which I fail to see), I'd
>> rather go the other way and be more permissive and fix default-directory
>> so it also works correctly when it doesn't have a trailing slash.
> Yes.  I don't remember how exactly much, but I've spent an inordinate amount
> of time finding out that default-directory needs a trailing slash, when
> working on xref.

I encourage you to fix it.  AFAIK the process.c code is the only one
that relies on the trailing slash.

I think the current handling of default-directory in process.c (where
anything after the last slash is ignored) is just a bug since it's
inconsistent with other uses (e.g. (let ((default-directory "/a/b"))
(expand-file-name "c")) returns "/a/b/c" as you'd expect and not "/a/c"
as process.c understands it).


        Stefan

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

[Stefan Monnier]

>> So you live dangerously if you forget the trailing slash in
>> default-directory, but you live dangerously if you do add it in
>> load-path?
> Yes, that's what the current implementation provides. I agree it's not
> consistent (apparently XEmacs is more consistent here).

If we really want to be anal-retentive, then at the very least we should
be consistent.

>> What's the benefit of this pickiness?
> When you are writing code that iterates thru load-path, using the
> entries for various things (checking that they exist, listing contents),
> it helps to know how they are defined.

I too can come up with hypothetical benefits: my question was about
*concrete* benefits.

>> Unless there's a real performance advantage (which I fail to see), 
> The only performance advantage so far is the difference between:
> (expand-file-name file dir)
> ;; full defensive programming
> (concat dir file)
> ;; assuming the doc string is right, and/or has been verified at a
> ;; higher level

I see 10 characters saved above.  Doesn't sound like a real performance
advantage [ yes, I know you were referring to another kind of
performance, but without real-world measurements this has no meaning.  ]

> which is not likely to be significant in code that is reading the actual
> disk (that will be the slow part).

So, it seems we agree that there is no performance advantage.

> You can't "fix" default-directory; you could change its definition, but
> then you would have to fix (or at least verify)_every_ use of it, which
> is impossible, since it could be used in everyone's private code.

My gut feeling is that the risk of introducing a bug when changing
process.c's handling of default-directory is lower than the probability
of fixing latent bugs.

> We are changing the doc string of load-path, but only because it was
> inconsistent with the actual implementation in core. It is now consistent.

No, it was not inconsistent.  "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.


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: dgutov@yandex.ru, stephen_leake@stephe-leake.org, emacs-devel@gnu.org
> Date: Tue, 27 Oct 2015 09:49:37 -0400
> 
> >> > Nothing, except that we can point them to the docs and say that they
> >> > live dangerously ;-)
> [...]
> > We are permissive.
> 
> The above two statement are not mutually consistent, IMO.

Why should they be?  "Hope for the best, plan for the worst."

> > We just want to be consistent in the stuff we generate.
> 
> I'm fine with this.  But I object to documenting too precisely the form
> that should be in load-path and then tell people that if they don't do
> that they live dangerously.

OK, I won't tell that.  (It was a joke, anyway.)

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: Eli Zaretskii <eliz@gnu.org>, Dmitry Gutov <dgutov@yandex.ru>,
>         emacs-devel@gnu.org
> Date: Tue, 27 Oct 2015 09:59:43 -0400
> 
> > We are changing the doc string of load-path, but only because it was
> > inconsistent with the actual implementation in core. It is now consistent.
> 
> No, it was not inconsistent.  "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.

That doc string was confusing because it used the terminology
differently from the manual.

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

[Stefan Monnier]

>> >> > Nothing, except that we can point them to the docs and say that they
>> >> > live dangerously ;-)
>> [...]
>> > We are permissive.
>> The above two statement are not mutually consistent, IMO.
> Why should they be?  "Hope for the best, plan for the worst."

In the context you wrote it "we are permissive" implies we don't frown
on either form.

>> > We just want to be consistent in the stuff we generate.
>> I'm fine with this.  But I object to documenting too precisely the form
>> that should be in load-path and then tell people that if they don't do
>> that they live dangerously.
> OK, I won't tell that.  (It was a joke, anyway.)

But even if we don't say it explicitly, the change in docstring hints at
the fact that this detail matters, whereas it really shouldn't.


        Stefan

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

[Stefan Monnier]

>> No, it was not inconsistent.  "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.
> That doc string was confusing because it used the terminology
> differently from the manual.

Can you (re)explain it, then?  Looks like I didn't understand
the problem.


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: dgutov@yandex.ru,  stephen_leake@stephe-leake.org,  emacs-devel@gnu.org
> Date: Tue, 27 Oct 2015 15:00:55 -0400
> 
> >> > We just want to be consistent in the stuff we generate.
> >> I'm fine with this.  But I object to documenting too precisely the form
> >> that should be in load-path and then tell people that if they don't do
> >> that they live dangerously.
> > OK, I won't tell that.  (It was a joke, anyway.)
> 
> But even if we don't say it explicitly, the change in docstring hints at
> the fact that this detail matters, whereas it really shouldn't.

I see nothing wrong with recommending best practices in doc strings.
We do that all the time.

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: stephen_leake@stephe-leake.org,  dgutov@yandex.ru,  emacs-devel@gnu.org
> Date: Tue, 27 Oct 2015 15:01:38 -0400
> 
> >> No, it was not inconsistent.  "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.
> > That doc string was confusing because it used the terminology
> > differently from the manual.
> 
> Can you (re)explain it, then?  Looks like I didn't understand
> the problem.

The manual says "directory name" ends in a slash, and talks about
"file name of a directory" which doesn't.  The doc string used
"directory name" while the strings in load-path didn't end in a slash.

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

[Stefan Monnier]

> I see nothing wrong with recommending best practices in doc strings.

I don't see why "foo/bar" is better than "/foo/bar/", really.  So it's
not a question of best practice.

> We do that all the time.

Yes, when one of the options is better (or worse) than the others.
This is a different case.


        Stefan

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

[Stefan Monnier]

> 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.

And indeed, if you look for this in the texi documentation, you see
things like:

   means that the alist applies to any mode; or you can specify a
   subdirectory name (a string), in which case the alist applies to all
   files in that subdirectory.
   
     Here's an example of a @file{.dir-locals.el} file:
   
   @example
   ((nil . ((indent-tabs-mode . t)
            (fill-column . 80)))
    (c-mode . ((c-file-style . "BSD")
               (subdirs . nil)))
    ("src/imported"
     . ((nil . ((change-log-default-name
                 . "ChangeLog.local"))))))
   @end example

where "src/imported" lacks a trailing slash.

> 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.


-- Stefan

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

[Dmitry Gutov]

On 10/27/2015 03:52 PM, Stefan Monnier wrote:

> I encourage you to fix it.  AFAIK the process.c code is the only one
> that relies on the trailing slash.

Any pointers? None of the matches for 'directory' in process.c seem 
relevant.

> I think the current handling of default-directory in process.c (where
> anything after the last slash is ignored) is just a bug since it's
> inconsistent with other uses (e.g. (let ((default-directory "/a/b"))
> (expand-file-name "c")) returns "/a/b/c" as you'd expect and not "/a/c"
> as process.c understands it).

Agree.

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

[Stephen Leake]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

>> We are changing the doc string of load-path, but only because it was
>> inconsistent with the actual implementation in core. It is now consistent.
>
> No, it was not inconsistent.  "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.

In that case, the info section Directory Names should be changed to say
that.

--
-- Stephe

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

[Stefan Monnier]

>> I encourage you to fix it.  AFAIK the process.c code is the only one
>> that relies on the trailing slash.
> Any pointers? None of the matches for 'directory' in process.c
> seem relevant.

It's in callproc.c, actually:

   dir = Funhandled_file_name_directory (dir);


-- Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: dgutov@yandex.ru, stephen_leake@stephe-leake.org, emacs-devel@gnu.org
> Date: Tue, 27 Oct 2015 18:18:39 -0400
> 
> > I see nothing wrong with recommending best practices in doc strings.
> 
> I don't see why "foo/bar" is better than "/foo/bar/", really.  So it's
> not a question of best practice.
> 
> > We do that all the time.
> 
> Yes, when one of the options is better (or worse) than the others.
> This is a different case.

Not IMO.

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

[Stephen J. Turnbull]

Stefan Monnier writes:
 > > I see nothing wrong with recommending best practices in doc strings.
 > 
 > I don't see why "foo/bar" is better than "/foo/bar/", really.  So it's
 > not a question of best practice.

Actually, usually it's the other way around (unless you think it's a
good idea to make an effort to break risky code):

    (find-file (concat "/foo/bar/" "baz"))

and

    (find-file (concat "/foo/bar/" "/" "baz"))

both have the same semantics (at the file system level) as

    (find-file (expand-file-name "baz" "/foo/bar"))

while

    (find-file (concat "/foo/bar" "baz"))

and

    (find-file (concat "/foo/bar" "/" "baz"))

are always different from each other, and only the latter is
equivalent to the recommended use of expand-file-name.  That's
XEmacs's rationale for ensuring that our additions to load-path (and
other foo-path variables) are slash-terminated.

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

[David Kastrup]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

>> 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 has had this very strict meaning, and also documented very strictly,
pretty much from the start.  If I remember correctly, the distinction
was very important for dealing with VAX (VMS?) directory names since the
name of the directory "as a file" was different from its usage as a path
component.

I don't know how much the respective file system semantics can be
considered gone these days.  Do we have native ports?  Does it make a
difference for ange-ftp and/or Tramp?

Most people have probably ignored the difference with occasional
Eli-like "can you please keep this working on my not-so-common system as
well?" admonishments eventually dying with the platform falling out of
use.

But yes, historically there was precise meaning and necessity for the
distinction.

-- 
David Kastrup

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

[Davis Herring]

> I don't know how much the respective file system semantics can be
> considered gone these days.  Do we have native ports?  Does it make a
> difference for ange-ftp and/or Tramp?

There is a distinction that remains even for POSIX: if /a/b is a symlink
to a directory, /a/b/ refers to the directory.  But this only matters in
a few cases like lstat(2), since of course most things will treat /a/b
as the target anyway.

Davis

-- 
This product is sold by volume, not by mass.  If it appears too dense or
too sparse, it is because mass-energy conversion has occurred during
shipping.

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Date: Tue, 27 Oct 2015 18:25:52 -0400
> Cc: emacs-devel@gnu.org, stephen_leake@stephe-leake.org, dgutov@yandex.ru
> 
> > 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.

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

[Stefan Monnier]

>> > 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.

In which way is it important for load-path?

> 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.

The problem here is in the manual: "directory name" is a general term
used in the POSIX world and beyond, and it usually doesn't care whether
there's a trailing slash.  There are a few particular situations where
the difference matters, indeed, but rather than co-opt the generally
known term and load it with a more precise semantics than is usual, I'd
prefer that we introduce new names for "directory name with a slash" and
"directory name without a slash".

And in all the cases where the difference shouldn't matter because
there's no ambiguity, then we shouldn't add extra restrictions.

> The changes to the doc string and to the manual were intended to
> rectify this confusion.  We now define another term, "directory file
> name",

That's fine to define "directory name without a slash".

> and use it in the doc string of load-path,

That's wrong, because an element of load-path may (or may not) have
a trailing slash and we should (and do) handle both cases correctly as
well, and all users of load-path (e.g. Stephen's code) should also
handle both cases.


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: emacs-devel@gnu.org, stephen_leake@stephe-leake.org, dgutov@yandex.ru
> Date: Wed, 28 Oct 2015 12:30:27 -0400
> 
> >> > 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.
> 
> In which way is it important for load-path?

The distinction between these two is important in any place where we
want to refer specifically to one but not the other.

> > 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.
> 
> The problem here is in the manual: "directory name" is a general term
> used in the POSIX world and beyond, and it usually doesn't care whether
> there's a trailing slash.

And the manual clearly notes, for this very reason, "This is not quite
the same as the usual Unix terminology."

> There are a few particular situations where the difference matters,
> indeed, but rather than co-opt the generally known term and load it
> with a more precise semantics than is usual, I'd prefer that we
> introduce new names for "directory name with a slash" and "directory
> name without a slash".

That's a mouthful that no one will use, and we will be back at the
same confusion.

What is wrong with "directory file name"?  It is shorter and matches
the name of the function used to return one.

> And in all the cases where the difference shouldn't matter because
> there's no ambiguity, then we shouldn't add extra restrictions.

That's a separate issue.  I was talking about the confusion in the
documentation, as you asked about that specifically.

> > The changes to the doc string and to the manual were intended to
> > rectify this confusion.  We now define another term, "directory file
> > name",
> 
> That's fine to define "directory name without a slash".
> 
> > and use it in the doc string of load-path,
> 
> That's wrong, because an element of load-path may (or may not) have
> a trailing slash and we should (and do) handle both cases correctly as
> well, and all users of load-path (e.g. Stephen's code) should also
> handle both cases.

I already said that I disagree.

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

[Random832]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:
> The problem here is in the manual: "directory name" is a general term
> used in the POSIX world and beyond, and it usually doesn't care whether
> there's a trailing slash.  There are a few particular situations where
> the difference matters, indeed, but rather than co-opt the generally
> known term and load it with a more precise semantics than is usual, I'd
> prefer that we introduce new names for "directory name with a slash" and
> "directory name without a slash".

I think the intent of the existing documentation is that a so-called
"directory name" is the one that may be concatenated to a filename to
form a path. For example, on VMS:
  DKA0:[MYDIR.SUBDIR1.SUBDIR2]        would be the "directory name"
  DKA0:[MYDIR.SUBDIR1]SUBDIR2.DIR;1   would be the "directory filename"

Maybe this should be called a "directory prefix"? I don't think you can
concatenate it to a relative path other than a simple filename on VMS
though. What _do_ (or did) these functions do on VMS or other systems
with exotic path formats (Risc OS?), if any are (were ever) supported?

I wonder, what Emacs does (or did) on classic MacOS. There, relative
pathnames started with a separator (:foo = foo in cwd) and absolute ones
did not (HD:foo == foo in root of HD volume). Doubling a path separator
would be interpreted as the parent directory (::foo == ../foo)

Logic would dictate, therefore, that both the "directory name" and
"directory filename" would not end with a colon, and that it would
only be valid to concatenate if you have a relative path (one that does
begin with a colon).

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

[Stefan Monnier]

> And the manual clearly notes, for this very reason, "This is not quite
> the same as the usual Unix terminology."

Differing from existing terminology is not a quality (tho it's
sometimes justified, of course).  Here I don't see what justifies it.

>> There are a few particular situations where the difference matters,
>> indeed, but rather than co-opt the generally known term and load it
>> with a more precise semantics than is usual, I'd prefer that we
>> introduce new names for "directory name with a slash" and "directory
>> name without a slash".
> That's a mouthful that no one will use, and we will be back at the
> same confusion.

I didn't suggest to use those terms; I suggested that we define new
terms for those specific concepts.  Note that the distinction is very
rarely needed, so those terms will rarely be used anyway.

>> That's wrong, because an element of load-path may (or may not) have
>> a trailing slash and we should (and do) handle both cases correctly as
>> well, and all users of load-path (e.g. Stephen's code) should also
>> handle both cases.
> I already said that I disagree.

So you think code which uses

   (dolist (d load-path)
     (... (concat d toto) ...))

should be considered correct and the users who did

   (add-to-list 'load-path "/foo/bar/")

[ Or should it be "/foo/bar"?  ]

is the one to blame?  How can that make sense?  Why put the burden on
the poor end user who barely understands what add-to-list does?
What's the benefit, when the code can trivially be fixed by using
`expand-file-name'?


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@IRO.UMontreal.CA>
> Cc: emacs-devel@gnu.org, stephen_leake@stephe-leake.org, dgutov@yandex.ru
> Date: Wed, 28 Oct 2015 14:22:22 -0400
> 
> > And the manual clearly notes, for this very reason, "This is not quite
> > the same as the usual Unix terminology."
> 
> Differing from existing terminology is not a quality (tho it's
> sometimes justified, of course).  Here I don't see what justifies it.

It is justified because we have special functions to convert one into
the other and vice versa.  There's no way of describing such
operations without calling the results by some names, which should of
course be different.

> >> There are a few particular situations where the difference matters,
> >> indeed, but rather than co-opt the generally known term and load it
> >> with a more precise semantics than is usual, I'd prefer that we
> >> introduce new names for "directory name with a slash" and "directory
> >> name without a slash".
> > That's a mouthful that no one will use, and we will be back at the
> > same confusion.
> 
> I didn't suggest to use those terms; I suggested that we define new
> terms for those specific concepts.

Which is what we did.  One is "directory name", the other "directory
file name".

> >> That's wrong, because an element of load-path may (or may not) have
> >> a trailing slash and we should (and do) handle both cases correctly as
> >> well, and all users of load-path (e.g. Stephen's code) should also
> >> handle both cases.
> > I already said that I disagree.
> 
> So you think code which uses
> 
>    (dolist (d load-path)
>      (... (concat d toto) ...))
> 
> should be considered correct and the users who did
> 
>    (add-to-list 'load-path "/foo/bar/")
> 
> [ Or should it be "/foo/bar"?  ]
> 
> is the one to blame?

I'm not talking about this, and I'm not going to pick up that
argument, sorry.  I submit that the changes discussed in this longish
thread have nothing to do with correct or incorrect code.  if someone
wants to use 'concat' instead of 'expand-file-name', they still can.
(But they should use (concat d "/" toto), of course.)

> Why put the burden on the poor end user who barely understands what
> add-to-list does?

The burden is not on the user, it's on us, the Emacs developers.
Users are still free to do what they want with load-path.

> What's the benefit, when the code can trivially be fixed by using
> `expand-file-name'?

I already answered that, more than once: consistency, which makes it
easier to have a more accurate doc string.

We are now back to the beginning of this discussion, for the second
time.  Can we please stop this, and agree to disagree?  Please?

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

[Stefan Monnier]

> Which is what we did.  One is "directory name", the other "directory
> file name".

But "directory name" is a term which already has another
meaning elsewhere.  I'm fine with "directory file name" for the
"non-slashed version" but for the slashed version we need something
*else* than either of those two.

This way, when we say "directory name" it will mean what everybody else
means by it.

>> Why put the burden on the poor end user who barely understands what
>> add-to-list does?
> The burden is not on the user, it's on us, the Emacs developers.
> Users are still free to do what they want with load-path.

So developers have to accept both slashed and non-slashed names in
load-path.  Glad we agree.

> I already answered that, more than once: consistency, which makes it
> easier to have a more accurate doc string.

I don't care if we put things in a consistent state (in the sense that
I don't oppose it).  But we still allow other people to do it
inconsistently, so we can't declare that load-path should only contain
"directory file names".

> We are now back to the beginning of this discussion, for the second
> time.  Can we please stop this, and agree to disagree?  Please?

I want the docstring of load-path to be changed not to say "directory
file names".


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: emacs-devel@gnu.org,  stephen_leake@stephe-leake.org,  dgutov@yandex.ru
> Date: Wed, 28 Oct 2015 15:25:16 -0400
> 
> > Which is what we did.  One is "directory name", the other "directory
> > file name".
> 
> But "directory name" is a term which already has another
> meaning elsewhere.  I'm fine with "directory file name" for the
> "non-slashed version" but for the slashed version we need something
> *else* than either of those two.
> 
> This way, when we say "directory name" it will mean what everybody else
> means by it.

That term was defined in the manual for many years to mean the version
with the trailing slash.  It's too late to change that, IMO.

> >> Why put the burden on the poor end user who barely understands what
> >> add-to-list does?
> > The burden is not on the user, it's on us, the Emacs developers.
> > Users are still free to do what they want with load-path.
> 
> So developers have to accept both slashed and non-slashed names in
> load-path.  Glad we agree.

We never disagreed on this one.

> > I already answered that, more than once: consistency, which makes it
> > easier to have a more accurate doc string.
> 
> I don't care if we put things in a consistent state (in the sense that
> I don't oppose it).  But we still allow other people to do it
> inconsistently, so we can't declare that load-path should only contain
> "directory file names".

That recommendation aimed at the developers.

> > We are now back to the beginning of this discussion, for the second
> > time.  Can we please stop this, and agree to disagree?  Please?
> 
> I want the docstring of load-path to be changed not to say "directory
> file names".

And I want it to stay put.

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

[Dmitry Gutov]

On 10/28/2015 10:15 PM, Eli Zaretskii wrote:

> That recommendation aimed at the developers.

Aren't you missing the fact that users also modify load-path in their 
configurations? And they read the docstrings sometimes?

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

[Eli Zaretskii]

> Cc: stephen_leake@stephe-leake.org, emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Wed, 28 Oct 2015 22:18:46 +0200
> 
> On 10/28/2015 10:15 PM, Eli Zaretskii wrote:
> 
> > That recommendation aimed at the developers.
> 
> Aren't you missing the fact that users also modify load-path in their 
> configurations? And they read the docstrings sometimes?

No, I'm not missing that fact.  It's good for them to know that.

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

[Drew Adams]

> But "directory name" is a term which already has another
> meaning elsewhere.  I'm fine with "directory file name" for the
> "non-slashed version" but for the slashed version we need something
> *else* than either of those two.
> 
> This way, when we say "directory name" it will mean what everybody else
> means by it.

Staying out of this discussion, generally.  I'd just offer that in
any context where the difference really matters, it's perhaps a good
idea not to _rely_ on just the (correct) name, but to instead add
text that makes things clear.  E.g.:

  "... a directory name, with or without trailing slash"
  "... a directory name, with trailing slash"
  "... the `directory-file-name'"
  "... a directory file name (no trailing slash)"

(And of course cross-reference the node(s) that define the terms.)

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

[Random832]

Random832 <random832@fastmail.com> writes:
> I think the intent of the existing documentation is that a so-called
> "directory name" is the one that may be concatenated to a filename to
> form a path. For example, on VMS:

tl;dr: Indeed. Code archaeology follows.

>   DKA0:[MYDIR.SUBDIR1.SUBDIR2]        would be the "directory name"
>   DKA0:[MYDIR.SUBDIR1]SUBDIR2.DIR;1   would be the "directory filename"
>
> Maybe this should be called a "directory prefix"? I don't think you can
> concatenate it to a relative path other than a simple filename on VMS
> though. What _do_ (or did) these functions do on VMS

To answer my own question, I refer to the source code of Emacs 22.

http://git.savannah.gnu.org/cgit/emacs.git/tree/src/fileio.c?id=emacs-22.3

| On VMS, converts \"[X]FOO.DIR\" to \"[X.FOO]\", etc.  */)

| On VMS, given a VMS-syntax directory name such as \"[X.Y]\",
| it returns a file name such as \"[X]Y.DIR.1\".  */)

In general, the code dedicated to VMS in these functions seems far more
extensive than the current versions that exclusively handle Unix and
Windows/DOS paths.


> or other systems with exotic path formats (Risc OS?), if any are (were
> ever) supported?

I couldn't find any reference to Risc OS ever being supported.

> I wonder, what Emacs does (or did) on classic MacOS.

At first I couldn't find any special code at all for this, and wondered
if the C runtime handled it. I eventually located this file:

http://git.savannah.gnu.org/cgit/emacs.git/tree/mac/src/mac.c?id=emacs-21.3

It was apparently removed immediately when OSX support was added in
2001, and no-one missed it.

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

[Dmitry Gutov]

On 10/28/2015 04:53 AM, Stefan Monnier wrote:
>>> I encourage you to fix it.  AFAIK the process.c code is the only one
>>> that relies on the trailing slash.
>> Any pointers? None of the matches for 'directory' in process.c
>> seem relevant.
>
> It's in callproc.c, actually:
>
>     dir = Funhandled_file_name_directory (dir);

Thank you. Pushed as ffa41ad. I've opted to use file-name-as-directory, 
in case some weird code out there depends on the trailing slash, but the 
simplest example works fine even if unhandled-file-name-directory 
returns filename unaltered.

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

[Stefan Monnier]

> That term was defined in the manual for many years to mean the version
> with the trailing slash.

I'd be interested to know what percentage of people on this list knew
that "directory name" in Emacs meant strictly "something with a trailing
slash".

> It's too late to change that, IMO.

I don't think it would break anything.  Quite the contrary, it would
"unbreak" the several places where we haven't been that picky.

So, I rather think "it's high time we change that".


        Stefan

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

[Stefan Monnier]

> Staying out of this discussion, generally.  I'd just offer that in
> any context where the difference really matters, it's perhaps a good
> idea not to _rely_ on just the (correct) name, but to instead add
> text that makes things clear.  E.g.:

Boy, now I'm worried: I fully agree with you!


        Stefan

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > > 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.

I took care to make that distinction clear.
If people have let it become fuzzy, let's clear it up.

The elements of 'load-path' (and every ...-path variable)
should properly be directory names, not file names.
Some things, perhaps many, will handle directory file names
in these variables, and it is ine being defensive in that way;
but clean code will only put directory names into the lists.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > I think the intent of the existing documentation is that a so-called
  > > "directory name" is the one that may be concatenated to a filename to
  > > form a path.

In GNU, we reserve the term "path" for a list of directories to
search.  We use the term "file name" to refer to a name that can be
used to open a file.  This eliminates an illogical ambiguity in Unix
terminology.

Normally you can concatenate a directory name with a relative file name
to get an absolute file name that starts from that directory.
-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Wed, 28 Oct 2015 15:25:16 -0400
> Cc: dgutov@yandex.ru, stephen_leake@stephe-leake.org, emacs-devel@gnu.org
> 
> I want the docstring of load-path to be changed not to say "directory
> file names".

Would adding something like the sentence below to the doc string
resolve the issues that bother you?

  However, code that processes this list should tolerate directories
  with and without trailing slashes alike.

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

[Random832]

Richard Stallman <rms@gnu.org> writes:
> I took care to make that distinction clear.
> If people have let it become fuzzy, let's clear it up.

I don't think it's a matter of the documentation being unclear, though
it'd certainly be _more_ clear if it still had the VMS examples. I think
what people don't get is the core concept.

On most operating systems that are relevant today, a string with "/"
already appended is just a string manipulation convenience, and not
really something that exists as a codified idea outside of Emacs. More
complex filename models (such as the VMS example) only appear in a few
niche operating systems, absolutely none of which Emacs supports
anymore.

To a modern user's eye, "directory file name" parses as "directory
filename" and looks like it ought to be a synonym of "directory name".

> The elements of 'load-path' (and every ...-path variable)
> should properly be directory names, not file names.

Apparently not exec-path. Which is a perfectly illustrative example,
because it shows how on POSIX-like OSes, anywhere you can store a
string representing a directory, the slash is entirely optional.

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

[Stefan Monnier]

> Would adding something like the sentence below to the doc string
> resolve the issues that bother you?

>   However, code that processes this list should tolerate directories
>   with and without trailing slashes alike.

That would help, yes,


        Stefan

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

[David Kastrup]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> That term was defined in the manual for many years to mean the version
>> with the trailing slash.
>
> I'd be interested to know what percentage of people on this list knew
> that "directory name" in Emacs meant strictly "something with a trailing
> slash".

It doesn't on VMS.  Which is one the salient points.

It likely does on Windows/MSDOS since C:filename and C:\filename mean
entirely different things.

-- 
David Kastrup

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

[Wolfgang Jenkner]

On Wed, Oct 28 2015, Richard Stallman wrote:

> In GNU, we reserve the term "path" for a list of directories to
> search.  We use the term "file name" to refer to a name that can be
> used to open a file.  This eliminates an illogical ambiguity in Unix
> terminology.

IIUC, this ambiguity doesn't exists in POSIX terminology, though, as
they seem to use the term "pathname".

By definition, a "pathname" can have trailing slashes, a "filename" can't.

Relevant to the present discussion, there also exists a "path prefix",
which is

    The part of a pathname up to, but not including, the last component
    and any trailing <slash> characters, unless the pathname consists
    entirely of <slash> characters, [...]
    

Those definitions can be found in [1].

Accordingly, [2] explains that

PATH

    shall represent the sequence of path prefixes [...]

[1] http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html

[2] http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html

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

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,  dgutov@yandex.ru,  stephen_leake@stephe-leake.org,  emacs-devel@gnu.org
> Date: Thu, 29 Oct 2015 09:24:19 +0100
> 
> > I'd be interested to know what percentage of people on this list knew
> > that "directory name" in Emacs meant strictly "something with a trailing
> > slash".
> 
> It likely does on Windows/MSDOS since C:filename and C:\filename mean
> entirely different things.

You are right in general.  However, in Emacs, C:foo and C:/foo (and
C:\foo) mean the same thing, at least on MS-Windows.  We don't support
the so-called "drive-relative" file names.  (Not that I think this
factoid matters for the purposes of this discussion; I just wanted to
refute a misconception.)

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

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Wed, 28 Oct 2015 22:32:58 -0400
> Cc: emacs-devel@gnu.org, stephen_leake@stephe-leake.org,
> 	monnier@IRO.UMontreal.CA, dgutov@yandex.ru
> 
> The elements of 'load-path' (and every ...-path variable)
> should properly be directory names, not file names.

What's the rationale for that?

> Some things, perhaps many, will handle directory file names
> in these variables, and it is ine being defensive in that way;
> but clean code will only put directory names into the lists.

We have never done that, AFAICS, neither with load-path, nor with
exec-path.  The value of load-path comes from directory-files, where
directories don't have trailing slashes.  The value of exec-path comes
from the environment variable PATH, where usually you won't see
trailing slashes, either.

Once we agree with the rationale, it's okay to make these lists have
directory names instead, but we need to code that, it won't happen by
itself.  And I see no such code in the history of Emacs since these
variables were introduced.  So apparently we never had directory names
in these variables, only directory file names.

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

[Dmitry Gutov]

On 10/29/2015 06:21 PM, Eli Zaretskii wrote:

> Once we agree with the rationale, it's okay to make these lists have
> directory names instead, but we need to code that, it won't happen by
> itself.

In theory, it makes sense, but that would be a backward-incompatible 
change (annoyed users), for little practical benefit.

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

[Eli Zaretskii]

> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Thu, 29 Oct 2015 18:31:44 +0200
> 
> On 10/29/2015 06:21 PM, Eli Zaretskii wrote:
> 
> > Once we agree with the rationale, it's okay to make these lists have
> > directory names instead, but we need to code that, it won't happen by
> > itself.
> 
> In theory, it makes sense, but that would be a backward-incompatible 
> change (annoyed users), for little practical benefit.

I'm not too enthusiastic about that, either, but unless I
misunderstood, some people here would like to see trailing slashes
there.

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

[Dmitry Gutov]

On 10/29/2015 06:42 PM, Eli Zaretskii wrote:

> I'm not too enthusiastic about that, either, but unless I
> misunderstood, some people here would like to see trailing slashes
> there.

Yeah, but that's what this discussion has been about. Tightening reins 
in this direction would make sense (store and accept "directory names" 
only where the values are used as directories), but a lot of fundamental 
functions accept both forms, and making them more strict is very likely 
to result in major breakage in third-party code.

Tightening the reins, selectively, in the other way, is safer (because 
any function that accepts the without-slash value probably accepts the 
with-slash value as well), but it doesn't make as much sense. Even if 
some documentation, in certain places, has been worded like this for a 
while.

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

[Stefan Monnier]

> Once we agree with the rationale, it's okay to make these lists have
> directory names instead, but we need to code that, it won't happen by
> itself.

Can we stop wasting time with trailing slashes and just move on?
There is *no* benefit to trying to design and enforce policies here.


        Stefan

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

[Stefan Monnier]

> Yeah, but that's what this discussion has been about. Tightening reins in
> this direction would ....

... just be a big waste of time,


        Stefan

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

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

I thought that load-path normally contained directory names
and always had.   It seems this is not so now.  If that was
the case in the past too, then I see no reason to change it now.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: rms@gnu.org,  emacs-devel@gnu.org,  stephen_leake@stephe-leake.org,  dgutov@yandex.ru
> Date: Thu, 29 Oct 2015 21:09:11 -0400
> 
> > Once we agree with the rationale, it's okay to make these lists have
> > directory names instead, but we need to code that, it won't happen by
> > itself.
> 
> Can we stop wasting time with trailing slashes and just move on?
> There is *no* benefit to trying to design and enforce policies here.

Stefan, this is highly unfair.  YOU were the one who for many mails
refused to stop this discussion, even when I explicitly asked for
that.  Now you are mad at us for sending a few more messages, when
Richard said something that looks like it contradicts old code he
himself wrote?  How sensible is that?

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

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: dgutov@yandex.ru, stephen_leake@stephe-leake.org,
> 	monnier@IRO.UMontreal.CA, emacs-devel@gnu.org
> Date: Thu, 29 Oct 2015 21:34:56 -0400
> 
> I thought that load-path normally contained directory names
> and always had.   It seems this is not so now.  If that was
> the case in the past too, then I see no reason to change it now.

It was never the case.  I looked through the history right up to the
first commit, when this code was born, and it always used
directory-files to collect the directories, and then just added them
to the list.  This procedure doesn't add trailing slashes.

I guess this closes this case.  Thanks.

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

[Stefan Monnier]

>> Can we stop wasting time with trailing slashes and just move on?
>> There is *no* benefit to trying to design and enforce policies here.
> Stefan, this is highly unfair.  YOU were the one who for many mails
> refused to stop this discussion, even when I explicitly asked for
> that.  Now you are mad at us for sending a few more messages, when
> Richard said something that looks like it contradicts old code he
> himself wrote?  How sensible is that?

I'm opposed to the time wasted designing and implementing the change
(and dealing with the inevitable consequences).
And that's why I'm wasting my time in this thread,


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: rms@gnu.org,  emacs-devel@gnu.org,  stephen_leake@stephe-leake.org,  dgutov@yandex.ru
> Date: Fri, 30 Oct 2015 09:30:11 -0400
> 
> >> Can we stop wasting time with trailing slashes and just move on?
> >> There is *no* benefit to trying to design and enforce policies here.
> > Stefan, this is highly unfair.  YOU were the one who for many mails
> > refused to stop this discussion, even when I explicitly asked for
> > that.  Now you are mad at us for sending a few more messages, when
> > Richard said something that looks like it contradicts old code he
> > himself wrote?  How sensible is that?
> 
> I'm opposed to the time wasted designing and implementing the change

That time was almost null.  It's the ensuing discussion that took any
tangible amount of time.

> (and dealing with the inevitable consequences).

The only consequence was this thread.

> And that's why I'm wasting my time in this thread,

It's your prerogative to waste your time, but I question the wisdom of
that.

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

[Nicolas Richard]

Eli Zaretskii <eliz@gnu.org> writes:
> (But they should use (concat d "/" toto), of course.)

(info "(elisp) Directory Names") has:

--8<---------------cut here---------------start------------->8---
Don't try concatenating a slash by hand, as in

     ;;; Wrong!
     (concat DIRFILE "/" RELFILE)
--8<---------------cut here---------------end--------------->8---

-- 
Nico.

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

[Eli Zaretskii]

> From: Nicolas Richard <nrichard@ulb.ac.be>
> Cc: Stefan Monnier <monnier@IRO.UMontreal.CA>,  dgutov@yandex.ru,  stephen_leake@stephe-leake.org,  emacs-devel@gnu.org
> Date: Mon, 23 Nov 2015 15:14:33 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> > (But they should use (concat d "/" toto), of course.)
> 
> (info "(elisp) Directory Names") has:
> 
> --8<---------------cut here---------------start------------->8---
> Don't try concatenating a slash by hand, as in

That's a recommendation some people resent.