diff options
Diffstat (limited to 'pearl.el')
| -rw-r--r-- | pearl.el | 50 |
1 files changed, 44 insertions, 6 deletions
@@ -228,6 +228,16 @@ leave the buffer expanded after updates." :type 'boolean :group 'pearl) +(defcustom pearl-help-header t + "When non-nil, render a folded \"* Pearl\" heading atop each Linear file. +The heading collapses on open (via a `:VISIBILITY: folded' property) and carries +the edit-then-save reminder, the keymap cues, and the priority-cookie legend, so +the help is discoverable without a dozen lines of `#' preamble cluttering the +buffer. It has no `LINEAR-ID', so save and merge ignore it. Set to nil to omit +it entirely, leaving just the machine `#+' keywords." + :type 'boolean + :group 'pearl) + (defcustom pearl-title-case-headings nil "When non-nil, render issue titles in the heading in smart title case. The default is nil: titles render verbatim, exactly as Linear stores them, so @@ -3603,6 +3613,35 @@ only add the ones a failed team fetch left out." issues)))) (append team-states issue-states)))) +;; Forward declaration: `pearl-keymap-prefix' is a defcustom in the keymap +;; section below, but the help header (rendered here) reads it for the key cues. +(defvar pearl-keymap-prefix) + +(defun pearl--help-header-string () + "Return the folded \"* Pearl\" heading shown atop a Linear file. +A collapsible section (`:VISIBILITY: folded') carrying the edit-then-save +reminder, a note that the section is local-only, the keymap cues, the +priority-cookie legend, and how to hide it. The cues reflect the live +`pearl-keymap-prefix' so a customized prefix shows the right chords; a nil +prefix (no binding) points at \\[execute-extended-command] instead. The +heading carries no `LINEAR-ID', so save and merge skip it (they walk only +`LINEAR-ID'-bearing subtrees -- see `pearl--issue-subtree-markers')." + (let ((p pearl-keymap-prefix)) + (concat + "* Pearl\n" + ":PROPERTIES:\n" + ":VISIBILITY: folded\n" + ":END:\n" + "Edit issues in this buffer, then save to push your changes to Linear.\n" + "This section is never sent to Linear. It is local help text only.\n" + (if p + (concat + (format "Inline edits (title, body, comments, [#A] cookie) save with %s s. %s S saves all.\n" p p) + (format "State / assignee / labels: %s e s / e a / e l. %s g refreshes; %s m menu; %s f s pick source.\n" p p p p)) + "No prefix is bound (pearl-keymap-prefix is nil); reach commands via M-x (e.g. M-x pearl-save-issue, M-x pearl-menu).\n") + "Priority cookies: [#A] Urgent, [#B] High, [#C] Medium, [#D] Low, no cookie = None.\n" + "Hide this section: set pearl-help-header to nil (M-x customize-variable RET pearl-help-header).\n"))) + (defun pearl--build-org-content (issues &optional source truncated states account) "Build the Org content string for the linear org file from ISSUES. SOURCE is the active-source descriptor recorded in the header so a later @@ -3631,13 +3670,12 @@ no side effects." (insert (format "#+LINEAR-FILTER: %s\n" (pearl--summarize-filter filter))) (insert (format "#+LINEAR-COUNT: %d\n" (length issues))) (insert (format "#+LINEAR-TRUNCATED: %s\n" (if truncated "yes" "no"))) - ;; Affordance preamble (org comments -- not rendered content). Keys - ;; reference the live `pearl-mode' keymap so the cues match what the - ;; user actually types, not the M-x longhand. - (insert "#\n") - (insert "# Inline edits (title, body, comments, [#A] cookie) save with C-; L s. C-; L S saves all.\n") - (insert "# State / assignee / labels: C-; L e s / e a / e l. C-; L g refreshes; C-; L m menu; C-; L f s pick source.\n") + ;; Optional folded help heading carries the cues + priority legend in a + ;; collapsible section (`pearl-help-header'), replacing the raw `#' + ;; affordance comments. It has no `LINEAR-ID', so sync/merge skip it. (insert "\n") + (when pearl-help-header + (insert (pearl--help-header-string))) ;; Single top-level parent so the issues are sortable as a group ;; (org-sort on this heading) instead of orphan headings, and so a |