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

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

> > 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.
> 
> I think that's the core of the misunderstanding.  The purpose of
> abbreviate-file-name is not to apply the above two steps.  Those steps
> are just the current way to reach the real goal, which is to 
> abbreviate the file name.

Do we have a spec declaring the intended purpose, or are we just making it up as
we go along? The closest thing we have to a statement of the purpose is the doc,
along with the code and its comments, of course. None of those support your
claim of the purpose.

> Admittedly, "abbreviate" is not exactly meant here as
> "shorten" but rather as "make it more concise/easy/pretty for 
> the user",

That's precisely the point. It's not exactly about shortening. The question is
whether ~/foo is more useful/pretty/understandable/consistent for the user than
(sometimes) c:\\foo and (sometimes) /foo.

> but still to a first approximation "not longer" is
> a very good design guideline.

No, not a very good guideline for usability and understandability. A one-char
length difference has no special utility for a user. And that one-character
difference is the length argument you are making here. Consistency (always
seeing `~' when the home dir is involved) is more important here for users.
IMHO.