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

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

[Cheong Yiu Fung]

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

Hi, I'm proposing a new option in `org-show-context-detail', which shows
current headline, its ancestors, *and the entry itself*. This is useful
when export matched subtrees and their contents quickly with least
manual intervention.

Consider when working on different aspects of a project and taking notes
as we go:

* Project
A project tree
** Task1
** Task2
*** ASK Something to align
Something for discussion
** Task3
** Task4
*** ASK Something else to align
Something else.

At some point, we may wish to export only certain contents. For example,
to export headings with TODO keyword of "ASK", along with the task
context (ancestors TASK<N> heading name), and their own content for
discussion with colleagues. Ideally, this can be done by
org-sparse-tree, followed by org-export with visible-only + subtree-only
option.

Expected output:
* Project
** Task2
*** ASK Something to align
Something for discussion
** Task4
*** ASK Something else to align
Something else.

Current options, though, either require manual expansion to show both
ancestors AND entry, which becomes tedious soon;

* Project
** Task2
*** ASK Something to align
** Task4
*** ASK Something else to align

or it shows extra contents (`local' will include the *next* heading, in
this example, the non-related Task3)

* Project
*** ASK Something to align
Something for discussion
** Task3
*** ASK Something else to align
Something else.

`ancestor-with-entries' is a long name that pose some difficulties to
updating documentations, so I wish to have some feedbacks before moving
on. Is there better way to achieve this effect? Am I overlooking
something?

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, Size: 1935 bytes --]

From 38703eace6062ec4e4ccdf1912a641b266efbf61 Mon Sep 17 00:00:00 2001
From: Cheong Yiu Fung <cheongyiufung@gmail.com>
Date: Fri, 16 Apr 2021 18:35:17 +0800
Subject: [PATCH] org.el (org-show-context-detail): add option
 'ancestors-with-entry

* lisp/org.el: Add option 'ancestors-with-entry to
`org-show-context-detail', which shows current headline, entry, and
its direct ancestors.
---
 lisp/org.el | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 675a614e2..0e625d9ed 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -1240,6 +1240,7 @@ more context."
 			   (const minimal)
 			   (const local)
 			   (const ancestors)
+                           (const ancestors-with-entry)
 			   (const lineage)
 			   (const tree)
 			   (const canonical))))))
@@ -6763,7 +6764,7 @@ DETAIL is either nil, `minimal', `local', `ancestors', `lineage',
 information."
   ;; Show current heading and possibly its entry, following headline
   ;; or all children.
-  (if (and (org-at-heading-p) (not (eq detail 'local)))
+  (if (and (org-at-heading-p) (not (memq detail '(local ancestors-with-entry))))
       (org-flag-heading nil)
     (org-show-entry)
     ;; If point is hidden within a drawer or a block, make sure to
@@ -6775,14 +6776,14 @@ information."
       (org-with-limited-levels
        (cl-case detail
 	 ((tree canonical t) (org-show-children))
-	 ((nil minimal ancestors))
+	 ((nil minimal ancestors ancestors-with-entry))
 	 (t (save-excursion
 	      (outline-next-heading)
 	      (org-flag-heading nil)))))))
   ;; 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-with-entry lineage tree canonical t))
     (save-excursion
       (while (org-up-heading-safe)
 	(org-flag-heading nil)
-- 
2.31.0

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

[Nicolas Goaziou]

Hello,

Cheong Yiu Fung <mail@yiufung.net> writes:

> Hi, I'm proposing a new option in `org-show-context-detail', which shows
> current headline, its ancestors, *and the entry itself*. This is useful
> when export matched subtrees and their contents quickly with least
> manual intervention.
>
> Consider when working on different aspects of a project and taking notes
> as we go:
>
> * Project
> A project tree
> ** Task1
> ** Task2
> *** ASK Something to align
> Something for discussion
> ** Task3
> ** Task4
> *** ASK Something else to align
> Something else.
>
> At some point, we may wish to export only certain contents. For example,
> to export headings with TODO keyword of "ASK", along with the task
> context (ancestors TASK<N> heading name), and their own content for
> discussion with colleagues. Ideally, this can be done by
> org-sparse-tree, followed by org-export with visible-only + subtree-only
> option.
>
> Expected output:
> * Project
> ** Task2
> *** ASK Something to align
> Something for discussion
> ** Task4
> *** ASK Something else to align
> Something else.
>
> Current options, though, either require manual expansion to show both
> ancestors AND entry, which becomes tedious soon;
>
> * Project
> ** Task2
> *** ASK Something to align
> ** Task4
> *** ASK Something else to align
>
> or it shows extra contents (`local' will include the *next* heading, in
> this example, the non-related Task3)
>
> * Project
> *** ASK Something to align
> Something for discussion
> ** Task3
> *** ASK Something else to align
> Something else.
>
> `ancestor-with-entries' is a long name that pose some difficulties to
> updating documentations, so I wish to have some feedbacks before moving
> on. Is there better way to achieve this effect? Am I overlooking
> something?

Don't you need to simply move point within the entry and use `ancestors'
view?

Regards,
-- 
Nicolas Goaziou

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

[Cheong Yiu Fung]

Hi Nicolas, 

> Don't you need to simply move point within the entry and use `ancestors'
> view?

Yes, but that would work only for one entry. My main use case is to first filter tree by `org-sparse-tree', then export all filtered contents with `visible-only' option. If I am to use `ancestors' view and move point within each entry one by one to expand, it would be very repetitive. I think this is helpful for generating HTML page or PDF from matching query quickly. 

Yiufung

On Mon, Apr 19, 2021, at 4:21 PM, Nicolas Goaziou wrote:
> Hello,
> 
> Cheong Yiu Fung <mail@yiufung.net> writes:
> 
> > Hi, I'm proposing a new option in `org-show-context-detail', which shows
> > current headline, its ancestors, *and the entry itself*. This is useful
> > when export matched subtrees and their contents quickly with least
> > manual intervention.
> >
> > Consider when working on different aspects of a project and taking notes
> > as we go:
> >
> > * Project
> > A project tree
> > ** Task1
> > ** Task2
> > *** ASK Something to align
> > Something for discussion
> > ** Task3
> > ** Task4
> > *** ASK Something else to align
> > Something else.
> >
> > At some point, we may wish to export only certain contents. For example,
> > to export headings with TODO keyword of "ASK", along with the task
> > context (ancestors TASK<N> heading name), and their own content for
> > discussion with colleagues. Ideally, this can be done by
> > org-sparse-tree, followed by org-export with visible-only + subtree-only
> > option.
> >
> > Expected output:
> > * Project
> > ** Task2
> > *** ASK Something to align
> > Something for discussion
> > ** Task4
> > *** ASK Something else to align
> > Something else.
> >
> > Current options, though, either require manual expansion to show both
> > ancestors AND entry, which becomes tedious soon;
> >
> > * Project
> > ** Task2
> > *** ASK Something to align
> > ** Task4
> > *** ASK Something else to align
> >
> > or it shows extra contents (`local' will include the *next* heading, in
> > this example, the non-related Task3)
> >
> > * Project
> > *** ASK Something to align
> > Something for discussion
> > ** Task3
> > *** ASK Something else to align
> > Something else.
> >
> > `ancestor-with-entries' is a long name that pose some difficulties to
> > updating documentations, so I wish to have some feedbacks before moving
> > on. Is there better way to achieve this effect? Am I overlooking
> > something?
> 
> Don't you need to simply move point within the entry and use `ancestors'
> view?
> 
> Regards,
> -- 
> Nicolas Goaziou
> 

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

[Nicolas Goaziou]

Hello,

"Cheong Yiu Fung" <mail@yiufung.net> writes:

> Yes, but that would work only for one entry. My main use case is to
> first filter tree by `org-sparse-tree', then export all filtered
> contents with `visible-only' option. If I am to use `ancestors' view
> and move point within each entry one by one to expand, it would be
> very repetitive. I think this is helpful for generating HTML page or
> PDF from matching query quickly.

OK. Then what about a shorter `ancestors-full'?

Also, could you provide tests for it in `test-org/show-set-visibility'?

Regards,
-- 
Nicolas Goaziou

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

[Cheong Yiu Fung]

Hi, 

> OK. Then what about a shorter `ancestors-full'?

That sounds better, I will use this one. 

> Also, could you provide tests for it in `test-org/show-set-visibility'?

Sure, I'll see how to do it and submit a patch later. 

Yiufung

On Tue, Apr 20, 2021, at 9:15 PM, Nicolas Goaziou wrote:
> Hello,
> 
> "Cheong Yiu Fung" <mail@yiufung.net> writes:
> 
> > Yes, but that would work only for one entry. My main use case is to
> > first filter tree by `org-sparse-tree', then export all filtered
> > contents with `visible-only' option. If I am to use `ancestors' view
> > and move point within each entry one by one to expand, it would be
> > very repetitive. I think this is helpful for generating HTML page or
> > PDF from matching query quickly.
> 
> OK. Then what about a shorter `ancestors-full'?
> 
> Also, could you provide tests for it in `test-org/show-set-visibility'?
> 
> Regards,
> -- 
> Nicolas Goaziou
> 

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

[Cheong Yiu Fung]

[-- 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

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

[Cheong Yiu Fung]

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

Hi Nicolas,

On Wed, Apr 21, 2021, at 5:15 PM, Cheong Yiu Fung wrote:
> 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. 

I would like to rescind my previous comments. It's awkward for me to realize I do have a
lot of ancestor text that I do not wish to be exported.

Please ignore patches in the previous message and use the latest ones attached. Thanks!

Yiufung

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 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 203364db88d25e5aea4cf295584617757c18591c 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


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #3: 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: 3562 bytes --]

From ad1611831535a602c1d4b0bd8c92fea2ddde0551 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              | 15 ++++++++++-----
 testing/lisp/test-org.el |  4 ++++
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 675a614e2..ac006eb6d 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -1199,6 +1199,8 @@ 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 subtree and its direct ancestors
+
   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 +1242,7 @@ more context."
 			   (const minimal)
 			   (const local)
 			   (const ancestors)
+                           (const ancestors-full)
 			   (const lineage)
 			   (const tree)
 			   (const canonical))))))
@@ -6758,9 +6761,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,14 +6778,16 @@ 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)
diff --git a/testing/lisp/test-org.el b/testing/lisp/test-org.el
index f6fb4b3ca..47732dfa3 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 7 8 9 10 11)
+                   (funcall list-visible-lines 'ancestors-full t)))
+    (should (equal '(0 3 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

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

[Nicolas Goaziou]

Hello,

"Cheong Yiu Fung" <mail@yiufung.net> writes:

> Subject: [PATCH 2/2] org-manual.org: add hints for visible-only export

Thanks. Some comments follow.

> +  particular headings.  See also the variable
> +  ~org-show-context-detail~ and the command ~org-sparse-tree~.

I would say

  See also [[*Sparse Trees]].

The ~org-show-context-detail~ variable is mentioned there anyway.

> +  ancestors-full show current subtree and its direct ancestors

IIUC, it seems to be current subtree, its direct ancestors along with
their contents. But see below.

> +    (should (equal '(0 3 7 8 9 10 11)
> +                   (funcall list-visible-lines 'ancestors-full t)))
> +    (should (equal '(0 3 7 8 9 10 11)
> +                   (funcall list-visible-lines 'ancestors-full nil)))

Are you sure you want to display line 10? No other visibility does that.

Regards,
-- 
Nicolas Goaziou

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

[Cheong Yiu Fung]

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

Hi,

On Thu, Apr 22, 2021, at 9:32 PM, Nicolas Goaziou wrote:
> I would say
> 
>   See also [[*Sparse Trees]].
> 
> The ~org-show-context-detail~ variable is mentioned there anyway.

I agree. A new patch for docs is attached. 

> > +  ancestors-full show current subtree and its direct ancestors
> 
> IIUC, it seems to be current subtree, its direct ancestors along with
> their contents. But see below.

Current subtree means everything under it: heading + entry + children.  They
are shown. 

Regarding its ancestors: Only headings are shown. Contents of ancestors are *not*
to be shown.  

> > +    (should (equal '(0 3 7 8 9 10 11)
> > +                   (funcall list-visible-lines 'ancestors-full t)))
> > +    (should (equal '(0 3 7 8 9 10 11)
> > +                   (funcall list-visible-lines 'ancestors-full nil)))
> 
> Are you sure you want to display line 10? No other visibility does that.

Yes, that is the main purpose. The idea is to show the whole subtree (what "full" would
mean). So, whether target is in Self(7) or Match(8), 7-11 should all be shown. This is to
facilitate using tag or TODO keyword to choose what tree to be shown.

Yiufung

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

From 5fdbffd88f573f132ace4bae2f1665e325bca3a4 Mon Sep 17 00:00:00 2001
From: Cheong Yiu Fung <mail@yiufung.net>
Date: Thu, 22 Apr 2021 23:25:03 +0800
Subject: [PATCH] org-manual.org: add hints for visible-only export

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

diff --git a/doc/org-manual.org b/doc/org-manual.org
index e809ecadb..74a7c735a 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -11524,7 +11524,7 @@ 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 [[*Sparse Trees]].
 
 ** Export Settings
 :PROPERTIES:
-- 
2.31.0

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

[Nicolas Goaziou]

Hello,

"Cheong Yiu Fung" <mail@yiufung.net> writes:
> Subject: [PATCH] org-manual.org: add hints for visible-only export

I tweaked your commit messages and applied your patches.

Thank you.

Regards,
-- 
Nicolas Goaziou