bug#4654: 23.1; Elisp manual doc of abbreviate-file-name

["Drew Adams" <drew.adams@oracle.com>]

> > ~/foo/ tells you that foo is directly under the home directory.
> 
> Actually, you can see right there: "~/foo" is longer than "/foo", 

Yes, you already said that once, and I already agreed with it once. Let me agree
with it again: it is one character longer. So it is not strictly an
abbreviation. I cannot argue with that.

However, there is nothing about this function that is necessarily abbreviation.
It is only in a general, average, overall, figurative sense that this function
performs abbreviation.

> so it would be wrong for abbreviate-file-name to do such a 
> replacement, since it wouldn't abbreviate.

That's being a bit too black-and-white, don't you think? In that case, it is
even more "wrong" to return c:\\foo instead of ~/foo, which is what we do now on
Windows. That's 3 chars longer, a threefold worsening of your non-shortening
problem. ;-) 

(Yes, I said that before too, but it apparently had no effect on your
must-be-shorter argument.)

The point is that unless you want the function to do somthing different in this
regard (home-dir replacement) on different platforms, strictly applying a
criterion of abbreviation in the sense of shortening is not TRT.

In this case (HOME as root) at least, we should decide based on something other
than simply whatever is shorter.

The stated feature of "abbreviation" for this function has two aspects: (1)
substituting a defined "abbreviation" from `directory-abbrev-list' - which is
_not_ necessarily shorter than what it replaces, in fact, and (2) substituting
`~' for the home dir. 

Neither aspect is always abbreviation in the sense of using something shorter.

IOW, the word "abbreviation" is used wrt this function only in a vague,
suggestive way. It cannot be seen as substitution of something necessarily
shorter. Nit-picking about a string being one-character longer is beside the
point.

> > it's not a toss-up, since the _purpose_ of the function is to use ~.
> 
> No it's not.  The purpose is to abbreviate, i.e. make shorter.

No, it's not. And it cannot be, in general - see above.

The stated purpose of the function is two-fold: (1) substitute a defined alias
(we call it an "abbreviation", but it is not necessarily shorter than what it
replaces), and (2) substitute `~' for the home dir (which is likewise not
necessarily abbreviation in the sense of replacement by something shorter, at
least on Windows).

The substitution we use should have the merits of (a) telling users something
(which is why I pointed out the advantages of both approaches in terms of
providing additional information) and (b) being consistent.

a. Always substituting `~' for the home dir is consistent; and it tells you
where the file is wrt the home dir.

b. Substituting `~' for the home dir except when it is the root dir breaks
consistency; but it does tell you where the file is wrt root (in that one
exceptional case only - otherwise, it tells you where the file is wrt the home
dir). It also has the advantage of legacy: consistency with the past and
existing code.

c. If we were to substitute `~' for the home dir except when that is the root
dir, on UNIX etc., but not substitute it for the home dir when that is the root
dir, on Windows, that would ensure that `~' substitution would always shorten
the file name. But that would introduce additional inconsistency.

And in any case, substituting using `directory-abbrev-alist' does not guarantee
shortening at all. Nothing prevents such "abbreviation" from lengthening the
name.

Overall, (a) is a better choice than (b) or (c) - unless the legacy
consideration has particular importance here for some reason (I don't think it
does).