howm: Update help generation for modes

[gerbercj]

Update the modes to generate their help text from the mode-maps, rather than list the contents of the menu manually.

Currently when I type C-h m to run describe-mode, some of the functions show keybindings of M-x <function>, rather than the keys that are bound. We can both fix this and simplify the code, by using the mode-maps like was already done for howm-remember-mode-map.

[kaorahi]

Thanks for pointing that out. Applying this PR seems like a better option if the current lists are not good enough and fixing them would be too much trouble. What do you think? Could you give some examples of issues with the current lists, including my awkward English, of course? :)

Handmade lists can offer higher quality if they are well-maintained. So, there seems to be pros and cons to this PR.

• Pros: simple, maintenance-free, and free from mistakes or oversights
• Cons: lower readability (alphabetical order instead of a meaningful order, function names instead of human-edited descriptions)

As for "M-x ..." in the current lists, I purposely included them for users' information, or I may have just forgotten to update the keymaps. I probably didn't notice the latter case since I use customized keymaps myself, as is common for long-time emacs fans.

[gerbercj]

Thanks for taking a look at this so quickly, and for your thoughtful comments. (Also, your English is great!)

My inspiration for looking at this was that the help text was not showing the key mappings for me. For example, when viewing all notes, with my point in the howm-view-summary, and pressing C-h m, I see the following:

...
memo viewer (summary mode)
key binding
--- -------
M-x howm-view-summary-open  Open file
C-n Next item
C-p Previous item
M-x riffle-pop-or-scroll-other-window   Pop and scroll contents
M-<prior>   Scroll contents
M-x riffle-scroll-other-window  Scroll contents one line
M-x riffle-scroll-other-window-down Scroll contents one line
M-x riffle-summary-to-contents  Concatenate all contents
M-x howm-view-summary-next-section  Next file (Skip items in the same file)
M-x howm-view-summary-previous-section  Previous file (Skip items in the same file)
...

After making the change to howm-view-summary-mode, I can see the keys mapped to the commands:

...
memo viewer (summary mode)

Key             Binding

TAB     howm-view-summary-next-section
C-j     howm-view-summary-open
RET     howm-view-summary-open
SPC     riffle-pop-or-scroll-other-window
!       howm-view-summary-shell-command
(       howm-date-backward
)       howm-date-forward
+       howm-date-forward
,       howm-menu
-       howm-date-backward
...

I do agree that a well curated list could be helpful, but as it was I needed to look up the mappings a different way. I found that M-x which-key-show-major-mode was a helpful alternative, but I'm used to using C-h m or describe-mode.

[kaorahi]

(AIs are great at fixing English today, but the docstrings were written a long time ago. :p)

I'm unable to reproduce the issue.

1. git checkout 93528f3; make clean
2. emacs -q --no-site-file -l sample/dot.emacs
3. C-c , a
4. M-x describe-mode RET

key binding
--- -------
C-j Open file
n   Next item
p   Previous item
SPC Pop and scroll contents
C-h Scroll contents
...
?   This help
M-x riffle-kill-buffer  Quit

It seems I've forgotten the "Quit" binding, but the other items seem OK.

Are you using any customizations, like a VI emulator? The fact that you can use C-h m already suggests that howm-view-summary-mode-map has been overwritten (cf. #15). If you see M-x riffle-pop-or-scroll-other-window instead of SPC in the help, it means there is no key binding for that function in your current environment. So, showing SPC is rather misleading here, since it doesn't actually work. Is my understanding correct?

[gerbercj]

1. Using ? rather than C-h m shows the same help.
2. The bindings (like SPC) do work, despite the binding not appearing in the help correctly.
3. I had tested with a minimal config, like you did, and it still reproduced on my work computer.
4. I just tested this on my home computer, and that machine is also showing the issue. Both machines are running Emacs 29.4, build 1 on Debian.
5. I also found that C-h b shows the bindings correctly, but I am using counsel.el for that.

I will keep debugging this locally, as I know that it works correctly for you, and agreeing that the curated help is more useful that the generated help. I'll let you know if I figure out what's happening here.

[kaorahi]

ac8eed0 should fix the issue. (cf. Info > Elisp > Documentation Tips > local map)

https://github.com/kaorahi/howm/tree/fix16_describe_mode

It seems we need \\<KEYMAP> before \\[FUNCTION] for newer emacsen. Thanks for the heads up!

I usuall add thx > ___ san (___ at ___.___) to ChangeLog etc. Is it okay if I copy your full name and email from the commit log? If you'd prefer not, I can use your github ID instead, for example.

[gerbercj]

That's interesting. I'm glad that you were able to find what changed and were able to create a fix. :)

My full name and email sounds fine. I believe it will be Chris Gerber chris@theGerb.com.

Thanks again for your help, and feel free to close this PR.

[kaorahi]

I've merged the above ac8eed0 into the master branch. Please let me know if you run into any issues.

[gerbercj]

I just updated my machine and the help text looks perfect. Thanks for figuring out how to fix this!