Re: [PATCH] org.el (org-show-context-detail): add option 'ancestors-with-entry

["Cheong Yiu Fung" <mail@yiufung.net>]

[-- Attachment #1: Type: text/plain, Size: 1113 bytes --]

Hi Nicolas,

The first patch implements the changes. I took the liberty to show entry of its ancestors
too (4 in the test case). Many users, I believe, rarely put text there, so it does not
make a difference. But when someone write short notes at this location, I think it serves
as brief "contextual" information for all its children, our target headline included. It
may indicate the intention to include contextual information in output too, so I go with
such guess. If user does not want it to be included, it is easier for him to work around
(e.g., by creating a new heading and put text under), than the other way around, that is,
to reveal text one by one.

The second patch suggests how it can be integrated with `org-sparse-tree' in the manual. I
think the new option, as the first visibility option to show subtree, would make
`visible-only' option a lot more useful. Whether to include it in the manual I leave it to
your consideration.

Lastly I'd like to say thanks as a daily Org user, thank you for putting time in
overseeing the project. Your efforts are appreciated by many :)

Regards,
Yiufung


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org.el-org-show-context-detail-add-option-ancestors-.patch --]
[-- Type: text/x-patch; name="0001-org.el-org-show-context-detail-add-option-ancestors-.patch", Size: 3863 bytes --]

From d278837240c2cd03bc3ac448b8fb40d8c0866c5c Mon Sep 17 00:00:00 2001
From: Cheong Yiu Fung <mail@yiufung.net>
Date: Wed, 21 Apr 2021 16:26:14 +0800
Subject: [PATCH 1/2] org.el (org-show-context-detail): add option
 'ancestors-full

* lisp/org.el: Add option 'ancestors-full to
`org-show-context-detail', update `org-show-set-visibility'
accordingly
* testing/lisp/test-org.el: Add tests.
---
 lisp/org.el              | 18 ++++++++++++------
 testing/lisp/test-org.el |  4 ++++
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 675a614e2..80039c802 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -1199,6 +1199,9 @@ Allowed visibility spans are
   ancestors      show current headline and its direct ancestors; if
                  point is not on headline, also show entry
 
+  ancestors-full show current headline, entry, subtree, current
+                 headline's direct ancestors and their entries
+
   lineage        show current headline, its direct ancestors and all
                  their children; if point is not on headline, also show
                  entry and first child
@@ -1240,6 +1243,7 @@ more context."
 			   (const minimal)
 			   (const local)
 			   (const ancestors)
+                           (const ancestors-full)
 			   (const lineage)
 			   (const tree)
 			   (const canonical))))))
@@ -6758,9 +6762,9 @@ be shown."
 
 (defun org-show-set-visibility (detail)
   "Set visibility around point according to DETAIL.
-DETAIL is either nil, `minimal', `local', `ancestors', `lineage',
-`tree', `canonical' or t.  See `org-show-context-detail' for more
-information."
+DETAIL is either nil, `minimal', `local', `ancestors',
+`ancestors-full', `lineage', `tree', `canonical' or t.  See
+`org-show-context-detail' for more information."
   ;; Show current heading and possibly its entry, following headline
   ;; or all children.
   (if (and (org-at-heading-p) (not (eq detail 'local)))
@@ -6775,18 +6779,20 @@ information."
       (org-with-limited-levels
        (cl-case detail
 	 ((tree canonical t) (org-show-children))
-	 ((nil minimal ancestors))
+	 ((nil minimal ancestors ancestors-full))
 	 (t (save-excursion
 	      (outline-next-heading)
 	      (org-flag-heading nil)))))))
+  ;; Show whole subtree.
+  (when (eq detail 'ancestors-full) (org-show-subtree))
   ;; Show all siblings.
   (when (eq detail 'lineage) (org-show-siblings))
   ;; Show ancestors, possibly with their children.
-  (when (memq detail '(ancestors lineage tree canonical t))
+  (when (memq detail '(ancestors ancestors-full lineage tree canonical t))
     (save-excursion
       (while (org-up-heading-safe)
 	(org-flag-heading nil)
-	(when (memq detail '(canonical t)) (org-show-entry))
+	(when (memq detail '(ancestors-full canonical t)) (org-show-entry))
 	(when (memq detail '(tree canonical t)) (org-show-children))))))
 
 (defvar org-reveal-start-hook nil
diff --git a/testing/lisp/test-org.el b/testing/lisp/test-org.el
index f6fb4b3ca..36658d51d 100644
--- a/testing/lisp/test-org.el
+++ b/testing/lisp/test-org.el
@@ -7982,6 +7982,10 @@ CLOCK: [2012-03-29 Thu 10:00]--[2012-03-29 Thu 16:40] =>  6:40"
     (should (equal '(0 7 8 9) (funcall list-visible-lines 'local nil)))
     (should (equal '(0 3 7) (funcall list-visible-lines 'ancestors t)))
     (should (equal '(0 3 7 8) (funcall list-visible-lines 'ancestors nil)))
+    (should (equal '(0 3 4 7 8 9 10 11)
+                   (funcall list-visible-lines 'ancestors-full t)))
+    (should (equal '(0 3 4 7 8 9 10 11)
+                   (funcall list-visible-lines 'ancestors-full nil)))
     (should (equal '(0 3 5 7 12) (funcall list-visible-lines 'lineage t)))
     (should (equal '(0 3 5 7 8 9 12) (funcall list-visible-lines 'lineage nil)))
     (should (equal '(0 1 3 5 7 12 13) (funcall list-visible-lines 'tree t)))
-- 
2.31.1


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 0002-org-manual.org-add-hints-for-visible-only-export.patch --]
[-- Type: text/x-patch; name="0002-org-manual.org-add-hints-for-visible-only-export.patch", Size: 823 bytes --]

From 86adcab8a83c782b9a039aa9791e7076f9ff2833 Mon Sep 17 00:00:00 2001
From: Cheong Yiu Fung <mail@yiufung.net>
Date: Wed, 21 Apr 2021 16:27:03 +0800
Subject: [PATCH 2/2] org-manual.org: add hints for visible-only export

---
 doc/org-manual.org | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index efe956877..16dd4a52f 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -11524,7 +11524,8 @@ further alter what is exported, and how.
 
   Toggle visible-only export.  This is useful for exporting only
   certain parts of an Org document by adjusting the visibility of
-  particular headings.
+  particular headings.  See also the variable
+  ~org-show-context-detail~ and the command ~org-sparse-tree~.
 
 ** Export Settings
 :PROPERTIES:
-- 
2.31.1