[RFC] Simplify `org-show-context' configuration

[RFC] Simplify `org-show-context' configuration

[Nicolas Goaziou]

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

Hello,

As explained in its commit message, the following patch is an attempt at
simplifying `org-show-context' configuration by offering a set of
5 predefined views to choose from instead of setting 4 different
variables (`org-show-following-heading', `org-show-siblings',
`org-show-entry-below' and `org-show-hierarchy-above'). These views are

  minimal        show current headline, and entry below if needed
  local          show current headline, entry below and next headline
  lineage        show direct ancestors and all siblings of current headline;
                 show entry only if required
  canonical      show direct ancestors and all of their siblings; show entry
                 only if required
  full           show direct ancestors, all their siblings and entry

To sum it up, if original buffer is

  * H1
  * H2
  ** Sub 1
  ** Sub 2
  *** Sub sub 1
  *** Sub sub 2
      Text
  *** Sub sub 3
  *** Sub sub 4
  ** Sub 3

and match is on "Text", minimal is

  * H1
  * H2
    * Sub sub 2
      Text

`local' is

  * H1
  * H2
  *** Sub sub 2
      Text
  *** Sub sub 3

`lineage' is

  * H1
  * H2
  ** Sub 2
  *** Sub sub 1
  *** Sub sub 2
      Text
  *** Sub sub 3
  *** Sub sub 4

`canonical' and `full' are

  * H1
  * H2
  ** Sub 1
  ** Sub 2
  *** Sub sub 1
  *** Sub sub 2
      Text
  *** Sub sub 3
  *** Sub sub 4
  ** Sub 3

Note that neither `canonical' nor `full' are possible to obtain with the
4 original variables.

"if required"/"if needed" means the entry will only be shown if point is
within the entry (i.e., not on the headline). Thus, for example,
`canonical' and `full' only differ when match is on a headline, since
only latter will show the entry.

I think this is enough, but I can add more views if needed.

WDYT?


Regards,

-- 
Nicolas Goaziou                                                0x80A93738

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Simplify-org-show-context-configuration.patch --]
[-- Type: text/x-diff, Size: 12971 bytes --]

From c04351a77a7d3af99d292f71e33d43f7e72410d2 Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Date: Mon, 16 Feb 2015 21:43:35 +0100
Subject: [PATCH] Simplify `org-show-context' configuration

* lisp/org.el (org-show-context-detail): New variable.
(org-context-choice, org-show-following-heading, org-show-siblings,
org-show-entry-below, org-show-hierarchy-above): Remove variables.
(org-show-set-visibility): New function.
(org-get-location, org-show-context, org-reveal): Use new function.
(org-link-search): Update docstring.

* lisp/org-agenda.el (org-agenda-cycle-show): Use new function.

Configuration of `org-show-context' is done with a single variable
offering five different views, instead of four variables for a total
of 16 configurations.
---
 lisp/org-agenda.el |  15 ++---
 lisp/org.el        | 190 ++++++++++++++++++++++-------------------------------
 2 files changed, 86 insertions(+), 119 deletions(-)

diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index 9f2d9d1..f7406d7 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -8696,11 +8696,12 @@ if it was hidden in the outline."
 (defvar org-agenda-cycle-counter nil)
 (defun org-agenda-cycle-show (&optional n)
   "Show the current entry in another window, with default settings.
-Default settings are taken from `org-show-hierarchy-above' and siblings.
-When use repeatedly in immediate succession, the remote entry will cycle
-through visibility
 
-children -> subtree -> folded
+Default settings are taken from `org-show-context-detail'.  When
+use repeatedly in immediate succession, the remote entry will
+cycle through visibility
+
+  children -> subtree -> folded
 
 When called with a numeric prefix arg, that arg will be passed through to
 `org-agenda-show-1'.  For the interpretation of that argument, see the
@@ -9521,11 +9522,7 @@ a timestamp can be added there."
     (unless (bolp) (insert "\n"))
     (unless (org-looking-at-p "^[ \t]*$") (save-excursion (insert "\n")))
     (when org-adapt-indentation (org-indent-to-column col)))
-  (let ((org-show-following-heading t)
-	(org-show-siblings t)
-	(org-show-hierarchy-above t)
-	(org-show-entry-below t))
-    (org-show-context)))
+  (org-show-set-visibility 'canonical))
 
 (defun org-agenda-diary-entry ()
   "Make a diary entry, like the `i' command from the calendar.
diff --git a/lisp/org.el b/lisp/org.el
index 4f047b2..bbabb9a 100755
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -1165,87 +1165,67 @@ effective."
   :tag "Org Reveal Location"
   :group 'org-structure)
 
-(defconst org-context-choice
-  '(choice
-    (const :tag "Always" t)
-    (const :tag "Never" nil)
-    (repeat :greedy t :tag "Individual contexts"
-	    (cons
-	     (choice :tag "Context"
-		     (const agenda)
-		     (const org-goto)
-		     (const occur-tree)
-		     (const tags-tree)
-		     (const link-search)
-		     (const mark-goto)
-		     (const bookmark-jump)
-		     (const isearch)
-		     (const default))
-	     (boolean))))
-  "Contexts for the reveal options.")
-
-(defcustom org-show-hierarchy-above '((default . t))
-  "Non-nil means show full hierarchy when revealing a location.
-Org-mode often shows locations in an org-mode file which might have
-been invisible before.  When this is set, the hierarchy of headings
-above the exposed location is shown.
-Turning this off for example for sparse trees makes them very compact.
-Instead of t, this can also be an alist specifying this option for different
-contexts.  Valid contexts are
+(defcustom org-show-context-detail '((isearch . canonical)
+				     (bookmark-jump . canonical)
+				     (default . lineage))
+  "Alist between context and visibility span when revealing a location.
+
+\\<org-mode-map>Some actions may move point into invisible
+locations.  As a consequence, Org always expose a neighborhood
+around point.  How much is shown depends on the initial action,
+or context.  Valid contexts are
+
   agenda         when exposing an entry from the agenda
-  org-goto       when using the command `org-goto' on key C-c C-j
-  occur-tree     when using the command `org-occur' on key C-c /
+  org-goto       when using the command `org-goto' (\\[org-goto])
+  occur-tree     when using the command `org-occur' (\\[org-sparse-tree] /)
   tags-tree      when constructing a sparse tree based on tags matches
   link-search    when exposing search matches associated with a link
   mark-goto      when exposing the jump goal of a mark
   bookmark-jump  when exposing a bookmark location
   isearch        when exiting from an incremental search
-  default        default for all contexts not set explicitly"
-  :group 'org-reveal-location
-  :type org-context-choice)
-
-(defcustom org-show-following-heading '((default . nil))
-  "Non-nil means show following heading when revealing a location.
-Org-mode often shows locations in an org-mode file which might have
-been invisible before.  When this is set, the heading following the
-match is shown.
-Turning this off for example for sparse trees makes them very compact,
-but makes it harder to edit the location of the match.  In such a case,
-use the command \\[org-reveal] to show more context.
-Instead of t, this can also be an alist specifying this option for different
-contexts.  See `org-show-hierarchy-above' for valid contexts."
-  :group 'org-reveal-location
-  :type org-context-choice)
-
-(defcustom org-show-siblings '((default . nil) (isearch t) (bookmark-jump t))
-  "Non-nil means show all sibling heading when revealing a location.
-Org-mode often shows locations in an org-mode file which might have
-been invisible before.  When this is set, the sibling of the current entry
-heading are all made visible.  If `org-show-hierarchy-above' is t,
-the same happens on each level of the hierarchy above the current entry.
-
-By default this is on for the isearch context, off for all other contexts.
-Turning this off for example for sparse trees makes them very compact,
-but makes it harder to edit the location of the match.  In such a case,
-use the command \\[org-reveal] to show more context.
-Instead of t, this can also be an alist specifying this option for different
-contexts.  See `org-show-hierarchy-above' for valid contexts."
-  :group 'org-reveal-location
-  :type org-context-choice
-  :version "24.4"
-  :package-version '(Org . "8.0"))
+  default        default for all contexts not set explicitly
+
+Allowed visibility spans are
 
-(defcustom org-show-entry-below '((default . nil))
-  "Non-nil means show the entry below a headline when revealing a location.
-Org-mode often shows locations in an org-mode file which might have
-been invisible before.  When this is set, the text below the headline that is
-exposed is also shown.
+  minimal        show current headline, and entry below if needed
+  local          show current headline, entry below and next headline
+  lineage        show direct ancestors and all siblings of current headline;
+                 show entry only if required
+  canonical      show direct ancestors and all of their siblings; show entry
+                 only if required
+  full           show direct ancestors, all their siblings and entry
 
-By default this is off for all contexts.
-Instead of t, this can also be an alist specifying this option for different
-contexts.  See `org-show-hierarchy-above' for valid contexts."
+As a special case, a nil (respectively t) value means
+`minimal' (respectively `full') detail level for all contexts.
+
+`minimal', `local' and, to a lesser extent `lineage', can make
+displayed information very compact, but also make it harder to
+edit the location of the match.  In such a case, use the command
+`org-reveal' (\\[org-reveal]) to show more context."
   :group 'org-reveal-location
-  :type org-context-choice)
+  :version "25.1"
+  :package-version '(Org . "8.3")
+  :type '(choice
+	  (const :tag "Full" t)
+	  (const :tag "Minimal" nil)
+	  (repeat :greedy t :tag "Individual contexts"
+		  (cons
+		   (choice :tag "Context"
+			   (const agenda)
+			   (const org-goto)
+			   (const occur-tree)
+			   (const tags-tree)
+			   (const link-search)
+			   (const mark-goto)
+			   (const bookmark-jump)
+			   (const isearch)
+			   (const default))
+		   (choice :tag "Detail level"
+			   (cons minimal)
+			   (cons local)
+			   (cons lineage)
+			   (cons canonical)
+			   (cons full))))))
 
 (defcustom org-indirect-buffer-display 'other-window
   "How should indirect tree buffers be displayed?
@@ -7522,11 +7502,8 @@ or nil."
 	 (setq buffer-read-only t)
 	 (if (and (boundp 'org-goto-start-pos)
 		  (integer-or-marker-p org-goto-start-pos))
-	     (let ((org-show-hierarchy-above t)
-		   (org-show-siblings t)
-		   (org-show-following-heading t))
-	       (goto-char org-goto-start-pos)
-	       (and (outline-invisible-p) (org-show-context)))
+	     (progn (goto-char org-goto-start-pos)
+		    (when (outline-invisible-p) (org-show-set-visibility t)))
 	   (goto-char (point-min)))
 	 (let (org-special-ctrl-a/e) (org-beginning-of-line))
 	 (message "Select location and press RET")
@@ -11002,9 +10979,8 @@ If the current buffer is in `dired-mode', grep will be used to search
 in all files.  If AVOID-POS is given, ignore matches near that position.
 
 When optional argument STEALTH is non-nil, do not modify
-visibility around point, thus ignoring
-`org-show-hierarchy-above', `org-show-following-heading' and
-`org-show-siblings' variables."
+visibility around point, thus ignoring `org-show-context-detail'
+variable."
   (let ((case-fold-search t)
 	(s0 (mapconcat 'identity (org-split-string s "[ \t\r\n]+") " "))
 	(markers (concat "\\(?:" (mapconcat (lambda (x) (regexp-quote (car x)))
@@ -13929,41 +13905,38 @@ starting point when no match is found."
 
 (defun org-show-context (&optional key)
   "Make sure point and context are visible.
-How much context is shown depends upon the variables
-`org-show-hierarchy-above', `org-show-following-heading',
-`org-show-entry-below' and `org-show-siblings'."
-  (let ((heading-p   (org-at-heading-p t))
-	(hierarchy-p (org-get-alist-option org-show-hierarchy-above key))
-	(following-p (org-get-alist-option org-show-following-heading key))
-	(entry-p     (org-get-alist-option org-show-entry-below key))
-	(siblings-p  (org-get-alist-option org-show-siblings key)))
-    ;; Show heading or entry text
-    (if (and heading-p (not entry-p))
-	(org-flag-heading nil)    ; only show the heading
-      (and (or entry-p (outline-invisible-p) (org-invisible-p2))
-	   (org-show-hidden-entry)))    ; show entire entry
-    (when following-p
-      ;; Show next sibling, or heading below text
+How much context is shown depends upon the variable
+`org-show-context-detail', which see."
+  (org-show-set-visibility (org-get-alist-option org-show-context-detail key)))
+
+(defun org-show-set-visibility (detail)
+  "Set visibility around point according to DETAIL.
+DETAIL is either nil, `minimal', `local', `lineage', `canonical'
+and `full'.  See `org-show-context-detail' for more information."
+  (let ((headingp (org-at-heading-p)))
+    (when headingp (org-flag-heading nil))
+    (when (or (not headingp) (memq detail '(full local)))
+      (org-show-entry))
+    (when (eq detail 'local)
       (save-excursion
-	(and (if heading-p (org-goto-sibling) (outline-next-heading))
-	     (org-flag-heading nil))))
-    (when siblings-p (org-show-siblings))
-    (when hierarchy-p
-      ;; show all higher headings, possibly with siblings
+	(outline-next-heading)
+	(org-flag-heading nil)))
+    (when (memq detail '(lineage canonical full t))
+      (org-show-siblings)
       (save-excursion
-	(while (and (ignore-errors (progn (org-up-heading-all 1) t))
-		    (not (bobp)))
+	(while (org-up-heading-safe)
 	  (org-flag-heading nil)
-	  (when siblings-p (org-show-siblings)))))))
+	  (when (memq detail '(canonical full t))
+	    (org-show-siblings)))))))
 
 (defvar org-reveal-start-hook nil
   "Hook run before revealing a location.")
 
 (defun org-reveal (&optional siblings)
   "Show current entry, hierarchy above it, and the following headline.
-This can be used to show a consistent set of context around locations
-exposed with `org-show-hierarchy-above' or `org-show-following-heading'
-not t for the search context.
+
+This can be used to show a consistent set of context around
+locations exposed with `org-show-context'.
 
 With optional argument SIBLINGS, on each level of the hierarchy all
 siblings are shown.  This repairs the tree structure to what it would
@@ -13973,10 +13946,7 @@ go to the parent and show the
 entire tree."
   (interactive "P")
   (run-hooks 'org-reveal-start-hook)
-  (let ((org-show-hierarchy-above t)
-	(org-show-following-heading t)
-	(org-show-siblings (if siblings t org-show-siblings)))
-    (org-show-context nil))
+  (org-show-set-visibility 'lineage)
   (when (equal siblings '(16))
     (save-excursion
       (when (org-up-heading-safe)
-- 
2.3.0

Re: [RFC] Simplify `org-show-context' configuration

[Kyle Meyer]

Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> As explained in its commit message, the following patch is an attempt at
> simplifying `org-show-context' configuration by offering a set of
> 5 predefined views to choose from instead of setting 4 different
> variables (`org-show-following-heading', `org-show-siblings',
> `org-show-entry-below' and `org-show-hierarchy-above'). These views are
>
>   minimal        show current headline, and entry below if needed
>   local          show current headline, entry below and next headline
>   lineage        show direct ancestors and all siblings of current headline;
>                  show entry only if required
>   canonical      show direct ancestors and all of their siblings; show entry
>                  only if required
>   full           show direct ancestors, all their siblings and entry
[...]
>
> I think this is enough, but I can add more views if needed.
>
> WDYT?

I prefer this to the old setup.  From a configuration standpoint, it's
much nicer to have all the relevant information in one variable.

[...]
> +As a special case, a nil (respectively t) value means
> +`minimal' (respectively `full') detail level for all contexts.

Minor: It took me some extra effort to parse this sentence because I'm
not used to seeing 'respectively' used in this way.  I think something
like below is more common.

  As special cases, a nil or t value means show all contexts in
  `minimal' or `full' view, respectively.

[...]
>  (defun org-reveal (&optional siblings)
>    "Show current entry, hierarchy above it, and the following headline.
> -This can be used to show a consistent set of context around locations
> -exposed with `org-show-hierarchy-above' or `org-show-following-heading'
> -not t for the search context.
> +
> +This can be used to show a consistent set of context around
> +locations exposed with `org-show-context'.
>
>  With optional argument SIBLINGS, on each level of the hierarchy all
>  siblings are shown.  This repairs the tree structure to what it would

Does a single C-u serve a purpose anymore?

--
Kyle

Re: [RFC] Simplify `org-show-context' configuration

[Nicolas Goaziou]

Kyle Meyer <kyle@kyleam.com> writes:

Thanks for the feedback.

> Minor: It took me some extra effort to parse this sentence because I'm
> not used to seeing 'respectively' used in this way.  I think something
> like below is more common.
>
>   As special cases, a nil or t value means show all contexts in
>   `minimal' or `full' view, respectively.

Updated. Thank you.

>>  (defun org-reveal (&optional siblings)
>>    "Show current entry, hierarchy above it, and the following headline.
>> -This can be used to show a consistent set of context around locations
>> -exposed with `org-show-hierarchy-above' or `org-show-following-heading'
>> -not t for the search context.
>> +
>> +This can be used to show a consistent set of context around
>> +locations exposed with `org-show-context'.
>>
>>  With optional argument SIBLINGS, on each level of the hierarchy all
>>  siblings are shown.  This repairs the tree structure to what it would
>
> Does a single C-u serve a purpose anymore?

Without it, it is `lineage' view. With it, it is `canonical' (but
I forgot to update it). I'm not sure we need the distinction however.

Also, I'm not sure how useful double C-u is.


Regards,

Re: [RFC] Simplify `org-show-context' configuration

[Sebastien Vauban]

Hello Nicolas,

Nicolas Goaziou wrote:
> As explained in its commit message, the following patch is an attempt at
> simplifying `org-show-context' configuration by offering a set of
> 5 predefined views to choose from instead of setting 4 different
> variables (`org-show-following-heading', `org-show-siblings',
> `org-show-entry-below' and `org-show-hierarchy-above'). These views are
>
>   minimal        show current headline, and entry below if needed
>   local          show current headline, entry below and next headline
>   lineage        show direct ancestors and all siblings of current headline;
>                  show entry only if required
>   canonical      show direct ancestors and all of their siblings; show entry
>                  only if required
>   full           show direct ancestors, all their siblings and entry
>
> To sum it up, if original buffer is
>
>   * H1
>   * H2
>   ** Sub 1
>   ** Sub 2
>   *** Sub sub 1
>   *** Sub sub 2
>       Text
>   *** Sub sub 3
>   *** Sub sub 4
>   ** Sub 3
>
> and match is on "Text", minimal is
>
>   * H1
>   * H2
>     * Sub sub 2
>       Text
>
> `local' is
>
>   * H1
>   * H2
>   *** Sub sub 2
>       Text
>   *** Sub sub 3
>
> `lineage' is
>
>   * H1
>   * H2
>   ** Sub 2
>   *** Sub sub 1
>   *** Sub sub 2
>       Text
>   *** Sub sub 3
>   *** Sub sub 4
>
> `canonical' and `full' are
>
>   * H1
>   * H2
>   ** Sub 1
>   ** Sub 2
>   *** Sub sub 1
>   *** Sub sub 2
>       Text
>   *** Sub sub 3
>   *** Sub sub 4
>   ** Sub 3
>
> Note that neither `canonical' nor `full' are possible to obtain with the
> 4 original variables.

Question: are the level-1 headlines always visible, all of them I mean?
I know that's the case as of now, but wondered if it'd be good to hide
the ones which are not significant.  Not a very sharp advice on this,
though.

> "if required"/"if needed" means the entry will only be shown if point is
> within the entry (i.e., not on the headline). Thus, for example,
> `canonical' and `full' only differ when match is on a headline, since
> only latter will show the entry.
>
> I think this is enough, but I can add more views if needed.
>
> WDYT?

My /personal/ preference is to see the ancestors, so that I can know
which path lead to the entry, and avoid confusion in case some "sub sub
sections" are repeated in many different "sub sections".

With your proposal, I then only have the choice between `lineage',
`full' and `canonical', while I'd like something which would give me:

--8<---------------cut here---------------start------------->8---
  * H1
  * H2
  ** Sub 2
  *** Sub sub 2
      Text
--8<---------------cut here---------------end--------------->8---

WDYT?

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [RFC] Simplify `org-show-context' configuration

[Nicolas Goaziou]

Sebastien Vauban <sva-news-D0wtAvR13HarG/iDocfnWg@public.gmane.org>
writes:

> Question: are the level-1 headlines always visible, all of them I mean?
> I know that's the case as of now, but wondered if it'd be good to hide
> the ones which are not significant.  Not a very sharp advice on this,
> though.

I have no strong opinion about this, but I think it would be odd if they
were invisible. After all, this is the basic structure of the document.

>> "if required"/"if needed" means the entry will only be shown if point is
>> within the entry (i.e., not on the headline). Thus, for example,
>> `canonical' and `full' only differ when match is on a headline, since
>> only latter will show the entry.
>>
>> I think this is enough, but I can add more views if needed.
>>
>> WDYT?
>
> My /personal/ preference is to see the ancestors, so that I can know
> which path lead to the entry, and avoid confusion in case some "sub sub
> sections" are repeated in many different "sub sections".
>
> With your proposal, I then only have the choice between `lineage',
> `full' and `canonical', while I'd like something which would give me:
>
>   * H1 * H2 ** Sub 2 *** Sub sub 2 Text
>
> WDYT?

I can add `ancestors' view, which would basically be `lineage' without
siblings.


Regards,

Re: [RFC] Simplify `org-show-context' configuration

[Sebastien Vauban]

Nicolas Goaziou wrote:
> Sebastien Vauban writes:
>
>> Question: are the level-1 headlines always visible, all of them
>> I mean?  I know that's the case as of now, but wondered if it'd be
>> good to hide the ones which are not significant.  Not a very sharp
>> advice on this, though.
>
> I have no strong opinion about this, but I think it would be odd if
> they were invisible. After all, this is the basic structure of the
> document.

Yes, that's why I'm not so pushy about it. OTOH, it's nice to hide them
when you have a lot of level-1 sections -- I remember that being asked
here by someone.

But, once again, for me, it's not that important.

>>> "if required"/"if needed" means the entry will only be shown if
>>> point is within the entry (i.e., not on the headline). Thus, for
>>> example, `canonical' and `full' only differ when match is on
>>> a headline, since only latter will show the entry.
>>>
>>> I think this is enough, but I can add more views if needed.
>>>
>>> WDYT?
>>
>> My /personal/ preference is to see the ancestors, so that I can know
>> which path lead to the entry, and avoid confusion in case some "sub
>> sub sections" are repeated in many different "sub sections".
>>
>> With your proposal, I then only have the choice between `lineage',
>> `full' and `canonical', while I'd like something which would give me:
>>
>>   * H1
>>   * H2
>>   ** Sub 2
>>   *** Sub sub 2
>>       Text
>>
>> WDYT?
>
> I can add `ancestors' view, which would basically be `lineage' without
> siblings.

That'd certainly be good -- and match my current Org config.

And, if I may, to be sure we are somehow "symmetrical", it'd be good to
have as well:

--8<---------------cut here---------------start------------->8---
     * H1
     * H2
     ** Sub 2
     *** Sub sub 1
     *** Sub sub 2
         Text
     *** Sub sub 3
     *** Sub sub 4
--8<---------------cut here---------------end--------------->8---

That is "ancestors" + the siblings of the leaf entry.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [RFC] Simplify `org-show-context' configuration

[Eric Abrahamsen]

Sebastien Vauban <sva-news@mygooglest.com>
writes:

> Nicolas Goaziou wrote:
>> Sebastien Vauban writes:
>>
>>> Question: are the level-1 headlines always visible, all of them
>>> I mean?  I know that's the case as of now, but wondered if it'd be
>>> good to hide the ones which are not significant.  Not a very sharp
>>> advice on this, though.
>>
>> I have no strong opinion about this, but I think it would be odd if
>> they were invisible. After all, this is the basic structure of the
>> document.
>
> Yes, that's why I'm not so pushy about it. OTOH, it's nice to hide them
> when you have a lot of level-1 sections -- I remember that being asked
> here by someone.
>
> But, once again, for me, it's not that important.

I'd prefer not to do that -- it's easy to get confused, and we've got
narrowing when we need to really focus.

>>>> "if required"/"if needed" means the entry will only be shown if
>>>> point is within the entry (i.e., not on the headline). Thus, for
>>>> example, `canonical' and `full' only differ when match is on
>>>> a headline, since only latter will show the entry.
>>>>
>>>> I think this is enough, but I can add more views if needed.
>>>>
>>>> WDYT?
>>>
>>> My /personal/ preference is to see the ancestors, so that I can know
>>> which path lead to the entry, and avoid confusion in case some "sub
>>> sub sections" are repeated in many different "sub sections".
>>>
>>> With your proposal, I then only have the choice between `lineage',
>>> `full' and `canonical', while I'd like something which would give me:
>>>
>>>   * H1
>>>   * H2
>>>   ** Sub 2
>>>   *** Sub sub 2
>>>       Text
>>>
>>> WDYT?
>>
>> I can add `ancestors' view, which would basically be `lineage' without
>> siblings.
>
> That'd certainly be good -- and match my current Org config.
>
> And, if I may, to be sure we are somehow "symmetrical", it'd be good to
> have as well:
>
>      * H1
>      * H2
>      ** Sub 2
>      *** Sub sub 1
>      *** Sub sub 2
>          Text
>      *** Sub sub 3
>      *** Sub sub 4
>
> That is "ancestors" + the siblings of the leaf entry.

This is the view I'd be interested in having, as well.

Thanks!
Eric

Re: [RFC] Simplify `org-show-context' configuration

[Sebastien Vauban]

Eric Abrahamsen wrote:
> Sebastien Vauban writes:
>> Nicolas Goaziou wrote:
>>> Sebastien Vauban writes:
>>>
>>>> Question: are the level-1 headlines always visible, all of them
>>>> I mean?  I know that's the case as of now, but wondered if it'd be
>>>> good to hide the ones which are not significant.  Not a very sharp
>>>> advice on this, though.
>>>
>>> I have no strong opinion about this, but I think it would be odd if
>>> they were invisible. After all, this is the basic structure of the
>>> document.
>>
>> Yes, that's why I'm not so pushy about it. OTOH, it's nice to hide them
>> when you have a lot of level-1 sections -- I remember that being asked
>> here by someone.
>>
>> But, once again, for me, it's not that important.
>
> I'd prefer not to do that -- it's easy to get confused, and we've got
> narrowing when we need to really focus.

Well, I never said it had to be the only (or default) behavior...  Just
mentioning that some people express that wish, from time to time.

But I won't push for it.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: [RFC] Simplify `org-show-context' configuration

[Nicolas Goaziou]

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

Actually, the first patch didn't pay attention to children, if any, of
the current headline. Here is a new patch, including feedback from Kyle
and Sébastien.

Considering the following buffer, "Text" being the matched location

    * Grandmother
    ** Uncle
    *** Heir
    ** Father
    *** Sister
    *** Self
        Text
    **** First born
         Other text
    **** The other child
    *** Brother
    ** Aunt

`minimal' is

    * Grandmother
    *** Self
        Text

`local' is

    * Grandmother
    *** Self
        Text
    **** First born

`ancestors' is

    * Grandmother
    ** Father
    *** Self
        Text

`lineage' is

    * Grandmother
    ** Father
    *** Sister
    *** Self
        Text
    **** First born
    *** Brother

`canonical' is

    * Grandmother
    ** Uncle
    ** Father
    *** Sister
    *** Self
        Text
    **** First born
    **** The other child
    *** Brother
    ** Aunt

`full' is

    * Grandmother
    ** Uncle
    ** Father
    *** Sister
    *** Self
        Text
    **** First born
         Other text
    **** The other child
    *** Brother
    ** Aunt


Regards,

-- 
Nicolas Goaziou

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Simplify-org-show-context-configuration.patch --]
[-- Type: text/x-diff, Size: 14280 bytes --]

From 7108b6a5fc2332f05979796af734b1d55e7a8172 Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Date: Mon, 16 Feb 2015 21:43:35 +0100
Subject: [PATCH] Simplify `org-show-context' configuration

* lisp/org.el (org-show-context-detail): New variable.
(org-context-choice, org-show-following-heading, org-show-siblings,
org-show-entry-below, org-show-hierarchy-above): Remove variables.
(org-show-set-visibility): New function.
(org-get-location, org-show-context, org-reveal): Use new function.
(org-link-search): Update docstring.

* lisp/org-agenda.el (org-agenda-cycle-show): Use new function.

Configuration of `org-show-context' is done with a single variable
offering six different views, instead of four variables for a total
of 16 configurations.
---
 lisp/org-agenda.el |  15 ++--
 lisp/org.el        | 228 +++++++++++++++++++++++++----------------------------
 2 files changed, 114 insertions(+), 129 deletions(-)

diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index 9f2d9d1..7adf351 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -8696,11 +8696,12 @@ if it was hidden in the outline."
 (defvar org-agenda-cycle-counter nil)
 (defun org-agenda-cycle-show (&optional n)
   "Show the current entry in another window, with default settings.
-Default settings are taken from `org-show-hierarchy-above' and siblings.
-When use repeatedly in immediate succession, the remote entry will cycle
-through visibility
 
-children -> subtree -> folded
+Default settings are taken from `org-show-context-detail'.  When
+use repeatedly in immediate succession, the remote entry will
+cycle through visibility
+
+  children -> subtree -> folded
 
 When called with a numeric prefix arg, that arg will be passed through to
 `org-agenda-show-1'.  For the interpretation of that argument, see the
@@ -9521,11 +9522,7 @@ a timestamp can be added there."
     (unless (bolp) (insert "\n"))
     (unless (org-looking-at-p "^[ \t]*$") (save-excursion (insert "\n")))
     (when org-adapt-indentation (org-indent-to-column col)))
-  (let ((org-show-following-heading t)
-	(org-show-siblings t)
-	(org-show-hierarchy-above t)
-	(org-show-entry-below t))
-    (org-show-context)))
+  (org-show-set-visibility 'lineage))
 
 (defun org-agenda-diary-entry ()
   "Make a diary entry, like the `i' command from the calendar.
diff --git a/lisp/org.el b/lisp/org.el
index 4f047b2..c707ff4 100755
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -1165,87 +1165,72 @@ effective."
   :tag "Org Reveal Location"
   :group 'org-structure)
 
-(defconst org-context-choice
-  '(choice
-    (const :tag "Always" t)
-    (const :tag "Never" nil)
-    (repeat :greedy t :tag "Individual contexts"
-	    (cons
-	     (choice :tag "Context"
-		     (const agenda)
-		     (const org-goto)
-		     (const occur-tree)
-		     (const tags-tree)
-		     (const link-search)
-		     (const mark-goto)
-		     (const bookmark-jump)
-		     (const isearch)
-		     (const default))
-	     (boolean))))
-  "Contexts for the reveal options.")
-
-(defcustom org-show-hierarchy-above '((default . t))
-  "Non-nil means show full hierarchy when revealing a location.
-Org-mode often shows locations in an org-mode file which might have
-been invisible before.  When this is set, the hierarchy of headings
-above the exposed location is shown.
-Turning this off for example for sparse trees makes them very compact.
-Instead of t, this can also be an alist specifying this option for different
-contexts.  Valid contexts are
+(defcustom org-show-context-detail '((isearch . lineage)
+				     (bookmark-jump . lineage)
+				     (default . ancestors))
+  "Alist between context and visibility span when revealing a location.
+
+\\<org-mode-map>Some actions may move point into invisible
+locations.  As a consequence, Org always expose a neighborhood
+around point.  How much is shown depends on the initial action,
+or context.  Valid contexts are
+
   agenda         when exposing an entry from the agenda
-  org-goto       when using the command `org-goto' on key C-c C-j
-  occur-tree     when using the command `org-occur' on key C-c /
+  org-goto       when using the command `org-goto' (\\[org-goto])
+  occur-tree     when using the command `org-occur' (\\[org-sparse-tree] /)
   tags-tree      when constructing a sparse tree based on tags matches
   link-search    when exposing search matches associated with a link
   mark-goto      when exposing the jump goal of a mark
   bookmark-jump  when exposing a bookmark location
   isearch        when exiting from an incremental search
-  default        default for all contexts not set explicitly"
-  :group 'org-reveal-location
-  :type org-context-choice)
-
-(defcustom org-show-following-heading '((default . nil))
-  "Non-nil means show following heading when revealing a location.
-Org-mode often shows locations in an org-mode file which might have
-been invisible before.  When this is set, the heading following the
-match is shown.
-Turning this off for example for sparse trees makes them very compact,
-but makes it harder to edit the location of the match.  In such a case,
-use the command \\[org-reveal] to show more context.
-Instead of t, this can also be an alist specifying this option for different
-contexts.  See `org-show-hierarchy-above' for valid contexts."
-  :group 'org-reveal-location
-  :type org-context-choice)
-
-(defcustom org-show-siblings '((default . nil) (isearch t) (bookmark-jump t))
-  "Non-nil means show all sibling heading when revealing a location.
-Org-mode often shows locations in an org-mode file which might have
-been invisible before.  When this is set, the sibling of the current entry
-heading are all made visible.  If `org-show-hierarchy-above' is t,
-the same happens on each level of the hierarchy above the current entry.
-
-By default this is on for the isearch context, off for all other contexts.
-Turning this off for example for sparse trees makes them very compact,
-but makes it harder to edit the location of the match.  In such a case,
-use the command \\[org-reveal] to show more context.
-Instead of t, this can also be an alist specifying this option for different
-contexts.  See `org-show-hierarchy-above' for valid contexts."
+  default        default for all contexts not set explicitly
+
+Allowed visibility spans are
+
+  minimal        show current headline, and entry below if needed
+  local          show current headline, entry below and next headline
+  ancestors      show direct ancestors of current headline; show entry only
+                 if required
+  lineage        show direct ancestors, all siblings and first child of
+                 current headline; show entry only if required
+  canonical      show current headline, all its children, direct ancestors
+                 and all their siblings; show entry only if required
+  full           show current headline and its whole subtree, all siblings,
+                 all ancestors including their siblings, and entry
+
+As special cases, a nil or t value means show all contexts in
+`minimal' or `full' view, respectively.
+
+`minimal', `local', `ancestors' and, to a lesser extent
+`lineage', can make displayed information very compact, but also
+make it harder to edit the location of the match.  In such
+a case, use the command `org-reveal' (\\[org-reveal]) to show
+more context."
   :group 'org-reveal-location
-  :type org-context-choice
-  :version "24.4"
-  :package-version '(Org . "8.0"))
-
-(defcustom org-show-entry-below '((default . nil))
-  "Non-nil means show the entry below a headline when revealing a location.
-Org-mode often shows locations in an org-mode file which might have
-been invisible before.  When this is set, the text below the headline that is
-exposed is also shown.
-
-By default this is off for all contexts.
-Instead of t, this can also be an alist specifying this option for different
-contexts.  See `org-show-hierarchy-above' for valid contexts."
-  :group 'org-reveal-location
-  :type org-context-choice)
+  :version "25.1"
+  :package-version '(Org . "8.3")
+  :type '(choice
+	  (const :tag "Full" t)
+	  (const :tag "Minimal" nil)
+	  (repeat :greedy t :tag "Individual contexts"
+		  (cons
+		   (choice :tag "Context"
+			   (const agenda)
+			   (const org-goto)
+			   (const occur-tree)
+			   (const tags-tree)
+			   (const link-search)
+			   (const mark-goto)
+			   (const bookmark-jump)
+			   (const isearch)
+			   (const default))
+		   (choice :tag "Detail level"
+			   (const minimal)
+			   (const local)
+			   (const ancestors)
+			   (const lineage)
+			   (const canonical)
+			   (const full))))))
 
 (defcustom org-indirect-buffer-display 'other-window
   "How should indirect tree buffers be displayed?
@@ -7522,11 +7507,9 @@ or nil."
 	 (setq buffer-read-only t)
 	 (if (and (boundp 'org-goto-start-pos)
 		  (integer-or-marker-p org-goto-start-pos))
-	     (let ((org-show-hierarchy-above t)
-		   (org-show-siblings t)
-		   (org-show-following-heading t))
-	       (goto-char org-goto-start-pos)
-	       (and (outline-invisible-p) (org-show-context)))
+	     (progn (goto-char org-goto-start-pos)
+		    (when (outline-invisible-p)
+		      (org-show-set-visibility 'lineage)))
 	   (goto-char (point-min)))
 	 (let (org-special-ctrl-a/e) (org-beginning-of-line))
 	 (message "Select location and press RET")
@@ -11002,9 +10985,8 @@ If the current buffer is in `dired-mode', grep will be used to search
 in all files.  If AVOID-POS is given, ignore matches near that position.
 
 When optional argument STEALTH is non-nil, do not modify
-visibility around point, thus ignoring
-`org-show-hierarchy-above', `org-show-following-heading' and
-`org-show-siblings' variables."
+visibility around point, thus ignoring `org-show-context-detail'
+variable."
   (let ((case-fold-search t)
 	(s0 (mapconcat 'identity (org-split-string s "[ \t\r\n]+") " "))
 	(markers (concat "\\(?:" (mapconcat (lambda (x) (regexp-quote (car x)))
@@ -13929,59 +13911,65 @@ starting point when no match is found."
 
 (defun org-show-context (&optional key)
   "Make sure point and context are visible.
-How much context is shown depends upon the variables
-`org-show-hierarchy-above', `org-show-following-heading',
-`org-show-entry-below' and `org-show-siblings'."
-  (let ((heading-p   (org-at-heading-p t))
-	(hierarchy-p (org-get-alist-option org-show-hierarchy-above key))
-	(following-p (org-get-alist-option org-show-following-heading key))
-	(entry-p     (org-get-alist-option org-show-entry-below key))
-	(siblings-p  (org-get-alist-option org-show-siblings key)))
-    ;; Show heading or entry text
-    (if (and heading-p (not entry-p))
-	(org-flag-heading nil)    ; only show the heading
-      (and (or entry-p (outline-invisible-p) (org-invisible-p2))
-	   (org-show-hidden-entry)))    ; show entire entry
-    (when following-p
-      ;; Show next sibling, or heading below text
-      (save-excursion
-	(and (if heading-p (org-goto-sibling) (outline-next-heading))
-	     (org-flag-heading nil))))
-    (when siblings-p (org-show-siblings))
-    (when hierarchy-p
-      ;; show all higher headings, possibly with siblings
-      (save-excursion
-	(while (and (ignore-errors (progn (org-up-heading-all 1) t))
-		    (not (bobp)))
-	  (org-flag-heading nil)
-	  (when siblings-p (org-show-siblings)))))))
+Optional argument KEY, when non-nil, is a symbol.  See
+`org-show-context-detail' for allowed values and how much is to
+be shown."
+  (org-show-set-visibility (org-get-alist-option org-show-context-detail key)))
+
+(defun org-show-set-visibility (detail)
+  "Set visibility around point according to DETAIL.
+DETAIL is either nil, `minimal', `local', `ancestors', `lineage',
+`canonical', `full' 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 (memq detail '(local full t))))
+      (org-flag-heading nil)
+    (org-show-entry)
+    (org-with-limited-levels
+     (case detail
+       ((full t)
+	(org-show-subtree)
+	(run-hook-with-args 'org-cycle-hook 'subtree))
+       (canonical (show-children))
+       ((nil minimal ancestors))
+       (t (save-excursion
+	    (outline-next-heading)
+	    (org-flag-heading nil))))))
+  ;; Show all siblings.
+  (when (memq detail '(lineage canonical full t)) (org-show-siblings))
+  ;; Show ancestors, possibly with their siblings.
+  (when (memq detail '(ancestors lineage canonical full t))
+    (save-excursion
+      (while (org-up-heading-safe)
+	(org-flag-heading nil)
+	(when (memq detail '(canonical full t)) (org-show-siblings))))))
 
 (defvar org-reveal-start-hook nil
   "Hook run before revealing a location.")
 
 (defun org-reveal (&optional siblings)
   "Show current entry, hierarchy above it, and the following headline.
-This can be used to show a consistent set of context around locations
-exposed with `org-show-hierarchy-above' or `org-show-following-heading'
-not t for the search context.
+
+This can be used to show a consistent set of context around
+locations exposed with `org-show-context'.
 
 With optional argument SIBLINGS, on each level of the hierarchy all
 siblings are shown.  This repairs the tree structure to what it would
 look like when opened with hierarchical calls to `org-cycle'.
+
 With double optional argument \\[universal-argument] \\[universal-argument], \
 go to the parent and show the
 entire tree."
   (interactive "P")
   (run-hooks 'org-reveal-start-hook)
-  (let ((org-show-hierarchy-above t)
-	(org-show-following-heading t)
-	(org-show-siblings (if siblings t org-show-siblings)))
-    (org-show-context nil))
-  (when (equal siblings '(16))
-    (save-excursion
-      (when (org-up-heading-safe)
-	(org-show-subtree)
-	(run-hook-with-args 'org-cycle-hook 'subtree)))))
+  (cond ((equal siblings '(4)) (org-show-set-visibility 'canonical))
+	((equal siblings '(16))
+	 (save-excursion
+	   (when (org-up-heading-safe)
+	     (org-show-subtree)
+	     (run-hook-with-args 'org-cycle-hook 'subtree))))
+	(t (org-show-set-visibility 'lineage))))
 
 (defun org-highlight-new-match (beg end)
   "Highlight from BEG to END and mark the highlight is an occur headline."
-- 
2.3.0

Re: [RFC] Simplify `org-show-context' configuration

[Samuel Wales]

i use maint, but looks good.  i'd use canonical most of the time.

it would be good to also have semi-canonical [i.e.
canonical-without-ancestor-body-text], where ancestor nodes do not
show body text.  text can obscure structure.  i use this view for
blogs.  otherwise i'd have to make fake headlines just to hide text.

does full show the entry below the headline that point is on?  i
wouldn't use this view if it is not canonical [i.e. does not show
children also].

do we presume that the entire buffer's visibility is changed for
showing context, or are things that already shown left showing?

-- 
The Kafka Pandemic: http://thekafkapandemic.blogspot.com

The disease DOES progress.  MANY people have died from it.  And
ANYBODY can get it.

Denmark: free Karina Hansen NOW.

Re: [RFC] Simplify `org-show-context' configuration

[Nicolas Goaziou]

Samuel Wales <samologist@gmail.com> writes:

> it would be good to also have semi-canonical [i.e.
> canonical-without-ancestor-body-text], where ancestor nodes do not
> show body text.  text can obscure structure.  i use this view for
> blogs.  otherwise i'd have to make fake headlines just to hide text.

I don't understand. Body text is not shown in ancestors. Considering the
following buffer:

    * Grandmother
    ** Uncle
    *** Heir
    ** Father
       Ancestor text
    *** Sister
        Sibling text
    *** Self
        Match
    **** First born
         Child text
    **** The other child
    *** Brother
    ** Aunt

`canonical' view is

    * Grandmother
    ** Uncle
    ** Father
    *** Sister
    *** Self
        Match
    **** First born
    **** The other child
    *** Brother
    ** Aunt

> does full show the entry below the headline that point is on?  i
> wouldn't use this view if it is not canonical [i.e. does not show
> children also].

`full', as its name suggests, shows complete subtree: all children and
their contents.

> do we presume that the entire buffer's visibility is changed for
> showing context, or are things that already shown left showing?

`canonical' change visibilty in subtree, so some parts of it could be
hidden in the process. Other views only augment current visibility.


Regards,

Re: [RFC] Simplify `org-show-context' configuration

[Samuel Wales]

hi nicolas,

On 2/17/15, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> I don't understand. Body text is not shown in ancestors. Considering the
> following buffer:
>
>     * Grandmother
>     ** Uncle
>     *** Heir
>     ** Father
>        Ancestor text
>     *** Sister
>         Sibling text
>     *** Self
>         Match
>     **** First born
>          Child text
>     **** The other child
>     *** Brother
>     ** Aunt
>
> `canonical' view is
>
>     * Grandmother
>     ** Uncle
>     ** Father
>     *** Sister
>     *** Self
>         Match
>     **** First born
>     **** The other child
>     *** Brother
>     ** Aunt

thanks for showing a complete example.

that is not canonical.  i thought we were working from my previous
posts over the years where i used the term "canonical".

you cannot create the visibility state you show from a fully-folded
buffer using only arrow keys and tab.

there are exactly two types of visibility.  each type has many
variants in principle, but we only need a few for each.

  1] can be created using arrows and tab from a fully-folded buffer
  2] cannot

this is a critical distinction.

org so far is not capable of doing any of the [1] states when going to
a location.  that's the problem that needs solving imo.

i actually don't care about any of the [2] states until [1] is possible.

within [1], there is a minimal state.  let's call it
minimal-canonical.  /that/ is the state that is most needed.  it's
roughly like what you show except with the body text for all
ancestors.

what you show is [2].  it is a great view, and needed, but it is not
minimal-canonical.

i don't want the term canonical to be used for any of the [2] states,
because then we will be back to missing the need for the
minimal-canonical view and the need for preserving an org buffer's [1]
status.

hope that clarifies.


samuel

-- 
The Kafka Pandemic: http://thekafkapandemic.blogspot.com

The disease DOES progress.  MANY people have died from it.  And
ANYBODY can get it.

Denmark: free Karina Hansen NOW.

Re: [RFC] Simplify `org-show-context' configuration

[Nicolas Goaziou]

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

Samuel Wales <samologist@gmail.com> writes:

> that is not canonical.  i thought we were working from my previous
> posts over the years where i used the term "canonical".
>
> you cannot create the visibility state you show from a fully-folded
> buffer using only arrow keys and tab.

You are right. Time for a third round, I guess. This patch removes
`full', which is useless, makes `canonical' really canonical, and adds
`tree' view, which is basically old wrong `canonical'. 

Original buffer, full view

    * Grandmother
    ** Uncle
    *** Heir
    ** Father
       Ancestor text
    *** Sister
        Sibling text
    *** Self
        Match
    **** First born
         Child text
    **** The other child
    *** Brother
    ** Aunt

`minimal'

    * Grandmother
    *** Self
        Match

`local'

    * Grandmother
    *** Self
        Match
    **** First born

`ancestors'

    * Grandmother
    ** Father
    *** Self
        Match

`lineage'

    * Grandmother
    ** Father
    *** Sister
    *** Self
        Match
    **** First born
    *** Brother

`tree'

    * Grandmother
    ** Uncle
    ** Father
    *** Sister
    *** Self
        Match
    **** First born
    **** The other child
    *** Brother
    ** Aunt

`canonical'

    * Grandmother
    ** Uncle
    ** Father
       Ancestor text
    *** Sister
    *** Self
        Match
    **** First born
    **** The other child
    *** Brother
    ** Aunt


Regards,


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Simplify-org-show-context-configuration.patch --]
[-- Type: text/x-diff, Size: 14398 bytes --]

From 6f903362065ab34bcf3a85658d2f2f178e1ecb78 Mon Sep 17 00:00:00 2001
From: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Date: Mon, 16 Feb 2015 21:43:35 +0100
Subject: [PATCH] Simplify `org-show-context' configuration

* lisp/org.el (org-show-context-detail): New variable.
(org-context-choice, org-show-following-heading, org-show-siblings,
org-show-entry-below, org-show-hierarchy-above): Remove variables.
(org-show-set-visibility): New function.
(org-get-location, org-show-context, org-reveal): Use new function.
(org-link-search): Update docstring.

* lisp/org-agenda.el (org-agenda-cycle-show): Use new function.

Configuration of `org-show-context' is done with a single variable
offering six different views, instead of four variables for a total
of 16 configurations.
---
 lisp/org-agenda.el |  15 ++--
 lisp/org.el        | 230 ++++++++++++++++++++++++++---------------------------
 2 files changed, 118 insertions(+), 127 deletions(-)

diff --git a/lisp/org-agenda.el b/lisp/org-agenda.el
index 9f2d9d1..7adf351 100644
--- a/lisp/org-agenda.el
+++ b/lisp/org-agenda.el
@@ -8696,11 +8696,12 @@ if it was hidden in the outline."
 (defvar org-agenda-cycle-counter nil)
 (defun org-agenda-cycle-show (&optional n)
   "Show the current entry in another window, with default settings.
-Default settings are taken from `org-show-hierarchy-above' and siblings.
-When use repeatedly in immediate succession, the remote entry will cycle
-through visibility
 
-children -> subtree -> folded
+Default settings are taken from `org-show-context-detail'.  When
+use repeatedly in immediate succession, the remote entry will
+cycle through visibility
+
+  children -> subtree -> folded
 
 When called with a numeric prefix arg, that arg will be passed through to
 `org-agenda-show-1'.  For the interpretation of that argument, see the
@@ -9521,11 +9522,7 @@ a timestamp can be added there."
     (unless (bolp) (insert "\n"))
     (unless (org-looking-at-p "^[ \t]*$") (save-excursion (insert "\n")))
     (when org-adapt-indentation (org-indent-to-column col)))
-  (let ((org-show-following-heading t)
-	(org-show-siblings t)
-	(org-show-hierarchy-above t)
-	(org-show-entry-below t))
-    (org-show-context)))
+  (org-show-set-visibility 'lineage))
 
 (defun org-agenda-diary-entry ()
   "Make a diary entry, like the `i' command from the calendar.
diff --git a/lisp/org.el b/lisp/org.el
index 4f047b2..1b20d50 100755
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -1165,87 +1165,80 @@ effective."
   :tag "Org Reveal Location"
   :group 'org-structure)
 
-(defconst org-context-choice
-  '(choice
-    (const :tag "Always" t)
-    (const :tag "Never" nil)
-    (repeat :greedy t :tag "Individual contexts"
-	    (cons
-	     (choice :tag "Context"
-		     (const agenda)
-		     (const org-goto)
-		     (const occur-tree)
-		     (const tags-tree)
-		     (const link-search)
-		     (const mark-goto)
-		     (const bookmark-jump)
-		     (const isearch)
-		     (const default))
-	     (boolean))))
-  "Contexts for the reveal options.")
-
-(defcustom org-show-hierarchy-above '((default . t))
-  "Non-nil means show full hierarchy when revealing a location.
-Org-mode often shows locations in an org-mode file which might have
-been invisible before.  When this is set, the hierarchy of headings
-above the exposed location is shown.
-Turning this off for example for sparse trees makes them very compact.
-Instead of t, this can also be an alist specifying this option for different
-contexts.  Valid contexts are
+(defcustom org-show-context-detail '((isearch . lineage)
+				     (bookmark-jump . lineage)
+				     (default . ancestors))
+  "Alist between context and visibility span when revealing a location.
+
+\\<org-mode-map>Some actions may move point into invisible
+locations.  As a consequence, Org always expose a neighborhood
+around point.  How much is shown depends on the initial action,
+or context.  Valid contexts are
+
   agenda         when exposing an entry from the agenda
-  org-goto       when using the command `org-goto' on key C-c C-j
-  occur-tree     when using the command `org-occur' on key C-c /
+  org-goto       when using the command `org-goto' (\\[org-goto])
+  occur-tree     when using the command `org-occur' (\\[org-sparse-tree] /)
   tags-tree      when constructing a sparse tree based on tags matches
   link-search    when exposing search matches associated with a link
   mark-goto      when exposing the jump goal of a mark
   bookmark-jump  when exposing a bookmark location
   isearch        when exiting from an incremental search
-  default        default for all contexts not set explicitly"
-  :group 'org-reveal-location
-  :type org-context-choice)
-
-(defcustom org-show-following-heading '((default . nil))
-  "Non-nil means show following heading when revealing a location.
-Org-mode often shows locations in an org-mode file which might have
-been invisible before.  When this is set, the heading following the
-match is shown.
-Turning this off for example for sparse trees makes them very compact,
-but makes it harder to edit the location of the match.  In such a case,
-use the command \\[org-reveal] to show more context.
-Instead of t, this can also be an alist specifying this option for different
-contexts.  See `org-show-hierarchy-above' for valid contexts."
-  :group 'org-reveal-location
-  :type org-context-choice)
-
-(defcustom org-show-siblings '((default . nil) (isearch t) (bookmark-jump t))
-  "Non-nil means show all sibling heading when revealing a location.
-Org-mode often shows locations in an org-mode file which might have
-been invisible before.  When this is set, the sibling of the current entry
-heading are all made visible.  If `org-show-hierarchy-above' is t,
-the same happens on each level of the hierarchy above the current entry.
-
-By default this is on for the isearch context, off for all other contexts.
-Turning this off for example for sparse trees makes them very compact,
-but makes it harder to edit the location of the match.  In such a case,
-use the command \\[org-reveal] to show more context.
-Instead of t, this can also be an alist specifying this option for different
-contexts.  See `org-show-hierarchy-above' for valid contexts."
-  :group 'org-reveal-location
-  :type org-context-choice
-  :version "24.4"
-  :package-version '(Org . "8.0"))
+  default        default for all contexts not set explicitly
+
+Allowed visibility spans are
+
+  minimal        show current headline; if point is not on headline,
+                 also show entry below
 
-(defcustom org-show-entry-below '((default . nil))
-  "Non-nil means show the entry below a headline when revealing a location.
-Org-mode often shows locations in an org-mode file which might have
-been invisible before.  When this is set, the text below the headline that is
-exposed is also shown.
+  local          show current headline, entry below and next headline
 
-By default this is off for all contexts.
-Instead of t, this can also be an alist specifying this option for different
-contexts.  See `org-show-hierarchy-above' for valid contexts."
+  ancestors      show direct ancestors of current headline; if point is
+                 not on headline, also show entry
+
+  lineage        show current headline, its direct ancestors and all
+                 their children; if point is not on headline, also show
+                 entry and first child
+
+  tree           show current headline, its direct ancestors and all
+                 their children; if point is not on headline, also show
+                 entry and all children
+
+  canonical      show current headline, its direct ancestors along with
+                 their entries and children; if point is not located on
+                 the headline, also show current entry and all children
+
+As special cases, a nil or t value means show all contexts in
+`minimal' or `canonical' view, respectively.
+
+Some views can make displayed information very compact, but also
+make it harder to edit the location of the match.  In such
+a case, use the command `org-reveal' (\\[org-reveal]) to show
+more context."
   :group 'org-reveal-location
-  :type org-context-choice)
+  :version "25.1"
+  :package-version '(Org . "8.3")
+  :type '(choice
+	  (const :tag "Canonical" t)
+	  (const :tag "Minimal" nil)
+	  (repeat :greedy t :tag "Individual contexts"
+		  (cons
+		   (choice :tag "Context"
+			   (const agenda)
+			   (const org-goto)
+			   (const occur-tree)
+			   (const tags-tree)
+			   (const link-search)
+			   (const mark-goto)
+			   (const bookmark-jump)
+			   (const isearch)
+			   (const default))
+		   (choice :tag "Detail level"
+			   (const minimal)
+			   (const local)
+			   (const ancestors)
+			   (const lineage)
+			   (const tree)
+			   (const canonical))))))
 
 (defcustom org-indirect-buffer-display 'other-window
   "How should indirect tree buffers be displayed?
@@ -7522,11 +7515,9 @@ or nil."
 	 (setq buffer-read-only t)
 	 (if (and (boundp 'org-goto-start-pos)
 		  (integer-or-marker-p org-goto-start-pos))
-	     (let ((org-show-hierarchy-above t)
-		   (org-show-siblings t)
-		   (org-show-following-heading t))
-	       (goto-char org-goto-start-pos)
-	       (and (outline-invisible-p) (org-show-context)))
+	     (progn (goto-char org-goto-start-pos)
+		    (when (outline-invisible-p)
+		      (org-show-set-visibility 'lineage)))
 	   (goto-char (point-min)))
 	 (let (org-special-ctrl-a/e) (org-beginning-of-line))
 	 (message "Select location and press RET")
@@ -11002,9 +10993,8 @@ If the current buffer is in `dired-mode', grep will be used to search
 in all files.  If AVOID-POS is given, ignore matches near that position.
 
 When optional argument STEALTH is non-nil, do not modify
-visibility around point, thus ignoring
-`org-show-hierarchy-above', `org-show-following-heading' and
-`org-show-siblings' variables."
+visibility around point, thus ignoring `org-show-context-detail'
+variable."
   (let ((case-fold-search t)
 	(s0 (mapconcat 'identity (org-split-string s "[ \t\r\n]+") " "))
 	(markers (concat "\\(?:" (mapconcat (lambda (x) (regexp-quote (car x)))
@@ -13929,59 +13919,63 @@ starting point when no match is found."
 
 (defun org-show-context (&optional key)
   "Make sure point and context are visible.
-How much context is shown depends upon the variables
-`org-show-hierarchy-above', `org-show-following-heading',
-`org-show-entry-below' and `org-show-siblings'."
-  (let ((heading-p   (org-at-heading-p t))
-	(hierarchy-p (org-get-alist-option org-show-hierarchy-above key))
-	(following-p (org-get-alist-option org-show-following-heading key))
-	(entry-p     (org-get-alist-option org-show-entry-below key))
-	(siblings-p  (org-get-alist-option org-show-siblings key)))
-    ;; Show heading or entry text
-    (if (and heading-p (not entry-p))
-	(org-flag-heading nil)    ; only show the heading
-      (and (or entry-p (outline-invisible-p) (org-invisible-p2))
-	   (org-show-hidden-entry)))    ; show entire entry
-    (when following-p
-      ;; Show next sibling, or heading below text
-      (save-excursion
-	(and (if heading-p (org-goto-sibling) (outline-next-heading))
-	     (org-flag-heading nil))))
-    (when siblings-p (org-show-siblings))
-    (when hierarchy-p
-      ;; show all higher headings, possibly with siblings
-      (save-excursion
-	(while (and (ignore-errors (progn (org-up-heading-all 1) t))
-		    (not (bobp)))
-	  (org-flag-heading nil)
-	  (when siblings-p (org-show-siblings)))))))
+Optional argument KEY, when non-nil, is a symbol.  See
+`org-show-context-detail' for allowed values and how much is to
+be shown."
+  (org-show-set-visibility (org-get-alist-option org-show-context-detail key)))
+
+(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."
+  ;; Show current heading and possibly its entry, following headline
+  ;; or all children.
+  (if (and (org-at-heading-p) (not (eq detail 'local)))
+      (org-flag-heading nil)
+    (org-show-entry)
+    (org-with-limited-levels
+     (case detail
+       ((tree canonical t) (show-children))
+       ((nil minimal ancestors))
+       (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))
+    (save-excursion
+      (while (org-up-heading-safe)
+	(org-flag-heading nil)
+	(when (memq detail '(canonical t)) (org-show-entry))
+	(when (memq detail '(tree canonical t)) (show-children))))))
 
 (defvar org-reveal-start-hook nil
   "Hook run before revealing a location.")
 
 (defun org-reveal (&optional siblings)
   "Show current entry, hierarchy above it, and the following headline.
-This can be used to show a consistent set of context around locations
-exposed with `org-show-hierarchy-above' or `org-show-following-heading'
-not t for the search context.
+
+This can be used to show a consistent set of context around
+locations exposed with `org-show-context'.
 
 With optional argument SIBLINGS, on each level of the hierarchy all
 siblings are shown.  This repairs the tree structure to what it would
 look like when opened with hierarchical calls to `org-cycle'.
+
 With double optional argument \\[universal-argument] \\[universal-argument], \
 go to the parent and show the
 entire tree."
   (interactive "P")
   (run-hooks 'org-reveal-start-hook)
-  (let ((org-show-hierarchy-above t)
-	(org-show-following-heading t)
-	(org-show-siblings (if siblings t org-show-siblings)))
-    (org-show-context nil))
-  (when (equal siblings '(16))
-    (save-excursion
-      (when (org-up-heading-safe)
-	(org-show-subtree)
-	(run-hook-with-args 'org-cycle-hook 'subtree)))))
+  (cond ((equal siblings '(4)) (org-show-set-visibility 'canonical))
+	((equal siblings '(16))
+	 (save-excursion
+	   (when (org-up-heading-safe)
+	     (org-show-subtree)
+	     (run-hook-with-args 'org-cycle-hook 'subtree))))
+	(t (org-show-set-visibility 'lineage))))
 
 (defun org-highlight-new-match (beg end)
   "Highlight from BEG to END and mark the highlight is an occur headline."
-- 
2.3.0

Re: [RFC] Simplify `org-show-context' configuration

[Samuel Wales]

looks good.

thanks for your effort on making a single variable.

Re: [RFC] Simplify `org-show-context' configuration

[Nicolas Goaziou]

Samuel Wales <samologist@gmail.com> writes:

> looks good.
>
> thanks for your effort on making a single variable.

Pushed with tests and documentation, in
4eb4f47141a1ac582330b903bd779dccbcb1c154.

Thank you.


Regards,