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

Previous Next

Full log

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'
 

Previous Next

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