From 6169288a7f3ad3a96a4cf07ed07a9ee81cee53c9 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Wed, 27 May 2026 15:39:15 -0500 Subject: docs: document pearl-mode and the completed keymap I replaced the old save/edit/new/delete prefix writeup with pearl-mode, which auto-enables in Linear buffers, and the full scheme: the hot keys directly under the prefix plus the fetch, edit, new, delete, and url groups. --- README.org | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) (limited to 'README.org') diff --git a/README.org b/README.org index 6dd3b92..cb3802e 100644 --- a/README.org +++ b/README.org @@ -150,19 +150,38 @@ Pearl writes one active Org file. Running a different query or view replaces tha (global-set-key (kbd "C-c L") #'pearl-menu) #+end_src -*** Prefix keymap +*** Prefix keymap and pearl-mode -For muscle memory, Pearl also defines an opt-in prefix keymap, =pearl-prefix-map=, organized as save / edit / new / delete. It is not bound at load -- a global multi-key prefix isn't reliably free across terminals and GUIs, so you bind it to a prefix that suits your setup. A suggested binding: +Pearl is fully keyboard-drivable. =pearl-mode=, a minor mode, turns on automatically in any buffer Pearl renders (it detects the =#+LINEAR-SOURCE= header) and binds the command keymap under =pearl-keymap-prefix= (default =C-; L=). So in a fetched buffer the keys are live with no setup. Change the prefix, or turn it off, with: #+begin_src emacs-lisp - (global-set-key (kbd "C-; L") pearl-prefix-map) - ;; or, with use-package: - ;; :bind-keymap ("C-; L" . pearl-prefix-map) + (setq pearl-keymap-prefix "C-c l") ; or nil to bind nothing #+end_src -With that prefix, =C-; L s s= saves the ticket at point, =C-; L s a= saves every ticket in the file, =C-; L e s= picks its state, =C-; L n t= creates a ticket, and =C-; L m= opens the full transient. If you use =which-key=, each step shows a labeled menu. +The hot-path commands sit one key under the prefix; the rest are grouped into category sub-maps. The common ones appear in both places, so =d= and =e d= both edit the description. + +| Key | Command | +|-----------+----------------------------------------------------------------------| +| =l= | list my open issues | +| =g= | refresh the view | +| =r= | refresh the issue at point | +| =s= / =S= | save the ticket at point / save every ticket in the file | +| =d= | edit the description | +| =c= | add a comment | +| =m= | open the full transient menu | +| =f= ... | fetch: =o= open issues, =p= by project, =f= filter, =v= view, =q= saved query | +| =e= ... | edit: =d= description, =s= state, =a= assignee, =l= labels, =c= comment | +| =n= ... | new: =t= ticket, =c= comment | +| =k= ... | delete: =t= ticket, =c= comment | +| =u= ... | url: =o= open issue in browser, =v= open view in Linear | + +To reach the map outside a Pearl buffer, bind it globally as well: + +#+begin_src emacs-lisp + (global-set-key (kbd "C-; L") pearl-prefix-map) +#+end_src -Every command is also available directly through =M-x=. +With =which-key=, each step shows a labeled menu. Every command is also available through =M-x=. *** Fetching and refreshing -- cgit v1.2.3