GNU bug report logs - #7111
24.0.50; `diff' argument order and doc string

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 7111 in the body.
You can then email your comments to 7111 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; `diff' argument order and doc string
Date: Sun, 26 Sep 2010 10:18:47 -0700

emacs -Q
C-h f diff
 
The order that the file names are read is NEW, then OLD.  The doc
string describes them in the order OLD, then NEW, which is per
Emacs doc convention: describe parameters in their order of appearance.
 
But this can be confusing for a user.  The params can be described in
that order in the first line, but when speaking about reading them
interactively it would be better to mention the read order explicitly:
 
Instead of this:
 
"When called interactively, read OLD and NEW using the minibuffer;
the default for NEW is the current buffer's file name, and the
default for OLD is a backup file for NEW, if one exists."
 
Use something like this:
 
"When called interactively, read NEW, then OLD, using the minibuffer.
                            ^^^^^^^^^^^^^^^^^^^
The default for NEW is the current buffer's file name, and the
default for OLD is a backup file for NEW, if one exists."
 
The doc string already describes NEW before OLD when it comes to the
default value.  Better to say that NEW is read before OLD.  And better
to split the compound sentence in two.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2010-09-20 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4) --no-opt --cflags
-Ic:/imagesupport/include'
 

Message #8 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Leo <sdl.web <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#7111: 24.0.50; `diff' argument order and doc string
Date: Sun, 26 Sep 2010 20:56:48 +0100

On 2010-09-26 18:18 +0100, Drew Adams wrote:
> "When called interactively, read NEW, then OLD, using the minibuffer.

BTW, I think the first time I actually used diff directly I was
surprised by this order. OLD then NEW is more natural.

Leo

Message #11 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Leo'" <sdl.web <at> gmail.com>, <bug-gnu-emacs <at> gnu.org>
Subject: RE: bug#7111: 24.0.50; `diff' argument order and doc string
Date: Sun, 26 Sep 2010 14:50:28 -0700

> BTW, I think the first time I actually used diff directly I was
> surprised by this order. OLD then NEW is more natural.

Yes, when `diff' is used as a command-line command.

But in Emacs you often want to diff a current file (line in Dired, current
buffer file, etc.) against some other file, often the backup (old version) of
the same file.  That is the rationale, I think, behind the chosen order.

Message #14 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Leo <sdl.web <at> gmail.com>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#7111: 24.0.50; `diff' argument order and doc string
Date: Mon, 27 Sep 2010 22:17:13 +0100

On 2010-09-26 22:50 +0100, Drew Adams wrote:
> Yes, when `diff' is used as a command-line command.
>
> But in Emacs you often want to diff a current file (line in Dired, current
> buffer file, etc.) against some other file, often the backup (old version) of
> the same file.  That is the rationale, I think, behind the chosen order.
>

I hardly use `diff' in emacs directly so no problem with this ;)

Leo

Message #21 received at 7111 <at> debbugs.gnu.org (full text, mbox):

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 7111 <at> debbugs.gnu.org
Subject: Re: 24.0.50; `diff' argument order and doc string
Date: Thu, 14 Jul 2011 16:15:45 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> Use something like this:
>
> "When called interactively, read NEW, then OLD, using the minibuffer.
>                             ^^^^^^^^^^^^^^^^^^^
> The default for NEW is the current buffer's file name, and the
> default for OLD is a backup file for NEW, if one exists."

I've now added this.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.