bug#24675: 26.0.50; Misleading suggestion in Ediff Info manual

bug#24675: 26.0.50; Misleading suggestion in Ediff Info manual

[Philipp Stephani]

The Ediff Info manual, in section 7.1 "Hooks", says:

‘ediff-cleanup-hook’
     This hook is run just before ‘ediff-quit-hook’.  This is a good
     place to do various cleanups, such as deleting the variant buffers.
     Ediff provides a function, ‘ediff-janitor’, as one such possible
     hook, which you can add to ‘ediff-cleanup-hook’ with ‘add-hook’.

However, ediff-cleanup-hook is a normal hook, and ediff-janitor is a
function taking two required arguments, so it cannot be added to
ediff-cleanup-hook.  The manual should e.g. state that a lambda wrapping
ediff-janitor can be added to ediff-cleanup-hook, but not ediff-janitor
itself.


In GNU Emacs 26.0.50.2 (x86_64-unknown-linux-gnu, GTK+ Version 3.10.8)
 of 2016-10-12 built on localhost
Repository revision: 59c5f36acfcbec4f6119996f7b80383bf86125d4
Windowing system distributor 'The X.Org Foundation', version 11.0.11501000
System Description:	Ubuntu 14.04 LTS

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Composing main Info directory...done
Mark saved where search started
Quit
Loading ediff-util...done
Type C-x 1 to delete the help window.

Entering debugger...
Back to top level

Configured using:
 'configure --with-modules --enable-checking
 --enable-check-lisp-object-type'

Configured features:
XPM JPEG TIFF GIF PNG SOUND GSETTINGS NOTIFY GNUTLS FREETYPE XFT ZLIB
TOOLKIT_SCROLL_BARS GTK3 X11 MODULES

Important settings:
  value of $LANG: en_US.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 debug ediff-merg ediff-wind ediff-diff
ediff-mult ediff-help ediff-init ediff-util cl-extra thingatpt help-fns
radix-tree help-mode cl-loaddefs pcase cl-lib misearch multi-isearch
info easymenu time-date mule-util tooltip eldoc electric uniquify
ediff-hook vc-hooks lisp-float-type mwheel term/x-win x-win
term/common-win x-dnd tool-bar dnd fontset image regexp-opt fringe
tabulated-list newcomment elisp-mode lisp-mode prog-mode register page
menu-bar rfn-eshadow 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 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 inotify dynamic-setting
system-font-setting font-render-setting move-toolbar gtk x-toolkit x
multi-tty make-network-process emacs)

Memory information:
((conses 16 112819 5354)
 (symbols 48 21981 0)
 (miscs 40 371 351)
 (strings 32 23152 4562)
 (string-bytes 1 795806)
 (vectors 16 16192)
 (vector-slots 8 479526 4745)
 (floats 8 200 219)
 (intervals 56 748 1479)
 (buffers 976 15)
 (heap 1024 23921 1152))

-- 
Google Germany GmbH
Erika-Mann-Straße 33
80636 München

Registergericht und -nummer: Hamburg, HRB 86891
Sitz der Gesellschaft: Hamburg
Geschäftsführer: Matthew Scott Sucherman, Paul Terence Manicle

Diese E-Mail ist vertraulich.  Wenn Sie nicht der richtige Adressat sind,
leiten Sie diese bitte nicht weiter, informieren Sie den Absender und löschen
Sie die E-Mail und alle Anhänge.  Vielen Dank.

This e-mail is confidential.  If you are not the right addressee please do not
forward it, please inform the sender, and please erase this e-mail including
any attachments.  Thanks.

bug#24675: 26.0.50; Misleading suggestion in Ediff Info manual

[Glenn Morris]

Philipp Stephani wrote:

> The Ediff Info manual, in section 7.1 "Hooks", says:
>
> 'ediff-cleanup-hook'
>      This hook is run just before 'ediff-quit-hook'.  This is a good
>      place to do various cleanups, such as deleting the variant buffers.
>      Ediff provides a function, 'ediff-janitor', as one such possible
>      hook, which you can add to 'ediff-cleanup-hook' with 'add-hook'.
>
> However, ediff-cleanup-hook is a normal hook, and ediff-janitor is a
> function taking two required arguments, so it cannot be added to
> ediff-cleanup-hook.  The manual should e.g. state that a lambda wrapping
> ediff-janitor can be added to ediff-cleanup-hook, but not ediff-janitor
> itself.

It seems the doc hasn't been updated in the past 14 years.
Before 50a07e1, there was a single optional argument.
You might be one of the few users of this functionality, so maybe you
would like to fix the doc yourself? (Making the arguments optional is
an additional possibility?)

Since the use of lambda for hooks is basic (eg documented in the
"Hooks" section of the manual), personally I don't see a need to
mention it here or in other places that refer to normal hook uses.

bug#24675: 26.0.50; Misleading suggestion in Ediff Info manual

[Philipp Stephani]

[-- Attachment #1.1: Type: text/plain, Size: 1292 bytes --]

Glenn Morris <rgm@gnu.org> schrieb am Di., 13. Dez. 2016 um 19:03 Uhr:

> Philipp Stephani wrote:
>
> > The Ediff Info manual, in section 7.1 "Hooks", says:
> >
> > 'ediff-cleanup-hook'
> >      This hook is run just before 'ediff-quit-hook'.  This is a good
> >      place to do various cleanups, such as deleting the variant buffers.
> >      Ediff provides a function, 'ediff-janitor', as one such possible
> >      hook, which you can add to 'ediff-cleanup-hook' with 'add-hook'.
> >
> > However, ediff-cleanup-hook is a normal hook, and ediff-janitor is a
> > function taking two required arguments, so it cannot be added to
> > ediff-cleanup-hook.  The manual should e.g. state that a lambda wrapping
> > ediff-janitor can be added to ediff-cleanup-hook, but not ediff-janitor
> > itself.
>
> It seems the doc hasn't been updated in the past 14 years.
> Before 50a07e1, there was a single optional argument.
> You might be one of the few users of this functionality, so maybe you
> would like to fix the doc yourself?


I don't use it myself, but I got a report from a colleague who interpreted
the manual such that you could add ediff-janitor directly to the hook with
add-hook. I've attached a patch to clarify this. I'll push it to emacs-25
in a few days until there are complaints.

[-- Attachment #1.2: Type: text/html, Size: 2075 bytes --]

[-- Attachment #2: 0001-Clarify-usage-of-ediff-cleanup-hook-Bug-24675.txt --]
[-- Type: text/plain, Size: 1229 bytes --]

From 28556ab1879d54534363f5cb4cc9678f014efcc5 Mon Sep 17 00:00:00 2001
From: Philipp Stephani <phst@google.com>
Date: Sun, 18 Dec 2016 22:18:01 +0100
Subject: [PATCH] Clarify usage of 'ediff-cleanup-hook' (Bug#24675)

* doc/misc/ediff.texi (Hooks): Clarify usage of 'ediff-cleanup-hook'
---
 doc/misc/ediff.texi | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi
index 376aaee..896a604 100644
--- a/doc/misc/ediff.texi
+++ b/doc/misc/ediff.texi
@@ -1247,9 +1247,14 @@ Hooks
 @vindex ediff-cleanup-hook
 This hook is run just before @code{ediff-quit-hook}.  This is a good
 place to do various cleanups, such as deleting the variant buffers.
-Ediff provides a function, @code{ediff-janitor}, as one such possible
-hook, which you can add to @code{ediff-cleanup-hook} with
-@code{add-hook}.
+Ediff provides a helper function, @code{ediff-janitor}, that you can
+invoke from a private hook function.  For example:
+
+@example
+(defun my-ediff-janitor ()
+  (ediff-janitor nil nil))
+(add-hook 'ediff-cleanup-hook #'my-ediff-janitor)
+@end example
 
 @findex ediff-janitor
 This function kills buffers A, B, and, possibly, C, if these buffers aren't
-- 
2.10.2

bug#24675: 26.0.50; Misleading suggestion in Ediff Info manual

[Philipp Stephani]

[-- Attachment #1: Type: text/plain, Size: 1446 bytes --]

Philipp Stephani <p.stephani2@gmail.com> schrieb am So., 18. Dez. 2016 um
22:25 Uhr:

> Glenn Morris <rgm@gnu.org> schrieb am Di., 13. Dez. 2016 um 19:03 Uhr:
>
> Philipp Stephani wrote:
>
> > The Ediff Info manual, in section 7.1 "Hooks", says:
> >
> > 'ediff-cleanup-hook'
> >      This hook is run just before 'ediff-quit-hook'.  This is a good
> >      place to do various cleanups, such as deleting the variant buffers.
> >      Ediff provides a function, 'ediff-janitor', as one such possible
> >      hook, which you can add to 'ediff-cleanup-hook' with 'add-hook'.
> >
> > However, ediff-cleanup-hook is a normal hook, and ediff-janitor is a
> > function taking two required arguments, so it cannot be added to
> > ediff-cleanup-hook.  The manual should e.g. state that a lambda wrapping
> > ediff-janitor can be added to ediff-cleanup-hook, but not ediff-janitor
> > itself.
>
> It seems the doc hasn't been updated in the past 14 years.
> Before 50a07e1, there was a single optional argument.
> You might be one of the few users of this functionality, so maybe you
> would like to fix the doc yourself?
>
>
> I don't use it myself, but I got a report from a colleague who interpreted
> the manual such that you could add ediff-janitor directly to the hook with
> add-hook. I've attached a patch to clarify this. I'll push it to emacs-25
> in a few days until there are complaints.
>

Pushed as f69bd7954f113719bb0e46e143231744c80bef34.

[-- Attachment #2: Type: text/html, Size: 2734 bytes --]