bug#42687: 26.3; `ediff-inferior-compare-regions' - doc (and behavior)

[Drew Adams]

I'd never tried this (`=' in Ediff) before, but a problem reported by
another user drew my attention to it.

I don't claim to understand it (what it does or is supposed to do), so
consider this feedback that of one naive first-time user.  Some of what
I report might not be real problems, from your point of view.  And there
may be additional problems, from the point of view of someone who really
understands.

1. I have two buffers, `*sc' and `*scratch*', whose text I compare with
`ediff-buffers'.  The only difference is that `*sc' has "FOO" in place
of "with". The second line in the buffers is highlighted, with the word
difference highlighted differently, to stand out.  All normal.

2. In the Ediff control window I use `C-h k =', and I see this:

  ediff-inferior-compare-regions is an interactive compiled Lisp
  function in 'ediff-util.el'.

  (ediff-inferior-compare-regions)

  Compare regions in an active Ediff session.
  Like `ediff-regions-linewise' but is called from under an active Ediff 
session on
  the files that belong to that session.

  After quitting the session invoked via this function, type C-l to the parent
  Ediff Control Panel to restore highlighting.

First, one line is too long (81 chars).

Second, I'm comparing buffers, not files, so the doc is off-base here:
"the files that belong to that session".

Third, the doc is obscure - not comprehensible to me, and I've used
Ediff for 35 years (but mostly just `ediff-buffers', and without being
an expert, by any means).

What does "is called from under an active Ediff session" means?  "Under"
a session?  (And what's an Ediff "session"?  OK, I can guess what is
meant by a "session", but I'm not sure it's a great name for it.)

It says, "After quitting the session invoked via this function, type C-l
to the parent Ediff Control Panel to restore highlighting."

How do I quit that child (?) session?  Does it mean quitting Ediff
altogether?  If not, do I use the same key, `q', to quit this "under",
or "child" session?  The doc should say how to quit this child Ediff.

3. Next, I look in the Ediff manual.

First, I try `i ediff-inferior-compare-regions', and it takes me to node
`Quick Help Commands', where I can read about `='.  OK.

But `C-s ediff-inferior-compare-regions' from the start of the manual
doesn't find that command anywhere.  And the doc for `=' doesn't give
its command name.  I think it should.

Next, that explanation of `=' talks only about files, not buffers,
except that it later talks about "files or buffers".  The main text
describing the command shouldn't make it sound like this is only about
comparing text in files.

4. The behavior of `ediff-inferior-compare-regions' (`=') seems really
awful, but I can't pronounce on that as I clearly don't understand some
of it.  With `ediff-buffers' for buffers in two different frames, `=',
and quitting from it and using `C-l' in the parent control window, ends
up duplicating one of the buffers in a window in the other buffer's
frame.  And you can easily get errors saying that a window is too small
to be split etc.  At first view, at least, this command seems like a
real mess.  But this bug report is about the doc, as I don't pretend to
understand the command well.


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''