bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*

bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*

[Van L]

Hello,

The *Help* buffer for diff-mode.el is better 
if the following key bindings are documented 

#+NAME: undocumented-key-bindings
| key   | binding        |
|-------+----------------|
| TAB   | diff-hunk-next |
| S-TAB | diff-hunk-prev |

the above make more sense than the following

#+NAME: existing-key-bindings-documented
| key   | binding        |
|-------+----------------|
| C-M-i | diff-hunk-next |
| M-n   |                |
|-------+----------------|
| M-p   | diff-hunk-prev |

And, for the word "hunk" to link to a Glossary's 
entry like for example

http://www-history.mcs.st-and.ac.uk/Glossary/oblong_number.html

is a feature to have unless it is already therein.

bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*

[Juri Linkov]

> The *Help* buffer for diff-mode.el is better
> if the following key bindings are documented
>
> #+NAME: undocumented-key-bindings
> | key   | binding        |
>
> |-------+----------------|
> | TAB   | diff-hunk-next |
> | S-TAB | diff-hunk-prev |
>
> the above make more sense than the following
>
> #+NAME: existing-key-bindings-documented
> | key   | binding        |
>
> |-------+----------------|
> | C-M-i | diff-hunk-next |
> | M-n   |                |
> |-------+----------------|
> | M-p   | diff-hunk-prev |

It seems what you want is:

(put 'diff-hunk-next :advertised-binding [tab])
(put 'diff-hunk-prev :advertised-binding [(shift tab)])

> And, for the word "hunk" to link to a Glossary's
> entry like for example
>
> http://www-history.mcs.st-and.ac.uk/Glossary/oblong_number.html
>
> is a feature to have unless it is already therein.

Better to link to the Info manual (info "(diffutils) Hunks")

bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*

[Van L]

> Juri Linkov wrote:
> 
>> And, for the word "hunk" to link to a Glossary's
>> entry like for example
>> 
>> http://www-history.mcs.st-and.ac.uk/Glossary/oblong_number.html
>> 
>> is a feature to have unless it is already therein.
> 
> Better to link to the Info manual (info "(diffutils) Hunks”)

The Emacs’s Concept Index leads to (info “(emacs) Diff Mode”) paragraph two, where hunk is explained.

I was hoping for a Glossary at the same level as Concept Index in the Info navigation. 

It would collect single paragraph explanations for easy finding, perhaps, the top-100 most frequently used jargonwords.

My plain Emacs and Slime installation doesn’t have diffutils in Info docs, but *vc-diff* works.

bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*

[Van L]

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


> (put 'diff-hunk-next :advertised-binding [tab])
> (put 'diff-hunk-prev :advertised-binding [(shift tab)])

The above, I've put in a patch for emacs-mac port, see below.

The development master as of now has

— quote

(easy-mmode-defmap diff-mode-shared-map
  '(("n" . diff-hunk-next)
    ("N" . diff-file-next)
    ("p" . diff-hunk-prev)
    ("P" . diff-file-prev)
    ("\t" . diff-hunk-next)
    ([backtab] . diff-hunk-prev)

— quote ends


[-- Attachment #2: 0005-List-key-bindings-for-describe-mode.patch --]
[-- Type: application/octet-stream, Size: 894 bytes --]

From 67b38816cf2cb81655adeb5b0d941141a8872dcd Mon Sep 17 00:00:00 2001
From: Van L <van@scratch.space>
Date: Mon, 21 Jan 2019 09:02:49 +1100
Subject: [PATCH 5/5] List key bindings for describe-mode

Documents the TAB, SHIFT-TAB behavior for stepping through hunks.
---
 lisp/vc/diff-mode.el | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/lisp/vc/diff-mode.el b/lisp/vc/diff-mode.el
index 7db5ca9b25..ce3277adf5 100644
--- a/lisp/vc/diff-mode.el
+++ b/lisp/vc/diff-mode.el
@@ -587,6 +587,10 @@ diff-end-of-file
 
 (defvar diff--auto-refine-data nil)
 
+;; List key bindings for describe-mode
+(put 'diff-hunk-next :advertised-binding [tab])
+(put 'diff-hunk-prev :advertised-binding [(shift tab)])
+
 ;; Define diff-{hunk,file}-{prev,next}
 (easy-mmode-define-navigation
  diff-hunk diff-hunk-header-re "hunk" diff-end-of-hunk diff-restrict-view
-- 
2.20.1

bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*

[Juri Linkov]

>> (put 'diff-hunk-next :advertised-binding [tab])
>> (put 'diff-hunk-prev :advertised-binding [(shift tab)])
>
> The above, I've put in a patch for emacs-mac port, see below.

Please attach the output after this change.  I would be interesting
to see how it is formatted on emacs-mac port.

bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*

[Van L]

>>> (put 'diff-hunk-next :advertised-binding [tab])
>>> (put 'diff-hunk-prev :advertised-binding [(shift tab)])
>> 
>> The above, I've put in a patch for emacs-mac port, see below.
> 
> Please attach the output after this change.  I would be interesting
> to see how it is formatted on emacs-mac port.

— quote

Compiling /Applications/MacPorts/EmacsMac.app/Contents/Resources/lisp/vc/diff-mode.el.gz...done
Wrote /Applications/MacPorts/EmacsMac.app/Contents/Resources/lisp/vc/diff-mode.elc

— quote ends

The change has had no desired effect.

: ESC <backtab>	diff-hunk-prev

There is that, from describe-mode by searching for 'tab.

bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*

[Lars Ingebrigtsen]

Van L <van@scratch.space> writes:

> The *Help* buffer for diff-mode.el is better 
> if the following key bindings are documented 
>
> #+NAME: undocumented-key-bindings
> | key   | binding        |
>
> |-------+----------------|
> | TAB   | diff-hunk-next |
> | S-TAB | diff-hunk-prev |

There are several modes defined in diff-mode.el.

Do you mean `diff-mode' itself?  TAB is not bound in `diff-mode', as far
as I can tell.

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

bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Van L <van@scratch.space> writes:
>
>> The *Help* buffer for diff-mode.el is better 
>> if the following key bindings are documented 
>>
>> #+NAME: undocumented-key-bindings
>> | key   | binding        |
>>
>> |-------+----------------|
>> | TAB   | diff-hunk-next |
>> | S-TAB | diff-hunk-prev |
>
> There are several modes defined in diff-mode.el.
>
> Do you mean `diff-mode' itself?  TAB is not bound in `diff-mode', as far
> as I can tell.

It wasn't bound if I said `M-x diff-mode', but it is bound in *vc-diff*
buffers...

And if I `C-h b' in that buffer, I get

key             binding
---             -------

TAB		diff-hunk-next
[...]
<backtab>	diff-hunk-prev

But it's right that they are not listed in `C-h m'.

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

bug#34080: 27.0.50, 26.1; undocumented key bindings for *vc-diff*

[Lars Ingebrigtsen]

Van L <van@scratch.space> writes:

> +;; List key bindings for describe-mode
> +(put 'diff-hunk-next :advertised-binding [tab])
> +(put 'diff-hunk-prev :advertised-binding [(shift tab)])
> +

I tried this patch, but `M-x describe-mode' in a *vc-diff* buffer did
not seem to care that much -- it listed diff-hunk-prev on M-p and ESC
<backtab> and -next on C-M-i/M-n only, with or without this patch.

Is :advertised-binding not working here, or is ... er ... something else
wrong?  The actual bindings are:

    ("\t" . diff-hunk-next)
    ([backtab] . diff-hunk-prev)

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