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

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

[Drew Adams]

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)'
 

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

[Stefan Monnier]

> 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.


        Stefan

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

[Drew Adams]

> > 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.

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

[Stefan Monnier]

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

Actually, you can see right there: "~/foo" is longer than "/foo", so it
would be wrong for abbreviate-file-name to do such a replacement, since
it wouldn't abbreviate.

> 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.

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

Patch welcome.  I myself have no idea what wording would please you
better, and the current wording is crystal clear to my mind.


        Stefan

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

[Drew Adams]

> > ~/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).

bug#4654: marked as done (23.1; Elisp manual doc of abbreviate-file-name)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 882 bytes --]

Your message dated Wed, 07 Oct 2009 12:21:55 +0200
with message-id <83ab03mrlo.fsf@gnu.org>
and subject line Re: bug#4654: 23.1; Elisp manual doc of abbreviate-file-name
has caused the Emacs bug report #4654,
regarding 23.1; Elisp manual doc of abbreviate-file-name
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@emacsbugs.donarmstrong.com
immediately.)


-- 
4654: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=4654
Emacs Bug Tracking System
Contact owner@emacsbugs.donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 3439 bytes --]

From: "Drew Adams" <drew.adams@oracle.com>
To: <bug-gnu-emacs@gnu.org>
Subject: 23.1; Elisp manual doc of abbreviate-file-name
Date: Tue, 6 Oct 2009 10:54:09 -0700
Message-ID: <A7B578F309F04902ACE8A24F56BECB9D@us.oracle.com>

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)'
 




[-- Attachment #3: Type: message/rfc822, Size: 3687 bytes --]

From: Eli Zaretskii <eliz@gnu.org>
To: Drew Adams <drew.adams@oracle.com>, 4654-done@emacsbugs.donarmstrong.com
Cc: monnier@iro.umontreal.ca
Subject: Re: bug#4654: 23.1; Elisp manual doc of abbreviate-file-name
Date: Wed, 07 Oct 2009 12:21:55 +0200
Message-ID: <83ab03mrlo.fsf@gnu.org>

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Wed, 7 Oct 2009 00:50:41 -0700
> Cc: 4654@emacsbugs.donarmstrong.com
> 
> 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.

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

[Stefan Monnier]

>> 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?

Not really.  Clearly abbreviate-file-name does not guarantee that the
returned file name will be shorter.  But it *should* aim to "do no
harm", i.e. not make file names longer (although it doesn't guarantee
that either, IIUC, since it depends on directory-abbrev-alist which is
free to lengthen at the user's heart's content).

> 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. ;-)

No: the relevant question is not "does it make it shorter", but "does
it make it longer".  So it's OK (tho suboptimal) to keep "C:\\foo" as
is, but it's not OK to turn "/foo" into "~/foo".  I wouldn't mind if
someone wants to change that behavior in w32, but I'll leave that to
people who actually care about w32.

> 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.  Admittedly, "abbreviate" is not exactly meant here as
"shorten" but rather as "make it more concise/easy/pretty for the user",
but still to a first approximation "not longer" is a very good
design guideline.


        Stefan

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

[Drew Adams]

> > 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.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <monnier@iro.umontreal.ca>
> Date: Wed, 7 Oct 2009 08:19:06 -0700
> 
> > I fixed the manual.  The description now says
> > 
> > (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.)
> > 
> > I hope this is something everybody can live with.
> 
> Thank you.
> 
> Consider also making clearer the direction of substitution (e.g a one-line
> example). As Stefan's own misstatement shows, it's easy for readers to
> understand the substitution backwards.

That is why the text quoted above makes a point of saying "replaced
with", which should be unequivocal.

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

[Drew Adams]

> > > I fixed the manual.  The description now says
> > > 
> > > (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.)
> >
> > Consider also making clearer the direction of substitution 
> > (e.g a one-line example). As Stefan's own misstatement shows,
> > it's easy for readers to understand the substitution backwards.
> 
> That is why the text quoted above makes a point of saying "replaced
> with", which should be unequivocal.

Yes, thanks, that helps (even though it is mentioned only wrt the root-dir
special casing).