Directory names versus directory file names

Terminology I'll use:
- a _directory name_ is one that on Unix always _has_ a trailing slash
- a _directory file name_ is one that on Unix _lacks_ a trailing slash
- "a string naming a directory" is deliberately ambiguous.

This is my understanding of how the Lisp programmer should deal with
these:

    (1) When Lisp code knows that a string names a directory, it should
    ensure that it ends in a trailing slash.  I.e., functions should
    pass and return known directories as strings with trailing slashes.
    The exceptions are:
    - Code dealing with only file names, and not files and directories
      themselves.
    - When the code couldn't know whether the string names a directory
      or a file without making additional system calls, which can mean a
      significant performance hit.

    (2) Code should usually be prepared to deal with both directory
    names and directory file names as much as is practical because lots
    of user (and core and package) code and scripting doesn't
    consistently append trailing slashes.

Relevant documentation:

    (elisp)Directory Names says "When an Emacs variable or function
    argument is described as being a directory name, a directory file
    name is not acceptable."

    `load-path': "Use ‘directory-file-name’ when adding items to this
    path.  However, Lisp programs that process this list should tolerate
    directories both with and without trailing slashes."

    `default-directory': Docstring says it must end with a slash.

But neither of these imply my point (1).  I.e. my point (1) is stronger
that what the documentation currently says.

Some interesting consequences if I'm correct:

    - directory-files returns directory file names instead of directory
      names.  But that's correct because determining which items name
      directories would require additional system calls.

    - directory-files-recursively also returns directory file names
      instead of directory names if INCLUDE-DIRECTORIES is non-nil.
      But that's buggy: it should always know when an item names a
      directory, so it can append the trailing slash.

~=~=~

But am I correct?  Spencer pointed out to me an interesting counter
argument: avoiding appending a trailing slash until and unless you need
to do something inside a directory could catch certain errors before
they happen.

For example, if you want to pass a directory to some shell commands
(like VC does), you don't need a trailing slash.  But then if the
directory file name ended up as the second argument to `rename-file',
there'd be an error instead of accidentally moving files inside the
directory.

This would suggest that when VC adds a known-directory to a fileset, it
could strip the trailing slash, for some added safety.  But that's
against (1).

~=~=~

My questions for others are

- do my (1) and (2) match your understanding?

- should VC change in the sort of way suggested here?
  Mainly this means that it will strip the trailing slash from
  default-directory before adding it to a fileset.

-- 
Sean Whitton