GNU bug report logs - #25046
26.0.50; Arguments of `ediff-janitor' undocumented

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 25046 in the body.
You can then email your comments to 25046 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: Philipp Stephani <p.stephani2 <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.0.50; Arguments of `ediff-janitor' undocumented
Date: Sun, 27 Nov 2016 21:30:18 +0100

The function `ediff-janitor' has two required arguments, ASK and
KEEP-JANITOR, which are not documented in the docstring.


In GNU Emacs 26.0.50.2 (x86_64-apple-darwin16.1.0, NS appkit-1504.60 Version 10.12.1 (Build 16B2555))
 of 2016-11-27 built on p
Repository revision: 416adda38521c6246f77877c57843264fa4ae711
Windowing system distributor 'Apple', version 10.3.1504
Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Quit
Loading ediff...done
Type C-x 1 to delete the help window.

Configured using:
 'configure --with-modules --enable-checking
 --enable-check-lisp-object-type --without-xml2 --disable-silent-rules
 'CFLAGS=-ggdb3 -O0''

Configured features:
RSVG IMAGEMAGICK DBUS NOTIFY ACL GNUTLS ZLIB TOOLKIT_SCROLL_BARS NS
MODULES

Important settings:
  value of $LANG: de_DE.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message subr-x puny seq byte-opt gv
bytecomp byte-compile cconv dired dired-loaddefs format-spec rfc822 mml
mml-sec password-cache epa derived epg epg-config gnus-util rmail
rmail-loaddefs mm-decode mm-bodies mm-encode mail-parse rfc2231
mailabbrev gmm-utils mailheader sendmail rfc2047 rfc2045 ietf-drums
mm-util mail-prsvr mail-utils ediff-merg ediff-wind ediff-diff
ediff-mult ediff-help ediff-init ediff-util ediff cl-extra thingatpt
help-fns radix-tree help-mode easymenu cl-loaddefs pcase cl-lib
time-date mule-util tooltip eldoc electric uniquify ediff-hook vc-hooks
lisp-float-type mwheel term/ns-win ns-win ucs-normalize term/common-win
tool-bar dnd fontset image regexp-opt fringe tabulated-list replace
newcomment text-mode elisp-mode lisp-mode prog-mode register page
menu-bar rfn-eshadow isearch timer select scroll-bar mouse jit-lock
font-lock syntax facemenu font-core term/tty-colors frame cl-generic
cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech
european ethiopic indian cyrillic chinese composite charscript
case-table epa-hook jka-cmpr-hook help simple abbrev obarray minibuffer
cl-preloaded nadvice loaddefs button faces cus-face macroexp files
text-properties overlay sha1 md5 base64 format env code-pages mule
custom widget hashtable-print-readable backquote dbusbind kqueue cocoa
ns multi-tty make-network-process emacs)

Memory information:
((conses 16 214548 8247)
 (symbols 48 21296 0)
 (miscs 40 59 218)
 (strings 32 21922 6536)
 (string-bytes 1 726263)
 (vectors 16 36800)
 (vector-slots 8 690820 5774)
 (floats 8 196 20)
 (intervals 56 234 4)
 (buffers 976 12))

Message #10 received at 25046-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Philipp Stephani <p.stephani2 <at> gmail.com>
Cc: 25046-done <at> debbugs.gnu.org
Subject: Re: bug#25046: 26.0.50; Arguments of `ediff-janitor' undocumented
Date: Fri, 02 Dec 2016 11:30:21 +0200

> From: Philipp Stephani <p.stephani2 <at> gmail.com>
> Date: Sun, 27 Nov 2016 21:30:18 +0100
> 
> The function `ediff-janitor' has two required arguments, ASK and
> KEEP-JANITOR, which are not documented in the docstring.

Thanks, fixed on the emacs-25 branch.

Message #13 received at 25046-done <at> debbugs.gnu.org (full text, mbox):

From: Philipp Stephani <p.stephani2 <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 25046-done <at> debbugs.gnu.org
Subject: Re: bug#25046: 26.0.50; Arguments of `ediff-janitor' undocumented
Date: Fri, 02 Dec 2016 13:47:33 +0000

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> schrieb am Fr., 2. Dez. 2016 um 10:30 Uhr:

> > From: Philipp Stephani <p.stephani2 <at> gmail.com>
> > Date: Sun, 27 Nov 2016 21:30:18 +0100
> >
> > The function `ediff-janitor' has two required arguments, ASK and
> > KEEP-JANITOR, which are not documented in the docstring.
>
> Thanks, fixed on the emacs-25 branch.
>

Thanks, however I'm still not quite sure about the meaning.
"ASK non-nil means ask the user whether to keep each unmodified buffer,
unless KEEP-VARIANTS is non-nil, in which case buffers are killed
unconditionally."
So if ASK = nil, KEEP-VARIANTS = nil: kill buffers, don't ask about any
buffer
ASK = (nil or non-nil), KEEP-VARIANTS = non-nil: don't kill any buffer,
don't ask
ASK = non-nil, KEEP-VARIANTS = nil: ask about each buffer

If that's the case, shouldn't the documentation rather be something like:
"If KEEP-VARIANTS is non-nil, only indirect buffers are killed [what does
that mean for the user?], and ASK is ignored. Otherwise, if ASK is non-nil,
ask the user for each unmodified buffer whether it should be killed.
Otherwise (both ASK and KEEP-VARIANTS) are nil, all unmodified buffers are
killed without confirmation."
WDYT?

[Message part 2 (text/html, inline)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Philipp Stephani <p.stephani2 <at> gmail.com>
Cc: 25046 <at> debbugs.gnu.org
Subject: Re: bug#25046: 26.0.50; Arguments of `ediff-janitor' undocumented
Date: Fri, 02 Dec 2016 16:37:48 +0200

> From: Philipp Stephani <p.stephani2 <at> gmail.com>
> Date: Fri, 02 Dec 2016 13:47:33 +0000
> Cc: 25046-done <at> debbugs.gnu.org
> 
> Thanks, however I'm still not quite sure about the meaning.
> "ASK non-nil means ask the user whether to keep each unmodified buffer, unless KEEP-VARIANTS is
> non-nil, in which case buffers are killed unconditionally."
> So if ASK = nil, KEEP-VARIANTS = nil: kill buffers, don't ask about any buffer

Yes.

> ASK = (nil or non-nil), KEEP-VARIANTS = non-nil: don't kill any buffer, don't ask

Yes, I've goofed.  KEEP-VARIANTS non-nil means never kill.  Now fixed.

> ASK = non-nil, KEEP-VARIANTS = nil: ask about each buffer

Yes.

> If that's the case, shouldn't the documentation rather be something like:
> "If KEEP-VARIANTS is non-nil, only indirect buffers are killed [what does that mean for the user?], and ASK is
> ignored. Otherwise, if ASK is non-nil, ask the user for each unmodified buffer whether it should be killed.
> Otherwise (both ASK and KEEP-VARIANTS) are nil, all unmodified buffers are killed without confirmation."
> WDYT? 

I don't think mentioning indirect buffers will add anything but
confusion.

I fixed the incorrect meaning of KEEP-VARIANTS, and I think the result
is okay, definitely so for an internal utility function.

Thanks.

Previous Next

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