branch: elpa/casual
commit 9bc23201d2cbcbcc69d58d6f84b38b7c6b1cc453
Author: Charles Choi <[email protected]>
Commit: Charles Choi <[email protected]>
Add Casual Help
- Add Transient UI support for `help-mode`.
---
README.org | 19 ++++-
docs/agenda.org | 15 +---
docs/bookmarks.org | 15 +---
docs/calc.org | 16 +---
docs/calendar.org | 15 +---
docs/casual.info | 148 ++++++++++++++++++++++++---------
docs/casual.org | 58 +++++++++++++
docs/dired.org | 15 +---
docs/editkit.org | 15 +---
docs/help.org | 66 +++++++++++++++
docs/ibuffer.org | 15 +---
docs/image.org | 15 +---
docs/images/casual-help-screenshot.png | Bin 0 -> 354135 bytes
docs/info.org | 15 +---
docs/isearch.org | 15 +---
docs/make-mode.org | 15 +---
docs/man.org | 16 +---
docs/re-builder.org | 15 +---
docs/timezone.org | 15 +---
lisp/Makefile | 5 ++
lisp/Makefile-help.make | 30 +++++++
lisp/casual-help-settings.el | 97 +++++++++++++++++++++
lisp/casual-help-utils.el | 67 +++++++++++++++
lisp/casual-help.el | 135 ++++++++++++++++++++++++++++++
lisp/casual-man-settings.el | 1 +
tests/Makefile | 5 ++
tests/casual-help-test-utils.el | 41 +++++++++
tests/test-casual-help-settings.el | 53 ++++++++++++
tests/test-casual-help-utils.el | 54 ++++++++++++
tests/test-casual-help.el | 100 ++++++++++++++++++++++
30 files changed, 853 insertions(+), 238 deletions(-)
diff --git a/README.org b/README.org
index 6a1f8b1ea9..1a9198c3ae 100644
--- a/README.org
+++ b/README.org
@@ -37,6 +37,7 @@ Editorially, all design decisions for Casual are ultimately
the opinion of Charl
- [[#calendar-elisp-library-casual-calendar][Calendar (Elisp library:
~casual-calendar~)]]
- [[#dired-elisp-library-casual-dired][Dired (Elisp library:
~casual-dired~)]]
- [[#editkit-elisp-library-casual-editkit][EditKit (Elisp library:
~casual-editkit~)]]
+ - [[#help-elisp-library-casual-help][Help (Elisp library: ~casual-help~)]]
- [[#ibuffer-elisp-library-casual-ibuffer][IBuffer (Elisp library:
~casual-ibuffer~)]]
- [[#image-elisp-library-casual-image][Image (Elisp library:
~casual-image~)]]
- [[#info-elisp-library-casual-info][Info (Elisp library: ~casual-info~)]]
@@ -87,14 +88,22 @@ An interface for
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Cal
[[file:docs/dired.org][file:docs/images/casual-dired-screenshot.png]]
** [[file:docs/editkit.org][EditKit]] (Elisp library: ~casual-editkit~)
- A cornucopia of interfaces for the different editing features (e.g. marking,
copying, killing, duplicating, transforming, deleting) of Emacs. Included are
interfaces for rectangle, register, macro, and project commands.
+A cornucopia of interfaces for the different editing features (e.g. marking,
copying, killing, duplicating, transforming, deleting) of Emacs. Included are
interfaces for rectangle, register, macro, and project commands.
[[file:docs/editkit.org][file:docs/images/casual-editkit-main-screenshot.png]]
+
+
+** [[file:docs/help.org][Help]] (Elisp library: ~casual-help~)
+
+An interface for ~help-mode~, a major mode for viewing help text and
navigating references in it.
+
+[[file:docs/help.org][file:docs/images/casual-help-screenshot.png]]
+
** [[file:docs/ibuffer.org][IBuffer]] (Elisp library: ~casual-ibuffer~)
- An interface for
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Buffer-Menus.html][IBuffer]],
a tool for managing buffers in Emacs. If one was to fancifully consider Emacs
as an OS, consider this to be its task manager.
+An interface for
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Buffer-Menus.html][IBuffer]],
a tool for managing buffers in Emacs. If one was to fancifully consider Emacs
as an OS, consider this to be its task manager.
- [[file:docs/info.org][file:docs/images/casual-ibuffer-screenshot.png]]
+[[file:docs/info.org][file:docs/images/casual-ibuffer-screenshot.png]]
** [[file:docs/image.org][Image]] (Elisp library: ~casual-image~)
An interface for viewing an image file with
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Image-Mode.html#Image-Mode][image-mode]].
This interface deviates significantly with naming conventions used by
~image-mode~ to be more in alignment with conventional image editing tools.
@@ -155,6 +164,7 @@ Configuration of a particular Casual user interface is
performed per mode. Go to
- [[file:docs/calendar.org::*Install][Calendar]]
- [[file:docs/dired.org::*Install][Dired]]
- [[file:docs/editkit.org::*Install][EditKit]]
+- [[file:docs/help.org::*Install][Help]]
- [[file:docs/ibuffer.org::*Install][IBuffer]]
- [[file:docs/image.org::*Install][Image]]
- [[file:docs/info.org::*Install][Info]]
@@ -162,7 +172,8 @@ Configuration of a particular Casual user interface is
performed per mode. Go to
- [[file:docs/make-mode.org::*Install][Make]]
- [[file:docs/man.org::*Install][Man]]
- [[file:docs/re-builder.org::*Install][Re-Builder]]
-
+- [[file:docs/timezone.org::*Install][Timezone]]
+
** Upgrading to Casual 2.x
If you have been using an earlier version 1.x of Casual, thank you. Please use
the following guidance:
diff --git a/docs/agenda.org b/docs/agenda.org
index 45a06fe6b7..aca7008455 100644
--- a/docs/agenda.org
+++ b/docs/agenda.org
@@ -71,17 +71,4 @@ If you enjoy using Casual Agenda, consider making a modest
financial contributio
[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/docs/bookmarks.org b/docs/bookmarks.org
index 386c81b979..dcf50a2c94 100644
--- a/docs/bookmarks.org
+++ b/docs/bookmarks.org
@@ -68,17 +68,4 @@ If you enjoy using Casual Bookmarks, consider making a
modest financial contribu
[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/docs/calc.org b/docs/calc.org
index f237e34b19..5eca55e792 100644
--- a/docs/calc.org
+++ b/docs/calc.org
@@ -54,17 +54,5 @@ If you enjoy using Casual Calc, consider making a modest
financial contribution
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
+
diff --git a/docs/calendar.org b/docs/calendar.org
index 031075bdbd..a6cbc92f88 100644
--- a/docs/calendar.org
+++ b/docs/calendar.org
@@ -83,17 +83,4 @@ If you enjoy using Casual Calendar, consider making a modest
financial contribut
[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/docs/casual.info b/docs/casual.info
index 76c198fd5d..cf889aa1c0 100644
--- a/docs/casual.info
+++ b/docs/casual.info
@@ -61,6 +61,7 @@ Casual Modes
* Calendar::
* Dired::
* EditKit::
+* Help::
* IBuffer::
* Image::
* Info::
@@ -208,6 +209,7 @@ The following modes are supported by Casual:
* Calendar::
* Dired::
* EditKit::
+* Help::
* IBuffer::
* Image::
* Info::
@@ -622,7 +624,7 @@ References
• *note Dired: (emacs)Dired.
-File: casual.info, Node: EditKit, Next: IBuffer, Prev: Dired, Up: Casual
Modes
+File: casual.info, Node: EditKit, Next: Help, Prev: Dired, Up: Casual Modes
4.6 EditKit
===========
@@ -683,9 +685,77 @@ References
• *note Registers: (emacs)Registers.
-File: casual.info, Node: IBuffer, Next: Image, Prev: EditKit, Up: Casual
Modes
+File: casual.info, Node: Help, Next: IBuffer, Prev: EditKit, Up: Casual
Modes
-4.7 IBuffer
+4.7 Help
+========
+
+Casual Help is a user interface for ‘help-mode’, a major mode for
+viewing help text and navigating references in it.
+
+Configuration
+=============
+
+In your initialization file, bind the Transient ‘casual-help-tmenu’ to
+your key binding of preference.
+
+ (require 'casual-help) ; optional
+ (keymap-set help-mode-map "C-o" #'casual-help-tmenu)
+
+‘casual-help-tmenu’ deviates from the default bindings of
+‘help-mode-map’ as shown in the table below.
+
+Default Binding Casual Binding Command
Notes
+------------------------------------------------------------------------------------------------------------------------
+l M-[ help-go-back
Make consistent with Casual Info behavior.
+r M-] help-go-forward
Make consistent with Casual Info behavior.
+n N help-goto-next-page Use
to navigate to next page.
+p P help-goto-previous-page Use
to navigate to previous page.
+ n casual-lib-browser-forward-paragraph Use
to navigate paragraph forward.
+ p casual-lib-browser-backward-paragraph Use
to navigate paragraph backward.
+
+The following keybindings are recommended to support consistent behavior
+between ‘help-mode’ and ‘casual-help-tmenu’.
+
+ (keymap-set help-mode-map "M-[" #'help-go-back)
+ (keymap-set help-mode-map "M-]" #'help-go-forward)
+ (keymap-set help-mode-map "p" #'casual-lib-browse-backward-paragraph)
+ (keymap-set help-mode-map "n" #'casual-lib-browse-forward-paragraph)
+ (keymap-set help-mode-map "P" #'help-goto-previous-page)
+ (keymap-set help-mode-map "N" #'help-goto-next-page)
+ (keymap-set help-mode-map "j" #'forward-button)
+ (keymap-set help-mode-map "k" #'backward-button)
+
+Usage
+=====
+
+Basic Usage
+-----------
+
+After invoking help via a ‘describe-’ command, invoke
+‘casual-help-tmenu’ using the binding ‘C-o’ (or your binding of
+preference).
+
+The following sections are offered in the menu:
+
+Navigation
+ Navigation commands with the document.
+History
+ Navigate history of help invocations.
+Link
+ Navigate to different references in the help buffer.
+Describe
+ Get help for different Elisp types.
+Info
+ If available, then open this help topic in Info (info.org).
+Source
+ Show the Elisp source. If the help displayed is for a customizable
+ variable, then show a customize menu item.
+
+
+File: casual.info, Node: IBuffer, Next: Image, Prev: Help, Up: Casual Modes
+
+4.8 IBuffer
===========
Casual IBuffer provides a user interface to Emacs IBuffer, a mode
@@ -760,7 +830,7 @@ References
File: casual.info, Node: Image, Next: Info, Prev: IBuffer, Up: Casual Modes
-4.8 Image
+4.9 Image
=========
Casual Image is a user interface for Image Mode. Its top level library
@@ -820,8 +890,8 @@ References
File: casual.info, Node: Info, Next: I-Search, Prev: Image, Up: Casual
Modes
-4.9 Info
-========
+4.10 Info
+=========
Casual Info is a user interface for the Emacs Info Reader. Its top
level library is ‘casual-info’.
@@ -883,7 +953,7 @@ References
File: casual.info, Node: I-Search, Next: Make, Prev: Info, Up: Casual Modes
-4.10 I-Search
+4.11 I-Search
=============
Casual I-Search is a user interface for Incremental Search. Its top
@@ -935,7 +1005,7 @@ References
File: casual.info, Node: Make, Next: Man, Prev: I-Search, Up: Casual Modes
-4.11 Make
+4.12 Make
=========
Casual Make is a user interface to ‘make-mode’, a mode tailored for
@@ -1014,7 +1084,7 @@ References
File: casual.info, Node: Man, Next: RE-Builder, Prev: Make, Up: Casual
Modes
-4.12 Man
+4.13 Man
========
Casual Man is a user interface for ‘Man-mode’, a Man page reader.
@@ -1101,7 +1171,7 @@ manual pages.
File: casual.info, Node: RE-Builder, Next: Timezone, Prev: Man, Up: Casual
Modes
-4.13 RE-Builder
+4.14 RE-Builder
===============
Casual RE-Builder is a user interface for RE-Builder. Its top level
@@ -1193,7 +1263,7 @@ References
File: casual.info, Node: Timezone, Prev: RE-Builder, Up: Casual Modes
-4.14 Timezone
+4.15 Timezone
=============
Casual Timezone is a library of commands to work with different time
@@ -1455,6 +1525,9 @@ File: casual.info, Node: Index, Next: Variable Index,
Prev: Acknowledgments,
* EditKit Usage: EditKit. (line 25)
* Feedback: Feedback & Discussion.
(line 6)
+* Help: Help. (line 6)
+* Help Configuration: Help. (line 12)
+* Help Usage: Help. (line 44)
* I-Search: I-Search. (line 6)
* I-Search Configuration: I-Search. (line 12)
* I-Search Usage: I-Search. (line 21)
@@ -1505,32 +1578,33 @@ File: casual.info, Node: Variable Index, Prev: Index,
Up: Top
Tag Table:
Node: Top228
-Node: Motivations1944
-Node: Requirements3437
-Node: Transient Conventions3701
-Node: Casual Modes5429
-Node: Agenda6442
-Node: Bookmarks7999
-Node: Calc10274
-Node: Calendar13415
-Node: Dired14763
-Node: EditKit17988
-Node: IBuffer19712
-Node: Image21777
-Node: Info23018
-Node: I-Search24484
-Node: Make25645
-Node: Man28022
-Node: RE-Builder31409
-Node: Timezone34832
-Node: UX Conventions38224
-Node: Customization40925
-Node: Feedback & Discussion41299
-Node: Sponsorship41717
-Node: About42011
-Node: Acknowledgments42288
-Node: Index42670
-Node: Variable Index47229
+Node: Motivations1953
+Node: Requirements3446
+Node: Transient Conventions3710
+Node: Casual Modes5438
+Node: Agenda6460
+Node: Bookmarks8017
+Node: Calc10292
+Node: Calendar13433
+Node: Dired14781
+Node: EditKit18006
+Node: Help19727
+Node: IBuffer22436
+Node: Image24498
+Node: Info25739
+Node: I-Search27207
+Node: Make28368
+Node: Man30745
+Node: RE-Builder34132
+Node: Timezone37555
+Node: UX Conventions40947
+Node: Customization43648
+Node: Feedback & Discussion44022
+Node: Sponsorship44440
+Node: About44734
+Node: Acknowledgments45011
+Node: Index45393
+Node: Variable Index50171
End Tag Table
diff --git a/docs/casual.org b/docs/casual.org
index 9396494614..70064e93bb 100644
--- a/docs/casual.org
+++ b/docs/casual.org
@@ -488,6 +488,64 @@ Casual EditKit has support for Register commands by
providing a sub-menu for it
#+TEXINFO: @unnumberedsec References
- [[info:emacs#Registers][Registers]]
+** Help
+#+CINDEX: Help
+
+Casual Help is a user interface for ~help-mode~, a major mode for viewing help
text and navigating references in it.
+
+
+#+TEXINFO: @unnumberedsec Configuration
+#+CINDEX: Help Configuration
+
+In your initialization file, bind the Transient ~casual-help-tmenu~ to your
key binding of preference.
+
+#+begin_src elisp :lexical no
+ (require 'casual-help) ; optional
+ (keymap-set help-mode-map "C-o" #'casual-help-tmenu)
+#+end_src
+
+~casual-help-tmenu~ deviates from the default bindings of ~help-mode-map~ as
shown in the table below.
+
+| Default Binding | Casual Binding | Command |
Notes |
+|-----------------+----------------+---------------------------------------+--------------------------------------------|
+| l | M-[ | help-go-back |
Make consistent with Casual Info behavior. |
+| r | M-] | help-go-forward |
Make consistent with Casual Info behavior. |
+| n | N | help-goto-next-page |
Use to navigate to next page. |
+| p | P | help-goto-previous-page |
Use to navigate to previous page. |
+| | n | casual-lib-browser-forward-paragraph |
Use to navigate paragraph forward. |
+| | p | casual-lib-browser-backward-paragraph |
Use to navigate paragraph backward. |
+
+The following keybindings are recommended to support consistent behavior
between ~help-mode~ and ~casual-help-tmenu~.
+
+#+begin_src elisp :lexical no
+ (keymap-set help-mode-map "M-[" #'help-go-back)
+ (keymap-set help-mode-map "M-]" #'help-go-forward)
+ (keymap-set help-mode-map "p" #'casual-lib-browse-backward-paragraph)
+ (keymap-set help-mode-map "n" #'casual-lib-browse-forward-paragraph)
+ (keymap-set help-mode-map "P" #'help-goto-previous-page)
+ (keymap-set help-mode-map "N" #'help-goto-next-page)
+ (keymap-set help-mode-map "j" #'forward-button)
+ (keymap-set help-mode-map "k" #'backward-button)
+#+end_src
+
+
+
+#+TEXINFO: @unnumberedsec Usage
+#+CINDEX: Help Usage
+
+#+TEXINFO: @unnumberedsubsec Basic Usage
+
+After invoking help via a ~describe-~ command, invoke ~casual-help-tmenu~
using the binding ~C-o~ (or your binding of preference).
+
+The following sections are offered in the menu:
+
+- Navigation :: Navigation commands with the document.
+- History :: Navigate history of help invocations.
+- Link :: Navigate to different references in the help buffer.
+- Describe :: Get help for different Elisp types.
+- Info :: If available, then open this help topic in [[file:info.org][Info]].
+- Source :: Show the Elisp source. If the help displayed is for a customizable
variable, then show a customize menu item.
+
** IBuffer
#+CINDEX: IBuffer
diff --git a/docs/dired.org b/docs/dired.org
index 43984452ca..42c9d30265 100644
--- a/docs/dired.org
+++ b/docs/dired.org
@@ -148,17 +148,4 @@ If you enjoy using Casual Dired, consider making a modest
financial contribution
[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/docs/editkit.org b/docs/editkit.org
index c91041a716..d6828a3717 100644
--- a/docs/editkit.org
+++ b/docs/editkit.org
@@ -206,17 +206,4 @@ If you enjoy using Casual EditKit, consider making a
modest financial contributi
[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/docs/help.org b/docs/help.org
new file mode 100644
index 0000000000..e17935d555
--- /dev/null
+++ b/docs/help.org
@@ -0,0 +1,66 @@
+[[../README.org][❮ Back to Casual]]
+
+* Casual Help
+
+Casual Help is a user interface for ~help-mode~, a major mode for viewing help
text and navigating references in it.
+
+[[file:images/casual-help-screenshot.png]]
+
+* Install
+
+In your initialization file, bind the Transient ~casual-help-tmenu~ to your
key binding of preference.
+
+#+begin_src elisp :lexical no
+ (require 'casual-help) ; optional
+ (keymap-set help-mode-map "C-o" #'casual-help-tmenu)
+#+end_src
+
+~casual-help-tmenu~ deviates from the default bindings of ~help-mode-map~ as
shown in the table below.
+
+| Default Binding | Casual Binding | Command |
Notes |
+|-----------------+----------------+---------------------------------------+--------------------------------------------|
+| l | M-[ | help-go-back |
Make consistent with Casual Info behavior. |
+| r | M-] | help-go-forward |
Make consistent with Casual Info behavior. |
+| n | N | help-goto-next-page |
Use to navigate to next page. |
+| p | P | help-goto-previous-page |
Use to navigate to previous page. |
+| | n | casual-lib-browser-forward-paragraph |
Use to navigate paragraph forward. |
+| | p | casual-lib-browser-backward-paragraph |
Use to navigate paragraph backward. |
+
+The following keybindings are recommended to support consistent behavior
between ~help-mode~ and ~casual-help-tmenu~.
+
+#+begin_src elisp :lexical no
+ (keymap-set help-mode-map "M-[" #'help-go-back)
+ (keymap-set help-mode-map "M-]" #'help-go-forward)
+ (keymap-set help-mode-map "p" #'casual-lib-browse-backward-paragraph)
+ (keymap-set help-mode-map "n" #'casual-lib-browse-forward-paragraph)
+ (keymap-set help-mode-map "P" #'help-goto-previous-page)
+ (keymap-set help-mode-map "N" #'help-goto-next-page)
+ (keymap-set help-mode-map "j" #'forward-button)
+ (keymap-set help-mode-map "k" #'backward-button)
+#+end_src
+
+* Usage
+
+** Basic Usage
+
+After invoking help via a ~describe-~ command, invoke ~casual-help-tmenu~
using the binding ~C-o~ (or your binding of preference).
+
+The following sections are offered in the menu:
+
+- Navigation :: Navigation commands with the document.
+- History :: Navigate history of help invocations.
+- Link :: Navigate to different references in the help buffer.
+- Describe :: Get help for different Elisp types.
+- Info :: If available, then open this help topic in [[file:info.org][Info]].
+- Source :: Show the Elisp source. If the help displayed is for a customizable
variable, then show a customize menu item.
+
+*** Unicode Symbol Support
+By enabling “Use Unicode Symbols” from the Settings menu, Casual Man will use
Unicode symbols as appropriate in its menus.
+
+* Sponsorship
+If you enjoy using Casual Man, consider making a modest financial contribution
to help support its development and maintenance.
+
+[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
+
+* See Also
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/docs/ibuffer.org b/docs/ibuffer.org
index e4325a574d..7ad7e2895d 100644
--- a/docs/ibuffer.org
+++ b/docs/ibuffer.org
@@ -160,17 +160,4 @@ If you enjoy using Casual IBuffer, consider making a
modest financial contributi
[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/docs/image.org b/docs/image.org
index 967d415965..8d0da8fc6a 100644
--- a/docs/image.org
+++ b/docs/image.org
@@ -74,17 +74,4 @@ If you enjoy using Casual Image, consider making a modest
financial contribution
[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/docs/images/casual-help-screenshot.png
b/docs/images/casual-help-screenshot.png
new file mode 100644
index 0000000000..9b79e3cee6
Binary files /dev/null and b/docs/images/casual-help-screenshot.png differ
diff --git a/docs/info.org b/docs/info.org
index 6420074842..feb4d9d74f 100644
--- a/docs/info.org
+++ b/docs/info.org
@@ -52,17 +52,4 @@ If you enjoy using Casual Info, consider making a modest
financial contribution
[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/docs/isearch.org b/docs/isearch.org
index 2616fb8d5e..35cac6d66e 100644
--- a/docs/isearch.org
+++ b/docs/isearch.org
@@ -61,17 +61,4 @@ If you enjoy using Casual I-Search, consider making a modest
financial contribut
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/docs/make-mode.org b/docs/make-mode.org
index ec4609e9e9..961481af3b 100644
--- a/docs/make-mode.org
+++ b/docs/make-mode.org
@@ -63,17 +63,4 @@ If you enjoy using Casual Make, consider making a modest
financial contribution
[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/docs/man.org b/docs/man.org
index 7ce7b37c37..764963f1a3 100644
--- a/docs/man.org
+++ b/docs/man.org
@@ -77,18 +77,4 @@ If you enjoy using Casual Man, consider making a modest
financial contribution t
[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
-
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/docs/re-builder.org b/docs/re-builder.org
index 60f406ad87..2cc7cfcf99 100644
--- a/docs/re-builder.org
+++ b/docs/re-builder.org
@@ -59,17 +59,4 @@ If you enjoy using Casual RE-Builder, consider making a
modest financial contrib
[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/docs/timezone.org b/docs/timezone.org
index d46194b05a..73e196cbe5 100644
--- a/docs/timezone.org
+++ b/docs/timezone.org
@@ -38,17 +38,4 @@ If you enjoy using Casual Timezone, consider making a modest
financial contribut
[[https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png]]
* See Also
-- [[file:agenda.org][Agenda]]
-- [[file:bookmarks.org][Bookmarks]]
-- [[file:calc.org][Calc]]
-- [[file:calendar.org][Calendar]]
-- [[file:dired.org][Dired]]
-- [[file:editkit.org][EditKit (numerous editing commands)]]
-- [[file:ibuffer.org][IBuffer]]
-- [[file:image.org][Image]]
-- [[file:info.org][Info]]
-- [[file:isearch.org][I-Search]]
-- [[file:make-mode.org][Make]]
-- [[file:man.org][Man]]
-- [[file:re-builder.org][RE-Builder]]
-- [[file:timezone.org][Timezone]]
+[[file:agenda.org][Agenda]], [[file:bookmarks.org][Bookmarks]],
[[file:calc.org][Calc]], [[file:calendar.org][Calendar]],
[[file:dired.org][Dired]], [[file:editkit.org][EditKit (numerous editing
commands)]], [[file:help.org][Help]], [[file:ibuffer.org][IBuffer]],
[[file:image.org][Image]], [[file:info.org][Info]],
[[file:isearch.org][I-Search]], [[file:make-mode.org][Make]],
[[file:man.org][Man]], [[file:re-builder.org][RE-Builder]],
[[file:timezone.org][Timezone]]
diff --git a/lisp/Makefile b/lisp/Makefile
index 06924dc3aa..67aee24056 100644
--- a/lisp/Makefile
+++ b/lisp/Makefile
@@ -25,6 +25,7 @@ calc-tests \
calendar-tests \
dired-tests \
editkit-tests \
+help-tests \
ibuffer-tests \
info-tests \
isearch-tests \
@@ -61,6 +62,10 @@ dired-tests:
editkit-tests:
$(MAKE) -C $(SRC_DIR) -f Makefile-editkit.make tests
+.PHONY: help-tests
+help-tests:
+ $(MAKE) -C $(SRC_DIR) -f Makefile-help.make tests
+
.PHONY: image-tests
image-tests:
$(MAKE) -C $(SRC_DIR) -f Makefile-image.make tests
diff --git a/lisp/Makefile-help.make b/lisp/Makefile-help.make
new file mode 100644
index 0000000000..ae3368698c
--- /dev/null
+++ b/lisp/Makefile-help.make
@@ -0,0 +1,30 @@
+##
+# Copyright (C) 2025 Charles Y. Choi
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+include Makefile--defines.make
+
+PACKAGE_NAME=casual-help
+ELISP_INCLUDES=casual-help-utils.el \
+casual-help-settings.el
+ELISP_PACKAGES=
+ELISP_TEST_INCLUDES=casual-help-test-utils.el
+PACKAGE_PATHS= \
+-L $(EMACS_ELPA_DIR)/compat-current \
+-L $(EMACS_ELPA_DIR)/seq-current \
+-L $(EMACS_ELPA_DIR)/transient-current \
+-L $(CASUAL_LIB_LISP_DIR)
+
+include Makefile--rules.make
diff --git a/lisp/casual-help-settings.el b/lisp/casual-help-settings.el
new file mode 100644
index 0000000000..752b79b8d5
--- /dev/null
+++ b/lisp/casual-help-settings.el
@@ -0,0 +1,97 @@
+;;; casual-help-settings.el --- Casual Help Settings -*- lexical-binding: t;
-*-
+
+;; Copyright (C) 2025 Charles Y. Choi
+
+;; Author: Charles Choi <[email protected]>
+;; Keywords: tools
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+;;
+
+;;; Code:
+(require 'help-mode)
+(require 'casual-lib)
+
+(transient-define-prefix casual-help-settings-tmenu ()
+ "Casual Help settings menu."
+ ["Casual Help: Settings"
+
+ [("G" "Help Group" casual-help--customize-group)
+ (casual-lib-customize-unicode)
+ (casual-lib-customize-hide-navigation)]]
+
+ [:class transient-row
+ (casual-lib-quit-one)
+ ("a" "About" casual-help-about :transient nil)
+ (casual-lib-quit-all)])
+
+(defun casual-help--customize-group ()
+ "Customize Helpfile group."
+ (interactive)
+ (customize-group "help"))
+
+;; (defun casual-help--customize-man-switches ()
+;; "Switch values passed to the man command, as a single string.
+
+;; Customize `Help-switches'."
+;; (interactive)
+;; (customize-variable 'Help-switches))
+
+;; (defun casual-help--customize-man-prefer-synchronous-call ()
+;; "Whether to call the Un*x \"man\" program synchronously.
+
+;; Customize `Help-prefer-synchronous-call'."
+;; (interactive)
+;; (customize-variable 'Help-prefer-synchronous-call))
+
+;; (defun casual-help--customize-man-support-remote-systems ()
+;; "Whether to call the Un*x \"man\" program on remote systems.
+
+;; Customize `Help-support-remote-systems'."
+;; (interactive)
+;; (customize-variable 'Help-support-remote-systems))
+
+
+(defun casual-help-about-man ()
+ "Casual Help is a Transient menu for `help-mode'.
+
+Learn more about using Casual Help at our discussion group on GitHub.
+Any questions or comments about it should be made there.
+URL `https://github.com/kickingvegas/casual/discussions'
+
+If you find a bug or have an enhancement request, please file an issue.
+Our best effort will be made to answer it.
+URL `https://github.com/kickingvegas/casual/issues'
+
+If you enjoy using Casual Help, consider making a modest financial
+contribution to help support its development and maintenance.
+URL `https://www.buymeacoffee.com/kickingvegas'
+
+Casual Help was conceived and crafted by Charles Choi in San Francisco,
+California.
+
+Thank you for using Casual Help.
+
+Always choose love."
+ (ignore))
+
+(defun casual-help-about ()
+ "About information for Casual Help."
+ (interactive)
+ (describe-function #'casual-help-about-man))
+
+(provide 'casual-help-settings)
+;;; casual-help-settings.el ends here
diff --git a/lisp/casual-help-utils.el b/lisp/casual-help-utils.el
new file mode 100644
index 0000000000..a829c4c541
--- /dev/null
+++ b/lisp/casual-help-utils.el
@@ -0,0 +1,67 @@
+;;; casual-help-utils.el --- Casual Help Utils -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2025 Charles Y. Choi
+
+;; Author: Charles Choi <[email protected]>
+;; Keywords: tools
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+;;
+
+;;; Code:
+(require 'help-mode)
+(require 'casual-lib)
+
+(defconst casual-help-unicode-db
+ '((:previous . '("↑" "Previous"))
+ (:next . '("↓" "Next"))
+ (:forward . '("→" "Forward"))
+ (:backward . '("←" "Backward"))
+ (:goto . '("→" "Goto…"))
+ (:link . '("🔗" "Link"))
+ (:beginning-of-buffer . '("⇱" "Beginning"))
+ (:end-of-buffer . '("⇲" "End"))
+ (:paragraph . '("¶" "Paragraph"))
+ (:page . '("📄" "Page")))
+
+ "Unicode symbol DB to use for Help Transient menus.")
+
+(defun casual-help-unicode-get (key)
+ "Lookup Unicode symbol for KEY in DB.
+
+- KEY symbol used to lookup Unicode symbol in DB.
+
+If the value of customizable variable `casual-lib-use-unicode'
+is non-nil, then the Unicode symbol is returned, otherwise a
+plain ASCII-range string."
+ (casual-lib-unicode-db-get key casual-help-unicode-db))
+
+
+(defun casual-help-info ()
+ "Open Info for Emacs Help Mode."
+ (interactive) (info "(emacs) Help Mode"))
+
+(defun casual-help--current-data-p ()
+ "Predicate if help mode current data exists."
+ help-mode--current-data)
+
+(defun casual-help--symbolp ()
+ "Predicate if current help mode has a symbol."
+ (let ((sym (plist-get help-mode--current-data :symbol)))
+ (or (boundp sym) (facep sym))))
+
+(provide 'casual-help-utils)
+;;; casual-help-utils.el ends here
diff --git a/lisp/casual-help.el b/lisp/casual-help.el
new file mode 100644
index 0000000000..a5afa01017
--- /dev/null
+++ b/lisp/casual-help.el
@@ -0,0 +1,135 @@
+;;; casual-help.el --- Transient UI for Help -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2025 Charles Y. Choi
+
+;; Author: Charles Choi <[email protected]>
+;; Keywords: tools
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; This library provides a Transient-based user interface for `help-mode'.
+
+;; INSTALLATION
+
+;; In your initialization file, bind the Transient `casual-help-tmenu' to your
+;; key binding of preference.
+
+;; (require 'casual-help) ; optional if using autoloaded menu
+;; (keymap-set help-mode-map "C-o" #'casual-help-tmenu)
+
+;; The following keybindings are recommended to support consistent behavior
+;; between `help-mode' and `casual-help-tmenu'.
+
+;; (keymap-set help-mode-map "M-[" #'help-go-back)
+;; (keymap-set help-mode-map "M-]" #'help-go-forward)
+;; (keymap-set help-mode-map "p" #'casual-lib-browse-backward-paragraph)
+;; (keymap-set help-mode-map "n" #'casual-lib-browse-forward-paragraph)
+;; (keymap-set help-mode-map "P" #'help-goto-previous-page)
+;; (keymap-set help-mode-map "N" #'help-goto-next-page)
+;; (keymap-set help-mode-map "j" #'forward-button)
+;; (keymap-set help-mode-map "k" #'backward-button)
+
+;;; Code:
+(require 'bookmark)
+(require 'button)
+(require 'casual-help-settings)
+(require 'casual-help-utils)
+
+;;;###autoload (autoload 'casual-help-tmenu "casual-help" nil t)
+(transient-define-prefix casual-help-tmenu ()
+ "Casual Help main menu."
+ :refresh-suffixes t
+ ["Casual Help"
+ ["Navigation"
+ :pad-keys t
+ ("C-p" "Previous" previous-line
+ :description (lambda () (casual-help-unicode-get :previous))
+ :transient t)
+ ("C-n" "Next" next-line
+ :description (lambda () (casual-help-unicode-get :next))
+ :transient t)
+ ("<" "Beginning" beginning-of-buffer
+ :description (lambda () (casual-help-unicode-get :beginning-of-buffer))
+ :transient t)
+ (">" "End" end-of-buffer
+ :description (lambda () (casual-help-unicode-get :end-of-buffer))
+ :transient t)]
+
+ [""
+ ("p" "Backward" casual-lib-browse-backward-paragraph
+ :description (lambda () (format "%s %s"
+ (casual-help-unicode-get :previous)
+ (casual-help-unicode-get :paragraph)))
+ :transient t)
+ ("n" "Forward" casual-lib-browse-forward-paragraph
+ :description (lambda () (format "%s %s"
+ (casual-help-unicode-get :next)
+ (casual-help-unicode-get :paragraph)))
+ :transient t)
+ ("P" "Backward" help-goto-previous-page
+ :description (lambda () (format "%s %s"
+ (casual-help-unicode-get :previous)
+ (casual-help-unicode-get :page)))
+ :transient t)
+ ("N" "Forward" help-goto-next-page
+ :description (lambda () (format "%s %s"
+ (casual-help-unicode-get :next)
+ (casual-help-unicode-get :page)))
+ :transient t)]
+
+ ["History"
+ ("M-[" "Previous" help-go-back
+ :description (lambda () (casual-help-unicode-get :previous))
+ :transient t)
+ ("M-]" "Next" help-go-forward
+ :description (lambda () (casual-help-unicode-get :next))
+ :transient t)]
+
+ ["Link"
+ :pad-keys t
+ ("j" "Forward" forward-button
+ :description (lambda () (casual-help-unicode-get :forward))
+ :transient t)
+ ("k" "Backward" backward-button
+ :description (lambda () (casual-help-unicode-get :backward))
+ :transient t)
+ ("RET" "Open" push-button)]]
+
+ [["Describe"
+ ("ds" "Symbol…" describe-symbol)
+ ("dv" "Variable…" describe-variable)]
+ [""
+ ("dc" "Command…" describe-command)
+ ("df" "Function…" describe-function)]
+
+ ["Info"
+ :if casual-help--current-data-p
+ ("i" "Goto" help-goto-info)
+ ("I" "Elisp" help-goto-lispref-info)]
+
+ ["Source"
+ ("s" "Source" help-view-source)
+ ("c" "Customize" help-customize
+ :if casual-help--symbolp)]]
+
+ [:class transient-row
+ (casual-lib-quit-one)
+ ("," "Settings" casual-help-settings-tmenu)
+ ("q" "Quit" quit-window)
+ (casual-lib-quit-all)])
+
+(provide 'casual-help)
+;;; casual-help.el ends here
diff --git a/lisp/casual-man-settings.el b/lisp/casual-man-settings.el
index 74049e8b0d..8a050e50ea 100644
--- a/lisp/casual-man-settings.el
+++ b/lisp/casual-man-settings.el
@@ -22,6 +22,7 @@
;;
;;; Code:
+(require 'man)
(require 'casual-lib)
(transient-define-prefix casual-man-settings-tmenu ()
diff --git a/tests/Makefile b/tests/Makefile
index 9002dd1be1..94e3b66a4e 100644
--- a/tests/Makefile
+++ b/tests/Makefile
@@ -24,6 +24,7 @@ calc-tests \
calendar-tests \
dired-tests \
editkit-tests \
+help-tests \
ibuffer-tests \
info-tests \
isearch-tests \
@@ -41,6 +42,7 @@ calc-tests \
calendar-tests \
dired-tests \
editkit-tests \
+help-tests \
ibuffer-tests \
info-tests \
isearch-tests \
@@ -70,6 +72,9 @@ dired-tests:
editkit-tests:
$(MAKE) -C $(SRC_DIR) $@
+help-tests:
+ $(MAKE) -C $(SRC_DIR) $@
+
ibuffer-tests:
$(MAKE) -C $(SRC_DIR) $@
diff --git a/tests/casual-help-test-utils.el b/tests/casual-help-test-utils.el
new file mode 100644
index 0000000000..40e5d36d8e
--- /dev/null
+++ b/tests/casual-help-test-utils.el
@@ -0,0 +1,41 @@
+;;; casual-help-test-utils.el --- Casual Test Utils -*- lexical-binding:
t; -*-
+
+;; Copyright (C) 2024-2025 Charles Y. Choi
+
+;; Author: Charles Choi <[email protected]>
+;; Keywords: tools
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;;
+
+;;; Code:
+(require 'ert)
+(require 'casual-lib)
+(require 'kmacro)
+
+(defun casualt-help-setup ()
+ "Casual Help setup."
+ (describe-symbol 'find-file)
+ (describe-symbol 'apropos-do-all)
+ (switch-to-buffer "*Help*"))
+
+(defun casualt-help-breakdown ()
+ "Casual help breakdown."
+ )
+
+(provide 'casual-help-test-utils)
+;;; casual-help-test-utils.el ends here
diff --git a/tests/test-casual-help-settings.el
b/tests/test-casual-help-settings.el
new file mode 100644
index 0000000000..75d8f34635
--- /dev/null
+++ b/tests/test-casual-help-settings.el
@@ -0,0 +1,53 @@
+;;; test-casual-help-settings.el --- Casual Make Settings Tests -*-
lexical-binding: t; -*-
+
+;; Copyright (C) 2025 Charles Y. Choi
+
+;; Author: Charles Choi <[email protected]>
+;; Keywords: tools
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;;
+
+;;; Code:
+
+(require 'ert)
+(require 'casual-help-test-utils)
+(require 'casual-help-settings)
+
+(ert-deftest test-casual-help-settings-tmenu ()
+ (let ()
+ (cl-letf ((casualt-mock #'casual-help--customize-group)
+ (casualt-mock #'casual-help-about)
+ ;;(casualt-mock #')
+
+ )
+
+ (let ((test-vectors
+ '((:binding "G" :command casual-help--customize-group)
+ (:binding "u" :command
casual-lib-customize-casual-lib-use-unicode)
+ (:binding "n" :command
casual-lib-customize-casual-lib-hide-navigation)
+ (:binding "a" :command casual-help-about))))
+
+ (casualt-suffix-testcase-runner test-vectors
+ #'casual-help-settings-tmenu
+ '(lambda () (random 5000)))))))
+
+(ert-deftest test-casual-help-about ()
+ (should (stringp (casual-help-about))))
+
+(provide 'test-casual-help-settings)
+;;; test-casual-help-setttings.el ends here
diff --git a/tests/test-casual-help-utils.el b/tests/test-casual-help-utils.el
new file mode 100644
index 0000000000..63e7695a28
--- /dev/null
+++ b/tests/test-casual-help-utils.el
@@ -0,0 +1,54 @@
+;;; test-casual-help-utils.el --- Casual Make Utils Tests -*-
lexical-binding: t; -*-
+
+;; Copyright (C) 2025 Charles Y. Choi
+
+;; Author: Charles Choi <[email protected]>
+;; Keywords: tools
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;;
+
+;;; Code:
+(require 'ert)
+(require 'casual-help-test-utils)
+(require 'casual-help-utils)
+
+(ert-deftest test-casual-help-unicode-get ()
+ (let ((casual-lib-use-unicode nil))
+ (should (string-equal (casual-help-unicode-get :previous) "Previous"))
+ (should (string-equal (casual-help-unicode-get :next) "Next"))
+ (should (string-equal (casual-help-unicode-get :forward) "Forward"))
+ (should (string-equal (casual-help-unicode-get :backward) "Backward"))
+ (should (string-equal (casual-help-unicode-get :goto) "Goto…"))
+ (should (string-equal (casual-help-unicode-get :link) "Link"))
+ (should (string-equal (casual-help-unicode-get :beginning-of-buffer)
"Beginning"))
+ (should (string-equal (casual-help-unicode-get :end-of-buffer) "End"))
+ (should (string-equal (casual-help-unicode-get :paragraph) "Paragraph"))
+ (should (string-equal (casual-help-unicode-get :page) "Page")))
+
+ (let ((casual-lib-use-unicode t))
+ (should (string-equal (casual-help-unicode-get :previous) "↑"))
+ (should (string-equal (casual-help-unicode-get :next) "↓"))
+ (should (string-equal (casual-help-unicode-get :goto) "→"))
+ (should (string-equal (casual-help-unicode-get :link) "🔗"))
+ (should (string-equal (casual-help-unicode-get :beginning-of-buffer) "⇱"))
+ (should (string-equal (casual-help-unicode-get :end-of-buffer) "⇲"))
+ (should (string-equal (casual-help-unicode-get :paragraph) "¶"))
+ (should (string-equal (casual-help-unicode-get :page) "📄"))))
+
+(provide 'test-casual-help-utils)
+;;; test-casual-help-utils.el ends here
diff --git a/tests/test-casual-help.el b/tests/test-casual-help.el
new file mode 100644
index 0000000000..7ef645af85
--- /dev/null
+++ b/tests/test-casual-help.el
@@ -0,0 +1,100 @@
+;;; test-casual-help.el --- Casual Make Tests -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2025 Charles Y. Choi
+
+;; Author: Charles Choi <[email protected]>
+;; Keywords: tools
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;;
+
+;;; Code:
+
+(require 'ert)
+(require 'casual-lib-test-utils)
+(require 'casual-help-test-utils)
+(require 'casual-help)
+
+(ert-deftest test-casual-help-tmenu ()
+ (let ()
+ (casualt-help-setup)
+
+ (cl-letf ((casualt-mock #'beginning-of-buffer)
+ (casualt-mock #'end-of-buffer)
+ (casualt-mock #'previous-line)
+ (casualt-mock #'next-line)
+ (casualt-mock #'casual-lib-browse-backward-paragraph)
+ (casualt-mock #'casual-lib-browse-forward-paragraph)
+ (casualt-mock #'help-goto-previous-page)
+ (casualt-mock #'help-goto-next-page)
+ (casualt-mock #'help-go-back)
+ (casualt-mock #'help-go-forward)
+ (casualt-mock #'forward-button)
+ (casualt-mock #'backward-button)
+ (casualt-mock #'push-button)
+ (casualt-mock #'describe-symbol)
+ (casualt-mock #'describe-command)
+ (casualt-mock #'describe-function)
+ (casualt-mock #'describe-variable)
+
+ (casualt-mock #'help-goto-info)
+ (casualt-mock #'help-goto-lispref-info)
+
+ (casualt-mock #'help-view-source)
+ (casualt-mock #'help-customize)
+ (casualt-mock #'casual-help-settings-tmenu)
+
+ (casualt-mock #'quit-window))
+
+ (let ((test-vectors
+ '((:binding ">" :command end-of-buffer)
+ (:binding "<" :command beginning-of-buffer)
+ (:binding "C-n" :command next-line)
+ (:binding "C-p" :command previous-line)
+ (:binding "n" :command casual-lib-browse-forward-paragraph)
+ (:binding "p" :command casual-lib-browse-backward-paragraph)
+ (:binding "P" :command help-goto-previous-page)
+ (:binding "N" :command help-goto-next-page)
+ (:binding "M-[" :command help-go-back)
+ (:binding "M-]" :command help-go-forward)
+
+ (:binding "j" :command forward-button)
+ (:binding "k" :command backward-button)
+ (:binding "RET" :command push-button)
+
+ ;; (:binding "ds" :command describe-symbol)
+ ;; (:binding "dv" :command describe-variable)
+ ;; (:binding "dc" :command describe-command)
+ ;; (:binding "df" :command describe-function)
+
+ (:binding "i" :command help-goto-info)
+ (:binding "I" :command help-goto-lispref-info)
+
+ (:binding "s" :command help-view-source)
+ ;;(:binding "c" :command help-customize)
+
+ (:binding "," :command casual-help-settings-tmenu)
+ (:binding "q" :command quit-window)
+ )))
+
+ (casualt-suffix-testcase-runner test-vectors
+ #'casual-help-tmenu
+ '(lambda () (random 5000)))))
+ (casualt-help-breakdown)))
+
+(provide 'test-casual-help)
+;;; test-casual-help.el ends here
![https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png](https://www.buymeacoffee.com/kickingvegas][file:images/default-yellow.png){kind=link}