feat(wip): introducing `org-remark-reveal-p'

This is stilla WIP but at present, the feature works like this.

Goal

I want `org-remark-next/prev` commands to be able to find "hidden"
highlights. In Emacs, there are mainly two ways parts of the current buffer
can be hidden: (1) Narrowed (eg narrowed to a heading, to a defun), or (2)
Folded (eg via folding an outline in Org, Markdown, or Outline modes).

Current behaviour

I have introduced the following:

- A new local variable: `org-remark-reveal-p'
- A new set of commands: org-remark-reveal-activate-locally
                                            org-remark-reveal-deactivate-locally

Use the commands to activate/deactivate `org-remark-reveal-p'.

When `org-remark-reveal-p' is non-nil, `org-remark-next/prev` will reveal
hidden highlights in the folded (2) parts. When the buffer is narrowed (1),
the next/prev commands will NOT find highlights outside the currently visible
parts.

org-remark.el

@@ -830,6 +830,7 @@ Return nil if not and outputs a message in the echo."
                (org-remark-find-prev-highlight))))
       (if p (progn
               (goto-char p)
+              (org-remark--reveal-context)
               ;; Setup the overriding keymap.
               (unless overriding-terminal-local-map
                 (let ((prefix-keys (substring (this-single-command-keys) 0 -1))
@@ -842,6 +843,18 @@ Return nil if not and outputs a message in the echo."
         (message "No visible highlights present in the buffer")
         nil))))
 
+(defun org-remark--reveal-context ()
+  (cond
+   ((and (derived-mode-p 'org)
+              (org-invisible-p (point)))
+    (org-fold-show-context 'link-search))
+   ((pcase-let*
+        ((`(,fn . ,ov) (get-char-property-and-overlay
+                         (point)
+                         'isearch-open-invisible))
+         (_ (functionp fn)))
+      (funcall fn ov)))))
+
 (defun org-remark-find-next-highlight ()
   "Return the beg point of the next highlight.
 Look through `org-remark-highlights' list."
@@ -1713,6 +1726,18 @@ This function also set `org-remark-highlights' to nil."
      (when (overlay-get ov 'org-remark-id)
        (delete-overlay ov)))))
 
+(defvar-local org-remark-reveal-p nil)
+
+(defun org-remark-reveal-activate-locally ()
+  (interactive)
+  (setq-local org-remark-reveal-p t)
+  (message "Org-remark-next/prev now show hidden highlighs."))
+
+(defun org-remark-reveal-deactivate-locally ()
+  (interactive)
+  (setq-local org-remark-reveal-p nil)
+  (message "Org-remark-next/prev now keep hidden highlighs hidden."))
+
 (defun org-remark-highlights-get-positions (&optional reverse)
   "Return list of the beginning point of all visible highlights in this buffer.
 By default, the list is in ascending order.  If REVERSE is
@@ -1728,13 +1753,17 @@ If none, return nil."
                   (lambda (h)
                     (let ((p (overlay-start h)))
                       ;; Checking if the p is visible or not
-                      (if (or
-                           (> p (point-max))
-                           (< p (point-min))
-                           ;; When the highlight is within a visible folded
-                           ;; area, this function returns 'outline
-                           (org-invisible-p p))
-                          nil p)))
+                      (cond ((or (> p (point-max)) (< p (point-min))) nil)
+                            ;; When the highlight is within a visible folded
+                            ;; area, this function returns 'outline
+
+                            ;; When `org-remark-reveal-p' is non-nil, invisible
+                            ;; highlights due to folding will be
+                            ;; revealed. Those highlights outside the narrowed
+                            ;; regions will remain hidden.
+                            ((org-invisible-p p)
+                             (if org-remark-reveal-p p nil))
+                            (t p))))
                   list))
       (setq list (remove nil list))
       (when list