branch: externals/logos
commit a63d1ab315ad6460836d7904824b96147d1f74a6
Author: Protesilaos Stavrou <i...@protesilaos.com>
Commit: Protesilaos Stavrou <i...@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.
