suggestion: simplify depth stepping of document structure (outline) visibility

suggestion: simplify depth stepping of document structure (outline) visibility

[Michael Brand]

Hi all,

I would like much more to increase the heading visibility depth step by step like with the following if it would be much easier to type

step 1 to see level  1:    C-u 1 S-Tab
step 2 to see levels 1..2: C-u 2 S-Tab
step 3 to see levels 1..3: C-u 3 S-Tab
step 4 to see levels 1..4: C-u 4 S-Tab
and so on until not repeated any more (no cycling, only as a sequence)

Did I miss some simpler work flow to do something similar (not cycling with Tab or S-Tab)?

Are there others who would like this sequence to be easily stepped through?

Which constantly repeatable key command as convenient as possible like cycling with Tab or S-Tab would be suitable?

I would suggest that any key command different to this new key command would stop stepping the sequence and that the first invoke of this new key command again would reset the visibility to overview again like `C-u 1 S-Tab' does (similar to the nice cycle reset behavior of a first `S-Tab').

The point on e. g. a level 3 heading would be nice to be there again after going through steps 1 to 3 (similar to the nice behavior of e. g. `S-Tab S-Tab S-Tab' when the point was in a body before).

- Michael

Re: suggestion: simplify depth stepping of document structure (outline) visibility

[Bernt Hansen]

Michael Brand <michael.brand@alumni.ethz.ch> writes:

> I would like much more to increase the heading visibility depth step by step like with the following if it would be much easier to type
>
> step 1 to see level  1:    C-u 1 S-Tab
> step 2 to see levels 1..2: C-u 2 S-Tab
> step 3 to see levels 1..3: C-u 3 S-Tab
> step 4 to see levels 1..4: C-u 4 S-Tab
> and so on until not repeated any more (no cycling, only as a sequence)
>
> Did I miss some simpler work flow to do something similar (not cycling with Tab or S-Tab)?
>
> Are there others who would like this sequence to be easily stepped through?
>
> Which constantly repeatable key command as convenient as possible like cycling with Tab or S-Tab would be suitable?
>
> I would suggest that any key command different to this new key command would stop stepping the sequence and that the first invoke of this new key command again would reset the visibility to overview again like `C-u 1 S-Tab' does (similar to the nice cycle reset behavior of a first `S-Tab').
>
> The point on e. g. a level 3 heading would be nice to be there again after going through steps 1 to 3 (similar to the nice behavior of e. g. `S-Tab S-Tab S-Tab' when the point was in a body before).

Hi Michael,

In case you aren't aware of it you can view sublevels for a tree with
C-c C-k and match specific levels with a tags match (C-c / m LEVEL=n
RET).

HTH,
-Bernt

Re: suggestion: simplify depth stepping of document structure (outline) visibility

[Michael Brand]

Hi all,

One reply is not that much feedback yet..., maybe I tried to be detailed but was not clear enough? Ok, I thought after having submitted a few bug reports before, it would be good to contribute in a way a bit more constructive this time ;-) and implemented what I have described in my previous post for headings (not for list elements).

For those who are interested in trying it out:
First you will have to upgrade to org-version 6.31a or newer (or take into account
http://thread.gmane.org/gmane.emacs.orgmode/17441)
and then put the code at the end of this post e. g. into your .emacs file and start a new Emacs. Use `C->' and `C-<' repeatedly back and forth on your files that have at least a few heading levels and tell how useful you find it.

I find the usage of my-orgstruct-dive very intuitive in contrast to the complicated look of both the description in my previous post and my implementation here. As a nice side effect this function also brings two functionalities from outline-mode to org-mode which I am missing in org-mode: outline-mode-`C-c C-q' (hide everything lower than heading level at point (cursor)) and outline-mode-`C-c C-i' (show direct subheadings but not body of heading at point).

------------------------------------------------------------
(global-set-key (kbd "C->") 'my-orgstruct-dive)
(global-set-key (kbd "C-<") 'my-orgstruct-dive-out)
(defvar my-orgstruct-dive-level 0)
(defun my-orgstruct-dive-out ()
  "Wrapper to simplify comparison with last-command in my-orgstruct-dive"
  (interactive)
  (my-orgstruct-dive t))
(defun my-orgstruct-dive (&optional dive-out)
  "Make visible one heading level more or less.
return value: undefined.
dive-out: If nil dive in, else dive out."
  (interactive)
  ;; determine new level
  (if (or (eq last-command 'my-orgstruct-dive)
          (eq last-command 'my-orgstruct-dive-out))
      ;; command repetition, increase/decrease level
      (setq my-orgstruct-dive-level
            (+ my-orgstruct-dive-level (if dive-out '-1 '1)))
    ;; init level to that of point
    (setq my-orgstruct-dive-level
          (if (outline-on-heading-p)
              (org-reduced-level
               (save-excursion (beginning-of-line) (org-outline-level)))
            '0)))
  ;; update heading visibility
  (when (or (<= my-orgstruct-dive-level 0) (<= 1000 my-orgstruct-dive-level))
    (setq my-orgstruct-dive-level 1))
  (org-shifttab my-orgstruct-dive-level))
------------------------------------------------------------

Re: suggestion: simplify depth stepping of document structure (outline) visibility

[Michael Brand]

Hi all

This is a follow-up to
http://thread.gmane.org/gmane.emacs.orgmode/17581

On 09-10-14 14:24 , I wrote:
> (global-set-key (kbd "C->") 'my-orgstruct-dive)
> (global-set-key (kbd "C-<") 'my-orgstruct-dive-out)
> (defvar my-orgstruct-dive-level 0)

Now I did a rewrite for some improvements, mainly to support dive in
and out of headings also in a variant that leaves the visibility of
siblings. The code is at the end.

Example 1: C-> C-> C-< C-> [...]
This changes only the visibility of of the current heading and leaves
the visibility of siblings, similar to Tab.

Example 2: C-u C-> C-> C-< C-< C-< C-> [...]
This changes the visibility of all headings, similar to S-Tab.

Michael

-----------------------------------------------------------
(global-set-key (kbd "C->") 'my-orgstruct-dive-in)
(global-set-key (kbd "C-<") 'my-orgstruct-dive-out)

(defun my-orgstruct-dive-in (arg)
   "This func is very similar to the func my-orgstruct-dive-out. They are
wrappers to simplify comparison with last-command in my-orgstruct-dive.

Without prefix C-u: Dive in and out the current heading (relative) and leave
the visibility of the siblings, similar to Tab. Having the point before the
first heading in a buffer does not make sense.
Example: `C-> C-> C-< C-> [...]'

With prefix C-u: Dive in and out all headings in the buffer (absolute),
similar to S-Tab. If the point is before the first heading then the behavior
is like if it is on a top level heading.
Example: `C-u C-> C-> C-< C-< C-< C-> [...]'"
   (interactive "P")
   (my-orgstruct-dive arg))

(defun my-orgstruct-dive-out (arg)
   "See the docstring of the very similar func my-orgstruct-dive-in."
   (interactive "P")
   (my-orgstruct-dive arg t))

(defvar my-orgstruct-dive-start-arg nil
   "State variable of func my-orgstruct-dive: The prefix state of the first
invoke of my-orgstruct-dive-in or my-orgstruct-dive-out, see their
docstrings.")

(defvar my-orgstruct-dive-level 1
   "State variable of func my-orgstruct-dive: The reduced level which is the
level of the heading and not necessarily the number of stars if oddeven.
The type of level is relative if my-orgstruct-dive-start-arg is nil, else
absolute. For both types of level the smallest possible value is 1.")

(defun my-orgstruct-dive (arg &optional dive-out)
   "Make visible one heading level more or less.
return value: Undefined.
arg: See the docstring about prefix C-u in func my-orgstruct-dive-in
dive-out: If nil dive in, else dive out."
   ;; determine new level
   (if (or arg  ; let any intermediate `C-u' break the invoke repetition
           (and (not (eq last-command 'my-orgstruct-dive-in))
                (not (eq last-command 'my-orgstruct-dive-out))))
       ;; this is the first invoke of dive
       (progn
         ;; move back to beginning of line with heading:
         ;; - to prepare the point location for possibly hitting some Tabs
         ;;   afterwards
         ;; - to skip list elements, they are not supported do dive in
         ;;   (this alone could also be covered within a save-excursion)
         ;; - for the func org-outline-level that requires beginning of line
         ;;   (this alone could also be covered within a save-excursion)
         (unless (org-before-first-heading-p) (outline-back-to-heading))

         ;; reset start arg and level
         (setq my-orgstruct-dive-start-arg arg)
         (setq my-orgstruct-dive-level
               (if my-orgstruct-dive-start-arg
                   ;; absolute level
                   (if (org-before-first-heading-p)
                       '1
                     (org-reduced-level (org-outline-level)))
                 ;; relative level
                 '1)))
     ;; this is a repeated invoke of dive: increase/decrease level
     (setq my-orgstruct-dive-level
           (+ my-orgstruct-dive-level (if dive-out '-1 '1)))
     (when (< my-orgstruct-dive-level 1) (setq my-orgstruct-dive-level 1)))

   ;; update heading visibility according to new level
   (if my-orgstruct-dive-start-arg
       ;; absolute level
       (org-shifttab my-orgstruct-dive-level)  ; logs the level itself
     ;; relative level
     (hide-subtree)
     (show-children (* (org-level-increment) (1- my-orgstruct-dive-level)))
     (message "Content view to relative level: %d" my-orgstruct-dive-level))

   ;; move back to beginning of line with heading to prepare
   ;; the point location for possibly hitting some Tabs afterwards
   (unless (org-before-first-heading-p) (outline-back-to-heading)))
-----------------------------------------------------------

Re: Re: suggestion: simplify depth stepping of document structure (outline) visibility

[Bastien]

Hi Michael,

Michael Brand <michael.brand@alumni.ethz.ch> writes:

> Now I did a rewrite for some improvements, mainly to support dive in
> and out of headings also in a variant that leaves the visibility of
> siblings. The code is at the end.

It tested the code, works nicely - thanks!

I just noticed two oddities: (1) it has no notion of content, it's just
about headlines, right?  Okay, I can always combine `C->' with the usual
TAB command but it's a bit surprising first; (2) the first press at C->
and C-< sets the "content relative view" to 1, whatever the initial
state was.  Feels a bit unintuitive to me...  

Hope others will test this!

-- 
 Bastien

Re: Re: suggestion: simplify depth stepping of document structure (outline) visibility

[Herbert Sitz]

[-- Attachment #1.1: Type: text/plain, Size: 2225 bytes --]

On Thu, Sep 2, 2010 at 6:26 PM, Bastien <bastien.guerry@wikimedia.fr> wrote:

> > Now I did a rewrite for some improvements, mainly to support dive in
> > and out of headings also in a variant that leaves the visibility of
> > siblings. The code is at the end.
>
> Michael Brand <michael.brand@alumni.ethz.ch> writes:
> It tested the code, works nicely - thanks!
>
> I just noticed two oddities: (1) it has no notion of content, it's just
> about headlines, right?  Okay, I can always combine `C->' with the usual
> TAB command but it's a bit surprising first;


Yes, it shows only the structure not the body text.  This is exactly what I
want.  The built-in visibility cycling always expands body text and that
makes it nearly useless in most of my documents, which have large amounts of
body text under each heading.  As soon as you try to do a <tab> cycle all
you can see is the body text under the heading, none of the subheadings.  So
the regular visibility cycling is useless at revealing document structure.
(For some documents the built-in tab visibility cycling is useful, but for
me it's a very limited set.)

The focus of Michael's function on headings invites a complementary function
that focuses on body text.  The function I"m thinking of would toggle body
text visibility on a subtree, operating only on the visible headings in the
subtree.

The other thing that I would like added is to have another step built-in,
which in step after last heading level in subtree is revealed it will toggle
body text on for all headings in subtree.  For example, for a 4 level
subtree the C-> operation would go successively like this:

a.  Reveal headings thru Level 2,
b.  Reveal headings thru Level 3,
c.  Reveal headings thru Level 4,
d.  show body text for all headings in subtree.


(2) the first press at C->
> and C-< sets the "content relative view" to 1, whatever the initial
> state was.  Feels a bit unintuitive to me...
>
>
Yes, I agree, starting from current view depth is a bit of polish that
should be added.

I'll help with whatever is needed.  As I told Michael, I think all of the
above can be done fairly easily by creating a new function based the
built-in show-children function.

Regards,

Herb Sitz

[-- Attachment #1.2: Type: text/html, Size: 2915 bytes --]

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: Re: suggestion: simplify depth stepping of document structure (outline) visibility

[Michael Brand]

Hi all

> On Thu, Sep 2, 2010 at 6:26 PM, Bastien <bastien.guerry@wikimedia.fr
> <mailto:bastien.guerry@wikimedia.fr>> wrote:
> > (2) the first press at C->
> > and C-< sets the "content relative view" to 1, whatever the initial
> > state was.  Feels a bit unintuitive to me...

On 10-09-03 07:01 , Herbert Sitz wrote:
> Yes, I agree, starting from current view depth is a bit of polish that
> should be added.

And what would one expect from the absolute variant (currently with
C-u) that also resets to the depth of the heading at point?

My point of view is different: First this current behavior is clearly
intended as an alternative for the absolute `C-u 3 S-Tab' but without
the need of counting manually, just like outline-mode-`C-c C-q' (hide
everything lower than heading level _at point_). Second I prefer to
keep things simple and don't like to think about bothering what the
initial view depth of
* 1
** 1.1
*** 1.1.1
** 1.2
*** 1.2.1
should be, when viewed as
* 1
** 1.1...
** 1.2
*** 1.2.1
with point on 1. Here I prefer to hit C-> repeatedly instead of an
automatic guess that can never know if one wants to see even 1.2.1 or
not.

Michael

Re: Re: suggestion: simplify depth stepping of document structure (outline) visibility

[Michael Brand]

Sorry, gmane.org thread broken here because of wrong reply.
follow-up for gmane.org is here:
http://thread.gmane.org/gmane.emacs.orgmode/29679