three bugs/misfeatures in org-reveal (or is org-reveal the wrong way to reveal around point?)

three bugs/misfeatures in org-reveal (or is org-reveal the wrong way to reveal around point?)

[Samuel Wales]

I hope a kind soul can comment here.

For years I have been trying to make it so that you can go
to Org from Magit and have it reveal the way I want.

[All I want is what for me is a normal visibility state, which means a
visibility state that can be recreated using only arrow keys and TAB.]

Is org-reveal the wrong tool for this job?  Is there another tool that
works better for it?

The apparent bugs are in the comments below.

Thanks.

Samuel

P.S.  I am also hoping for the same effect upon going from the Org
agenda to the Org outline.

===

(defadvice magit-visit-item (after org-visibility activate compile)
  "Make going to Org from Magit reveal canonically."
  (when (eq major-mode 'org-mode)
    (alpha-org-reveal-canonically)))

(defun alpha-org-reveal-canonically ()
  "Reveal around point canonically.

Canonical visibility means that the buffer is always in a
visibility state that can be created solely by arrow keys + TAB.

Thus, merely showing the next header without all of its siblings
is not canonical.  Also, showing children without showing the
parent's entry text is not canonical."
  (interactive)

  ;; bug 1: when point is in entry text, the first child of that
  ;; entry shows, but its siblings (i.e. the other children) do
  ;; not show, even though i have org-show-siblings and
  ;; org-show-hierarchy-above both set to t.
  ;;
  ;; the entry text must show because point is in it.  and
  ;; because it must show, so must all children.  how do i get it
  ;; to do this?
  ;;
  ;; bug 2: when point is on the first child headline, its
  ;; siblings show, but the entry text of its parent does not
  ;; show.  how do i get it to show the parent's entry text?
  ;;
  ;; bug 3: org-reveal takes several seconds to run.  is there a
  ;; way to speed it up?

  (org-reveal t)
  ;; (if ...)
  ;; (show-entry)
  )

Re: three bugs/misfeatures in org-reveal (or is org-reveal the wrong way to reveal around point?)

[Sebastien Vauban]

Hi Samuel,

Samuel Wales wrote:
> I hope a kind soul can comment here.
>
> For years I have been trying to make it so that you can go
> to Org from Magit and have it reveal the way I want.
>
> [All I want is what for me is a normal visibility state, which means a
> visibility state that can be recreated using only arrow keys and TAB.]
>
> Is org-reveal the wrong tool for this job?  Is there another tool that
> works better for it?
>
> The apparent bugs are in the comments below.
>
> Thanks.
>
> Samuel
>
> P.S.  I am also hoping for the same effect upon going from the Org
> agenda to the Org outline.
>
> ===
>
> (defadvice magit-visit-item (after org-visibility activate compile)
>   "Make going to Org from Magit reveal canonically."
>   (when (eq major-mode 'org-mode)
>     (alpha-org-reveal-canonically)))
>
> (defun alpha-org-reveal-canonically ()
>   "Reveal around point canonically.
>
> Canonical visibility means that the buffer is always in a
> visibility state that can be created solely by arrow keys + TAB.
>
> Thus, merely showing the next header without all of its siblings
> is not canonical.  Also, showing children without showing the
> parent's entry text is not canonical."
>   (interactive)
>
>   ;; bug 1: when point is in entry text, the first child of that
>   ;; entry shows, but its siblings (i.e. the other children) do
>   ;; not show, even though i have org-show-siblings and
>   ;; org-show-hierarchy-above both set to t.
>   ;;
>   ;; the entry text must show because point is in it.  and
>   ;; because it must show, so must all children.  how do i get it
>   ;; to do this?
>   ;;
>   ;; bug 2: when point is on the first child headline, its
>   ;; siblings show, but the entry text of its parent does not
>   ;; show.  how do i get it to show the parent's entry text?
>   ;;
>   ;; bug 3: org-reveal takes several seconds to run.  is there a
>   ;; way to speed it up?
>
>   (org-reveal t)
>   ;; (if ...)
>   ;; (show-entry)
>   )

Just a question: did you play with the following settings?

--8<---------------cut here---------------start------------->8---
  ;; show full hierarchy when revealing a location
  (setq org-show-hierarchy-above t)

  ;; don't show following heading when revealing a location
  (setq org-show-following-heading nil)

  ;; don't show all sibling headings when revealing a location
  (setq org-show-siblings nil)

  ;; show the entry below a headline when revealing a location
  ;; (setq org-show-entry-below t)
  (setq org-show-entry-below '((org-goto . t)))
--8<---------------cut here---------------end--------------->8---

Do they impact or resolve some of the things you consider as bugs?

Best regards,
  Seb

-- 
Sebastien Vauban

Re: three bugs/misfeatures in org-reveal (or is org-reveal the wrong way to reveal around point?)

[Samuel Wales]

Hi Sebastien,

On 8/6/13, Sebastien Vauban <sva-news@mygooglest.com> wrote:
> Just a question: did you play with the following settings?

Yes.  They don't seem to fix it.

> --8<---------------cut here---------------start------------->8---
>   ;; show full hierarchy when revealing a location
>   (setq org-show-hierarchy-above t)

I always have this.

>
>   ;; don't show following heading when revealing a location
>   (setq org-show-following-heading nil)

Its default value is ((default)).  Yet it shows the following heading
anyway.  Seems like a bug.

>
>   ;; don't show all sibling headings when revealing a location
>   (setq org-show-siblings nil)

Opposite of what I want.

>
>   ;; show the entry below a headline when revealing a location
>   ;; (setq org-show-entry-below t)
>   (setq org-show-entry-below '((org-goto . t)))

Setting it to t in some cases reveals a headline, then an ellipsis on
a line by itself below that which stands for the entire subtree.  I
don't want ellipses in unusual places like that.  It did not show the
entry as it was supposed to.

However, if it worked for me, I would use this variable.

> Do they impact or resolve some of the things you consider as bugs?

They do not resolve them.

Samuel

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

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

Denmark: free Karina Hansen NOW.

Re: three bugs/misfeatures in org-reveal (or is org-reveal the wrong way to reveal around point?)

[Samuel Wales]

i think i found one of the bugs in org.el's org-show-context.  is
anybody willing to confirm and fix it?

On 8/5/13, Samuel Wales <samologist@gmail.com> wrote:
>   ;; bug 1: when point is in entry text, the first child of that
>   ;; entry shows, but its siblings (i.e. the other children) do
>   ;; not show, even though i have org-show-siblings and
>   ;; org-show-hierarchy-above both set to t.

    (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))

the part in the save-excursion needs to check for siblings-p also.

Re: three bugs/misfeatures in org-reveal (or is org-reveal the wrong way to reveal around point?)

[Nicolas Goaziou]

Hello,

Samuel Wales <samologist@gmail.com> writes:

> i think i found one of the bugs in org.el's org-show-context.  is
> anybody willing to confirm and fix it?
>
> On 8/5/13, Samuel Wales <samologist@gmail.com> wrote:
>>   ;; bug 1: when point is in entry text, the first child of that
>>   ;; entry shows, but its siblings (i.e. the other children) do

Siblings are other headlines at the same level, not children.

>>   ;; not show, even though i have org-show-siblings and
>>   ;; org-show-hierarchy-above both set to t.
>
>     (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))
>
> the part in the save-excursion needs to check for siblings-p also.

I don't understand why it should. SIBLINGS-P means "show all siblings".
This is handled later in the function.


Regards,

-- 
Nicolas Goaziou

Re: three bugs/misfeatures in org-reveal (or is org-reveal the wrong way to reveal around point?)

[Samuel Wales]

thanks for clarifying.  that seems to eliminate all possibility of
specifying canonical visibility using org show variables.

thus, this is a feature that is strangely missing in org, as opposed
to a bug.  [yet it is what i think would be a good default for
newcomers.]

canonical visibility roughly means a visibility state that can be
created at any time using org-cycle and arrow keys.

for example, if only the first child is showing, then it is not
canonical visibility.  the only things that should NOT show are
entirely folded headers, blocks, etc.

this is the only kind of visibility that i ever use unless i am doing
a sparse tree, which is extremely rare.

the lack of ability to specify canonical visibility is the  reason i
have spent many years trying to fix it.  i have actually have now
around-defadviced the isearch version of org-show-context, but i don't
know what i am doing and it is slow and there are other contexts that
need fixing.  i think i will have to eliminate org-show-context
entirely if i am to get canonical visibility.

Re: three bugs/misfeatures in org-reveal (or is org-reveal the wrong way to reveal around point?)

[Nicolas Goaziou]

Hello,

Samuel Wales <samologist@gmail.com> writes:

> thanks for clarifying.  that seems to eliminate all possibility of
> specifying canonical visibility using org show variables.

Indeed.

> thus, this is a feature that is strangely missing in org, as opposed
> to a bug.

I agree. Also, I find the configuration in this area overly complicated.

> canonical visibility roughly means a visibility state that can be
> created at any time using org-cycle and arrow keys.
>
> for example, if only the first child is showing, then it is not
> canonical visibility.  the only things that should NOT show are
> entirely folded headers, blocks, etc.
>
> this is the only kind of visibility that i ever use unless i am doing
> a sparse tree, which is extremely rare.

I think we could simplify the show context configuration and, at the
same time, provide a way to show "canonical visibility". 

For example, we can merge `org-show-hierarchy-above',
`org-show-following-heading', `org-show-siblings' and
`org-show-entry-below' into a single variable,
`org-show-context-detail', where each context is associated to a level,
e.g., for current default configuration,

  ((default . 2)
   (occur-tree . 1)
   (tags-tree . 1)
   (isearch . 3)
   (bookmark-jump . 3))

where

  1. means only the minimal location is shown, i.e., top level
     headline + headline, and section (no child) if match is not on
     a headline.

  2. means context 1 + hierarchy above

  3. means context 2 + siblings

  4. means canonical view, i.e, show full hierarchy above and siblings,
     and, if match is within a section, show also section and all
     children.

We lose a bit of control, but I think left out combinations are not very
interesting. But I may be wrong.

WDYT?


Regards,

-- 
Nicolas Goaziou

Re: three bugs/misfeatures in org-reveal (or is org-reveal the wrong way to reveal around point?)

[Samuel Wales]

On 1/18/15, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>   ((default . 2)
>    (occur-tree . 1)
>    (tags-tree . 1)
>    (isearch . 3)
>    (bookmark-jump . 3))
>
> where
>
>   1. means only the minimal location is shown, i.e., top level
>      headline + headline, and section (no child) if match is not on
>      a headline.
>
>   2. means context 1 + hierarchy above
>
>   3. means context 2 + siblings
>
>   4. means canonical view, i.e, show full hierarchy above and siblings,
>      and, if match is within a section, show also section and all
>      children.

i definitely like the idea of a single place to set visibility.  i
imagine that would clarify the code and make it so that users can
quickly determine what is possible.

please refresh me on the grammar.  does section mean something like
header + body text + children as a whole?

as a ui note, it might work to use symbols instead of numbers.  if the
code could support it bloatlessly, maybe even allow mix and match so
that you can do 3 without 2 if you want?

===

as a brainstorm, a new visibility command could cycle among the
available visibility states locally [i.e. as if you had set the
variable differently].  that might be implementationally troublesome,
but i would use it if it existed.  of course i'd use canonical as the
default.

in such a cycling, if it were implemented, i personally would want a
state that is like canonical visibility, but without body text.

it would be similar to doing show-branches in a highly time-consuming
way where you show siblings and hierarchy above and siblings above but
no body text.  this is /almost/ canonical, in that it does not leave
out anything except body text.  i think that would be particularly
useful for people who write books or blog posts as you'd get
everything related to structure and nothing not related to it.  i.e.
never surprised at the lack of a headline.

> We lose a bit of control, but I think left out combinations are not very
> interesting. But I may be wrong.
>
> WDYT?

one issue with existing code is that isearch-mode-end-hook and
defadvice of org-show-context seem not to always work, perhaps because
org sets a post-command-hook, which i find confusing. still have not
figured it out.  getting rid of post-command-hook stuff might be
useful?

another issue is speed; the existing code is slow for me, although
perhaps not much can be improved.


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: three bugs/misfeatures in org-reveal (or is org-reveal the wrong way to reveal around point?)

[Nicolas Goaziou]

Samuel Wales <samologist@gmail.com> writes:

> On 1/18/15, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
>>   ((default . 2)
>>    (occur-tree . 1)
>>    (tags-tree . 1)
>>    (isearch . 3)
>>    (bookmark-jump . 3))
>>
>> where
>>
>>   1. means only the minimal location is shown, i.e., top level
>>      headline + headline, and section (no child) if match is not on
>>      a headline.
>>
>>   2. means context 1 + hierarchy above
>>
>>   3. means context 2 + siblings
>>
>>   4. means canonical view, i.e, show full hierarchy above and siblings,
>>      and, if match is within a section, show also section and all
>>      children.
>

[...]

> please refresh me on the grammar.  does section mean something like
> header + body text + children as a whole?

Section is what you call the body text.

> as a ui note, it might work to use symbols instead of numbers.  if the
> code could support it bloatlessly, maybe even allow mix and match so
> that you can do 3 without 2 if you want?

I suggested numbers because the visibility states defined were
incremental. It is also possible to name "views" with symbols. However
this is not the issue at the moment.

I'd like to know first what "views" are useful. Currently, for a given
context, there are 16 possible combinations. I'm pretty sure at least
half of them can be dropped.

"Minimal" view (state 1 above) and "canonical view" (state 4) are
mandatory. In between, I'm not sure what is used. I suggested two of
them. Apparently, you would also need 3 without 2 (i.e., siblings
without hierachy above).

Regards,

Re: three bugs/misfeatures in org-reveal (or is org-reveal the wrong way to reveal around point?)

[Samuel Wales]

hi nicolas,

On 1/21/15, Nicolas Goaziou <mail@nicolasgoaziou.fr> wrote:
> "Minimal" view (state 1 above) and "canonical view" (state 4) are
> mandatory. In between, I'm not sure what is used. I suggested two of
> them. Apparently, you would also need 3 without 2 (i.e., siblings
> without hierachy above).

thanks for considering this topic.

i would use a state that is exactly like canonical except that all
body text [sections] would not show unless point is in a section.  we
can call it semi-canonical for lack of a better term.

otherwise i'm not qualified to select the intermediate states, as i
would not use them.  i'd use canonical and semi-canonical.


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.