Subject: bug#4654 closed by Eli Zaretskii <[email-masked]> (Re: bug#4654: 23.1; Elisp manual doc of abbreviate-file-name)

From: [email-masked] (Emacs bug Tracking System)
Date: Wed, 07 Oct 2009 10:30:16 +0000

This is an automatic notification regarding your bug report
which was filed against the emacs package:

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

It has been closed by Eli Zaretskii <[email-masked]>.

Their explanation is attached below along with your original report.
If this explanation is unsatisfactory and you have not received a
better one in a separate message then please contact Eli Zaretskii <[email-masked]> by
replying to this email.

-- 
4654: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=4654
Emacs Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#4654: 23.1; Elisp manual doc of abbreviate-file-name
From: Eli Zaretskii <[email-masked]>
To: Drew Adams <[email-masked]>, [email-masked]
Cc: [email-masked]
Date: Wed, 07 Oct 2009 12:21:55 +0200

> From: "Drew Adams" <[email-masked]>
> Date: Wed, 7 Oct 2009 00:50:41 -0700
> Cc: [email-masked]
> 
> 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).

I hope no one is seriously suggesting to change the behavior of one of
the oldest Emacs APIs...

I fixed the manual.  The description now says

    This function applies abbreviations from @code{directory-abbrev-alist}
    to its argument, and also substitutes @samp{~} for the user's home
    directory if the argument names a file in the home directory or one of
    its subdirectories.  (If the home directory is a root directory, it is
    not replaced with @samp{~}, because this does not make the result
    shorter on many systems.)  You can use it for directory names and for
    file names, because it recognizes abbreviations even as part of the
    name.

I hope this is something everybody can live with.

Subject: 23.1; Elisp manual doc of abbreviate-file-name
From: "Drew Adams" <[email-masked]>
To: <[email-masked]>
Date: Tue, 6 Oct 2009 10:54:09 -0700

The doc string mentions this qualification, but the Elisp manual does
not: " (unless the home directory is a root directory)".
 
Please mention this in the manual also.
 
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.
 
In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'