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

[Philipp Stephani <p.stephani2@gmail.com>]

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