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

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

> > Question: Why? What is the rationale for not substituting 
> > `~' when it is a root directory? If the reason is short to
> > express, perhaps it should be included in the doc.
> > Understanding the rationale helps one remember what the
> > function does.
>  
> "a root directory" means "/".  The reason is that substituting "/" for
> "~" doesn't really abbreviate anything.  If anythingn to me it "looks"
> longer because I expect ~ to expand to something longer.

1. Don't tell me; put it in the doc., please. ;-) That's the point of the bug
report.

I would add that the doc could be a tiny bit clearer that the expanded form of
the home dir is replaced by ~, and not vice versa.

The current phrasing ("substitutes "~" for the user's home directory") is
correct, but many people routinely misread such phrases. (You yourself just made
this mistake, for example: You said "substituting / for ~", when you presumably
meant "substituting ~ for /".)

In particular, it is not uncommon for people to incorrectly substitute "replace"
for "substitute". Using "replace" here (and reversing the order) is likely to be
a bit clearer. Clarity would be enhanced further by adding a simple example.


2. FWIW, I don't have a set opinion on this, but I lean toward saying that this
exception for a root homedir should in fact be removed. Why? Because `~' lets
you know that it _is_ the home directory.

~/foo/ tells you that foo is directly under the home directory.

On the other hand, /foo/ tells you that foo is directly under the root, which
~/foo/ does not tell you. This goes along with what you were saying about
expecting ~ to expand to something longer. ~ tells you that you are at the home
dir, but it doesn't tell you where that is.

Each side thus has a legitimate argument that additional info is provided. But
it's not a toss-up, since the _purpose_ of the function is to use ~. That, and
also the elimination of a shaky exception (Occam's razor), is why I lean toward
always using ~, even for a root homedir.

Finally, the one-char length difference argument should be irrelevant here. And
on Windows the length argument actually goes the other way: ~ is shorter than
c:\\.

Anyway, this bug report is about the doc - please clear that up.