GNU bug report logs - #10346
24.0.92; doc string of `save-buffer'

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 10346 in the body.
You can then email your comments to 10346 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.92; doc string of `save-buffer'
Date: Wed, 21 Dec 2011 14:15:05 -0800

Please describe the optional argument ARGS (which should be called ARG,
BTW, since it is not &rest and it is not a cons in general).
 
The doc string talks about the prefix arg, but no connection is made to
ARGS for use in Lisp.
 
Furthermore, "With a numeric argument of 0" is incorrect and misleads.
For an interactive user, this should be stated in terms of the numeric
value of the prefix argument, not just "a numeric argument".
 
In general, reread the doc string, and I'm sure you will see that it
could be improved wrt describing the use of a prefix arg and the use of
the argument from Lisp.
 

In GNU Emacs 24.0.92.1 (i386-mingw-nt5.1.2600) of 2011-12-06 on MARVIN
 Windowing system distributor `Microsoft Corp.', version 5.1.2600
 configured using `configure --with-gcc (4.6) --no-opt --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-2.10.1/include --ldflags
 -LD:/devel/emacs/libs/gnutls-2.10.1/lib'

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <10346 <at> debbugs.gnu.org>
Subject: RE: bug#10346: 24.0.92; doc string of `save-buffer'
Date: Sun, 16 Sep 2012 17:19:59 -0700

ping

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 10346 <at> debbugs.gnu.org
Subject: Re: bug#10346: 24.0.92; doc string of `save-buffer'
Date: Sat, 08 Feb 2014 21:35:45 -0800

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

> Please describe the optional argument ARGS (which should be called ARG,
> BTW, since it is not &rest and it is not a cons in general).

Fixed on trunk.

> The doc string talks about the prefix arg, but no connection is made to
> ARGS for use in Lisp.

Yes.  But the values for ARG are so...  non-Lispey, I have a feeling
that it's been left off by choice.  The values are basically 0, 4, 16
and 64, which are ... kinda opaque when calling a function like that.

I don't know.  Should these values be documented or not?

> Furthermore, "With a numeric argument of 0" is incorrect and misleads.
> For an interactive user, this should be stated in terms of the numeric
> value of the prefix argument, not just "a numeric argument".

Fixed on trunk.

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 10346 <at> debbugs.gnu.org
Subject: RE: bug#10346: 24.0.92; doc string of `save-buffer'
Date: Tue, 11 Feb 2014 07:02:20 -0800 (PST)

> > The doc string talks about the prefix arg, but no connection is
> > made to ARGS for use in Lisp.
> 
> Yes.  But the values for ARG are so...  non-Lispey, I have a feeling
> that it's been left off by choice.  The values are basically 0, 4,
> 16 and 64, which are ... kinda opaque when calling a function like
> that.
> 
> I don't know.  Should these values be documented or not?

Of course.

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 10346 <at> debbugs.gnu.org
Subject: Re: bug#10346: 24.0.92; doc string of `save-buffer'
Date: Thu, 28 Apr 2016 13:58:51 +0200

Lars Ingebrigtsen <larsi <at> gnus.org> writes:

>> The doc string talks about the prefix arg, but no connection is made to
>> ARGS for use in Lisp.
>
> Yes.  But the values for ARG are so...  non-Lispey, I have a feeling
> that it's been left off by choice.  The values are basically 0, 4, 16
> and 64, which are ... kinda opaque when calling a function like that.
>
> I don't know.  Should these values be documented or not?

I think they're left out on purpose.  Closing.

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 10346 <at> debbugs.gnu.org
Subject: RE: bug#10346: 24.0.92; doc string of `save-buffer'
Date: Thu, 28 Apr 2016 07:13:15 -0700 (PDT)

> Lars Ingebrigtsen <larsi <at> gnus.org> writes:
> 
> >> The doc string talks about the prefix arg, but no connection is made to
> >> ARGS for use in Lisp.
> >
> > Yes.  But the values for ARG are so...  non-Lispey, I have a feeling
> > that it's been left off by choice.  The values are basically 0, 4, 16
> > and 64, which are ... kinda opaque when calling a function like that.
> >
> > I don't know.  Should these values be documented or not?
> 
> I think they're left out on purpose.  Closing.

Do you realize that you answered your own question?

This is a command.  Interactively, ARG is the numeric prefix
arg.  This should be stated in the doc string: What ARG is for
and how it is used.

Previous Next

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