[elpa] externals/logos a63d1ab315 20/25: Always reveal Org/Outline entry

[ELPA Syncer]

branch: externals/logos
commit a63d1ab315ad6460836d7904824b96147d1f74a6
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Always reveal Org/Outline entry
    
    Otherwise we have a bug where page motions can move inside a heading
    with subheadings.
---
 README.org | 39 ++++++++++++++++++++++++++-------------
 logos.el   | 23 ++++++++++++++++++++++-
 2 files changed, 48 insertions(+), 14 deletions(-)

diff --git a/README.org b/README.org
index c4f25eec0a..4d04e7e2fc 100644
--- a/README.org
+++ b/README.org
@@ -227,19 +227,39 @@ be disabled when we exit.
 (add-hook 'logos-focus-mode-hook #'my-logos--olivetti-mode)
 #+end_src
 
-** Automatically reveal Org or Outline heading
+** Automatically reveal Org or Outline subtree
 :PROPERTIES:
 :CUSTOM_ID: h:e18f828f-f9a8-4821-b73b-46793be57abb
 :END:
-#+cindex: Always show the Org or Outline subtree or entry
+#+cindex: Always show the Org or Outline subtree
 
-The Logos page motions simply jump between positions.  If the heading is
-folded, they will keep it that way.  To always reveal the contents use
-something like this:
+The Logos page motions normally jump between positions.  Though Org and
+Outline require that Logos also reveals the headings' contents.  This is
+necessary to avoid invisible motions inside a folded heading that
+contains subheadings.  The unfolding only applies to the current entry.
+This is the relevant snippet from =logos.el=:
+
+#+begin_src emacs-lisp
+(defun logos--reveal-entry ()
+  "Reveal Org or Outline entry."
+  (cond
+   ((and (eq major-mode 'org-mode)
+         (org-at-heading-p))
+    (org-show-entry))
+   ((or (eq major-mode 'outline-mode)
+        (bound-and-true-p outline-minor-mode))
+    (outline-show-entry))))
+
+(add-hook 'logos-page-motion-hook #'logos--reveal-entry)
+#+end_src
+
+Users may prefer to reveal the entire subtree instead of the current
+entry: the heading at point and all of its subheadings.  In this case,
+one may override the definition of ~logos--reveal-entry~:
 
 #+begin_src emacs-lisp
 ;; glue code to expand an Org/Outline heading
-(defun my-logos--reveal ()
+(defun logos--reveal-entry ()
   "Reveal Org or Outline entry."
   (cond
    ((and (eq major-mode 'org-mode)
@@ -248,15 +268,8 @@ something like this:
    ((or (eq major-mode 'outline-mode)
         (bound-and-true-p outline-minor-mode))
     (outline-show-subtree))))
-
-(add-hook 'logos-page-motion-hook #'my-logos--reveal)
 #+end_src
 
-Notice that it applies to the entire subtree (heading and subheadings).
-If the intent is to reveal just the current heading, replace
-~org-show-subtree~ and ~outline-show-subtree~ with ~org-show-entry~ and
-~outline-show-entry~.
-
 ** Recenter at the top upon page motion
 :PROPERTIES:
 :CUSTOM_ID: h:bba965c6-7451-4c76-84d6-7e03c99ed546
diff --git a/logos.el b/logos.el
index 283fe82bd3..f76809d1f7 100644
--- a/logos.el
+++ b/logos.el
@@ -88,7 +88,12 @@ When this variable is nil, pages are demarcated by the
     (org-mode . "^\\*+ +")
     (t . ,(or outline-regexp logos--page-delimiter)))
   "Alist of major mode and regular expression of the outline.
-Only used when `logos-outlines-are-pages' is non-nil."
+Only used when `logos-outlines-are-pages' is non-nil.
+
+The major mode also targets any of its derivatives.  For example,
+`lisp-interaction-mode' (the standard scratch buffer) is based on
+`emacs-lisp-mode' so one only needs to set the outline regexp of
+the latter."
   :type `(alist :key-type symbol :value-type string) ; TODO 2022-03-02: ensure 
symbol is mode?
   :group 'logos)
 
@@ -184,6 +189,22 @@ page."
   (interactive "p")
   (logos--page-motion count :back))
 
+(declare-function org-at-heading-p "org" (&optional _))
+(declare-function org-show-entry "org")
+(declare-function outline-show-entry "outline")
+
+(defun logos--reveal-entry ()
+  "Reveal Org or Outline entry."
+  (cond
+   ((and (eq major-mode 'org-mode)
+         (org-at-heading-p))
+    (org-show-entry))
+   ((or (eq major-mode 'outline-mode)
+        (bound-and-true-p outline-minor-mode))
+    (outline-show-entry))))
+
+(add-hook 'logos-page-motion-hook #'logos--reveal-entry)
+
 ;;;; Narrowing
 ;; NOTE 2022-03-02: This section is most likely unnecessary, but let's
 ;; keep it for now.