* bug#4654: 23.1; Elisp manual doc of abbreviate-file-name @ 2009-10-06 17:54 ` Drew Adams 2009-10-06 20:21 ` Stefan Monnier 2009-10-07 10:30 ` bug#4654: marked as done (23.1; Elisp manual doc of abbreviate-file-name) Emacs bug Tracking System 0 siblings, 2 replies; 10+ messages in thread From: Drew Adams @ 2009-10-06 17:54 UTC (permalink / raw) To: bug-gnu-emacs 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)' ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#4654: 23.1; Elisp manual doc of abbreviate-file-name 2009-10-06 17:54 ` bug#4654: 23.1; Elisp manual doc of abbreviate-file-name Drew Adams @ 2009-10-06 20:21 ` Stefan Monnier 2009-10-06 21:12 ` Drew Adams 2009-10-07 10:30 ` bug#4654: marked as done (23.1; Elisp manual doc of abbreviate-file-name) Emacs bug Tracking System 1 sibling, 1 reply; 10+ messages in thread From: Stefan Monnier @ 2009-10-06 20:21 UTC (permalink / raw) To: Drew Adams; +Cc: bug-gnu-emacs, 4654 > 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#4654: 23.1; Elisp manual doc of abbreviate-file-name 2009-10-06 20:21 ` Stefan Monnier @ 2009-10-06 21:12 ` Drew Adams 2009-10-07 5:47 ` Stefan Monnier 0 siblings, 1 reply; 10+ messages in thread From: Drew Adams @ 2009-10-06 21:12 UTC (permalink / raw) To: 'Stefan Monnier'; +Cc: bug-gnu-emacs, 4654 > > 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#4654: 23.1; Elisp manual doc of abbreviate-file-name 2009-10-06 21:12 ` Drew Adams @ 2009-10-07 5:47 ` Stefan Monnier 2009-10-07 7:50 ` Drew Adams 0 siblings, 1 reply; 10+ messages in thread From: Stefan Monnier @ 2009-10-07 5:47 UTC (permalink / raw) To: Drew Adams; +Cc: 4654 > ~/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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#4654: 23.1; Elisp manual doc of abbreviate-file-name 2009-10-07 5:47 ` Stefan Monnier @ 2009-10-07 7:50 ` Drew Adams 2009-10-07 14:09 ` Stefan Monnier 0 siblings, 1 reply; 10+ messages in thread From: Drew Adams @ 2009-10-07 7:50 UTC (permalink / raw) To: 'Stefan Monnier'; +Cc: 4654 > > ~/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). ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#4654: 23.1; Elisp manual doc of abbreviate-file-name 2009-10-07 7:50 ` Drew Adams @ 2009-10-07 14:09 ` Stefan Monnier 2009-10-07 15:21 ` Drew Adams 0 siblings, 1 reply; 10+ messages in thread From: Stefan Monnier @ 2009-10-07 14:09 UTC (permalink / raw) To: Drew Adams; +Cc: 4654 >> 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#4654: 23.1; Elisp manual doc of abbreviate-file-name 2009-10-07 14:09 ` Stefan Monnier @ 2009-10-07 15:21 ` Drew Adams 0 siblings, 0 replies; 10+ messages in thread From: Drew Adams @ 2009-10-07 15:21 UTC (permalink / raw) To: 'Stefan Monnier'; +Cc: 4654 > > 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#4654: marked as done (23.1; Elisp manual doc of abbreviate-file-name) 2009-10-06 17:54 ` bug#4654: 23.1; Elisp manual doc of abbreviate-file-name Drew Adams 2009-10-06 20:21 ` Stefan Monnier @ 2009-10-07 10:30 ` Emacs bug Tracking System 1 sibling, 0 replies; 10+ messages in thread From: Emacs bug Tracking System @ 2009-10-07 10:30 UTC (permalink / raw) To: Eli Zaretskii [-- 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
[parent not found: <1E8768BDE1464D019FC9EED701E222F4@us.oracle.com>]
* bug#4654: 23.1; Elisp manual doc of abbreviate-file-name [not found] ` <1E8768BDE1464D019FC9EED701E222F4@us.oracle.com> @ 2009-10-07 17:44 ` Eli Zaretskii 2009-10-07 17:55 ` Drew Adams 0 siblings, 1 reply; 10+ messages in thread From: Eli Zaretskii @ 2009-10-07 17:44 UTC (permalink / raw) To: Drew Adams; +Cc: 4654 > 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* bug#4654: 23.1; Elisp manual doc of abbreviate-file-name 2009-10-07 17:44 ` bug#4654: 23.1; Elisp manual doc of abbreviate-file-name Eli Zaretskii @ 2009-10-07 17:55 ` Drew Adams 0 siblings, 0 replies; 10+ messages in thread From: Drew Adams @ 2009-10-07 17:55 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: 4654 > > > 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). ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2009-10-07 17:55 UTC | newest] Thread overview: 10+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <83ab03mrlo.fsf@gnu.org> 2009-10-06 17:54 ` bug#4654: 23.1; Elisp manual doc of abbreviate-file-name Drew Adams 2009-10-06 20:21 ` Stefan Monnier 2009-10-06 21:12 ` Drew Adams 2009-10-07 5:47 ` Stefan Monnier 2009-10-07 7:50 ` Drew Adams 2009-10-07 14:09 ` Stefan Monnier 2009-10-07 15:21 ` Drew Adams 2009-10-07 10:30 ` bug#4654: marked as done (23.1; Elisp manual doc of abbreviate-file-name) Emacs bug Tracking System [not found] ` <1E8768BDE1464D019FC9EED701E222F4@us.oracle.com> 2009-10-07 17:44 ` bug#4654: 23.1; Elisp manual doc of abbreviate-file-name Eli Zaretskii 2009-10-07 17:55 ` Drew Adams
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.