bug#7111: 24.0.50; `diff' argument order and doc string

bug#7111: 24.0.50; `diff' argument order and doc string

[Drew Adams]

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'
 

bug#7111: 24.0.50; `diff' argument order and doc string

[Leo]

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

bug#7111: 24.0.50; `diff' argument order and doc string

[Drew Adams]

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

bug#7111: 24.0.50; `diff' argument order and doc string

[Leo]

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

bug#7111: 24.0.50; `diff' argument order and doc string

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@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/